73dba66 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

Copyedits

commit73dba661375e245c51253a9dcbd781411dfb4191 authorMatilde Park <matilde@tlon.io> dateMon 7 Oct 2019, 18:48 (7 years ago) parentdf17de3

3 files changed+74−89

compare with master

unifiedsplit

content/develop.md+29−44 content/operations.md+44−44 templates/page_indiced.html+1−1

content/develop.md+29−44

@@ -3,77 +3,62 @@ title = "Develop"

33template = "page_indiced.html"

44+++

6−## Core Development {#core}

6+We recognize that not every developer wants to work on Urbit itself – there’s a lot of space for developers building their applications on Urbit. To help you get settled, we have information that distinguishes the goals for both core and application development:

8−## Application Development {#application}

8+- Core development: improving and extending Urbit itself

9+- Application development: building end-user peer-to-peer applications that run on Urbit

910

10−## Creating a Development Ship {#creating-a-development-ship}

11+This guide will start by getting you set up to run an Urbit ship, and then tell you everything you need to now do to either.

1112

12−To do work with Hoon and with the system, we recommended using a "fake" ship -- one not connected to the network.

13−

14−Because such a ship has no presence on the network, you don't need an Azimuth identity for its purposes. You just need to have [installed our software](/install).

15−

16−To create a fake ship named `~zod`, run the command below. You can replace `zod` with any valid Urbit ship-name.

17−

18−```

19−urbit -F zod

20−```

13+### Setting up your environment

2114

22−Now you should see a block of boot messages, starting with the Urbit version number. Welcome!

15+We assume you’ve gotten a basic introduction to Urbit. If you haven’t, read the [Understanding Urbit](@/understanding-urbit/_index.md) series, or just jump ahead to the [Technical Overview](@/understanding-urbit/technical-overview.md).

2316

24−### Basic Operations

17+Once you’re ready, you can get started on the network right away and take some first steps, without acquiring an identity, by [creating a comet](@/operations.md#creating-a-comet).

2518

26−Welcome to your ship! There's a few things you should do to become oriented.

19+When developing, however, we recommend [booting a development ship](#creating-a-development-ship) and working locally.

2720

28−#### The Dojo

21+## Core development {#core}

2922

30−Let's try out the Dojo, the Arvo command line and Hoon REPL:

23+Working on the core means improving the Urbit project itself, working with a global community of developers.

3124

32−```

33−~sample-planet:dojo> (add 2 2)

34−```

25+Just arrived and unsure what to work on? An ideal way to get started is by experimenting with the system, talking to other developers, and reading (or [contributing to](https://github.com/urbit/docs)) the [documentation](/docs/).

3526

36−Should produce:

27+Prefer learning with an instructor? We also offer an online course that covers the basics of Urbit development called [Hoon School](@/hoonschool.md). If course-based learning works well for you, we recommend you sign up.

3728

38−```

39−> (add 2 2)

40−4

41−```

29+The Urbit developer community congregates around [the urbit-dev mailing list](https://groups.google.com/a/urbit.org/forum/#!forum/dev), the `~dopzod/urbit-help channel` on Landscape, and [Urbit’s GitHub repository](https://github.com/urbit/urbit). It’s a good idea to sign up, see what people are talking about, and introduce yourself.

4230

43−Good.

31+Once you’re comfortable working with Urbit, check out the [project’s issues on GitHub](https://github.com/urbit/urbit/issues) or some of our [contribution bounties](https://grants.urbit.org/).

4432

45−#### Mounting

33+If you’re looking for some guidance, need help, or would prefer direct communication for your ideas, you can also always reach out to us directly at [support@urbit.org](mailto:support@urbit.org).

4634

47−Your ship's filesystem being "mounted" means that its filesystem can be interacted with through Unix. This makes things much easier for you.

35+## Application development {#application}

4836

49−The Arvo filesystem isn't mounted to Unix by default. Switch to the Dojo prompt and run:

37+Building an application on Urbit provides a lot of features for you. It means being able to leverage its [personal key infrastructure](https://azimuth.network/), which verifies its scarce address space and associating that verification with other data; or the [global filesystem](@/docs/arvo/clay.md), enabling permissioned directories and social software. Building your application on Urbit could be building decentralized applications for your own groups. Building your application on Urbit could also just be building your ship’s access to the rest of the world.

5038

51−```

52−~sample-planet:dojo> |mount %

53−```

39+The Arvo vane that manages user applications is called [Gall](@/docs/hoon/hoon-tutorial/gall.md). When writing your application, you will want to consult its documentation for information on its interface to the rest of your ship (or to other ships).

5440

55−This should produce:

41+Gall applications don’t tie you to use any particular user interface. They can work without providing a response to the user; or by printing to the Dojo; or with an interface in Landscape, which uses [Eyre](@/docs/arvo/eyre.md), the Arvo vane that serves HTTP, to serve a React-based interface to the application through a web browser.

5642

57−```

58−> |mount %

59−>=

60−```

43+Landscape has both tile-specific and full-screen applications. For a Landscape template wizard, check out our [create-landscape-app](https://github.com/urbit/create-landscape-app) repository.

6144

62−which indicates that the command was processed.

45+For examples of Gall applications, you can see the [Egg Timer example](@/docs/hoon/hoon-tutorial/egg-timer.md) in the documentation; Gall applications with a Landscape interface include the [Weather tile](https://github.com/urbit/urbit/blob/master/pkg/arvo/app/weather.hoon) (its Landscape interface code is located [here](https://github.com/urbit/urbit/blob/master/pkg/interface/weather/tile/tile.js) and compiled separately).

6346

64−`|mount %` will cause a `home/` directory to appear inside your _pier_ folder in Unix (the "pier" is our shorthand for the directory whose name corresponds to your Azimuth point). Changes to these files can be committed to your pier by running `|commit %home` once you're done.

47+## Creating a development ship {#creating-a-development-ship}

6548

66−#### Shutting Down and Restarting

49+To do work with Hoon and with the system, we recommended using a "fake" ship -- one not connected to the network.

6750

68−You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.

51+Because such a ship has no presence on the network, you don't need an Azimuth identity for its purposes. You just need to have [installed our software](/install).

6952

70−To restart your ship, simply pass the name of your pier:

53+To create a fake ship named `~zod`, run the command below. You can replace `zod` with any valid Urbit ship-name.

7154

7255```

73−urbit some-planet

56+urbit -F zod

7457```

7558

76−## Community Tutorials {#community-tutorials}

59+Now you should see a block of boot messages, starting with the Urbit version number. Welcome!

60+

61+## Community tutorials {#community-tutorials}

7762

7863Here are some tutorials written by members of the Urbit community. Some are a little outdated, but they may still prove useful.

7964

content/operations.md+44−44

@@ -33,7 +33,7 @@ Note: Bridge allows you to both make reads and writes to the Ethereum blockchain

3333

3434Once the program is running in your browser, go through the steps presented according to the type of wallet you have. You’ll be presented with a few login options. A notable option is Urbit Master Ticket. This is for those who used our Wallet Generator software. If you bought points from an Urbit sale and then used the Wallet Generator, your networking keys will be set for you. All other login options will require you to set your own networking keys.

3535

36−### Accept Your Transfer

36+### Accept your transfer

3737

3838If you were given points by Tlon you likely already fully own them. But if someone else sent you a point, then you will first need to use Bridge to accept that transfer.

3939

@@ -43,7 +43,7 @@ Now you'll be on the management page of your point. The transfer isn't completed

4343

4444If you already own a point, click on the `Details ->` under your sigil in the `Your Points` section.

4545

46−### Set Your Networking Keys

46+### Set your networking keys

4747

4848If you just accepted a point, you'll be returned to your point screen. Notice that that links and buttons are now clickable. You now own this point!

4949

@@ -57,14 +57,14 @@ and use the result.

5757

5858It should be noted that setting your network keys is an event on the Ethereum network and will therefore cost a trivial, but non-zero, amount of [gas](https://github.com/ethereum/wiki/wiki/Design-Rationale#gas-and-fees) to complete.

5959

60−### Generate Your Keyfile

60+### Generate your keyfile

6161

6262From the detail page associated with your point, click the `Generate Arvo Keyfile` link and you'll be taken to a page with a field titled `Network seed`. This field should already be filled in, and should match the hexadecimal string that you entered in the previous step. If it's not filled in or does not match, fill it in with the correct string.

6363Click `Generate ->`, which will download a keyfile onto your machine.

6464

6565With that keyfile in hand, you can now exit Bridge and continue to the guide to [install the Urbit binary](@/install.md).

6666

67−## Using Your Ship {#urbit-administration}

67+## Using your ship {#urbit-administration}

6868

6969Your urbit (also called your _ship_) is a persistent Unix process that you mainly control from the console.

7070

@@ -238,7 +238,7 @@ Because Urbit networking is stateful we call this a _continuity breach_. Everyth

238238

239239When this happens, back up any files you'd like to save, shut down your urbit, and recreate it (as if you were starting for the first time).

240240

241−## Creating a Comet {#creating-a-comet}

241+## Creating a comet {#creating-a-comet}

242242

243243**Comets** are urbits whose names are 128-bits or 16 syllables, such as:

244244

@@ -246,7 +246,7 @@ When this happens, back up any files you'd like to save, shut down your urbit, a

246246

247247Comet names aren't quite as memorable as others, but they're disposable identities that anyone can make for free to join the live network.

248248

249−### Booting a Comet

249+### Booting a comet

250250

251251To boot your comet, go into the command line and run the following command from the directory that was created during Urbit installation:

252252

@@ -264,7 +264,7 @@ http: live (insecure, loopback) on 12321

264264~dasres_marzod:dojo>

265265```

266266

267−## DNS Proxying {#dns-proxying}

267+## DNS proxying {#dns-proxying}

268268

269269We have a system that lets you request a domain name for your ship in the form of `ship.arvo.network`, where `ship` is your ship's name minus the `~`. This allows users to access their ships remotely using Landscape, our graphical web interface.

270270

@@ -308,7 +308,7 @@ This will make HTTP-requests to self-check availability over `galaxy.$AMES-DOMAI

308308

309309Otherwise, `:dns|auto` works the same as `:dns|ip` does with stars and planets: if it's available or unavailable, talk messages, and so on.

310310

311−### More Information

311+### More information

312312

313313Configuring a ship's domain causes the `:acme` app to request an HTTPS certificate for that domain from LetsEncrypt. Note that LetsEncrypt also requires that the HTTP server be listening on port 80. If the certificate request fails, `:acme` will send a `:talk` message with an explanation. Once the certificate is successfully retrieved, `:acme` will install it, causing the HTTP servers to restart. A secure server will be started on port 443 (the HTTPS default) if it's available. Otherwise, it will try 8443, and then increment to the next port until it can successfully bind one.

314314

@@ -352,7 +352,7 @@ You'll see your message printed below messages from others that came before it:

352352~your-urbit= Hello, world!

353353```

354354

355−### Direct Messaging

355+### Direct messaging

356356

357357To send a direct message to someone, first set your audience:

358358

@@ -475,7 +475,7 @@ will print as

475475~your-urbit=^ Well, thanks!

476476```

477477

478−#### Activating Lines

478+#### Activating lines

479479

480480A line number identifying the **subsequent** line is displayed every 5 lines.

481481

@@ -559,7 +559,7 @@ To delete our example above:

559559sampel-palnet:talk> ;delete %coolbox 'people sent uncool messages'

560560```

561561

562−#### Change Description

562+#### Change description

563563

564564Syntax: `;depict %name 'description'`

565565

@@ -639,17 +639,17 @@ For example:

639639~sampel-palnet:talk> ;unsource %coolbox ~marzod/urbit-help

640640```

641641

642−#### Circle Membership

642+#### Circle membership

643643

644644If you have joined a circle, you can make this information publicly available to help others find that circle as well.

645645

646−#### Show Membership

646+#### Show membership

647647

648648Syntax: `;show ~some/circle`

649649

650650Adds a circle to your public membership list on your Hall profile. Hall profiles are not used yet.

651651

652−#### Hide Membership

652+#### Hide membership

653653

654654Syntax: `;hide ~some/circle`

655655

@@ -659,13 +659,13 @@ Removes a circle from your public membership list on your Hall profile. Hall pro

659659

660660You'll see status notifications when people enter or leave circles you're subscribed to.

661661

662−#### Notifications Off

662+#### Notifications off

663663

664664Syntax: `;set quiet`

665665

666666Turn off status (and config) notifications.

667667

668−#### Notifications On

668+#### Notifications on

669669

670670Syntax: `;unset quiet`

671671

@@ -703,7 +703,7 @@ For example:

703703~sampel-palnet:talk> ;attend ~marzod/urbit-help idle

704704```

705705

706−#### Set Display Name

706+#### Set display name

707707

708708Syntax: `;name ~some/circle 'my handle'`

709709

@@ -717,7 +717,7 @@ An audience consists of one or more messaging targets. These can be

717717circles or ships. (In the latter case, it's secretly the `~ship/inbox`

718718circle.)

719719

720−#### Circle Glyphs

720+#### Circle glyphs

721721

722722Glyphs are found at the end of your prompt to as a quick indicator of where

723723your messages will be sent.

@@ -804,31 +804,31 @@ There are a few special-purpose glyphs:

804804

805805### Configuration

806806

807−#### Set Audience

807+#### Set audience

808808

809809`;~ship/circle`

810810

811811Set audience to `~ship/circle`.

812812

813−#### Set Audience by Glyph

813+#### Set audience by glyph

814814

815815Syntax: `;[glyph]`

816816

817817Set audience to the circle previously bound to the chosen glyph.

818818

819−#### Set Audience to Ship

819+#### Set audience to ship

820820

821821syntax `;~ship`

822822

823823Set audience to another ship.

824824

825−#### Set Audience to Own Circle

825+#### Set audience to own circle

826826

827827Syntax: `;%circle`

828828

829829Set audience to a circle on your own ship.

830830

831−#### Set Audience + Send Message

831+#### Set audience and send message

832832

833833Syntax: `;~dannum-mitryl this is a private message`

834834

@@ -843,44 +843,44 @@ Your audience is configured with regard to the following rules (in order):

843843

844844### Local nicknames

845845

846−#### See Nicknames

846+#### See nicknames

847847

848848Syntax: `;nick`

849849

850850List all local nicknames.

851851

852−#### Find Nickname

852+#### Find nickname

853853

854854Syntax: `;nick ~some-urbit`

855855

856856Look up a nickname using the known ship-name.

857857

858−#### Reverse Find Nickname

858+#### Reverse-find nickname

859859

860860syntax: `;nick plato`

861861

862862Find a ship's name using its nickname.

863863

864−#### Set Nickname

864+#### Set nickname

865865

866866Syntax: `;nick ~some-urbit plato`

867867

868868Create a new nickname.

869869

870−#### Clear Nickname

870+#### Clear nickname

871871

872872Syntax: `;nick ~some-urbit ~`

873873

874874Clear an assigned nickname.

875875

876−#### Display Nicks, Not Ship-Names

876+#### Display nicknames, not ship names

877877

878878Syntax: `;set nicks`

879879

880880Show nicknames instead of ship-names. If no local nickname is set, uses

881881that user's handle. If the user has no handle, just the urbit name.

882882

883−#### Display Ship-Names, Not Nicks

883+#### Display ship names, not nicknames

884884

885885Syntax: `;unset nicks`

886886

@@ -892,38 +892,38 @@ phonebook.

892892

893893### Miscellaneous configuration

894894

895−#### Show Timestamps

895+#### Show timestamps

896896

897897Syntax: `;set showtime`

898898

899899Show the timestamp for each message.

900900

901−#### Hide Timestamps

901+#### Hide timestamps

902902

903903Syntax: `;unset showtime`

904904

905905Stop showing the timestamp for each message.

906906

907−#### Change Time Zone

907+#### Change timezone

908908

909909Syntax: `;set timezone [+/-][hours]`

910910

911911Adjust the display of timestamps to a specific timezone. Relative to UTC.

912912

913−#### Sound Notification On

913+#### Sound notification on

914914

915915Syntax: `;set notify`

916916

917917Emit a terminal bell sound if your six-syllable ship name is mentioned in

918918a message.

919919

920−#### Sound Notification Off

920+#### Sound notification off

921921

922922Syntax `;unset notify`

923923

924924Do not notify when your ship name is mentioned.

925925

926−#### Set Width

926+#### Set width

927927

928928Syntax: `;set width [number]`

929929

@@ -973,7 +973,7 @@ Use `=var` to save faces to the Dojo subject.

973973Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a

974974face in a `.hoon` file in this way.

975975

976−#### System Commands

976+#### System commands

977977

978978Use `=dir` to set the current working directory:

979979

@@ -1167,7 +1167,7 @@ Set any environment variable:

11671167Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a

11681168variable in a `.hoon` file in this way.

11691169

1170−#### Special Variables

1170+#### Special variables

11711171

11721172There are a few special variables that the Dojo maintains.

11731173

@@ -1285,7 +1285,7 @@ fintyr-haldet-fassev-solhex

12851285You can use `=` to set an environment variable in Dojo, but there are

12861286a few reserved names that have special uses.

12871287

1288−#### dir

1288+#### `dir`

12891289

12901290Current working `%clay` desk and revision. Read / write.

12911291

@@ -1297,7 +1297,7 @@ Current working `%clay` desk and revision. Read / write.

12971297404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/

12981298```

12991299

1300−#### lib

1300+#### `lib`

13011301

13021302Current set of libraries (`/lib`) in your environment. Can be set

13031303with `/+`. Read / write.

@@ -1312,7 +1312,7 @@ Now we can use arms from lib/number-to-words.hoon

13121312~your-urbit:dojo> (to-words:eng-us:number-to-words 123.456)

13131313```

13141314

1315−#### sur

1315+#### `sur`

13161316

13171317Current set of structures (`/sur`) in your environment. Can be set

13181318with `/-`. Read / write.

@@ -1327,7 +1327,7 @@ Now we can use arms in sur/sole.hoon.

13271327~your-urbit:dojo> `sole-effect:sole`[%bel ~]

13281328```

13291329

1330−#### now

1330+#### `now`

13311331

13321332The current (128-bit `@da`) time. Read-only.

13331333

@@ -1338,7 +1338,7 @@ The current (128-bit `@da`) time. Read-only.

13381338~2016.3.21..21.10.57..429a

13391339```

13401340

1341−#### our

1341+#### `our`

13421342

13431343The current urbit ship. Read-only.

13441344

@@ -1349,7 +1349,7 @@ The current urbit ship. Read-only.

13491349~your-urbit

13501350```

13511351

1352−#### eny

1352+#### `eny`

13531353

13541354512 bits of entropy. Read-only.

13551355

templates/page_indiced.html+1−1

@@ -46,7 +46,7 @@

4646{% endif %}

4747{% endfor %}

4848</nav>

49− <article class="mt4 mb4 c1-12 c6-12-md c4-10-lg">

49+ <article class="mt4 mb7 c1-12 c6-12-md c4-10-lg">

5050 {% if page.extra.author %}

5151 <span class="mt2 dib" rel="author"> {{ page.extra.author }} </span>

5252 {% if page.extra.ship %}