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

Revision 20646, 9.1 KB checked in by ghudson, 18 years ago (diff)
Add examples of how to properly configure software for lockers. Remove the suggestions on volume management since even the biggest of lockers fit handily in a single AFS volume these days.
Line 
1.TH LOCKERS 7 "6 March 1998"
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 in some organization under a single filesystem. Athena
9suggests and supports a particular convention for doing this.
10
11The primary purpose of this convention is to provide a standard way of
12separating machine dependent binaries into different directories for
13ease of use and maintenance. Generality, backwards compatibility, and
14neatness also count.
15
16.SH MACHINE DEPENDENT FILES
17
18In order to avoid any sort of clutter in the top level directory of a
19locker, all machine dependent directories are placed under a directory
20called \fIarch\fR. Under \fIarch\fR is one directory, for each
21supported platform, named after the AFS "@sys" values (pmax_ul4,
22sun4m_53, etc.). Under each of these directories are directories
23containing a specific type of machine dependent data, such as binaries
24or libraries (bin, lib, etc.).
25
26For example, a locker containing libraries and binaries might look
27like:
28
29/mit/locker/arch/
30                 pmax_ul4/
31                          bin/
32                          lib/
33                 rs_aix32/
34                          bin/
35                          lib/
36                 sgi_52/
37                        bin/
38                        lib/
39                 sun4m_53/
40                          bin/
41                          lib/
42
43Possibilities for data subdirectories include bin, lib, etc, man, and
44build.
45
46Note that due to the fact there is binary compatibility across
47multiple AFS "@sys" values, there will also be many symbolic links:
48
49/mit/locker/arch/
50                 sun4c_51 -> sun4m_53
51                 sun4c_53 -> sun4m_53
52                 sun4m_51 -> sun4m_53
53
54Note also that the string "@sys" should never be used literally,
55except in convenience symlinks described below; the string
56"$ATHENA_SYS" should be used instead. Continue reading for more
57details.
58
59.SH MACHINE INDEPENDENT FILES
60
61Many files, such as manual pages or data files, may be the same for
62all machine architectures. Currently, the only defined convention for
63such files applies only to manual pages. That convention is simply
64that, in the top level directory of a locker there is a directory
65called "man" that follows the conventions for manual directories
66followed by most flavors of Unix.
67
68Note that the \fIadd\fR command also supports the possibility of
69machine specific manual pages when modifying the MANPATH, in that it
70first checks for the existence of the directory arch/@sys/man prior
71to falling back on man itself.
72
73.SH CONVENIENCE SYMLINKS
74
75While the \fIadd\fR command deals for the user with finding the
76appropriate binary directory for their platform, some users sometimes
77do not use \fIadd\fR, instead typing explicit paths on their own.
78This could become tedious when they need to type "cd
79/mit/lockername/arch/pmax_ul4/bin." For the user's convenience then,
80we suggest that you make a link "bin -> arch/@sys/bin" and possibly
81others (for lib, etc.) as it makes sense. This is the \fIonly\fR case
82where we suggest using the explicit string "@sys." See the end of the
83section \fIUSER SUPPORT\fR, below, for the reasons.
84
85.SH BACKWARDS COMPATIBILITY AND BINARY LAYOUT
86
87The previous file layout conventions included only standards for
88binary and manual directories, and no suggestions for hierarchies to
89avoid clutter or other general hints. The main convention was that the
90output from \fImachtype\fR(1) be used to generate a binary directory
91for a given platform, e.g. `machtype`bin (decmipsbin, sun4bin, etc.).
92Because of the inflexibility of the shell \fIbindir\fR variable, we
93cannot simply tell everyone to begin using arch/@sys/bin for their
94binary directories. Old lockers may still be using `machtype`bin and
95not the new convention, and there is no practical way to update the
96entire world simultaneously. Therefore, lockers should contain
97structures such as
98
99/mit/locker/
100            arch/pmax_ul4/bin
101            decmipsbin -> arch/pmax_ul4/bin
102
103That is, there should be compatibility symlinks provided from the old
104convention to the new convention, for such platforms as were supported
105under the old convention. Those platforms are vax, rt, decmips, sun4,
106and rsaix. New platforms, such as SGI, need not provide these symlinks
107as they don't have an old bindir value to worry about.
108
109.SH USER SUPPORT
110
111There are four forms of support provided to the user for handling
112locker conventions: the \fIadd\fR command, the \fIathdir\fR command,
113the \fIbindir\fR C shell variable, and the \fIATHENA_SYS\fR
114environment variable.
115
116The \fIadd\fR command (see \fIadd\fR(1) for details on use), for
117binary directories, initially checks for the existence of the new
118style binary directory. If it finds it, it adds that to the user's
119search path. If not, it falls back to the old \fImachtype\fR based
120convention. Similiarly, in order to more easily support machine
121dependent manual pages, it checks for an arch/@sys/man directory
122before falling back to the traditional man directory.
123
124The \fIathdir\fR command is in some ways a generalization of the
125\fIadd\fR command. The most important functionality it provides is as
126a replacement for the use of the /mit/locker/`machtype`bin string.
127`athdir /mit/locker` should now be used instead, and will work
128correctly whether old or new directory conventions are in use in
129that locker. \fIathdir\fR is also potentially useful for finding
130library or include directories from inside of makefiles. See
131\fIathdir\fR(1) for details.
132
133The \fIbindir\fR variable, on older platforms, is set to the value
134`machtype`bin. On newer platforms, it is set to arch/@sys/bin. Note
135that it is not set literally to arch/@sys/bin, but to arch/(the value
136of @sys)/bin; the literal string @sys should never be used except in
137convenience symlinks.
138
139The \fIATHENA_SYS\fR environment variable is used lieu of the AFS
140string @sys. In all cases, it should be equal to what @sys resolves to
141for any particular platform. So in shell scripts, makefiles, etc., one
142should never attempt to find one's libraries with a string such as
143"arch/@sys/lib" but rather "arch/$ATHENA_SYS/lib." It is usually
144preferable to use \fIathdir\fR, however.
145
146\fIATHENA_SYS\fR is derived in the global cshrc from the output of
147``machtype -S''.
148
149Avoidance of the literal string ``@sys'' is done in order to keep the
150locker conventions filesystem independent. If for some reason a locker
151is copied to (or is maintained in) NFS space, it will still work
152correctly.  If AFS is translated through some other medium which does
153not magically know how to cope with the "@sys" string properly, it
154will also still work correctly. If Athena migrates to another kind of
155filesystem that does not support the use of "@sys," nothing will need
156to be done to update lockers and everything will still work.
157
158.SH OPERATING SYSTEM COMPATIBILITY SUPPORT
159
160As mentioned above, a given operating system may have the ability to
161run binaries from various @sys values. For example, a sun4x_56 system
162can run binaries from sun4x_55 and sun4m_54. In part to ease the
163transition of machines to new operating systems, where ordinarily they
164would find no support initially for their @sys values in lockers,
165there is the environment variable \fIATHENA_SYS_COMPAT\fR. This
166variable is a colon separated list of fallback @sys values which are
167known to be generally compatible with the current system. So in the
168above example, this variable might be set to sun4x_55:sun4m_54 to
169enable lockers that have not yet been updated for the new operating
170system to continue to function. Both \fIadd\fR(1) and \fIathdir\fR(1)
171support this variable.
172
173.SH MAINTENANCE SUPPORT
174
175The \fIlockers\fR locker contains tools to aid in the maintenance of
176lockers. "add lockers; man lockertools" for more information.
177
178.SH SUGGESTIONS ON CONFIGURING SOFTWARE
179
180Many software packages use autoconf-generated configure scripts.
181These packages can generally be configured for a locker with a command
182like "./configure --prefix=/mit/lockername
183--exec-prefix=/mit/lockername/arch/$ATHENA_SYS".  This command will
184configure the program to install its shared data files directly under
185/mit/lockername, and to install architecture-dependent materials under
186the appropriate arch directory.
187
188Alternatively, one could configure with simply "./configure
189--prefix=/mit/lockername/arch/$ATHENA_SYS" to install all materials
190under the appropriate arch directory.  This option may waste space,
191but may also be more resistant to flaws in the package (e.g. the
192package might install architecture-dependent materials under the
193prefix instead of the exec-prefix, or an installation of a newer
194version of the package might break an older installation for an older
195platform by overwriting the shared data area).
196
197Some software in lockers is configured to use the full AFS path as a
198prefix instead of /mit/lockername.  This practice is not recommended
199because it is incompatible with the local-lockers framework.  It is
200also not recommended to use arch/@sys (instead of arch/$ATHENA_SYS) in
201the prefix, since that can fail when the software is used via
202\fIATHENA_SYS_COMPAT\fR.
203
204.SH SEE ALSO
205
206add(1), athdir(1), machtype(1), athena-ws discuss meeting, txns
2071932-1961 more or less, /etc/athena/local-lockers.conf
Note: See TracBrowser for help on using the repository browser.