git.iko.soy/urbit.org
on 4fdc19d help sign in
urbit.org/content/docs/development/environment.md
331 lines 8.9 kB history raw
1+++
2title = "Environment Setup"
3description = "How to set up an environment for Urbit development."
4weight = 11
5template = "doc.html"
6+++
8This guide covers best practices for preparing your environment to develop
9within the Urbit ecosystem.
11## Text editors
13A variety of plugins have been built to provide support for the Hoon language in
14different text editors. These are listed below.
16**Note:** The hoon compiler expects Unix-style line endings (LF) and will
17fail to parse Windows-style line endings (CRLF). Make sure your editor is set
18to use LF for line endings, especially if you're developing on Windows.
20#### Atom
22Atom is free and open-source and runs on all major operating systems. It is
23available [here](https://atom.io/). A package for Hoon support is maintained by
24Tlon and may be obtained using the package manager within the editor by
25searching for `Hoon`.
27#### Sublime Text
29Sublime Text is closed-source, but may be downloaded for free and there is no
30enforced time limit for evaluation. It runs on all major operating systems. It
31is available [here](https://www.sublimetext.com/).
33#### Visual Studio Code
35Visual Studio Code is free and open-source and runs on all major operating
36systems. It is available [here](https://code.visualstudio.com/). Hoon support
37may be acquired in the Extensions menu within the editor by searching for
38`Hoon`.
40#### Emacs
42Emacs is free and open-source and runs on all major operating systems. It is
43available [here](https://www.gnu.org/software/emacs/). Hoon support is available
44with [hoon-mode.el](https://github.com/urbit/hoon-mode.el).
46#### Vim
48Vim is free and open-source and runs on all major operating systems. It is
49available [here](https://www.vim.org/). Hoon support is available with
50[hoon.vim](https://github.com/urbit/hoon.vim).
52## Development ships
54### Creating a fake ship
56To do work with Hoon, we recommended using a "fake" ship — one that's not
57connected to the network.
59Because such a ship has no presence on the network, you don't need an Azimuth
60identity. You just need to have [installed the Urbit binary](/getting-started/cli).
62To create a fake ship named `~zod`, run the command below. You can replace `zod`
63with any valid Urbit ship-name.
65```
66./urbit -F zod
67```
69This should take a couple of minutes, during which you should see a block of boot
70messages, starting with the Urbit version number.
72### Fake ship networking
74Fake ships on the same machine can automatically talk to one another. Having
75created a fakezod, you can create a fake `~bus` the same way:
77```
78./urbit -F bus
79```
81Now in the fakezod's dojo, try:
83```
84> |hi ~bus
85>=
86hi ~bus successful
87```
89### Faster fake ship booting
91While working with Hoon, you'll often want to delete an old fake ship and
92recreate a fresh one. Rather than having to wait a few minutes for the fresh
93ship to be initialised, you can instead create a backup copy of a fake ship.
94That way you can just delete the current copy, replace it with the backup, and
95reboot in a matter of seconds.
97To do this, boot a fresh fake ship like usual, but with a different name:
99```
100./urbit -F zod -c zod.new
101```
103Once it's finished booting, it's a good idea to mount its desks so you don't
104have to do it again each time. In the dojo:
106```
107> |mount %base
108>=
109> |mount %garden
110>=
111> |mount %landscape
112>=
113> |mount %bitcoin
114>=
115> |mount %webterm
116>=
117```
119Next, shut the ship down with `ctrl+D`. Then, copy the pier and start using the
120copy instead:
122```
123cp -r zod.new zod
124./urbit zod
125```
127Now whenever you want a fresh fakezod, you can just shut it down and do:
129```
130rm -r zod
131cp -r zod.new zod
132./urbit zod
133```
135## Working with desks
137If you're just working in the dojo or experimenting with generators, committing
138to the `%base` desk on a fake ship is fine. If you're working on a Gall agent or
139developing a desk for distribution, you'll most likely want to work on a
140separate desk and it's slightly more complicated.
142### Mount a desk
144To mount a desk to Unix so you can add files, you just need to run the `|mount`
145command in the dojo and specify the name of the desk to mount:
147```
148|mount %base
149```
151The desk will now appear in the root of your pier (zod in this case):
153```
154zod
155└── base
156```
158You can unmount it again by running the `|unmount` command in the dojo:
160```
161|unmount %base
162```
164### Create a new desk
166To create a new desk, you'll need to merge from an existing one, typically
167`%base`. In the dojo, run the following (you can change `%mydesk` to your
168preferred name):
170```
171|merge %mydesk our %base
172```
174If you now mount it, you'll have `/mydesk` directory in your pier with all the
175files of the `%base` desk inside. You can then delete the contents, copy in your
176own files and `|commit` it.
178Desks must contain all the `mark` files, libraries, etc, that they need. A
179`sys.kelvin` file is mandatory, and there are a few `mark` files necessary as
180well. In the next couple of sections we'll look at different ways to populate a
181new desk with the necessary files.
183### Minimal desk
185This is the absolute minimal desk you'll be able to commit:
187```
188skeleton
189├── mar
190│ ├── hoon.hoon
191│ ├── kelvin.hoon
192│ ├── mime.hoon
193│ ├── noun.hoon
194│ ├── txt-diff.hoon
195│ └── txt.hoon
196└── sys.kelvin
197```
199`sys.kelvin` specifies the kernel kelvin version with which the desk is
200compatible. You can copy it across from the `%base` desk, or just run the
201following in the terminal from within the desk directory:
203```sh
204echo "[%zuse 419]" > sys.kelvin
205```
207The other `mark` files can just be copied across from the `%base` desk.
209### Using dev desks
211If you're working on something more complex, for example a desk with agents and
212a front-end, there will be a number of `mark` files, libraries, etc, that will
213be necessary. Rather than having to manually copy all the files from the
214relevant default desks, the [urbit git repo](https://github.com/urbit/urbit)
215includes some dev desks which can be used as a base. To get these, make sure you
216have git installed and then clone the repo:
218```
219git clone https://github.com/urbit/urbit ~/git/urbit
220```
222If you now change to the `~/git/urbit/pkg` directory, you'll see the source for
223the default desks, among other things:
225```
226cd ~/git/urbit/pkg
227```
229The desks ending in `-dev`, like `base-dev` and `garden-dev`, contain files for
230interfacing with those respective desks. If you're creating a new desk that has
231a tile and front-end, for example, you might like to use `base-dev` and
232`garden-dev` as a base. To create such a base, there's a `symbolic-merge.sh`
233script included in the directory. You can use it like so:
235```
236./symbolic-merge base-dev mydesk
237./symbolic-merge garden-dev mydesk
238```
240After running that, you'll have a `mydesk` desk in the `pkg` directory that
241contains the symlinked files from both those dev desks. To copy the files into
242your pier, you can create and mount a mydesk desk in the dojo:
244```
245|merge %mydesk our %base
246|mount %mydesk
247```
249Then, you can go into your pier:
251```
252cd /path/to/fake/zod
253```
255Delete the contents of `mydesk`:
257```
258rm -r mydesk/*
259```
261And then copy in the contents of the desk you created:
263```
264cp -rL ~/git/urbit/pkg/mydesk/* mydesk
265```
267Note you have to use `cp -rL` rather than just `cp -r` because the
268`symbolic-merge.sh` script creates symlinks, so the `L` flag is to resolve them
269and copy the actual files.
271Now you can just add a `sys.kelvin` file:
273```
274echo "[%zuse 419]" > mydesk/sys.kelvin
275```
277And you'll be able to mount the desk with `|commit %mydesk`.
279## Project organization
281When you're developing a desk, it's best to structure your working directory
282with the same hierarchy as a real desk. For example, `~/project/mydesk` might
283look like:
285```
286mydesk
287├── app
288│ └── foo.hoon
289├── desk.bill
290├── desk.docket-0
291├── lib
292│ └── foo.hoon
293├── mar
294│ └── foo
295│ ├── action.hoon
296│ └── update.hoon
297├── sur
298│ └── foo.hoon
299└── sys.kelvin
301```
303That way, whenever you want to test your changes, you can just copy it across to
304your pier like:
306```
307cp -ruv mydesk/* /path/to/fake/zod/mydesk
308```
310And then just commit it in the dojo:
312```
313|commit %mydesk
314```
316If you're [using dev desks](#using-dev-desks) as a base, it's best to keep those
317files separate from your own code.
319### Syncing repos
321A useful pattern is to work from a git repo and sync your work with the pier of
322a fake ship. An easy way to do this is with the following command:
324```
325watch rsync -zr --delete /working/repo/desk/* /path/to/fake/zod/mydesk
326```
328Here `/working/repo/desk` is the folder that has the proper desk structure
329outlined above, and `/path/to/fake/zod/mydesk` is the desk you wish to copy the
330contents of the working repo to. From here, you can edit from the working repo
331and perform git commands there, while testing your changes on the fake ship.