This guide covers best practices for preparing your environment to develop within the Urbit ecosystem.
A variety of plugins have been built to provide support for the Hoon language in different text editors. These are listed below.
Note: The hoon compiler expects Unix-style line endings (LF) and will fail to parse Windows-style line endings (CRLF). Make sure your editor is set to use LF for line endings, especially if you're developing on Windows.
Atom is free and open-source and runs on all major operating systems. It is available here. A package for Hoon support is maintained by Tlon and may be obtained using the package manager within the editor by searching for
Sublime Text is closed-source, but may be downloaded for free and there is no enforced time limit for evaluation. It runs on all major operating systems. It is available here.
Visual Studio Code
Visual Studio Code is free and open-source and runs on all major operating systems. It is available here. Hoon support may be acquired in the Extensions menu within the editor by searching for
Creating a fake ship
To do work with Hoon, we recommended using a "fake" ship — one that's not connected to the network.
Because such a ship has no presence on the network, you don't need an Azimuth identity. You just need to have installed the Urbit binary.
To create a fake ship named
~zod, run the command below. You can replace
zod with any valid Urbit ship-name.
./urbit -F zod
This should take a couple of minutes, during which you should see a block of boot messages, starting with the Urbit version number.
Fake ship networking
Fake ships on the same machine can automatically talk to one another. Having created a fakezod, you can create a fake
~bus the same way:
./urbit -F bus
Now in the fakezod's dojo, try:
> |hi ~bus>=hi ~bus successful
Fake ships run on their own network using fake keys and do not communicate with live-net ships in any way. Multiple fake ships running on the same machine can network with each other. However, these fake ships still have 'realistic' packet routing: fake galaxies can talk to each other, but fake stars/planets cannot - unless they have the appropriate fake sponsors running, too.
~tex & ~mex: GOOD~tex & ~bintex: GOOD~mex & ~bintex: BAD~tex, ~mex, & ~bintex: GOOD
For your convenience, note the following relationships of several convenient planets and stars:
Other points can be calculated using the layout of Azimuth.
Faster fake ship booting
While working with Hoon, you'll often want to delete an old fake ship and recreate a fresh one. Rather than having to wait a few minutes for the fresh ship to be initialised, you can instead create a backup copy of a fake ship. That way you can just delete the current copy, replace it with the backup, and reboot in a matter of seconds.
To do this, boot a fresh fake ship like usual, but with a different name:
./urbit -F zod -c zod.new
Once it's finished booting, it's a good idea to mount its desks so you don't have to do it again each time. In the dojo:
> |mount %base>=> |mount %garden>=> |mount %landscape>=> |mount %bitcoin>=> |mount %webterm>=
Next, shut the ship down with
ctrl+D. Then, copy the pier and start using the copy instead:
cp -r zod.new zod./urbit zod
Now whenever you want a fresh fakezod, you can just shut it down and do:
rm -r zodcp -r zod.new zod./urbit zod
Working with desks
If you're just working in the dojo or experimenting with generators, committing to the
%base desk on a fake ship is fine. If you're working on a Gall agent or developing a desk for distribution, you'll most likely want to work on a separate desk and it's slightly more complicated.
Mount a desk
To mount a desk to Unix so you can add files, you just need to run the
|mount command in the dojo and specify the name of the desk to mount:
The desk will now appear in the root of your pier (zod in this case):
You can unmount it again by running the
|unmount command in the dojo:
Create a new desk
To create a new desk, you'll need to merge from an existing one, typically
%base. In the dojo, run the following (you can change
%mydesk to your preferred name):
|merge %mydesk our %base
If you now mount it, you'll have
/mydesk directory in your pier with all the files of the
%base desk inside. You can then delete the contents, copy in your own files and
Desks must contain all the
mark files, libraries, etc, that they need. A
sys.kelvin file is mandatory, and there are a few
mark files necessary as well. In the next couple of sections we'll look at different ways to populate a new desk with the necessary files.
This is the absolute minimal desk you'll be able to commit:
skeleton├── mar│ ├── hoon.hoon│ ├── kelvin.hoon│ ├── mime.hoon│ ├── noun.hoon│ ├── txt-diff.hoon│ └── txt.hoon└── sys.kelvin
sys.kelvin specifies the kernel kelvin version with which the desk is compatible. You can copy it across from the
%base desk, or just run the following in the terminal from within the desk directory:
echo "[%zuse 417]" > sys.kelvin
mark files can just be copied across from the
Using dev desks
If you're working on something more complex, for example a desk with agents and a front-end, there will be a number of
mark files, libraries, etc, that will be necessary. Rather than having to manually copy all the files from the relevant default desks, the urbit git repo includes some dev desks which can be used as a base. To get these, make sure you have git installed and then clone the repo:
git clone https://github.com/urbit/urbit ~/git/urbit
If you now change to the
~/git/urbit/pkg directory, you'll see the source for the default desks, among other things:
The desks ending in
garden-dev, contain files for interfacing with those respective desks. If you're creating a new desk that has a tile and front-end, for example, you might like to use
garden-dev as a base. To create such a base, there's a
symbolic-merge.sh script included in the directory. You can use it like so:
./symbolic-merge base-dev mydesk./symbolic-merge garden-dev mydesk
After running that, you'll have a
mydesk desk in the
pkg directory that contains the symlinked files from both those dev desks. To copy the files into your pier, you can create and mount a mydesk desk in the dojo:
|merge %mydesk our %base|mount %mydesk
Then, you can go into your pier:
Delete the contents of
rm -r mydesk/*
And then copy in the contents of the desk you created:
cp -rL ~/git/urbit/pkg/mydesk/* mydesk
Note you have to use
cp -rL rather than just
cp -r because the
symbolic-merge.sh script creates symlinks, so the
L flag is to resolve them and copy the actual files.
Now you can just add a
echo "[%zuse 417]" > mydesk/sys.kelvin
And you'll be able to mount the desk with
When you're developing a desk, it's best to structure your working directory with the same hierarchy as a real desk. For example,
~/project/mydesk might look like:
mydesk├── app│ └── foo.hoon├── desk.bill├── desk.docket-0├── lib│ └── foo.hoon├── mar│ └── foo│ ├── action.hoon│ └── update.hoon├── sur│ └── foo.hoon└── sys.kelvin
That way, whenever you want to test your changes, you can just copy it across to your pier like:
cp -ruv mydesk/* /path/to/fake/zod/mydesk
And then just commit it in the dojo:
If you're using dev desks as a base, it's best to keep those files separate from your own code.
A useful pattern is to work from a git repo and sync your work with the pier of a fake ship. An easy way to do this is with the following command:
watch rsync -zr --delete /working/repo/desk/* /path/to/fake/zod/mydesk
/working/repo/desk is the folder that has the proper desk structure outlined above, and
/path/to/fake/zod/mydesk is the desk you wish to copy the contents of the working repo to. From here, you can edit from the working repo and perform git commands there, while testing your changes on the fake ship.