[25594] in Source-Commits
Re: /svn/athena r25103 - in trunk/debathena/debathena/dotfiles: .
daemon@ATHENA.MIT.EDU (Geoffrey Thomas)
Wed Apr 27 10:24:22 2011
Date: Wed, 27 Apr 2011 10:23:49 -0400 (EDT)
From: Geoffrey Thomas <geofft@MIT.EDU>
To: Benjamin Kaduk <kaduk@mit.edu>
cc: source-commits@mit.edu
In-Reply-To: <201104231924.p3NJO65G001140@drugstore.mit.edu>
Message-ID: <alpine.DEB.2.00.1104271019320.10639@tyger.mit.edu>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed
On Sat, 23 Apr 2011, Benjamin Kaduk wrote:
> 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
I think you mean "Under each sysname's"?
> +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.
"to 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
Other than that, looks good, thanks!
--
Geoffrey Thomas
geofft@mit.edu
