[25585] in Source-Commits
/svn/athena r25103 - in trunk/debathena/debathena/dotfiles: . debian
daemon@ATHENA.MIT.EDU (Benjamin Kaduk)
Sat Apr 23 15:24:13 2011
Date: Sat, 23 Apr 2011 15:24:06 -0400
From: Benjamin Kaduk <kaduk@MIT.EDU>
Message-Id: <201104231924.p3NJO65G001140@drugstore.mit.edu>
To: source-commits@mit.edu
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Author: kaduk
Date: 2011-04-23 15:24:06 -0400 (Sat, 23 Apr 2011)
New Revision: 25103
Modified:
trunk/debathena/debathena/dotfiles/debian/changelog
trunk/debathena/debathena/dotfiles/lockers.7
Log:
In dotfiles:
* Update lockers.7 for modern sysnames and the ubiquity of the
arch/@sys/ convention (Trac #871)
Modified: trunk/debathena/debathena/dotfiles/debian/changelog
===================================================================
--- trunk/debathena/debathena/dotfiles/debian/changelog 2011-04-23 05:25:13 UTC (rev 25102)
+++ trunk/debathena/debathena/dotfiles/debian/changelog 2011-04-23 19:24:06 UTC (rev 25103)
@@ -1,3 +1,10 @@
+debathena-dotfiles (10.0.28-0debathena1) unstable; urgency=low
+
+ * Update lockers.7 for modern sysnames and the ubiquity of the
+ arch/@sys/ convention (Trac #871)
+
+ -- Benjamin Kaduk <kaduk@mit.edu> Sat, 23 Apr 2011 15:23:31 -0400
+
debathena-dotfiles (10.0.27-0debathena1) unstable; urgency=low
* Suppress stdout/stderr for sftp sessions (Trac #512)
Modified: trunk/debathena/debathena/dotfiles/lockers.7
===================================================================
--- trunk/debathena/debathena/dotfiles/lockers.7 2011-04-23 05:25:13 UTC (rev 25102)
+++ trunk/debathena/debathena/dotfiles/lockers.7 2011-04-23 19:24:06 UTC (rev 25103)
@@ -1,151 +1,152 @@
-.TH LOCKERS 7 "6 March 1998"
+.TH LOCKERS 7 "22 April 2011"
.ds ]W MIT Athena
.SH NAME
-lockers - description of Athena locker organization conventions
+lockers -- description of Athena locker organization conventions
.SH 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.
+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 also count.
+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
+.SH 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 \fIarch\fR. Under \fIarch\fR 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.).
+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 of 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/
- pmax_ul4/
+ amd64_deb40/
bin/
lib/
- rs_aix32/
+ i386_ubuntu1004/
bin/
lib/
- sgi_52/
- bin/
- lib/
- sun4m_53/
+ sun4x_510/
bin/
lib/
+ i386_rhel4/
+ bin/
+ lib/
-Possibilities for data subdirectories include bin, lib, etc, man, and
-build.
+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/
- sun4c_51 -> sun4m_53
- sun4c_53 -> sun4m_53
- sun4m_51 -> sun4m_53
+ sun4x_510 -> sun4x_59
+ i386_deb50 -> i386_deb40
-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.
+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
+.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 there is a directory
-called "man" that follows the conventions for manual directories
-followed by most flavors of Unix.
+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 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.
+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
-While the \fIadd\fR command deals for the user with finding the
-appropriate binary directory for their platform, some users sometimes
-do not use \fIadd\fR, 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 \fIonly\fR case
-where we suggest using the explicit string "@sys." See the end of the
-section \fIUSER SUPPORT\fR, below, for the reasons.
+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, and no suggestions for hierarchies to
-avoid clutter or other general hints. 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, sun4bin, etc.).
-Because of the inflexibility of the shell \fIbindir\fR 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
+binary and manual directories, with no suggestions for how to
+arrange directories 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.
-/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.
-
.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 \fIbindir\fR C shell variable, and the \fIATHENA_SYS\fR
-environment variable.
+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
+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. 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. \fIathdir\fR is also potentially useful for finding
-library or include directories from inside of makefiles. See
-\fIathdir\fR(1) for details.
+\fIadd\fR command;
+it is useful for finding library or include directories, especially
+within makefiles.
+See \fIathdir\fR(1) for details.
-The \fIbindir\fR 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 \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, however.
+preferable to use \fIathdir\fR, though.
-\fIATHENA_SYS\fR is derived in the global cshrc from the output of
-``machtype -S''.
+\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
@@ -158,17 +159,20 @@
.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, 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 \fIATHENA_SYS_COMPAT\fR. 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 \fIadd\fR(1) and \fIathdir\fR(1)
-support this variable.
+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
@@ -196,12 +200,14 @@
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
+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, /etc/athena/local-lockers.conf
+1932-1961 more or less
