Introduction

This document provides an overview of the philosophies and practices of the UNIX Services Group in regards to source maintenance. This is a not an exhaustive enumeration of what we do or how we do it. It does put forth some basic concepts and explains the structure that we have established.

This structure is not set in stone - it evolves as our needs and environment change.

Why have sources?

Why do we maintain sources? Let's back up further and ask what our group does on our systems. We

Install vendor OS software and configure it to do what we need.
Respond to user needs by installing free software.
Share this responsibility between multiple staff members.
Try to operate multiple CPU architectures with a similar ``feel''.
Serve as a resource for other system administrators on campus.

These goals are often best served by being able refer to the original and/or desired state of the software and configuration files installed on the system. In other words, the sources.

The source policy is really a set of principles from which you can quickly derive a suitable procedure for making whatever change you need to.

Tracking changes made to configuration files.
Building copies of software on multiple systems simultaneously.
Allowing multiple people to manage a particular subsystem.
Making bug fixes, changes and scripts available to campus admins.
Determining the source of a program that is having a problem.

Basic concepts

One master copy of source for all architectures.
Handle system dependencies dynamically - configuration files, system identity calls.
Make things as same as possible across systems.

The source control system is your friend.
Document, document, document.
You cannot be indispensable.

Source management bylaws

Find the source from where the binary lives.
All files under source control.
Use "build trees".
Same path to access sources on all systems.
All sources live in the source tree.
Access is controlled via group memberships.
Anyone can be working on any source.

Where sources live

Sources are stored on the Software Distribution Services Network Appliance NFS server.

graceland:/export/unix-source: Mounted as /usr/src/ut
graceland:/export/public/source: Mounted as /usr/src/public
/usr/src/ut: Locally written software, proprietary sources and other UT-specific sources.
/usr/src/public: Sources imported from the Internet and locally written programs that we wish to make generally available.
/usr/src/{vendor}: Sources from vendor distributions, e.g. /usr/src/sun, /usr/src/att. These are mostly vestigial because we don't get OS sources any more.

Structure of /usr/src/ut

/usr/src/ut/share: Sources than can be used on all CPU architectures and UNIX variants.
/usr/src/ut/{sunos4, sunos5, aix, osf1}: Sources specific to that UNIX variant.
/usr/src/ut/print-service: Sources specific to the printing service.

Under each of these directories, the UNIX file system hierarchy is duplicated:

/usr/src/ut/{share,sunos4, ...}
        /share
                /share/transcript-4.0
        /etc
        /bin
        /usr
                /usr/bin        
                /usr/etc
                /usr/lib
                        /usr/lib/sendmail-8....
                /usr/local
                        /usr/local/bin
                                /usr/local/bin/TeX-3.1415
                        /usr/local/etc
                        /usr/local/lib

/usr/src/ut/share/packages: Sources for imported packages that may live in arbitrary locations. All commercial sources are stored here, along with public packages that have been extensively modified for UT use.

The sources in this area are organized by functionality.

The structure of /usr/src/public

This area contains things we have imported from the Internet. It is organized on the lines of the GNU / Redhat Linux categories of functionality. We make it available via anonymous FTP, gopher and NFS.

Every source directory should have the version number of the package in the name. This allows multiple versions to be available.

See the description in /usr/src/public/README

Example paths in the public source area:

        /usr/src/public/networking/services/tcp-ip/bind-4.9.2
        /usr/src/public/applications/mail/sendmail-8.6.11
        /usr/src/public/applications/editors/emacs-19.24

Where to put binaries

Put it in /usr/local unless it won't work or legitimately replaces vendor supplied programs. For example, the sendmail distribution supplants the sendmail program.
Single programs go in /usr/local/bin. This directory is added to the default PATH, usually in the shell init files provided by newuser.
Packages should be configured to live under a single tree named /usr/local/name-version; for example /usr/local/perl-4.036. A symbolic link is made to the generic package name, e.g. /usr/local/perl will always point to the official PERL installation, regardless of version.
Packages should not be configured with the generic package directory name. The pieces of PERL 4.036 should look for each other in /usr/local/perl-4.036. This allows multiple versions to be available without conflict.
Using package directories helps with maintenance and exporting.
In the package directory, the UNIX /usr hierarchy is replicated:

        /usr/local/perl/bin
        /usr/local/perl/lib
        /usr/local/perl/man/man{1,3,...}

Manual pages go into the appropriate man/manN subdirectory of the package directory. Access to man pages via the man command is dealt with the manpath front end program.
Some packages have components that we deem need to be in the default user PATH. In these cases, the actual binary is installed in the package directory, but a symbolic link to it is made in /usr/local/bin. Such links are made to the generic package directory. For example,

        /usr/local/bin/perl -> /usr/local/perl/bin/perl

About /usr/src/local

The /usr/src/local directory is a collection of build trees for that OS/CPU type.

A build tree is a replica of a source tree. The directory hierarchy is replicated, and the files are symbolic links into the source area. These are built by lndir program which is provided in the MIT X distribution.

The why and how of build trees

Keeps the source area cleaner.
Allows retention of state so that rebuilds after incremental changes are quicker.
Localizes changes (e.g. results of package auto-configurators).
The UNIX /usr hierarchy is replicated in /usr/src/local.

There is one build area per OS/CPU environment:

       Solaris 2 - elvis:/usr/src/local
       SunOS 4.X - lal:/usr/src/local
       OSF/1 - curly:/usr/src/local
       NeXT 68k: onyx:/usr/src/local
       AIX - ginger:/usr/src/local

Most of these areas are NFS exported to and automounted by other systems of the same architecture.

Some service machines have a /usr/src/local for that system or group of systems.

        soong:/usr/src/local for print servers;
        geraldo:/usr/src/local for USENET servers;
        mcfeeely:/usr/src/local for the list server.
        mrzip:/usr/src/local for the list server.

Documentation

The master database of system installations and changes is maintained in the following newsgroups.

utexas.hpcf.sysmod utexas.cc.sysmod utexas.cc.sysmod.nt utexas.cc.sysmod.vms utexas.ecelrc.sysmod

Post messages via email: sysmod@cc.utexas.edu
Read via USENET readers.
Don't install without a sysmod.
Prototype message: /usr/local/staff/sysmod.notice
WAIS indexed for searching.
Index search via WAIS and gopher.

System administration rules to live by

(Learned the hard way)

Diff before you install.
Never install version X.0 or 0.X.
Use the source motel.
Gonzalez' maxim (aka The Friday Rule):

Don't sweat minor revisions and patches.
Wrapper scripts are like Bondo and a coat of primer.
"make -n" is your friend.
Unverified backups are evil.
Backwards-compatible dump and restore programs aren't.
Emacs is great for patching binaries.

Document version 1.5

Last modified 09/25/98
Source file /usr/src/ut/share/usr/local/staff/SourcePolicy.html