git.iko.soy/urbit.org
on 883cb21 help sign in
urbit.org/content/docs/development/environment.md
313 lines 8.1 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.