@@ -0,0 +1,121 @@
1++++
2+title = "1.1 Introduction"
3+weight = 1
4+template = "doc.html"
5+aliases = ["/docs/learn/hoon/hoon-tutorial/setup/"]
6++++
7+
8+This series is designed to teach you Hoon without assuming you have an extensive
9+programming background. In fact, you should be able to follow much of it even if
10+you have no programming experience at all, though of course experience helps. We
11+strongly encourage you to try out all the examples of each lesson. These lessons
12+are meant for the beginner, but they aren't meant to be skimmed. Each lesson
13+falls into one of two categories: **readings**, which are prose-heavy
14+explanations of Hoon fundamentals, and **walkthroughs**, which are line-by-line
15+explanations of example programs. Walkthroughs are found between readings,
16+offering a practical implementation of the concepts taught in the reading
17+before.
18+
19+If you're curious about why Urbit is written in this new language, we recommend
20+reading the [Hoon overview](/docs/hoon/overview) that covers the high-level
21+design decisions behind the language.
22+
23+Chapter 1 introduces and explains the fundamental concepts you need in order to
24+understand Hoon's semantics.
25+
26+Hoon is a "subject-oriented" programming language — every expression of
27+Hoon is evaluated relative to a **subject**. The subject is a piece of data that
28+represents the environment, or the context, of an expression. After reading
29+Chapter 1 you should understand what the subject is and how to refer to its
30+various parts. In this chapter you'll also learn about
31+**[cores](/docs/glossary/core/)**, which are an important data structure in
32+Hoon. Once you get the hang of [cores](/docs/glossary/core/) you'll be able to
33+write your own functions in Hoon.
34+
35+Chapter 2 covers the type system, writing basic apps, and the workings of the
36+Arvo kernel.
37+
38+## Environment Setup
39+
40+Before beginning, you'll need to get a development ship running and configure an
41+appropriate editor. See the [Environment Setup](/docs/development/environment)
42+guide for details.
43+
44+## Getting started
45+
46+Once 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:
47+
48+```
49+fake: ~zod
50+ames: czar: ~zod on 31337 (localhost only)
51+http: live (insecure, public) on 80
52+http: live (insecure, loopback) on 12321
53+> (add 2 2)
54+4
55+~zod:dojo>
56+```
57+
58+You just used a function from the Hoon standard library, `add`. Next, quit Urbit
59+with `ctrl-d`:
60+
61+```
62+> (add 2 2)
63+4
64+~zod:dojo>
65+$
66+```
67+
68+Your ship isn't running anymore and you're back at your computer's normal
69+terminal prompt. If your ship is `~zod`, then you can restart the ship by
70+typing:
71+
72+```sh
73+urbit zod
74+```
75+
76+## Another Noun
77+
78+You've already used a standard library function to produce one value, in the
79+Dojo. Now that your ship is running again, let's try another. Enter the number
80+`17`.
81+
82+We won't show the `~zod:dojo> ` prompt from here on out. We'll just show the
83+echoed command along with its result.
84+
85+You'll see:
86+
87+```
88+> 17
89+17
90+```
91+
92+You asked Dojo to evaluate `17` and it echoed the number back at you. This value
93+is a "noun". We'll talk more about [nouns](/docs/glossary/noun/) in [Lesson
94+1.2](/docs/hoon/hoon-school/nouns), but first let's write a very basic program.
95+
96+## Generators
97+
98+Generators are the most straightforward way to write Hoon programs. They are a
99+concept in Arvo, and involve saving Hoon code in a `.hoon` text file. While they
100+aren't strictly part of the Hoon language, we'll be dealing with generators
101+throughout this tutorial.
102+
103+The simplest type of generator is the **naked generator**. All naked generators
104+are `gates`: functions that take an argument and produce an output. To create a
105+generator, all you need to do is write a `gate`, save it in a `.hoon` file, and
106+add it to the `/gen` directory of a desk on your ship.
107+
108+To be able to add files easily, you'll need to mount a desk to the Unix
109+filesystem. We'll use the `%base` desk throughout Hoon School since we're using
110+a fake ship, but note a different one would be more suitable on a live ship. To
111+mount `%base`, just run `|mount %base` in the dojo. If you look in your
112+[pier](/glossary/pier), you should now see a `base` folder. Once you've added
113+the `.hoon` file in `base/gen`, you'll need to run `|commit %base` in the dojo
114+so the new file is recognised by your ship. To run a generator named
115+`mygen.hoon`, you would type `+mygen <argument>` in your ship's dojo. If you
116+added it to a desk other than `%base`, you can run `+desk!mygen <argument>`
117+where `desk` is the desk you put it in.
118+
119+If this doesn't make sense yet, that's okay. In the [next
120+lesson](/docs/hoon/hoon-school/list-of-numbers), we will walk you through an
121+example `gate` that is run as a generator.