Environment Setup

This guide covers best practices for preparing your environment to develop within the Urbit ecosystem.

Text editors

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.

Sublime Text

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 Hoon.

Emacs

Emacs is free and open-source and runs on all major operating systems. It is available here↗. Hoon support is available with hoon-mode.el↗.

Vim

Vim is free and open-source and runs on all major operating systems. It is available here↗. Hoon support is available with hoon.vim↗.

Development ships

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

Local Networking

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 initialized, 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 %landscape
>=

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 zod
cp -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:

|mount %base

The desk will now appear in the root of your pier (zod in this case):

zod
└── base

You can unmount it again by running the |unmount command in the dojo:

|unmount %base

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 |commit it.

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.

Minimal desk

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 416]" > sys.kelvin

The other mark files can just be copied across from the %base desk.

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 OS 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:

cd ~/git/urbit/pkg

The desks ending in -dev, like base-dev and landscae-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 base-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

After running that, you'll have a mydesk desk in the pkg directory that contains the symlinked files from that dev desk. 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:

cd /path/to/fake/zod

Delete the contents of mydesk:

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 sys.kelvin file:

echo "[%zuse 416]" > mydesk/sys.kelvin

And you'll be able to mount the desk with |commit %mydesk.

Project organization

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:

|commit %mydesk

If you're using dev desks as a base, it's best to keep those files separate from your own code.

Syncing repos

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

Here /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.