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
Line 
1.TH LOCKERS 7 "22 April 2011"
2.ds ]W MIT Athena
3.SH NAME
4lockers -- description of Athena locker organization conventions
5.SH DESCRIPTION
6
7There are many possible ways to provide binaries for multiple
8architectures with some form of
9organization under a single filesystem.
10Athena suggests and supports a particular convention for doing this.
11
12The primary purpose of this convention is to provide a standard way of
13separating machine-dependent binaries into different directories for
14ease of use and maintenance.
15Generality, backwards compatibility, and
16neatness are also considered.
17
18.SH MACHINE-DEPENDENT FILES
19
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\.).
26Under each sysname's directory are subdirectories
27containing specific types of machine-dependent data, such as binaries
28or libraries (bin, lib, etc\.).
29
30For example, a locker containing libraries and binaries might look
31like:
32
33/mit/locker/arch/
34                 amd64_deb40/
35                          bin/
36                          lib/
37                 i386_ubuntu1004/
38                          bin/
39                          lib/
40                 sun4x_510/
41                          bin/
42                          lib/
43                 i386_rhel4/
44                          bin/
45                          lib/
46
47Possible machine-dependent subdirectories include bin, lib, etc,
48man, and build.
49
50Note that due to the fact there is binary compatibility across
51multiple AFS "@sys" values, there will also be many symbolic links:
52
53/mit/locker/arch/
54                 sun4x_510 -> sun4x_59
55                 i386_deb50 -> i386_deb40
56
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.
62
63.SH MACHINE-INDEPENDENT FILES
64
65Many files, such as manual pages or data files, may be the same for
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.
73
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.
78
79.SH CONVENIENCE SYMLINKS
80
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
87/mit/lockername/arch/amd64_ubuntu1010/bin
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.
98
99.SH BACKWARDS COMPATIBILITY AND BINARY LAYOUT
100
101The previous file layout conventions included only standards for
102binary and manual directories, with no suggestions for how to
103arrange directories and avoid clutter.
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.
112
113.SH USER SUPPORT
114
115There are four forms of support provided to the user for handling
116locker conventions: the \fIadd\fR command, the \fIathdir\fR command,
117the \fIATHENA_SYS\fR environment variable, and the \fIbindir\fR C
118shell variable.
119
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
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
126before falling back to the traditional man directory.
127
128The \fIathdir\fR command is in some ways a generalization of the
129\fIadd\fR command;
130it is useful for finding library or include directories, especially
131within makefiles.
132See \fIathdir\fR(1) for details.
133
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
139preferable to use \fIathdir\fR, though.
140
141\fIATHENA_SYS\fR is derived in the global shell dotfiles from the
142output of ``machtype -S''.
143
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.
149
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.
158
159.SH OPERATING SYSTEM COMPATIBILITY SUPPORT
160
161As mentioned above, a given operating system may have the ability to
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
168available.
169This
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.
176
177.SH MAINTENANCE SUPPORT
178
179The \fIlockers\fR locker contains tools to aid in the maintenance of
180lockers. "add lockers; man lockertools" for more information.
181
182.SH SUGGESTIONS ON CONFIGURING SOFTWARE
183
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.
191
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).
200
201Some software in lockers is configured to use the full AFS path as a
202prefix instead of /mit/lockername.  This practice is not recommended
203because it is incompatible with possible extensions to the lockers
204framework.
205It is also not recommended to use arch/@sys (instead of
206arch/$ATHENA_SYS) in
207the prefix, since that can fail when the software is used via
208\fIATHENA_SYS_COMPAT\fR.
209
210.SH SEE ALSO
211
212add(1), athdir(1), machtype(1), athena-ws discuss meeting, txns
2131932-1961 more or less
Note: See TracBrowser for help on using the repository browser.