 |
 |
 |
 |
The goal of these standards is to make it as easy as possible to upgrade packages with minimal disruption to normal usage of the system; a secondary, related goal is to make it possible to maintain and use multiple versions of a given package simultaneously, without allowing them to interfere with each other.
In the descriptions which follow,
For software which does not maintain a version number of its own, two possibilities exist. If there is no interest in maintaining multiple versions, a version number of 0 (zero) may be used; otherwise, the version specifier should be YYYYMMDD (eg 19931021), indicating the date when the distribution was last modified (preferable, if known) or when it was acquired.
All local software is installed in the directory /local, which is usually placed in its own disk partition, or sharing a partition with other non-O/S material such as /home.
Avoid placing /local on a partition used by the O/S, otherwise you risk having your packages overwritten when the O/S is upgraded.
The organization within /local is described below.
Every software package installed on the system will be placed in its own subdirectory of /local/pkg (except legacy installations in /local/src; see below). Each subdirectory will be named PKG, and contain files and directories as follows:
This directory contains a compressed copy of the package's distribution archive (optional in the case of locally written software, but strongly recommended even so). For example, for emacs-19.19, the contents of /local/pkg/emacs/DIST would be the file emacs-19.19.tar.gz.
This directory contains the unpacked (ie "live") source distribution.
This is the installation directory for run-time files which belong to this package. The prefix root- is literal.
root-PKG-VERSION will usually contain subdirectories bin and man, and often lib, var or include.
All files needed by this package should be installed somewhere in or under root-PKG-VERSION; if a particular package requires a file or directory somewhere else, a symlink to a location under root-PKG-VERSION should be used instead.
Note that at least one manual page is required for any package which will be "published" (see below), while all other content is optional.
Provenance information; see below for format.
This file should begin with a header including the date, your name, and (in parentheses) a short summary of what you did (installed version N.NN, copied an installation from machine foo, patched to resolve problem bar, etc.); the purpose of this header is to provide a quick history of modifications.
The body of the file should contain the steps you took to install the package, with as much detail as necessary to make it easy for someone else to be able to reproduce them. In general, the goal is to make it easy for a colleague (or yourself :-) to duplicate the current installation exactly, by following the steps outlined in this file.
Where feasible, the format of TRANSCRIPT should match that of OSMODS (see below), though this is a suggestion rather than a strict requirement.
Summary of modifications made to the operating system when this package was installed, if any; examples include the installation of boot-time startup scripts, entries in the password or group file, entries in /etc/inetd.conf or /etc/syslog.conf, entries in root's crontab file, etc.
An OSMODS file is REQUIRED if and only if any such modifications are made.
In 1999 we instituted a specific format for this file, to facilitate collecting OSMODS for redoing them after a system upgrade:
Summary of modifications to /local, /public, or any other non-OS directory outside /local/pkg/PKG (other than the creation and population of the directories mentioned in this document, and the "publication" of programs).
Examples include creation of version-independent symbolic links (eg /local/lib/sendmail pointing to /local/pkg/sendmail/data), entries in other packages' configuration files (eg TCP Wrappers, newsyslog, etc.), adding icons to a local installation of X11R6, adding icons to /public/apache, etc.
A LOCALMODS file is REQUIRED if and only if any such modifications are made.
This directory contains files which are produced, written or substantially edited locally, and which would be lost when the package is upgraded if they were simply left in PKG-VERSION or root-PKG-VERSION.
Examples of suitable content include new helper scripts (eg a boot-time startup script or cron job), man pages for a package which doesn't include any of its own, significant changes to a configuration file, etc.
The localmods directory should exist only if there are files to be put in it.
Modifications needed on some other host in order to support this package. One example might be a .ssh/authorized_keys entry required on another machine in order to support access to that host from within a cron job.
Where appropriate, this directory contains data files which are independent of the currently installed version of a package. For example, /local/pkg/web-helpers/data contains web page source files, which should not be replicated separately under root-web-helpers-VERSION each time this package is upgraded.
Additional comments, for example debugging instructions, which don't really belong in a TRANSCRIPT.
Note that multiple versions of a package may exist simultaneously; in
such a case, archives for each version exist in
PKG/DIST, and separate directories are
maintained as PKG/PKG-VERSION and
PKG/root-PKG-VERSION. If
necessary, suffixes may be appended to the documentation files
to distinguish between multiple versions (eg,
TRANSCRIPT-VERSION, OSMODS-VERSION,
WHERE_I_CAME_FROM-VERSION, etc.).
A sample WHERE_I_CAME_FROM file looks like this:
Once a package has been installed into
root-PKG-VERSION, the last step is to make its
files easily accessible to users. This is done using a Perl script
called publish (see /local/pkg/publish), which creates
symbolic links for executable files (which are normally found in
root-PKG-VERSION/bin), man pages
(root-PKG-VERSION/man), #include
files (root-PKG-VERSION/include), and
library files (root-PKG-VERSION/lib).
These symlinks are placed into shared directories ("symlink farms"),
which are normally located in
/local/paths, /local/manpaths, /local/includepaths
and
/local/libpaths.
Once created, the symlinks can be conveniently added to users' search
paths or used (via -I or -L directives) during
compilation of other packages.
Note that the existence of /local/paths does not replace the
use of the local_path mechanism (see local_path(1)
and/or /local/pkg/local_path); instead it complements
local_path by reducing the number of directories in
/local/etc/local_path.list.
There are three ways to handle the case where two or more packages
contain executable files with identical names:
Note that for conflicts involving manual pages, it's usually better to
add a suffix rather than change the base name (unless the change matches
a change to the corresponding executable file); this amounts to giving
one of the man pages a private extension.
For example, if man page foo.1 conflicts with an existing man
page for foo, the new one might be renamed as
foo.1new; this would allow the existing page to be retrieved by
"man foo", while the new one can be read by
"man 1new foo". (If desired, the foo.1new page may
be altered to include a See Also reference to
foo(1).)
For details on what publish does and how it works, see
publish(8) and/or read the header comments in
/local/pkg/publish/publish-VERSION/publish.pl
(Note: As existing packages installed according to these standards are upgraded, they should be adjusted to follow the new standard described above.)
Packages installed in /local/pkg prior to April 1999 were installed without a consistent equivalent to the root-PKG-VERSION directory which has become the current standard. As a result, run-time components may be located anywhere in or under /local/pkg/PKG (eg, in a directory equivalent to root-PKG-VERSION but with a different name, as parallel directories at the level of /local/pkg/PKG, or even as subdirectories of PKG-VERSION).
The one exception to this is that old-style /local/pkg installations must have a corresponding subdirectory called /local/man/PKG-VERSION.
As a result, publish is unable to find the installed components without help, in the form of a list of full pathnames for every component to be symlinked. This list takes the form of any or all of the following files, which if present must be located in PKG-VERSION: .BINARIES, .INCLUDES, .LIBRARIES and .MANPAGES. The effect of these files is as follows:
In all cases, the format of each file is a list of absolute pathnames, with one pathname per line.
Note that the standard documentation files are expected to exist in /local/pkg/PKG.
From 1993 until April 1999, the preferred standard for installation of local software was to keep the source in /local/src/PKG/PKG-VERSION, with installed content in corresponding directories elsewhere in /local; eg, executable files would go in /local/bin/PKG-VERSION, man pages in /local/man/PKG-VERSION, etc. Note that the standard documentation files are expected to exist in /local/src/PKG.
These directories contain any software which has been downloaded but not yet installed. Note that /local/src/PENDING is obsolete and should not be used for any new packages.
Contains one-off system administration scripts for which no version tracking is done.
On some systems, contains symbolic links to directories containing GNU "info" files for various packages in /local/pkg; these are maintained manually.
Some systems have an existing /usr/local directory. In most cases, we remove this directory and its contents, and replace it with a symlink to /local. In other cases, we keep /usr/local as a directory, but replace its contents with symlinks as follows:
The reason for this is that certain operating systems (such as Tru64Unix) will find shared libraries in /local/lib, but won't find them in our usual custom location without compile-time options, run-time environment settings, and so on.
Some software packages have their own very stubborn ideas as to where they should be installed, and may require a "root directory", which should be (a symlink) under /local/pkg/PKG/PKG-VERSION.
One way or another, make sure that the binaries linked from /local/paths are somewhere under /local/pkg/PKG/PKG-VERSION, even if you have to use symlinks to fake it out. Otherwise the "sw_revs" version tracking software won't be able to find them.
Preferred standard:
Note that this scheme is deprecated and should be used only if absolutely necessary -- and we expect that it won't be necessary nearly as often under the current standard as it used to be with the older /local/src standard. As usual, existing installations of this type should be converted to the current standard if possible as they're upgraded.
/local/pkg/_OS is where we keep O/S-related information. Most systems should have a layout in this directory somewhat like this:
A series of dated one-line entries to indicate major work on the system: O/S upgrades and patches, hardware upgrades, hardware replacements.
Messages displayed on the console during a typical boot sequence; among other things, this includes a list of hardware devices found by the kernel at boot time. This information will typically be found in the syslog "messages" file (/var/log/messages, /var/adm/syslog/messages, etc.), though this is system-dependent. On some versions of Unix, boot messages are produced by dmesg(8).
If your O/S install procedure writes logs, put them here.
If your O/S requires licenses, put copies here.
If you wrote new programs for the O/S, such as boot-time startup scripts, place them here.
Disk documentation, including the following files and directories:
Show the partitions and mount points, desired sizes, use, and, if applicable, other comments such as level of activity.
Copy of /etc/fstab.
For "advanced file system" (AdvFS) domains, a recursive listing of /etc/fdmns [applicable to Compaq (formerly DEC) systems only].
For each disk, a copy of its disk label, including disk parameters and partition information.
The RAID configuration, in human-readable format (possibly a symlink to a file in ../RAID/).
On systems with a RAID controller, this directory contains a copy of the RAID configuration (both in native format and plain text), as well as any pertinent notes.
Contains entries for each service call made to the vendor, including reference number, date submitted, problem description, resolution, and date closed.
Data to be printed out, for system recovery in case of catastrophe. This should include the RAID configuration, partition tables, AdvFS layouts, and so on.
Revision History
Clarified DEC to Compaq transition.
Added paragraph about /usr/local.
Conversion from plain text to HTML, plus minor wording improvements.
Minor revisions, some suggested by Anne, others involving typos and similar small improvements.
Performed a major rewrite to reflect the fact that /local/pkg is being used for all new installations, while /local/src is now considered obsolete.
More changes per group discussion (meeting). This document needs to be reworked to show the primacy of the "pkg" style of installation.
Changes per group discussion (e-mail).
Revised for current conventions.
This document is five years old, and has to some extent been overtaken by subsequent events. However, it will do as a starting point until it can be brought up to date. Most of the changes will involve adding new material (eg, localmods, LOCALMODS, etc.) rather than actual changes to the existing items.
The conventions described here represent an evolutionary change to the methods in use at Computing Services since 1990. Various refinements are proposed, based on experience, for improving management of multiple versions of given packages.
|
Copyright, © 2004,
Concordia University,
|
![[IITS Home]](/style/button_iits_home.gif)
|
![[Concordia Home]](/style/button_conu_home.gif)
|