A publisher has sovereign control over its “org tree”, and is therefore free to organize it as it sees fit. However, as keeping the tree's structure constant over time is important, certain conventions that have been found to work well are worth documenting. The rest of this section is about these best practices.

Overall structure

The suggested top-level structure for the tree is as follows.

/org/publisher/bin/         architecture-dependent commands, i.e. binaries
/org/publisher/doc/         documentation
/org/publisher/lib/         program libraries
/org/publisher/man/         man pages (in *roff format)
/org/publisher/src/         program source code

/org/publisher/cmd/         architecture-independent commands (scripts, jackets, symlinks)
/org/publisher/proto/       prototypes of svc instance directories
/org/publisher/shared/      svc implementation directories (files shared between instances)
/org/publisher/private/     stuff that shouldn't be referred to from outside the tree

/org/publisher/etc/         administrative metadata and dangerous maintenance utilities for the tree
/org/publisher/pkg/         package management information for the tree

/org/publisher/tmp/         used when running in a chroot jail

Not every org tree necessarily needs all the above directories, but unless there is a good reason to deviate from this general structure, it is probably best to follow this naming scheme for the directories that are present.

In the above list, the first group of directories (bin, doc, lib, man and src) implement the classic type-oriented organization model. These directories are used like their traditional Unix counterparts (but see “Host independence” below). The second group of directories (cmd, proto, shared and private) implement a new object-oriented organization model. The third group of directories (etc and pkg) are used for meta information and maintenance utilities for the tree.

Host independence

An org tree is meant to be host independent. This does not just mean host instance independence, but also operating system independence and CPU independence. The tree does not have to include compiled executables for every imaginable machine architecture, but it needs to be organized in such a way that it theoretically could. This means no reuse of pathnames.

The suggested way to achieve this is to use a GNU style configuration name as a pathname component wherever the pathname would otherwise have to be reused.


Support for chrooted execution

If the org tree includes unsecure software, i.e. software for which the source code has not been published, or software whose security status has been questioned, it needs to be able to function in a chroot jail.

To be chroot ready, the tree needs to be 100% self-contained, and all absolute pathname references must assume the root of the filesystem is /org/publisher/.

Communication with the outside world happens through pipes (set up by the forking process) or through the directory /org/publisher/tmp/ (or /tmp/ when viewed from inside the chroot jail).

Software package management

The /org/publisher/pkg/ directory can be used to store meta data about the tree. The format of files in the directory is discussed in a separate article.