git.iko.soy/urbit.org
on ed43ffa help sign in
urbit.org/learn/hoon/hoon-tutorial/setup.md
119 lines 5.7 kB history raw
1+++
2title = "1.1 Setup"
3weight = 1
4template = "doc.html"
5+++
6Before we begin working on Hoon, you should first (1) have Urbit installed and (2) boot a ship that you can use for trying out Hoon examples. Interactive learning is far superior to passive reading.
8## Installing Urbit
10You can install Urbit on any Mac or Unix machine; follow the steps for [creating a development ship](/docs/using/creating-a-development-ship). On Windows, make a virtual Linux machine using VirtualBox or a similar tool.
12Once you're finished you can boot your very own ship.
14## What is an urbit?
16An **urbit** is an Urbit virtual computer with persistent state that can connect to the Urbit network. (Note the lowercase 'u' here. 'Urbit' is the entire software stack, whereas 'an urbit' is a local instance.) Each urbit is associated with a unique number that plays three distinct roles: (1) it's an address on the Urbit network, (2) it's a cryptographic identity, and (3) it's (in principle) a human memorable name. Normally an urbit's name is represented as a string starting with `~`, as in `~zod` or `~taglux-nidsep`.
18These may not look like numbers, but they are. Each urbit name is written in a base-256 format, where each 'digit' is a syllable. Imagine your phone number as a pronounceable string which sounds like a name in a foreign language. An ordinary user-level urbit is a 'planet', and it's named by a 32-bit number. The latter is represented as a four-syllable string; e.g., the planet name `~taglux-nidsep` is the number 6,095,360.
20For this tutorial you'll boot and run what we call a 'comet'. **Comets** are urbits whose names are 128-bits or 16 syllables, such as:
22`~hillyn-pitwet-hasdur-paswer--miszod-rabpex-divrup-fogdur`
24Comet names aren't quite as memorable as others, but they're disposable identities that anyone can make for free to join the live network. Thus, comets make the ideal urbit for playing around with Hoon, asking for help from other Urbit devs in [Talk](./docs/using/messaging.md) if you need it, and showing off Urbit to your friends.
26## Booting a Comet
28To boot your comet, go into the command line and run the following command from the directory that was created during Urbit installation:
30```
31$ urbit -c mycomet
32```
34This will take a few minutes and will spin out a bunch of boot messages. Toward the end, you'll see something like:
36```
37ames: on localhost, UDP 31337.
38http: live (insecure, public) on 8080
39http: live ("secure", public) on 8443
40http: live (insecure, loopback) on 12321
41~palnul_nocser:dojo>
42```
44(There will likely be other messages as well.)
46Look at the prompt, `~palnul_nocser:dojo>`. To the left of the `:` you'll see an abbreviation of the comet name you just booted, `~palnul_nocser` in this case. To the right is the name of a local application, `dojo`. **Dojo** is the Urbit command line app; it's also a Hoon [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) we'll use to run simple Hoon examples.
48To make sure everything is working, type `(add 2 2)` at the prompt and hit return. Your screen now shows:
50```
51ames: on localhost, UDP 31337.
52http: live (insecure, public) on 8080
53http: live ("secure", public) on 8443
54http: live (insecure, loopback) on 12321
55> (add 2 2)
57~palnul_nocser:dojo>
58```
60You just used a function from the Hoon standard library, `add`. Next, quit Urbit with `ctrl-d`:
62```
63> (add 2 2)
65~palnul_nocser:dojo>
67```
69Your comet isn't running anymore and you're back at your computer's normal terminal prompt. You now have a `mycomet` directory for your Urbit comet; this directory is your comet's **pier** and it contains the entirety of your comet's state.
71Right now the only thing in your pier is your comet's system files:
73```
74$ ls -a /path/to/mycomet
75./ ../ .urb/
76```
78Restarting your already-created comet from the terminal is like creating a new one, but without the `-c` flag. (The `-c` is for "create".)
80```
81$ urbit mycomet
82```
84Because the comet has already been booted it won't take very long to get it running again. There are also fewer startup messages:
86```
87$ urbit mycomet
88[...]
89ames: on localhost, UDP 31337.
90http: live (insecure, public) on 8080
91http: live ("secure", public) on 8443
92http: live (insecure, loopback) on 12321
93~palnul_nocser:dojo>
94```
96## Another Noun
98You've already used a standard library function to produce one value, in the dojo. Now that your comet is running again, let's try another. Enter the number `17`.
100> We won't show the `~palnul_nocser:dojo> ` prompt from here on out. We'll just show the echoed command along with its result.
102You'll see:
104```
105> 17
10617
107```
109You asked dojo to evaluate `17` and it echoed the number back at you. This value is a 'noun'. But what is a noun? Move on to lesson 1.2 for the answer.
111## Generators
113Generators are the most straightforward way to write Hoon programs. They are a concept in Arvo, and involve saving Hoon code in a `.hoon` text file. While they aren't strictly part of the Hoon language, we'll be dealing with generators throughout this tutorial.
115The simplest type of generator is the **naked generator**. All naked generators are `gates`: functions that take an argument and produce an output. So, to create a generator, all you need to do is write a `gate` and put it into a file in the `/home/gen` directory of your ship as a `.hoon` file. To run a generator named `mygen.hoon`, you would type `+myhoon <argument>` in your ship's Dojo.
117If this doesn't make sense yet, that's okay. In the next lesson, we will walk you through an example `gate` that is run as a generator.
119### [Next Up: Walkthrough -- List of Numbers](../list-of-numbers)