@@ -0,0 +1,71 @@
2+title = "Filesystem Hierarchy"
7+Here we describe what each of the primary folders present in the `%home` `desk`
8+are used for. This organization is merely a convention, and the exact location
9+of any file does not affect its operation. That being said, some [Ford
10+runes](@/docs/arvo/ford/ford.md) are designed with this structure in mind, and
11+applications such as dojo look in specific folders for code to run. Furthermore,
12+this organization is not perfectly adhered to - sometimes you may find structure
13+definitions in `/lib`, for example.
15+ - `/app` contains userspace applications, i.e. [Gall
16+ agents](@/docs/userspace/gall/gall.md).
17+ - `/gen` contains generators. Many applications make use of generators, but
18+ also each generator in this folder may be run from dojo using `+`. For
19+ example, `/gen/foo/hoon` is run with `+foo`.
20+ - `/lib` contains libraries that may be shared by multiple agents, threads,
21+ generators, etc. However, this is not the location of the standard libraries
22+ (see `/sys`). Libraries are imported from `/lib` with `/+`.
23+ - `/mar` contains [mark](@/docs/arvo/clay/architecture.md#marks) definitions.
24+ - `/sur` contains shared [structure](@/docs/hoon/reference/rune) definitions.
25+ Whenever you expect structures to be used by code across multiple files, it
26+ is recommended to place their shared structures in `/sur`. Structures are
27+ imported from `/sur` with `/-`.
28+ - `/sys` contains the code that defines the kernel and standard libraries.
29+ `/sys/vane` contains the code for the vanes, aka kernel modules. `/sys` is
30+ the exception to the rule - structures and functions that are central to
31+ Hoon, Arvo, and its vanes, are all located within this folder rather than in
32+ `/lib` and `/sur`. See [below](#sys) for more information on `/sys`.
33+ - `/ted` contains [threads](@/docs/userspace/threads/overview.md). These may be
34+ run from dojo using `-`. For example, `/ted/foo/hoon` is run with `-foo`.
35+ - `/tests` contains unit tests intended to be run using the `test` thread. To
36+ run a particular test `+test-bar` in `/tests/foo.hoon` in dojo, enter `-test
37+ %/tests/foo/test-bar ~`. If a file is specified, every test in that file will
38+ run. If a folder is specified, every test in that folder will run.
43+`/sys` contains four files: `hoon.hoon`, `arvo.hoon`, `lull.hoon`, and
44+`zuse.hoon`. These are the files used to construct kernelspace. The chain of
45+dependencies is `hoon.hoon` -> `arvo.hoon` -> `lull.hoon` -> `zuse.hoon`. We
46+give a brief description of each of them.
47+ - `hoon.hoon` contains the Hoon compiler and the [Hoon standard
48+ library](@/docs/hoon/reference/stdlib/table-of-contents.md). The Hoon
49+ compiler is self-hosted. This is the first file loaded by the Nock virtual
50+ machine, [Vere](@/docs/vere/runtime.md), in order for it to learn how to
51+ interpret Hoon. The kelvin version number is the subject of `hoon.hoon`,
52+ currently at 140. One may see this from dojo by inspecting the subject with
53+ `.` and noting that `%140` is the final entry of the subject.
54+ - `arvo.hoon` contains the [Arvo kernel](@/docs/arvo/overview.md) and
55+ additional structures and functions directly relevant to the kernel. This is
56+ Urbit's "traffic cop", and as such contains the structure definitions for
57+ call stacks such as `duct`s and `bone`s. Once Vere understands Hoon, it loads
58+ and interprets `arvo.hoon` to create the kernel. `hoon.hoon` is the subject
60+ - `lull.hoon` primarily contains structures shared among the kernel and its
61+ vanes, as well as a few functions. In particular, this includes the
62+ definitions of the `card`s utilized by each vane, each of which are
63+ documented in their respective documentation. `lull.hoon` is loaded by the
64+ kernel during the [larval stage](@/docs/arvo/overview.md#larval-stage-core)
65+ in order to prepare to create the vanes. `arvo.hoon` is the subject of `lull.hoon`.
66+ - `zuse.hoon` is the Arvo standard library. It consists primarily of functions
67+ shared by the kernel and vanes, such as the ones related to
68+ [cryptography](@/docs/arvo/reference/cryptography.md). `zuse.hoon` is loaded
69+ by the larval kernel following `lull.hoon`. `lull.hoon` is the subject of
70+ `zuse.hoon`. Then `zuse` is the subject of the vanes.