Here we describe what each of the primary folders present in a Clay desk. This
organization is merely a convention, and the exact location of any file does not
affect its operation. That being said, some Ford runes
are designed with this structure in mind, and applications such as dojo and
spider look in specific folders for code to run. Furthermore, this organization
is not perfectly adhered to - sometimes you may find structure definitions in
/lib, for example.
/appcontains userspace applications, i.e. Gall agents.
/gencontains generators. Many applications make use of generators, but also each generator in this folder may be run from dojo using
+. For example,
%basedesk is run with
+foo. Generators on desks other than
%basecan be run with
/libcontains libraries that may be shared by multiple agents, threads, generators, etc. However, this is not the location of the standard libraries (see
/sys). Libraries are imported from
/marcontains mark definitions.
/surcontains shared structure definitions. Whenever you expect structures to be used by code across multiple files, it is recommended to place their shared structures in
/sur. Structures are imported from
/syscontains the code that defines the kernel and standard libraries. Note that only the
%basedesk should contain these
/sysfiles, other desks omit the directory and instead just depend on
/sys/vanecontains the code for the vanes, aka kernel modules.
/sysis the exception to the rule - structures and functions that are central to Hoon, Arvo, and its vanes, are all located within this folder rather than in
/sur. See below for more information on
/tedcontains threads. These may be run from dojo using
-. For example,
%basedesk is run with
-foo. Threads on desks other than the
%basedesk can be run with
/testscontains unit tests intended to be run using the
testthread. To run a particular test
/tests/foo.hoonin dojo, enter
-test %/tests/foo/test-bar ~. If a file is specified, every test in that file will run. If a folder is specified, every test in that folder will run.
/sys contains four files:
zuse.hoon. These are the files used to construct kernelspace. Only the
desk contains these files, other desks omit the
/sys directory and instead
just depend on
%base. The chain of dependencies is
zuse.hoon. We give a brief description of each of them.
hoon.hooncontains the Hoon compiler and the Hoon standard library. The Hoon compiler is self-hosted. This is the first file loaded by the Nock virtual machine, Vere, in order for it to learn how to interpret Hoon. The kelvin version number is the subject of
hoon.hoon, currently at 140. One may see this from dojo by inspecting the subject with
.and noting that
%140is the final entry of the subject.
arvo.hooncontains the Arvo kernel and additional structures and functions directly relevant to the kernel. This is Urbit's "traffic cop", and as such contains the structure definitions for call stacks such as
bones. Once Vere understands Hoon, it loads and interprets
arvo.hoonto create the kernel.
hoon.hoonis the subject of
lull.hoonprimarily contains structures shared among the kernel and its vanes, as well as a few functions. In particular, this includes the definitions of the
gifts utilized by each vane, each of which are documented in their respective documentation.
lull.hoonis loaded by the kernel during the larval stage in order to prepare to create the vanes.
arvo.hoonis the subject of
zuse.hoonis the Arvo standard library. It consists primarily of functions shared by the kernel and vanes, such as the ones related to cryptography.
zuse.hoonis loaded by the larval kernel following
lull.hoonis the subject of
zuseis the subject of the vanes. Some of the functions in Zuse are documented here.
A desk is an independently revision-controlled branch of a ship that uses the
Clay filesystem. Each desk contains its own apps, mark definitions, files, and
so forth. The basic filesystem structure is the same for all desks, with the
exception that only the
%base desk contains a
Additionally, there are a handful of special files related to the management of
desks and their Gall agents:
sys.kelvin- This specifies the version of Arvo the desk is compatible with. This file is mandatory in all desks.
desk.bill- This file specifies the Gall agents on a desk which should be automatically started when it's installed. This file may be omitted if there are no agents to start.
desk.docket-0- This file configures the tile, glob and other metadata for apps with a front-end. This file may be omitted if the desk does not have a tile or front-end to be installed. This file is versioned so the number appended may change in the future as changes to its specification are made. See the Docket File documentation for more details.
desk.ship- This specifies the original publisher of the desk and is useful if a desk is being republished. It is optional and may be omitted.
For more details of creating and distributing desks, see the Distribution documentation.