SIPB Locker Maintenance Guide Abstract The SIPB locker is a repository of free software on Athena, provided as a service by the MIT Student Information Processing Board (SIPB). It is jointly maintained by dozens of SIPB members, and used by thousands of Athena users. In the past, the SIPB locker has not been treated as the very large group project that it is. There has been a lack of communication between the many maintainers of the SIPB locker, resulting in a mess of software that not always easy to use, and is very difficult to expand and maintain. This document is intended to be a first step towards changing all that. The first section of this guide describes the filesystem layout of the SIPB locker. The second section provides some guidelines for building and installing software in the locker. 1.0 Filesystem Layout 1.1 /mit/sipb The SIPB locker is made available on an Athena workstation by running "attach sipb". The top of the SIPB locker is mounted on /mit/sipb. /mit/sipb contains only subdirectories. No files are stored directly in /mit/sipb. It contains these directories: +-arch Architecture dependent files +-@sys/bin Programs +-@sys/build Build trees +-@sys/lib C libraries and architecture-dependent runtime files +-bin Symlink to arch/@sys/bin +-doc Documentation +-examples Reference files provided by SIPB +-include Header files for C libraries +-info Texinfo documentaion +-lib Symlink to arch/@sys/lib +-man Manual pages +-share Architecture-independent runtime files +-X11 Runtime files shared by X11 applications +-X11/app-defaults X11 app-default files +-X11/bitmaps X11 bitmap files in xbm format +-src Source code 1.2 arch /mit/sipb/arch contains only subdirectories. No files are stored directly in the arch subdirectory. The name of the subdirectory for a given architecture is the output of the command "/bin/athena/machtype -S" on that architecture. Symlinks may be created for backwards compatability. For example, there can be a symlink to "processor-os1.2" named "processor-os1.1", or vice-versa. 1.3 arch/@sys/bin /mit/sipb/arch/@sys/bin contains all executable programs for the system. Note: Throughout this document, "@sys" is used to represent the output of "machtype -S" for a given architecture. Note: If there is a shell script called "Mosaic" that runs a binary called "Mosaic.real", then both "Mosaic" and "Mosaic.real" must be in this directory. Note: This directory may not contain symlinks to source trees or build trees. Shell scripts are treated no different from binary programs: They must be installed and tested independently on each platform. If the script works on all platforms, it may be stored in the share directory and symlinked to the bin directory. 1.4 arch/@sys/build /mit/sipb/arch/@sys/build is not required to contain anything. Optionally, it may be used to store build trees. 1.5 arch/@sys/lib /mit/sipb/arch/@sys/lib contains C libraries and architecture-dependent runtime files used by software in the SIPB locker. Software that uses files in this directory should reference the directory through the pathname /mit/sipb/arch/${ATHENA_SYS}/lib, where ${ATHENA_SYS} is evaluated at compile-time. 1.6 bin /mit/sipb/bin is a symlink to arch/@sys/bin. The actual string "@sys" appears in the symlink. Thus, this symlink is only useful as long as the SIPB locker is stored in AFS. 1.7 doc /mit/sipb/doc contains general documentation provided by SIPB. It is not necessarily specific to the SIPB locker. This directory may be a symlink to /afs/sipb.mit.edu/project/doc/current for historical reasons. 1.8 examples /mit/sipb/examples contains files that can be viewed as examples of how to use software in the SIPB locker or elsewhere on Athena. 1.9 include /mit/sipb/include contains include files for C libraries found in /mit/sipb/arch/@sys/lib. The recommended way to use these files is to compile with -I/mit/sipb/include and link with -L/mit/sipb/arch/@sys/lib. 1.10 info /mit/sipb/info contains hypertext documentation in the format that is generated from texinfo documents. 1.11 lib /mit/sipb/lib is a symlink to arch/@sys/lib. Because this symlink is only meaningful in AFS, no software should ever depend on this symlink. 1.12 man /mit/sipb/man contains manual pages for software in the SIPB locker. All manual pages must be in "nroff -man" format. All manual pages are installed as /mit/sipb/man{n}/program.{n}, where {n} is a number based on the type of thing being documented. /mit/sipb/man contains these subdirectories: man1 User programs man3 Library functions and subroutines man4 File formants man5 Miscellany man6 Games man7 Special files man8 System administration programs and daemons /mit/sipb/man also contains subdirectories called cat1, cat3, cat4, cat5, cat6, cat7, and cat8. These directories contains manual pages formatted as plaintext. No manual page should ever be installed directly in a cat{n} directory. (Plaintext documentation should probably go in /mit/sipb/doc...?) The pages in the cat{n} directories are generated from the man{n} directories. Manual pages in the man{n} and cat{n} directories must be stored uncompressed, as not all man programs can handle compressed pages. /mit/sipb/man may also contain files that describe what manual pages are available, such as "whatis", "whatis.db", and "windex". In the event that you add or remove a man page from the SIPB locker, please update the man pages indices. [[ Note: instructions on how to do this would be useful. To create the windex file under Solaris, use: catman -w -M /afs/.sipb/project/sipb/man ]] In particular, if you do not update the windex file, man under Solaris will fail to display the man page in question. If updating the windex file is prohibitive, please remove it entirely. 1.13 share /mit/sipb/share contains architecture-independent files used at runtime by software in the SIPB locker. It contains both regular files and subdirectories. A subdirectory is made for any software package that uses a lot of runtime files. 1.14 share/X11 /mit/sipb/share/X11 contains architecture-independent files that can be shared by various X11 applications, such as app-defaults and bitmaps. 1.15 share/X11/app-defaults Most X-Windows software packages use a file called an app-defaults file which describes window layouts in a standard format. To be consistent with a stupid standard established by the X Consortium, the SIPB locker has a subdirectory of /mit/sipb/share called X11 which contains only the subdirectory app-defaults. All app-defaults files are stored here. 1.16 share/X11/bitmaps /mit/sipb/share/X11/bitmaps contains xbm format bitmap files used at runtime by software in the SIPB locker. 1.17 src /mit/sipb/src contains source code for all software in the SIPB locker. Each source tree is in a subdirectory of /mit/sipb/src. The name of the subdirectory is the name of the software package, optionally with the version number appended. As the SIPB locker is a repository of freely-redistributable software, no software may be installed in the SIPB locker unless the source tree is also installed and world-readable. Source trees must be convenient; they are not to be stored tarred or compressed. There should never be any object or binary files in any subdirectory of /mit/sipb/src. 2.0 Hints For Installing Software 1. Download (or write) the source code in a subdirectory of /mit/sipb/src. It is recommended, although not required, that you use RCS to log any changes you make to downloaded software. You do not have to RCS check-in every file as soon as you download the program. It's acceptable to simply remove write-permission from all files, and enter a file into RCS control when you decide to edit it. If you modify a program that someone else installed in the SIPB locker, please use RCS so that the original maintainer may verify your changes. 2. Create a build tree somewhere. In most cases, this build tree is simply a "symlink farm" back to the source tree. Often, you will want to have different Makefiles for different systems. In this case, you should make "Makefile" in the build tree a symlink to "Makefile.@sys" in the source tree; You should not store the Makefile in the build tree. Try to avoid editing Makefiles generated automatically by imake. If possible, try to set it up so that you can build the software with a command as simple as "make all" and so that you can install the software with a command as simple as "make install". If the build/install procedure is complicated, document it in a file in the source tree. Remember that you will not maintain this program in the SIPB locker forever; Others will take over for you. Try to make it easy for them. 3. Test the software before installing it in the SIPB locker. Remember that the SIPB locker is considered a production service. Don't install software that doesn't work. 4. Install the software. Make sure that all installed files went into the proper directories. The proper directory is determined by the first section of this document. [AFS hint: Currently, if you try to install programs in /mit/sipb, the command will fail because /mit/sipb is a read-only AFS mountpoint. To temporarily make /mit/sipb a read-write mountpoint on a machine without the pyhesiodfs automounter, try: detach sipb; attach -t afs -e /afs/.sipb/project/sipb After the program is installed, you can restore the read-only mountpoint with: detach /mit/sipb; attach sipb On a machine with the pyhesiodfs automounter, just recreate the appropriate symlinks: rm /mit/sipb; ln -s /afs/.sipb.mit.edu/project/sipb /mit/sipb To restore: rm /mit/sipb. The automounter will restore it when you use it next. ] 5. Hardcoded pathnames: A program in the SIPB locker should reference it's runtime files through the pathname starting with /mit/sipb. Other pathnames, such as /usr/sipb, /afs/athena/contrib/sipb, or /afs/sipb/project/sipb, are absolutely wrong. If the program is an X11 program, make sure it can find it's app-defaults file. The suggested method is to add /mit/sipb/share/%T/%N to the end of the XFILESEARCHPATH environment variable. To do this, you will probably need to either: (a) write a shell script that edits the environment variable and then runs the actual program, or (b) edit the main() function of the C program. 6. Run the program! It should work. If it doesn't, fix it. 7. Install the software for some more platforms. 8. Send email to bug-sipb@mit.edu announcing what software you have installed or changed. If you installed new software, you might want to send an announcement to the software-announce@mit.edu mailing list. 9. Now that you're a maintainer, you have to respond to bug reports. (Nobody said it would be easy.) Get yourself added to the bug-sipb@mit.edu mailing list, or read the archive in Discuss. If someone reports a problem with your software, fix it.