@@ -4,34 +4,39 @@ weight = 20
44template = "doc.html"
55+++
66
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) 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.
7+Here we describe what each of the primary folders present in a Clay desk. This
8+organization is merely a convention, and the exact location of any file does not
9+affect its operation. That being said, some [Ford runes](/docs/arvo/ford/ford)
10+are designed with this structure in mind, and applications such as dojo and
11+spider look in specific folders for code to run. Furthermore, this organization
12+is not perfectly adhered to - sometimes you may find structure definitions in
13+`/lib`, for example.
1414
1515- `/app` contains userspace applications, i.e. [Gall
1616 agents](/docs/userspace/gall/gall).
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`.
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`.
2021- `/lib` contains libraries that may be shared by multiple agents, threads,
2122 generators, etc. However, this is not the location of the standard libraries
2223 (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.
2425- `/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
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
2728 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). These may be
34− run from dojo using `-`. For example, `/ted/foo/hoon` is run with `-foo`.
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`.
3540- `/tests` contains unit tests intended to be run using the `test` thread. To
3641 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
3742 run. If a folder is specified, every test in that folder will run.
@@ -39,9 +44,10 @@ definitions in `/lib`, for example.
3944## `/sys` {#sys}
4045
4146`/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
43−dependencies is `hoon.hoon` -> `arvo.hoon` -> `lull.hoon` -> `zuse.hoon`. We
44−give a brief description of each of them.
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
49+just 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.
4551
4652- `hoon.hoon` contains the Hoon compiler and the [Hoon standard
4753 library](/docs/hoon/reference/stdlib/table-of-contents). The Hoon
@@ -58,12 +64,40 @@ give a brief description of each of them.
5864 of `arvo.hoon`.
5965- `lull.hoon` primarily contains structures shared among the kernel and its
6066 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
62− documented in their respective documentation. `lull.hoon` is loaded by the
63− kernel during the [larval stage](/docs/arvo/overview#larval-stage-core)
64− in order to prepare to create the vanes. `arvo.hoon` is the subject of `lull.hoon`.
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
71+ `lull.hoon`.
6572- `zuse.hoon` is the Arvo standard library. It consists primarily of functions
6673 shared by the kernel and vanes, such as the ones related to
67− [cryptography](/docs/arvo/reference/cryptography). `zuse.hoon` is loaded
68− by the larval kernel following `lull.hoon`. `lull.hoon` is the subject of
69− `zuse.hoon`. Then `zuse` is the subject of the vanes.
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).
78+
79+## Desks
80+
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:
87+
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.
101+
102+For more details of creating and distributing desks, see the
103+[Distribution](/docs/userspace/dist/dist) documentation.