git.iko.soy/urbit.org
on 7ea7fa5 help sign in
urbit.org/tutorials/hoon/setup.md
107 lines 6.6 kB history raw
1+++
2title = "1.1 Setup"
3weight = 1
4template = "doc.html"
5aliases = ["/docs/learn/hoon/hoon-tutorial/setup/"]
6+++
8Before 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.
10## What is an urbit?
12An **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`.
14These 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.
16## Installing Urbit
18You can install Urbit on any Mac or Unix machine; if you're just trying out Urbit or creating a development ship, you can follow the steps for creating a development ship [here](@/using/develop.md#creating-a-development-ship). On Windows, make a virtual Linux machine using VirtualBox or a similar tool.
21Once you're finished, you can [boot your very own ship](@/using/install.md#booting-your-ship). While you can develop in Hoon on your own ship on the live network, we strongly suggest developing on a development ship first.
23## Getting started
25Once you've created your development ship, let's try a basic command. Type `(add 2 2)` at the prompt and hit return. Your screen now shows:
27```
28fake: ~zod
29ames: czar: ~zod on 31337 (localhost only)
30http: live (insecure, public) on 80
31http: live (insecure, loopback) on 12321
32> (add 2 2)
34~zod:dojo>
35```
37You just used a function from the Hoon standard library, `add`. Next, quit Urbit with `ctrl-d`:
39```
40> (add 2 2)
42~zod:dojo>
44```
46Your ship isn't running anymore and you're back at your computer's normal terminal prompt. If your ship is `~zod`, then you can restart the ship by typing:
48```sh
49urbit zod
50```
52## Another Noun
54You've already used a standard library function to produce one value, in the dojo. Now that your ship is running again, let's try another. Enter the number `17`.
56> We won't show the `~zod:dojo> ` prompt from here on out. We'll just show the echoed command along with its result.
58You'll see:
60```
61> 17
6217
63```
65You asked dojo to evaluate `17` and it echoed the number back at you. This value is a 'noun'. We'll talk more about [nouns](/docs/glossary/noun/) in [Lesson 1.2](@/docs/tutorials/hoon/nouns.md), but first let's write a very basic program.
67## Generators
69Generators 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.
71The simplest type of generator is the **naked generator**. All naked generators are `gates`: functions that take an argument and produce an output. Before creating generator you need to mount your `desk` to Unix, for 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. (Assuming you've already mounted with `|mount /=home=`.) After this, you need to run `|commit %home` in dojo and the new file will be recognized by your ship. To run a generator named `mygen.hoon`, you would type `+mygen <argument>` in your ship's Dojo.
73If this doesn't make sense yet, that's okay. In the [next lesson](@/docs/tutorials/hoon/list-of-numbers.md), we will walk you through an example `gate` that is run as a generator.
75## Text editors
77Writing code in any language is typically done using a text editor, but common programs like Notepad, Microsoft Word, or OpenOffice Writer are not suitable for programming. You'll want instead a text editor that is specifically designed for writing code. This will assist with things such as colorizing keywords, finding patterns, matching parentheses and brackets, etc.
79Below is a complete list of text editors that have support for Hoon [syntax highlighting](https://en.wikipedia.org/wiki/Syntax_highlighting) -- an important tool for any programming language. For each of these editors, you'll need to download the editor and then you'll need to install some additional syntax-highlighter package. The process for adding Hoon support differs for every editor. For most newbie-friendly text editors, this is easily accomplished from within the editor itself, and you'll learn how to do so following a newbie tutorial for that editor.
81If you are brand new to programming, don't think too much about which editor to use; any of the newbie-friendly options will suit you.
83### Newbie-friendly text editors
85These editors are easy to use for first-time coders.
87#### Atom
88Atom 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`.
90#### Sublime
91Sublime 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/).
93#### Visual Studio Code
94Visual 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`.
96### Advanced text editors
98These text editors have a high learning curve and are only recommended for experienced programmers.
100#### Emacs
102Emacs 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).
104#### Vim
106Vim 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) and is maintained by Tlon.