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

Revision 25115, 8.5 KB checked in by kaduk, 13 years ago (diff)
fix grammar errors in r25103 spotted by geofft
[25103]1.TH LOCKERS 7 "22 April 2011"
[7757]2.ds ]W MIT Athena
[25103]4lockers -- description of Athena locker organization conventions
7There are many possible ways to provide binaries for multiple
[25103]8architectures with some form of
9organization under a single filesystem.
10Athena suggests and supports a particular convention for doing this.
12The primary purpose of this convention is to provide a standard way of
[25103]13separating machine-dependent binaries into different directories for
14ease of use and maintenance.
15Generality, backwards compatibility, and
16neatness are also considered.
[25103]20In order to avoid clutter in the top-level directory of a
21locker, all machine-dependent directories are placed under a
22common directory \fIarch\fR.
23Under \fIarch\fR there is one directory for each
24supported platform, named after the AFS "@sys" values (amd64_deb40,
25sun4x_510, etc\.).
[25115]26Under each sysname's directory are subdirectories
[25103]27containing specific types of machine-dependent data, such as binaries
28or libraries (bin, lib, etc\.).
30For example, a locker containing libraries and binaries might look
[25103]34                 amd64_deb40/
[7757]35                          bin/
36                          lib/
[25103]37                 i386_ubuntu1004/
[7757]38                          bin/
39                          lib/
[25103]40                 sun4x_510/
[7757]41                          bin/
42                          lib/
[25103]43                 i386_rhel4/
44                          bin/
45                          lib/
[25103]47Possible machine-dependent subdirectories include bin, lib, etc,
48man, and build.
50Note that due to the fact there is binary compatibility across
51multiple AFS "@sys" values, there will also be many symbolic links:
[25103]54                 sun4x_510 -> sun4x_59
55                 i386_deb50 -> i386_deb40
[25103]57Note also that the string "@sys" should never be used literally
58(in Makefiles or scripts)
59except for the convenience symlinks described below; the string
60"$ATHENA_SYS" should be used instead.
61Further details appear below.
65Many files, such as manual pages or data files, may be the same for
[25103]66all machine architectures.
67Currently, the only defined convention for
68such files applies only to manual pages.
69That convention is simply
70that in the top-level directory of a locker the "man"
71directory contains the manual pages, in agreement with the
72conventions for most flavors of Unix.
[25103]74Note that the \fIadd\fR command supports the possibility of
75machine-specific manual pages when modifying the MANPATH, in that it
76first checks for the existence of the directory arch/@sys/man before
77falling back to a man directory in the root of the locker.
[25103]81The \fIadd\fR
82command is the standard way for users to find the appropriate
83binary for their platform, but some users prefer to
84not use \fIadd\fR
85and type explicit paths on their own.
86When the correct binary is located in
88this proves tedious.
89For these users' convenience, it is recommended to make
90a symbolic link "bin -> arch/@sys/bin" and possibly
91others (for lib, etc\.) as it makes sense.
92This is the \fIonly\fR case
93where it makes sense to use the explicit string "@sys".
94Even so, this symbolic link is not needed for normal operation of
95\fIadd\fR, it is merely for the convenience of users.
96Further details regarding the non-recommendation of "@sys"
97appear at the end of section \fIUSER SUPPORT\fR.
101The previous file layout conventions included only standards for
[25103]102binary and manual directories, with no suggestions for how to
[25115]103arrange directories and avoid clutter.
[25103]104The main convention was that the
105output from
106\fImachtype\fR(1) be used to generate a binary directory
107for a given platform, e.g. `machtype`bin (decmipsbin, rsaixbin, etc.).
108The plaforms that supported the old convention are quite old and
109essentially historical curiosities that might be encountered
110in very old lockers:
111vax, rt, decmips, sun4, and rsaix.
115There are four forms of support provided to the user for handling
116locker conventions: the \fIadd\fR command, the \fIathdir\fR command,
[25103]117the \fIATHENA_SYS\fR environment variable, and the \fIbindir\fR C
118shell variable.
120The \fIadd\fR command (see \fIadd\fR(1) for details on use), for
121binary directories, initially checks for the existence of the new
122style binary directory. If it finds it, it adds that to the user's
[25103]123search path. If not, it falls back to the old \fImachtype\fR-based
124convention. Similiarly, in order to more easily support
125machine-dependent manual pages, it checks for an arch/@sys/man directory
[7757]126before falling back to the traditional man directory.
128The \fIathdir\fR command is in some ways a generalization of the
[25103]129\fIadd\fR command;
130it is useful for finding library or include directories, especially
131within makefiles.
132See \fIathdir\fR(1) for details.
134The \fIATHENA_SYS\fR environment variable is used lieu of the AFS
135string @sys. In all cases, it should be equal to what @sys resolves to
136for any particular platform. So in shell scripts, makefiles, etc., one
137should never attempt to find one's libraries with a string such as
138"arch/@sys/lib" but rather "arch/$ATHENA_SYS/lib." It is usually
[25103]139preferable to use \fIathdir\fR, though.
[25103]141\fIATHENA_SYS\fR is derived in the global shell dotfiles from the
142output of ``machtype -S''.
[25103]144The \fIbindir\fR variable is set only for legacy purposes;
145it is always set to arch/@sys/bin.
146Note that it is not set literally to arch/@sys/bin, but rather to
147arch/(the value of @sys)/bin; the literal string @sys should never
148be used except in convenience symlinks.
[7757]150Avoidance of the literal string ``@sys'' is done in order to keep the
151locker conventions filesystem independent. If for some reason a locker
152is copied to (or is maintained in) NFS space, it will still work
153correctly.  If AFS is translated through some other medium which does
154not magically know how to cope with the "@sys" string properly, it
155will also still work correctly. If Athena migrates to another kind of
156filesystem that does not support the use of "@sys," nothing will need
157to be done to update lockers and everything will still work.
161As mentioned above, a given operating system may have the ability to
[25103]162run binaries from various @sys values. For example, an amd64_ubuntu1010
163system can run binaries from amd64_deb50 and amd64_ubuntu1004.
164In part to ease the
165transition of machines to new operating systems, which would normally
166have no support for their new @sys values barring locker maintainer
167action, the environment variable \fIATHENA_SYS_COMPAT\fR is
170variable holds a colon-separated list of fallback @sys values which are
171known to be generally compatible with the current system.
172In the above example, this variable might be set to
173amd64_deb50:amd64_ubuntu1004 to allow lockers that have not been updated
174for the new operating system to continue to function.
175Both \fIadd\fR(1) and \fIathdir\fR(1) support this variable.
179The \fIlockers\fR locker contains tools to aid in the maintenance of
180lockers. "add lockers; man lockertools" for more information.
[20646]184Many software packages use autoconf-generated configure scripts.
185These packages can generally be configured for a locker with a command
186like "./configure --prefix=/mit/lockername
187--exec-prefix=/mit/lockername/arch/$ATHENA_SYS".  This command will
188configure the program to install its shared data files directly under
189/mit/lockername, and to install architecture-dependent materials under
190the appropriate arch directory.
[20646]192Alternatively, one could configure with simply "./configure
193--prefix=/mit/lockername/arch/$ATHENA_SYS" to install all materials
194under the appropriate arch directory.  This option may waste space,
195but may also be more resistant to flaws in the package (e.g. the
196package might install architecture-dependent materials under the
197prefix instead of the exec-prefix, or an installation of a newer
198version of the package might break an older installation for an older
199platform by overwriting the shared data area).
201Some software in lockers is configured to use the full AFS path as a
202prefix instead of /mit/lockername.  This practice is not recommended
[25103]203because it is incompatible with possible extensions to the lockers
205It is also not recommended to use arch/@sys (instead of
206arch/$ATHENA_SYS) in
[20646]207the prefix, since that can fail when the software is used via
[7757]210.SH SEE ALSO
212add(1), athdir(1), machtype(1), athena-ws discuss meeting, txns
[25103]2131932-1961 more or less
Note: See TracBrowser for help on using the repository browser.