@@ -8,25 +8,7 @@ template = "doc.html"
88This guide covers best practices for preparing your environment to develop
99within the Urbit ecosystem.
1010
11−## Creating a development ship
12−
13−To do work with Hoon, we recommended using a "fake" ship — one that's not
14−connected to the network.
15−
16−Because such a ship has no presence on the network, you don't need an Azimuth
17−identity. You just need to have [installed the Urbit binary](/getting-started/cli).
18−
19−To create a fake ship named `~zod`, run the command below. You can replace `zod`
20−with any valid Urbit ship-name.
21−
22−```
23−./urbit -F zod
24−```
25−
26−This should take a couple of minutes, during which you should see a block of boot
27−messages, starting with the Urbit version number.
28−
29−## Hoon support in text editors
11+## Text editors
3012
3113A variety of plugins have been built to provide support for the Hoon language in
3214different text editors:
@@ -61,4 +43,271 @@ with [hoon-mode.el](https://github.com/urbit/hoon-mode.el).
6143
6244Vim is free and open-source and runs on all major operating systems. It is
6345available [here](https://www.vim.org/). Hoon support is available with
64−[hoon.vim](https://github.com/urbit/hoon.vim) and is maintained by Tlon.
46+[hoon.vim](https://github.com/urbit/hoon.vim).
47+
48+## Development ships
49+
50+### Creating a fake ship
51+
52+To do work with Hoon, we recommended using a "fake" ship — one that's not
53+connected to the network.
54+
55+Because such a ship has no presence on the network, you don't need an Azimuth
56+identity. You just need to have [installed the Urbit binary](/getting-started/cli).
57+
58+To create a fake ship named `~zod`, run the command below. You can replace `zod`
59+with any valid Urbit ship-name.
60+
61+```
62+./urbit -F zod
63+```
64+
65+This should take a couple of minutes, during which you should see a block of boot
66+messages, starting with the Urbit version number.
67+
68+### Fake ship networking
69+
70+Fake ships on the same machine can automatically talk to one another. Having
71+created a fakezod, you can create a fake `~bus` the same way:
72+
73+```
74+./urbit -F bus
75+```
76+
77+Now in the fakezod's dojo, try:
78+
79+```
80+> |hi ~bus
81+>=
82+hi ~bus successful
83+```
84+
85+### Faster fake ship booting
86+
87+While working with Hoon, you'll often want to delete an old fake ship and
88+recreate a fresh one. Rather than having to wait a few minutes for the fresh
89+ship to be initialised, you can instead create a backup copy of a fake ship.
90+That way you can just delete the current copy, replace it with the backup, and
91+reboot in a matter of seconds.
92+
93+To do this, boot a fresh fake ship like usual, but with a different name:
94+
95+```
96+./urbit -F zod -c zod.new
97+```
98+
99+Once it's finished booting, it's a good idea to mount its desks so you don't
100+have to do it again each time. In the dojo:
101+
102+```
103+> |mount %base
104+>=
105+> |mount %garden
106+>=
107+> |mount %landscape
108+>=
109+> |mount %bitcoin
110+>=
111+> |mount %webterm
112+>=
113+```
114+
115+Next, shut the ship down with `ctrl+D`. Then, copy the pier and start using the
116+copy instead:
117+
118+```
119+cp -r zod.new zod
120+./urbit zod
121+```
122+
123+Now whenever you want a fresh fakezod, you can just shut it down and do:
124+
125+```
126+rm -r zod
127+cp -r zod.new zod
128+./urbit zod
129+```
130+
131+## Working with desks
132+
133+If you're just working in the dojo or experimenting with generators, committing
134+to the `%base` desk on a fake ship is fine. If you're working on a Gall agent or
135+developing a desk for distribution, you'll most likely want to work on a
136+separate desk and it's slightly more complicated.
137+
138+### Mount a desk
139+
140+To mount a desk to Unix so you can add files, you just need to run the `|mount`
141+command in the dojo and specify the name of the desk to mount:
142+
143+```
144+|mount %base
145+```
146+
147+The desk will now appear in the root of your pier (zod in this case):
148+
149+```
150+zod
151+└── base
152+```
153+
154+You can unmount it again by running the `|unmount` command in the dojo:
155+
156+```
157+|unmount %base
158+```
159+
160+### Create a new desk
161+
162+To create a new desk, you'll need to merge from an existing one, typically
163+`%base`. In the dojo, run the following (you can change `%mydesk` to your
164+preferred name):
165+
166+```
167+|merge %mydesk our %base
168+```
169+
170+If you now mount it, you'll have `/mydesk` directory in your pier with all the
171+files of the `%base` desk inside. You can then delete the contents, copy in your
172+own files and `|commit` it.
173+
174+Desks must contain all the `mark` files, libraries, etc, that they need. A
175+`sys.kelvin` file is mandatory, and there are a few `mark` files necessary as
176+well. In the next couple of sections we'll look at different ways to populate a
177+new desk with the necessary files.
178+
179+### Minimal desk
180+
181+This is the absolute minimal desk you'll be able to commit:
182+
183+```
184+skeleton
185+├── mar
186+│ ├── hoon.hoon
187+│ ├── kelvin.hoon
188+│ ├── mime.hoon
189+│ ├── noun.hoon
190+│ ├── txt-diff.hoon
191+│ └── txt.hoon
192+└── sys.kelvin
193+```
194+
195+`sys.kelvin` specifies the kernel kelvin version with which the desk is
196+compatible. You can copy it across from the `%base` desk, or just run the
197+following in the terminal from within the desk directory:
198+
199+```sh
200+echo "[%zuse 420]" > sys.kelvin
201+```
202+
203+The other `mark` files can just be copied across from the `%base` desk.
204+
205+### Using dev desks
206+
207+If you're working on something more complex, for example a desk with agents and
208+a front-end, there will be a number of `mark` files, libraries, etc, that will
209+be necessary. Rather than having to manually copy all the files from the
210+relevant default desks, the [urbit git repo](https://github.com/urbit/urbit)
211+includes some dev desks which can be used as a base. To get these, make sure you
212+have git installed and then clone the repo:
213+
214+```
215+git clone https://github.com/urbit/urbit ~/git/urbit
216+```
217+
218+If you now change to the `~/git/urbit/pkg` directory, you'll see the source for
219+the default desks, among other things:
220+
221+```
222+cd ~/git/urbit/pkg
223+```
224+
225+The desks ending in `-dev`, like `base-dev` and `garden-dev`, contain files for
226+interfacing with those respective desks. If you're creating a new desk that has
227+a tile and front-end, for example, you might like to use `base-dev` and
228+`garden-dev` as a base. To create such a base, there's a `symbolic-merge.sh`
229+script included in the directory. You can use it like so:
230+
231+```
232+./symbolic-merge base-dev mydesk
233+./symbolic-merge garden-dev mydesk
234+```
235+
236+After running that, you'll have a `mydesk` desk in the `pkg` directory that
237+contains the symlinked files from both those dev desks. To copy the files into
238+your pier, you can create and mount a mydesk desk in the dojo:
239+
240+```
241+|merge %mydesk our %base
242+|mount %mydesk
243+```
244+
245+Then, you can go into your pier:
246+
247+```
248+cd /path/to/fake/zod
249+```
250+
251+Delete the contents of `mydesk`:
252+
253+```
254+rm -r mydesk/*
255+```
256+
257+And then copy in the contents of the desk you created:
258+
259+```
260+cp -rL ~/git/urbit/pkg/mydesk/* mydesk
261+```
262+
263+Note you have to use `cp -rL` rather than just `cp -r` because the
264+`symbolic-merge.sh` script creates symlinks, so the `L` flag is to resolve them
265+and copy the actual files.
266+
267+Now you can just add a `sys.kelvin` file:
268+
269+```
270+echo "[%zuse 420]" > mydesk/sys.kelvin
271+```
272+
273+And you'll be able to mount the desk with `|commit %mydesk`.
274+
275+## Project organization
276+
277+When you're developing a desk, it's best to structure your working directory
278+with the same hierarchy as a real desk. For example, `~/project/mydesk` might
279+look like:
280+
281+```
282+mydesk
283+├── app
284+│ └── foo.hoon
285+├── desk.bill
286+├── desk.docket-0
287+├── lib
288+│ └── foo.hoon
289+├── mar
290+│ └── foo
291+│ ├── action.hoon
292+│ └── update.hoon
293+├── sur
294+│ └── foo.hoon
295+└── sys.kelvin
296+
297+```
298+
299+That way, whenever you want to test your changes, you can just copy it across to
300+your pier like:
301+
302+```
303+cp -ruv mydesk/* /path/to/fake/zod/mydesk
304+```
305+
306+And then just commit it in the dojo:
307+
308+```
309+|commit %mydesk
310+```
311+
312+If you're [using dev desks](#using-dev-desks) as a base, it's best to keep those
313+files separate from your own code.