git.iko.soy/urbit.org
on bb41d13 help sign in
urbit.org/content/docs/development/environment.md
327 lines 8.7 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:
16#### Atom
18Atom is free and open-source and runs on all major operating systems. It is
19available [here](https://atom.io/). A package for Hoon support is maintained by
20Tlon and may be obtained using the package manager within the editor by
21searching for `Hoon`.
23#### Sublime Text
25Sublime Text is closed-source, but may be downloaded for free and there is no
26enforced time limit for evaluation. It runs on all major operating systems. It
27is available [here](https://www.sublimetext.com/).
29#### Visual Studio Code
31Visual Studio Code is free and open-source and runs on all major operating
32systems. It is available [here](https://code.visualstudio.com/). Hoon support
33may be acquired in the Extensions menu within the editor by searching for
34`Hoon`.
36#### Emacs
38Emacs is free and open-source and runs on all major operating systems. It is
39available [here](https://www.gnu.org/software/emacs/). Hoon support is available
40with [hoon-mode.el](https://github.com/urbit/hoon-mode.el).
42#### Vim
44Vim is free and open-source and runs on all major operating systems. It is
45available [here](https://www.vim.org/). Hoon support is available with
46[hoon.vim](https://github.com/urbit/hoon.vim).
48## Development ships
50### Creating a fake ship
52To do work with Hoon, we recommended using a "fake" ship — one that's not
53connected to the network.
55Because such a ship has no presence on the network, you don't need an Azimuth
56identity. You just need to have [installed the Urbit binary](/getting-started/cli).
58To create a fake ship named `~zod`, run the command below. You can replace `zod`
59with any valid Urbit ship-name.
61```
62./urbit -F zod
63```
65This should take a couple of minutes, during which you should see a block of boot
66messages, starting with the Urbit version number.
68### Fake ship networking
70Fake ships on the same machine can automatically talk to one another. Having
71created a fakezod, you can create a fake `~bus` the same way:
73```
74./urbit -F bus
75```
77Now in the fakezod's dojo, try:
79```
80> |hi ~bus
81>=
82hi ~bus successful
83```
85### Faster fake ship booting
87While working with Hoon, you'll often want to delete an old fake ship and
88recreate a fresh one. Rather than having to wait a few minutes for the fresh
89ship to be initialised, you can instead create a backup copy of a fake ship.
90That way you can just delete the current copy, replace it with the backup, and
91reboot in a matter of seconds.
93To do this, boot a fresh fake ship like usual, but with a different name:
95```
96./urbit -F zod -c zod.new
97```
99Once it's finished booting, it's a good idea to mount its desks so you don't
100have to do it again each time. In the dojo:
102```
103> |mount %base
104>=
105> |mount %garden
106>=
107> |mount %landscape
108>=
109> |mount %bitcoin
110>=
111> |mount %webterm
112>=
113```
115Next, shut the ship down with `ctrl+D`. Then, copy the pier and start using the
116copy instead:
118```
119cp -r zod.new zod
120./urbit zod
121```
123Now whenever you want a fresh fakezod, you can just shut it down and do:
125```
126rm -r zod
127cp -r zod.new zod
128./urbit zod
129```
131## Working with desks
133If you're just working in the dojo or experimenting with generators, committing
134to the `%base` desk on a fake ship is fine. If you're working on a Gall agent or
135developing a desk for distribution, you'll most likely want to work on a
136separate desk and it's slightly more complicated.
138### Mount a desk
140To mount a desk to Unix so you can add files, you just need to run the `|mount`
141command in the dojo and specify the name of the desk to mount:
143```
144|mount %base
145```
147The desk will now appear in the root of your pier (zod in this case):
149```
150zod
151└── base
152```
154You can unmount it again by running the `|unmount` command in the dojo:
156```
157|unmount %base
158```
160### Create a new desk
162To 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
164preferred name):
166```
167|merge %mydesk our %base
168```
170If you now mount it, you'll have `/mydesk` directory in your pier with all the
171files of the `%base` desk inside. You can then delete the contents, copy in your
172own files and `|commit` it.
174Desks 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
176well. In the next couple of sections we'll look at different ways to populate a
177new desk with the necessary files.
179### Minimal desk
181This is the absolute minimal desk you'll be able to commit:
183```
184skeleton
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```
195`sys.kelvin` specifies the kernel kelvin version with which the desk is
196compatible. You can copy it across from the `%base` desk, or just run the
197following in the terminal from within the desk directory:
199```sh
200echo "[%zuse 419]" > sys.kelvin
201```
203The other `mark` files can just be copied across from the `%base` desk.
205### Using dev desks
207If you're working on something more complex, for example a desk with agents and
208a front-end, there will be a number of `mark` files, libraries, etc, that will
209be necessary. Rather than having to manually copy all the files from the
210relevant default desks, the [urbit git repo](https://github.com/urbit/urbit)
211includes some dev desks which can be used as a base. To get these, make sure you
212have git installed and then clone the repo:
214```
215git clone https://github.com/urbit/urbit ~/git/urbit
216```
218If you now change to the `~/git/urbit/pkg` directory, you'll see the source for
219the default desks, among other things:
221```
222cd ~/git/urbit/pkg
223```
225The desks ending in `-dev`, like `base-dev` and `garden-dev`, contain files for
226interfacing with those respective desks. If you're creating a new desk that has
227a 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`
229script included in the directory. You can use it like so:
231```
232./symbolic-merge base-dev mydesk
233./symbolic-merge garden-dev mydesk
234```
236After running that, you'll have a `mydesk` desk in the `pkg` directory that
237contains the symlinked files from both those dev desks. To copy the files into
238your pier, you can create and mount a mydesk desk in the dojo:
240```
241|merge %mydesk our %base
242|mount %mydesk
243```
245Then, you can go into your pier:
247```
248cd /path/to/fake/zod
249```
251Delete the contents of `mydesk`:
253```
254rm -r mydesk/*
255```
257And then copy in the contents of the desk you created:
259```
260cp -rL ~/git/urbit/pkg/mydesk/* mydesk
261```
263Note 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
265and copy the actual files.
267Now you can just add a `sys.kelvin` file:
269```
270echo "[%zuse 419]" > mydesk/sys.kelvin
271```
273And you'll be able to mount the desk with `|commit %mydesk`.
275## Project organization
277When you're developing a desk, it's best to structure your working directory
278with the same hierarchy as a real desk. For example, `~/project/mydesk` might
279look like:
281```
282mydesk
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
297```
299That way, whenever you want to test your changes, you can just copy it across to
300your pier like:
302```
303cp -ruv mydesk/* /path/to/fake/zod/mydesk
304```
306And then just commit it in the dojo:
308```
309|commit %mydesk
310```
312If you're [using dev desks](#using-dev-desks) as a base, it's best to keep those
313files separate from your own code.
315### Syncing repos
317A useful pattern is to work from a git repo and sync your work with the pier of
318a fake ship. An easy way to do this is with the following command:
320```
321watch rsync -zr --delete /working/repo/desk/* /path/to/fake/zod/mydesk
322```
324Here `/working/repo/desk` is the folder that has the proper desk structure
325outlined above, and `/path/to/fake/zod/mydesk` is the desk you wish to copy the
326contents of the working repo to. From here, you can edit from the working repo
327and perform git commands there, while testing your changes on the fake ship.