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.
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
*roffformat) /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
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
a new object-oriented organization model.
The third group of directories (
pkg) are used for
meta information and maintenance utilities for the tree.
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.
/org/publisher/bin/i386-pc-linux-gnu/xyzzy /org/publisher/bin/rs6000-ibm-aix3.2/xyzzy /org/publisher/bin/sparc-sun-solaris2.7/xyzzy
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
Communication with the outside world happens through pipes
(set up by the forking process) or through the directory
/tmp/ when viewed
from inside the chroot jail).
Software package management
/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.