@@ -4,34 +4,39 @@ weight = 20
4template = "doc.html"
4template = "doc.html"
7−Here we describe what each of the primary folders present in the `%home` `desk`
7+Here we describe what each of the primary folders present in a Clay desk. This
8−are used for. This organization is merely a convention, and the exact location
8+organization is merely a convention, and the exact location of any file does not
9−of any file does not affect its operation. That being said, some [Ford
9+affect its operation. That being said, some [Ford runes](/docs/arvo/ford/ford)
10−runes](/docs/arvo/ford/ford) are designed with this structure in mind, and
10+are designed with this structure in mind, and applications such as dojo and
11−applications such as dojo look in specific folders for code to run. Furthermore,
11+spider look in specific folders for code to run. Furthermore, this organization
12−this organization is not perfectly adhered to - sometimes you may find structure
12+is not perfectly adhered to - sometimes you may find structure definitions in
13−definitions in `/lib`, for example.
13+`/lib`, for example.
15- `/app` contains userspace applications, i.e. [Gall
15- `/app` contains userspace applications, i.e. [Gall
16 agents](/docs/userspace/gall/gall).
16 agents](/docs/userspace/gall/gall).
17−- `/gen` contains generators. Many applications make use of generators, but
17+- `/gen` contains generators. Many applications make use of generators, but also
18− also each generator in this folder may be run from dojo using `+`. For
18+ each generator in this folder may be run from dojo using `+`. For example,
19− example, `/gen/foo/hoon` is run with `+foo`.
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`.
20- `/lib` contains libraries that may be shared by multiple agents, threads,
21- `/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 generators, etc. However, this is not the location of the standard libraries
22 (see `/sys`). Libraries are imported from `/lib` with `/+`.
23 (see `/sys`). Libraries are imported from `/lib` with `/+`.
23−- `/mar` contains [mark](/docs/arvo/clay/architecture#marks) definitions.
24+- `/mar` contains [mark](/docs/arvo/clay/marks/marks) definitions.
24- `/sur` contains shared [structure](/docs/hoon/reference/rune/) definitions.
25- `/sur` contains shared [structure](/docs/hoon/reference/rune/) definitions.
25− Whenever you expect structures to be used by code across multiple files, it
26+ Whenever you expect structures to be used by code across multiple files, it is
26− is recommended to place their shared structures in `/sur`. Structures are
27+ recommended to place their shared structures in `/sur`. Structures are
27 imported from `/sur` with `/-`.
28 imported from `/sur` with `/-`.
28−- `/sys` contains the code that defines the kernel and standard libraries.
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
29− `/sys/vane` contains the code for the vanes, aka kernel modules. `/sys` is
32+ the code for the vanes, aka kernel modules. `/sys` is the exception to the
30− the exception to the rule - structures and functions that are central to
33+ rule - structures and functions that are central to Hoon, Arvo, and its vanes,
31− Hoon, Arvo, and its vanes, are all located within this folder rather than in
34+ are all located within this folder rather than in `/lib` and `/sur`. See
32− `/lib` and `/sur`. See [below](#sys) for more information on `/sys`.
35+ [below](#sys) for more information on `/sys`.
33−- `/ted` contains [threads](/docs/userspace/threads/overview). These may be
36+- `/ted` contains [threads](/docs/userspace/threads/overview). These may be run
34− run from dojo using `-`. For example, `/ted/foo/hoon` is run with `-foo`.
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`.
35- `/tests` contains unit tests intended to be run using the `test` thread. To
40- `/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 %/tests/foo/test-bar ~`. If a file is specified, every test in that file will
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
37 run. If a folder is specified, every test in that folder will run.
42 run. If a folder is specified, every test in that folder will run.
@@ -39,9 +44,10 @@ definitions in `/lib`, for example.
39## `/sys` {#sys}
44## `/sys` {#sys}
41`/sys` contains four files: `hoon.hoon`, `arvo.hoon`, `lull.hoon`, and
46`/sys` contains four files: `hoon.hoon`, `arvo.hoon`, `lull.hoon`, and
42−`zuse.hoon`. These are the files used to construct kernelspace. The chain of
47+`zuse.hoon`. These are the files used to construct kernelspace. Only the `%base`
48+desk contains these files, other desks omit the `/sys` directory and instead
43−dependencies is `hoon.hoon` -> `arvo.hoon` -> `lull.hoon` -> `zuse.hoon`. We
49+just depend on `%base`. The chain of dependencies is `hoon.hoon` -> `arvo.hoon`
44−give a brief description of each of them.
50+-> `lull.hoon` -> `zuse.hoon`. We give a brief description of each of them.
46- `hoon.hoon` contains the Hoon compiler and the [Hoon standard
52- `hoon.hoon` contains the Hoon compiler and the [Hoon standard
47 library](/docs/hoon/reference/stdlib/table-of-contents). The Hoon
53 library](/docs/hoon/reference/stdlib/table-of-contents). The Hoon
@@ -58,12 +64,40 @@ give a brief description of each of them.
58 of `arvo.hoon`.
64 of `arvo.hoon`.
59- `lull.hoon` primarily contains structures shared among the kernel and its
65- `lull.hoon` primarily contains structures shared among the kernel and its
60 vanes, as well as a few functions. In particular, this includes the
66 vanes, as well as a few functions. In particular, this includes the
61− definitions of the `card`s utilized by each vane, each of which are
67+ definitions of the `task`s and `gift`s utilized by each vane, each of which
62− documented in their respective documentation. `lull.hoon` is loaded by the
68+ are documented in their respective documentation. `lull.hoon` is loaded by the
63− kernel during the [larval stage](/docs/arvo/overview#larval-stage-core)
69+ kernel during the [larval stage](/docs/arvo/overview#larval-stage-core) in
64− in order to prepare to create the vanes. `arvo.hoon` is the subject of `lull.hoon`.
70+ order to prepare to create the vanes. `arvo.hoon` is the subject of
65- `zuse.hoon` is the Arvo standard library. It consists primarily of functions
72- `zuse.hoon` is the Arvo standard library. It consists primarily of functions
66 shared by the kernel and vanes, such as the ones related to
73 shared by the kernel and vanes, such as the ones related to
67− [cryptography](/docs/arvo/reference/cryptography). `zuse.hoon` is loaded
74+ [cryptography](/docs/arvo/reference/cryptography). `zuse.hoon` is loaded by
68− by the larval kernel following `lull.hoon`. `lull.hoon` is the subject of
75+ the larval kernel following `lull.hoon`. `lull.hoon` is the subject of
69− `zuse.hoon`. Then `zuse` is the subject of the vanes.
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).
81+A desk is an independently revision-controlled branch of a ship that uses the
82+Clay filesystem. Each desk contains its own apps, mark definitions, files, and
83+so forth. The basic filesystem structure is the same for all desks, with the
84+exception that only the `%base` desk contains a [`/sys`](#sys) directory.
85+Additionally, there are a handful of special files related to the management of
86+desks 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.
102+For more details of creating and distributing desks, see the
103+[Distribution](/docs/userspace/dist/dist) documentation.