source: trunk/debathena/debathena/dotfiles/lockers.7 @ 25115

.TH LOCKERS 7 "22 April 2011"
.ds ]W MIT Athena
.SH NAME
lockers -- description of Athena locker organization conventions
.SH DESCRIPTION

There are many possible ways to provide binaries for multiple
architectures with some form of
organization under a single filesystem.
Athena suggests and supports a particular convention for doing this.

The primary purpose of this convention is to provide a standard way of
separating machine-dependent binaries into different directories for
ease of use and maintenance.
Generality, backwards compatibility, and
neatness are also considered.

.SH MACHINE-DEPENDENT FILES

In order to avoid clutter in the top-level directory of a
locker, all machine-dependent directories are placed under a
common directory \fIarch\fR.
Under \fIarch\fR there is one directory for each
supported platform, named after the AFS "@sys" values (amd64_deb40,
sun4x_510, etc\.).
Under each sysname's directory are subdirectories
containing specific types of machine-dependent data, such as binaries
or libraries (bin, lib, etc\.).

For example, a locker containing libraries and binaries might look
like:

/mit/locker/arch/
                 amd64_deb40/
                          bin/
                          lib/
                 i386_ubuntu1004/
                          bin/
                          lib/
                 sun4x_510/
                          bin/
                          lib/
                 i386_rhel4/
                          bin/
                          lib/

Possible machine-dependent subdirectories include bin, lib, etc,
man, and build.

Note that due to the fact there is binary compatibility across
multiple AFS "@sys" values, there will also be many symbolic links:

/mit/locker/arch/
                 sun4x_510 -> sun4x_59
                 i386_deb50 -> i386_deb40

Note also that the string "@sys" should never be used literally
(in Makefiles or scripts)
except for the convenience symlinks described below; the string
"$ATHENA_SYS" should be used instead.
Further details appear below.

.SH MACHINE-INDEPENDENT FILES

Many files, such as manual pages or data files, may be the same for
all machine architectures.
Currently, the only defined convention for
such files applies only to manual pages.
That convention is simply
that in the top-level directory of a locker the "man"
directory contains the manual pages, in agreement with the
conventions for most flavors of Unix.

Note that the \fIadd\fR command supports the possibility of
machine-specific manual pages when modifying the MANPATH, in that it
first checks for the existence of the directory arch/@sys/man before
falling back to a man directory in the root of the locker.

.SH CONVENIENCE SYMLINKS

The \fIadd\fR
command is the standard way for users to find the appropriate
binary for their platform, but some users prefer to
not use \fIadd\fR
and type explicit paths on their own.
When the correct binary is located in
/mit/lockername/arch/amd64_ubuntu1010/bin
this proves tedious.
For these users' convenience, it is recommended to make
a symbolic link "bin -> arch/@sys/bin" and possibly
others (for lib, etc\.) as it makes sense.
This is the \fIonly\fR case
where it makes sense to use the explicit string "@sys".
Even so, this symbolic link is not needed for normal operation of
\fIadd\fR, it is merely for the convenience of users.
Further details regarding the non-recommendation of "@sys"
appear at the end of section \fIUSER SUPPORT\fR.

.SH BACKWARDS COMPATIBILITY AND BINARY LAYOUT

The previous file layout conventions included only standards for
binary and manual directories, with no suggestions for how to
arrange directories and avoid clutter.
The main convention was that the
output from
\fImachtype\fR(1) be used to generate a binary directory
for a given platform, e.g. `machtype`bin (decmipsbin, rsaixbin, etc.).
The plaforms that supported the old convention are quite old and
essentially historical curiosities that might be encountered
in very old lockers:
vax, rt, decmips, sun4, and rsaix.

.SH USER SUPPORT

There are four forms of support provided to the user for handling
locker conventions: the \fIadd\fR command, the \fIathdir\fR command,
the \fIATHENA_SYS\fR environment variable, and the \fIbindir\fR C
shell variable.

The \fIadd\fR command (see \fIadd\fR(1) for details on use), for
binary directories, initially checks for the existence of the new
style binary directory. If it finds it, it adds that to the user's
search path. If not, it falls back to the old \fImachtype\fR-based
convention. Similiarly, in order to more easily support
machine-dependent manual pages, it checks for an arch/@sys/man directory
before falling back to the traditional man directory.

The \fIathdir\fR command is in some ways a generalization of the
\fIadd\fR command;
it is useful for finding library or include directories, especially
within makefiles.
See \fIathdir\fR(1) for details.

The \fIATHENA_SYS\fR environment variable is used lieu of the AFS
string @sys. In all cases, it should be equal to what @sys resolves to
for any particular platform. So in shell scripts, makefiles, etc., one
should never attempt to find one's libraries with a string such as
"arch/@sys/lib" but rather "arch/$ATHENA_SYS/lib." It is usually
preferable to use \fIathdir\fR, though.

\fIATHENA_SYS\fR is derived in the global shell dotfiles from the
output of ``machtype -S''.

The \fIbindir\fR variable is set only for legacy purposes;
it is always set to arch/@sys/bin.
Note that it is not set literally to arch/@sys/bin, but rather to
arch/(the value of @sys)/bin; the literal string @sys should never
be used except in convenience symlinks.

Avoidance of the literal string ``@sys'' is done in order to keep the
locker conventions filesystem independent. If for some reason a locker
is copied to (or is maintained in) NFS space, it will still work
correctly.  If AFS is translated through some other medium which does
not magically know how to cope with the "@sys" string properly, it
will also still work correctly. If Athena migrates to another kind of
filesystem that does not support the use of "@sys," nothing will need
to be done to update lockers and everything will still work.

.SH OPERATING SYSTEM COMPATIBILITY SUPPORT

As mentioned above, a given operating system may have the ability to
run binaries from various @sys values. For example, an amd64_ubuntu1010
system can run binaries from amd64_deb50 and amd64_ubuntu1004.
In part to ease the
transition of machines to new operating systems, which would normally
have no support for their new @sys values barring locker maintainer
action, the environment variable \fIATHENA_SYS_COMPAT\fR is
available.
This
variable holds a colon-separated list of fallback @sys values which are
known to be generally compatible with the current system.
In the above example, this variable might be set to
amd64_deb50:amd64_ubuntu1004 to allow lockers that have not been updated
for the new operating system to continue to function.
Both \fIadd\fR(1) and \fIathdir\fR(1) support this variable.

.SH MAINTENANCE SUPPORT

The \fIlockers\fR locker contains tools to aid in the maintenance of
lockers. "add lockers; man lockertools" for more information.

.SH SUGGESTIONS ON CONFIGURING SOFTWARE

Many software packages use autoconf-generated configure scripts.
These packages can generally be configured for a locker with a command
like "./configure --prefix=/mit/lockername
--exec-prefix=/mit/lockername/arch/$ATHENA_SYS".  This command will
configure the program to install its shared data files directly under
/mit/lockername, and to install architecture-dependent materials under
the appropriate arch directory.

Alternatively, one could configure with simply "./configure
--prefix=/mit/lockername/arch/$ATHENA_SYS" to install all materials
under the appropriate arch directory.  This option may waste space,
but may also be more resistant to flaws in the package (e.g. the
package might install architecture-dependent materials under the
prefix instead of the exec-prefix, or an installation of a newer
version of the package might break an older installation for an older
platform by overwriting the shared data area).

Some software in lockers is configured to use the full AFS path as a
prefix instead of /mit/lockername.  This practice is not recommended
because it is incompatible with possible extensions to the lockers
framework.
It is also not recommended to use arch/@sys (instead of
arch/$ATHENA_SYS) in
the prefix, since that can fail when the software is used via
\fIATHENA_SYS_COMPAT\fR.

.SH SEE ALSO

add(1), athdir(1), machtype(1), athena-ws discuss meeting, txns
1932-1961 more or less