Provided by:
debathena-dotfiles_10.0.24-0debathena1~ubuntu10.10_all 
NAME
lockers - description of Athena locker organization conventions
DESCRIPTION
There are many possible ways to provide binaries for multiple
architectures in some 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 also count.
MACHINE DEPENDENT FILES
In order to avoid any sort of clutter in the top level directory of a
locker, all machine dependent directories are placed under a directory
called arch. Under arch is one directory, for each supported platform,
named after the AFS "@sys" values (pmax_ul4, sun4m_53, etc.). Under
each of these directories are directories containing a specific type 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/
pmax_ul4/
bin/
lib/
rs_aix32/
bin/
lib/
sgi_52/
bin/
lib/
sun4m_53/
bin/
lib/
Possibilities for data 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/
sun4c_51 -> sun4m_53
sun4c_53 -> sun4m_53
sun4m_51 -> sun4m_53
Note also that the string "@sys" should never be used literally, except
in convenience symlinks described below; the string "$ATHENA_SYS"
should be used instead. Continue reading for more details.
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 there is a directory called "man"
that follows the conventions for manual directories followed by most
flavors of Unix.
Note that the add command also 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 prior to
falling back on man itself.
CONVENIENCE SYMLINKS
While the add command deals for the user with finding the appropriate
binary directory for their platform, some users sometimes do not use
add, instead typing explicit paths on their own. This could become
tedious when they need to type "cd /mit/lockername/arch/pmax_ul4/bin."
For the user's convenience then, we suggest that you make a link "bin
-> arch/@sys/bin" and possibly others (for lib, etc.) as it makes
sense. This is the only case where we suggest using the explicit string
"@sys." See the end of the section USER SUPPORT, below, for the
reasons.
BACKWARDS COMPATIBILITY AND BINARY LAYOUT
The previous file layout conventions included only standards for binary
and manual directories, and no suggestions for hierarchies to avoid
clutter or other general hints. The main convention was that the output
from machtype(1) be used to generate a binary directory for a given
platform, e.g. `machtype`bin (decmipsbin, sun4bin, etc.). Because of
the inflexibility of the shell bindir variable, we cannot simply tell
everyone to begin using arch/@sys/bin for their binary directories. Old
lockers may still be using `machtype`bin and not the new convention,
and there is no practical way to update the entire world
simultaneously. Therefore, lockers should contain structures such as
/mit/locker/
arch/pmax_ul4/bin
decmipsbin -> arch/pmax_ul4/bin
That is, there should be compatibility symlinks provided from the old
convention to the new convention, for such platforms as were supported
under the old convention. Those platforms are vax, rt, decmips, sun4,
and rsaix. New platforms, such as SGI, need not provide these symlinks
as they don't have an old bindir value to worry about.
USER SUPPORT
There are four forms of support provided to the user for handling
locker conventions: the add command, the athdir command, the bindir C
shell variable, and the ATHENA_SYS environment variable.
The add command (see add(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 machtype 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 athdir command is in some ways a generalization of the add command.
The most important functionality it provides is as a replacement for
the use of the /mit/locker/`machtype`bin string. `athdir /mit/locker`
should now be used instead, and will work correctly whether old or new
directory conventions are in use in that locker. athdir is also
potentially useful for finding library or include directories from
inside of makefiles. See athdir(1) for details.
The bindir variable, on older platforms, is set to the value
`machtype`bin. On newer platforms, it is set to arch/@sys/bin. Note
that it is not set literally to arch/@sys/bin, but to arch/(the value
of @sys)/bin; the literal string @sys should never be used except in
convenience symlinks.
The ATHENA_SYS 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 athdir, however.
ATHENA_SYS is derived in the global cshrc from the output of ``machtype
-S''.
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.
OPERATING SYSTEM COMPATIBILITY SUPPORT
As mentioned above, a given operating system may have the ability to
run binaries from various @sys values. For example, a sun4x_56 system
can run binaries from sun4x_55 and sun4m_54. In part to ease the
transition of machines to new operating systems, where ordinarily they
would find no support initially for their @sys values in lockers, there
is the environment variable ATHENA_SYS_COMPAT. This variable is a colon
separated list of fallback @sys values which are known to be generally
compatible with the current system. So in the above example, this
variable might be set to sun4x_55:sun4m_54 to enable lockers that have
not yet been updated for the new operating system to continue to
function. Both add(1) and athdir(1) support this variable.
MAINTENANCE SUPPORT
The lockers locker contains tools to aid in the maintenance of lockers.
"add lockers; man lockertools" for more information.
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 the local-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
ATHENA_SYS_COMPAT.
SEE ALSO
add(1), athdir(1), machtype(1), athena-ws discuss meeting, txns
1932-1961 more or less, /etc/athena/local-lockers.conf
6 March 1998 LOCKERS(7)