+++
title = "Environment Setup"
description = "How to set up an environment for Urbit development."
weight = 11
template = "doc.html"
+++

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:

#### Atom

Atom is free and open-source and runs on all major operating systems. It is
available [here](https://atom.io/). A package for Hoon support is maintained by
Tlon and may be obtained using the package manager within the editor by
searching for `Hoon`.

#### 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](https://www.sublimetext.com/).

#### Visual Studio Code

Visual Studio Code is free and open-source and runs on all major operating
systems. It is available [here](https://code.visualstudio.com/). 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](https://www.gnu.org/software/emacs/). Hoon support is available
with [hoon-mode.el](https://github.com/urbit/hoon-mode.el).

#### Vim

Vim is free and open-source and runs on all major operating systems. It is
available [here](https://www.vim.org/). Hoon support is available with
[hoon.vim](https://github.com/urbit/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](/getting-started/cli).

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
```

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

```sh
echo "[%zuse 419]" > 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 git repo](https://github.com/urbit/urbit)
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 `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 `base-dev` and
`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:

```
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 419]" > 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](#using-dev-desks) as a base, it's best to keep those
files separate from your own code.