2title = "Filesystem Hierarchy"
7Here we describe what each of the primary folders present in a Clay desk. This
8organization is merely a convention, and the exact location of any file does not
9affect its operation. That being said, some [Ford runes](/docs/arvo/ford/ford)
10are designed with this structure in mind, and applications such as dojo and
11spider look in specific folders for code to run. Furthermore, this organization
12is not perfectly adhered to - sometimes you may find structure definitions in
15- `/app` contains userspace applications, i.e. [Gall
16 agents](/docs/arvo/gall/gall).
17- `/gen` contains generators. Many applications make use of generators, but also
18 each generator in this folder may be run from dojo using `+`. For example,
19 `/gen/foo/hoon` in the `%base` desk is run with `+foo`. Generators on desks
20 other than `%base` can be run with `+desk!generator` like `+garden!foo`.
21- `/lib` contains libraries that may be shared by multiple agents, threads,
22 generators, etc. However, this is not the location of the standard libraries
23 (see `/sys`). Libraries are imported from `/lib` with `/+`.
24- `/mar` contains [mark](/docs/arvo/clay/marks/marks) definitions.
25- `/sur` contains shared [structure](/docs/hoon/reference/rune/) definitions.
26 Whenever you expect structures to be used by code across multiple files, it is
27 recommended to place their shared structures in `/sur`. Structures are
28 imported from `/sur` with `/-`.
29- `/sys` contains the code that defines the kernel and standard libraries. Note
30 that only the `%base` desk should contain these `/sys` files, other desks
31 omit the directory and instead just depend on `%base`. `/sys/vane` contains
32 the code for the vanes, aka kernel modules. `/sys` is the exception to the
33 rule - structures and functions that are central to Hoon, Arvo, and its vanes,
34 are all located within this folder rather than in `/lib` and `/sur`. See
35 [below](#sys) for more information on `/sys`.
36- `/ted` contains [threads](/docs/userspace/threads/overview). These may be run
37 from dojo using `-`. For example, `/ted/foo/hoon` on the `%base` desk is run
38 with `-foo`. Threads on desks other than the `%base` desk can be run with
39 `-desk!thread` like `-garden!foo`.
40- `/tests` contains unit tests intended to be run using the `test` thread. To
41 run a particular test `+test-bar` in `/tests/foo.hoon` in dojo, enter `-test %/tests/foo/test-bar ~`. If a file is specified, every test in that file will
42 run. If a folder is specified, every test in that folder will run.
46`/sys` contains four files: `hoon.hoon`, `arvo.hoon`, `lull.hoon`, and
47`zuse.hoon`. These are the files used to construct kernelspace. Only the `%base`
48desk contains these files, other desks omit the `/sys` directory and instead
49just depend on `%base`. The chain of dependencies is `hoon.hoon` -> `arvo.hoon`
50-> `lull.hoon` -> `zuse.hoon`. We give a brief description of each of them.
52- `hoon.hoon` contains the Hoon compiler and the [Hoon standard
53 library](/docs/hoon/reference/stdlib/table-of-contents). The Hoon
54 compiler is self-hosted. This is the first file loaded by the Nock virtual
55 machine, [Vere](/docs/vere/runtime), in order for it to learn how to
56 interpret Hoon. The kelvin version number is the subject of `hoon.hoon`,
57 currently at 140. One may see this from dojo by inspecting the subject with
58 `.` and noting that `%140` is the final entry of the subject.
59- `arvo.hoon` contains the [Arvo kernel](/docs/arvo/overview) and
60 additional structures and functions directly relevant to the kernel. This is
61 Urbit's "traffic cop", and as such contains the structure definitions for
62 call stacks such as `duct`s and `bone`s. Once Vere understands Hoon, it loads
63 and interprets `arvo.hoon` to create the kernel. `hoon.hoon` is the subject
65- `lull.hoon` primarily contains structures shared among the kernel and its
66 vanes, as well as a few functions. In particular, this includes the
67 definitions of the `task`s and `gift`s utilized by each vane, each of which
68 are documented in their respective documentation. `lull.hoon` is loaded by the
69 kernel during the [larval stage](/docs/arvo/overview#larval-stage-core) in
70 order to prepare to create the vanes. `arvo.hoon` is the subject of
72- `zuse.hoon` is the Arvo standard library. It consists primarily of functions
73 shared by the kernel and vanes, such as the ones related to
74 [cryptography](/docs/arvo/reference/cryptography). `zuse.hoon` is loaded by
75 the larval kernel following `lull.hoon`. `lull.hoon` is the subject of
76 `zuse.hoon`. Then `zuse` is the subject of the vanes. Some of the functions in
77 Zuse are documented [here](/docs/hoon/reference/zuse/table-of-contents).
81A desk is an independently revision-controlled branch of a ship that uses the
82Clay filesystem. Each desk contains its own apps, mark definitions, files, and
83so forth. The basic filesystem structure is the same for all desks, with the
84exception that only the `%base` desk contains a [`/sys`](#sys) directory.
85Additionally, there are a handful of special files related to the management of
86desks and their Gall agents:
88- `sys.kelvin` - This specifies the version of Arvo the desk is compatible with.
89 This file is mandatory in all desks.
90- `desk.bill` - This file specifies the Gall agents on a desk which should be
91 automatically started when it's installed. This file may be omitted if there
92 are no agents to start.
93- `desk.docket-0` - This file configures the tile,
94 [glob](/docs/userspace/dist/glob) and other metadata for apps with a
95 front-end. This file may be omitted if the desk does not have a tile or
96 front-end to be installed. This file is versioned so the number appended may
97 change in the future as changes to its specification are made. See the [Docket
98 File](/docs/userspace/dist/docket) documentation for more details.
99- `desk.ship` - This specifies the original publisher of the desk and is useful
100 if a desk is being republished. It is optional and may be omitted.
102For more details of creating and distributing desks, see the
103[Distribution](/docs/userspace/dist/dist) documentation.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list