1.8 What you need to know and do before beginning

How & where to run Urbit

Let’s go through a list of course materials that you’ll need in order to succeed:

    1. A running urbit ship. It’s beyond the scope of these course documents to describe how to install a planet or a comet, though much of that can be found here: https://urbit.org/using/install/, and the basics of running things can be found here: https://urbit.org/using/operations/using-your-ship/. Incidentally, once you have your planet up and running, it is strongly recommended to do all development work on a disposable ship, either a fakezod, comet or moon. If you mess up your planet’s files somehow while tinkering, it may be impossible to fix without a “breach” (a version of starting fresh), but since you have 4.3 billion moons per planet, they make an excellent resource for coding and will not harm your planet should you make a big mistake. You would just delete that moon, create a new one and keep going.
    2. A basic understanding of navigating your terminal environment of choice. Currently, Urbit only works in a “Unix-based” environment, which generally means: macOS or any Linux distribution including the most popular one Ubuntu. The “terminal” commands will vary somewhat depending on what you choose for your setup, and so we will also consider the basics as to how to move around the file directories in your environment to be google-able and beyond the scope of these lessons.
    3. Installation of at least one linux text editor that is friendly for coders – ~rabsef likes Vim, so you’ll probably see some of that in the lessons – here are some options:
      • https://code.visualstudio.com/ (among the most user-friendly interfaces and includes a plugin that helps annotate Hoon code – noobies probably should start here)
      • https://www.vim.org/ (a much more spartan interface, commonly for more serious coders)
      • https://www.gnu.org/software/emacs/
      • https://atom.io/
      • There are many others – take your pick. Once you install this software on your machine where your Urbit lives, you may then finally take your baseball cap labelled “hacker” from beneath the glass dome and put it on your head.
      • Note: In some text editors, particularly on Windows, text files are saved using a different “new line” character than the unix standard and will not work in Urbit. Make sure your text editor supports “LF” newline characters.
    4. A basic understanding of what the dojo is and what the chat-client is in Urbit. Please refer to the following section titled “Intro to the Dojo” for a bit more on this. In short, the dojo and chat-client are the two types of prompts within your terminal once your Urbit is up and running. You can switch between them with Ctrl-x. In a section that follows shortly, we will get comfortable with the dojo. But for now, know that you are looking for a prompt that will show your ship’s name and then :dojo>, like this:


Note that when your urbit is “thinking” or busy, you might see something after the word dojo, or a symbol or animation other than > . In these circumstances, you usually only need to wait a bit for your ship to get current on whatever it is trying to do. If you don’t see dojo> but instead see:


then you are in the “chat client,” the other of the two command-line interfaces of your Urbit ship. The chat client is used for all of the interface commands that have to do with chats and publications. You can hit Ctrl-x to switch between your dojo and your chat client.

If you are enticed and you want to skip ahead to the section on getting comfortable with the dojo, how it works and how to do some limited Hoon coding feel free ahead to that Introduction to the Dojo section, and then come back here to continue your learning.

1.9 “Mounting” your “desk.”

This next section might be a lot, but for now, know this: you cannot see any of the files in your urbit from your Linux or Mac interface unless you “mount your desk.”

If you were to look in your urbit directory after you booted up your ship for the first time, you would find a directory that appears to be empty. The Urbit files are kept hidden because everything in Urbit is stored in a way that Unix/Linux cannot understand. To copy a version of your ship over that Unix/Linux can understand, you need to “mount” it. From within your development ship (i.e. moon as we suggested above), a mounted “Clay” (your urbit’s filesystem) “desk”. A desk is something like a hard drive or storage space, where every change is recorded and revision controlled, which is to say that Clay not only records the current state of your desk, but also every previous state and every transfer function between states.

  • To mount your desk, from dojo enter the command |mount /=home=
    > |mount /=home=

This will make a copy of your “desk” called “home,” which will then be visible from your external operating system. After you do this, when you open your file manager and navigate to the folder that is your ship, you will then see a new directory called “home.” Inside that you will see one directory called “gen” and this is where the hoon program files you write will live! There are already files in gen that do various things – we may look at some of those but, for now, just know that we will need to save files in that location, in order to run them, later. The /gen directory, within the /home directory, is your hoon coding primary location.

2.1 |commit programs so that your Urbit can “see” it

Before we move on though, you need to know that the new files you put into that gen folder are sitting in the mounted copy of your ship’s files, so they will not make it into your urbit ship until you run another command to “commit” those files to the filesystem of your ship.

  • To commit your new or altered files back into your desk, from dojo enter the command

|commit %home
> |commit %home
Each time you do this you will then see a list of the new or changed files that have been ported into your urbit ship with this command. So, even though it seems like a lot of work, every single time you make a change to a program and want to test it, you need to |commit %home before you do so. Fortunately in the dojo, if you hit the up arrow it will recall your prior commands in sequence, so if you enter |commit %home once then you can easily find it with the up arrow thereafter.

2.1.1 Introduction to the dojo: finally getting into it

We jumped the gun a bit up there regarding the dojo, so now we are going to take a step back and make sure that you are comfortable entering commands into the dojo. The dojo itself can be like a test zone for coding, and it will become your friend in terms of feeling in control of your ship and also in terms of coding with Hoon. But it can be a bit heady to understand at first. We felt that the best intro to the dojo, would be a literal friendly “intro to the dojo” in the form of a video. Please watch this fairly high-yield conversation as a 45 minute lesson that will take you where you need to go.

Introduction to the dojo video: https://www.youtube.com/watch?v=CRrW3dfD0DM

Please be sure that you understand these basic concepts as you make your way through the video – you can print this and use it as a literal checklist:

2.2 Concepts covered in the intro to dojo video:
      • Booting a fake (network disconnected, much safer for coding) ship such as a fake ~feb
      • Joining a chat
      • Seeing the “subject” for the first time and learning what the dojo’s subject is
      • How to think about the dojo in context of the dojo’s commands and in the context of hoon
      • Binding something to a face, and then cleaning up that face
      • Returning to the subject for a deeper dive: what is it?
        The subject is a potentially expandable environment, of things that are available to the computational device at the time. The dojo exists within a subject and hoon generators also exist within their own subject.
      • How to clear something out that was bound to the subject
      • Mounting and committing your urbit
      • The final line of your subject (accessed with . ) which shows you the number of hoon.hoon functions available to you in each category
      • Some items requiring parentheticals if input/arguments are required (i.e. “eny” vs “add” usage format)
      • Dojo parsing your text in real time, and how to use this to find your syntax errors
      • Some syntax differences exist between dojo and Hoon, so beware. Some single vs double space examples of this.
      • The dojo remains “open” while a function is not complete, and how to use this to determine how many children a command requires: =/ and ?: runes as examples
      • Committing files and running a generator
      • Other useful commands: Dojo commands
        • |syncs
        • +trouble
        • Ctrl-R – Search backwards in your dojo
        • Ctrl-D – Shut down urbit without sudden “kill” – more reliable way to exit your ship
        • Ctrl-Z – Kill urbit, go back to Linux terminal
        • Ctrl-X – toggle between dojo and chat client
      • Other useful commands: Chat client commands
        • Subscribe to a notebook:
          :publish|subscribe ~starorplanetname %notebook-nameOr, as an example of a great one to join with lots of information on other things to join::publish|subscribe ~wicdev-wisryt %bulletin-board
        • Subscribe to a chat:
          ;join ~/~dopzod/urbit-help

You will learn over and over again that you can do very short versions of programs using the dojo to either work out a small bit of code that has an error, or trying something to see if it will confirm your level of understanding by working as you would have predicted. The dojo is definitely your friend as you work through the nuances of learning hoon.

2.3 The “Landscape” interface: we won’t be using it

There is a beautiful and wonderful way to experience Urbit, that is via a web browser and makes chatting, notebooks and groups beautiful and easy. It’s called “Landscape” and just keeps getting better and better with each update. However, it has very little to do with coding until beyond the beginner level, so we won’t be using it or referring to it at all in this course. Everything in this course will be via the dojo prompt and urbit terminal, with some references to the file locations in your linux/mac system for files that Urbit uses.

2.3.1 Just to be sure: let’s |commit a program

If you like, let’s do a simple exercise to make sure you can write a program, save it, commit it and then use it in your dojo.

Open your text editor and save the following code as “mynumber.hoon” in your “gen” folder:
|= myname=@p
:- `@ud`myname

Note: Whether you put one or two spaces in your code matters a LOT in Hoon. Here, there are two spaces between |= (bartis) and myname=@p, as well as two spaces between :- (colhep) and `@ud`myname. Urbit can only tell the difference between spacing at one level: one space (called ace), or more than one space / new line (called gap). Many runes require specific spacing. In this case, the runes we’re using expect a “gap” (more than one space) between each of their subsequent arguments. There will be much more on this later, but as an early peek, we use some of the pronunciations for these symbols (like “gap”) which can be found here.

Back in your urbit environment, we will need to “commit” our changes (that is, update our home desk to reflect the new file we just added in the unix side of things). Use the |commit %home command to sync your changes back into your urbit. You should get output like the following:

  • > |commit %home
  • >=
  • : /~rabsef-bicrym/home/143/gen/mynumber/hoon
  • : /~rabsef-bicrym/dojo>

Once again, it’s really important (and easy to forget) that you |commit %home, after saving your .hoon file before you can run it. Your ship will be unable to see that new file you created or saved until you run that |commit % command. If you learn this early you’ll spare yourself some wasted energy trying to run programs that you forgot to commit after you made changes in their code.

Also, in urbit, just like in linux, file extensions are listed as another / in the path, so mynumber.hoon becomes mynumber/hoon in this example above. Further, the number that is listed before gen relates to the revision number for your current desk – you shouldn’t worry about this too much. If you’ve done everything right so far, you should now be able to call (run) your program. You’ll need to give it input as well. Try running this program (or “calling this generator” in Hoonspeak) using your ship’s name. Generators are called by typing + and then the name of the generator, and then a space and any input that is needed. Back in the dojo we go:

  • > +mynumber ~rabsef-bicrym
  • [ ~rabsef-bicrym]

It gives us back our ship’s name and the related number, or point, where our ship exists within the Urbit address/namespace. We’re hackers, hacking the s- out of that s-! Okay, maybe not quite yet but we are getting somewhere, and heck: you just wrote your first hoon program inside of the dojo!