OK, you're ready to take the plunge into the wonderful world of /uns package maintenance. I assume you've already read the users' unFAQ, so you know what /uns is all about (and why this document is called an unFAQ).
Please send comments, additions, and corrections regarding the unFAQ to the /uns coordinator, unsadmin@cs.washington.edu.
A package maintainer is responsible for one or more installed software packages in /uns. As a maintainer, your job is to keep your packages functional and up-to-date, and to field problem reports from your packages' users.
In case you got here by mistake... you don't have to be a package maintainer to use the software in /uns. Becoming a maintainer just gives you write access to the various /uns partitions, which (outside of a few globally writable directories in /uns/share) should never be required simply to use the programs in /uns.
First, read this unFAQ. Then, send an email request to unsadmin@cs.washington.edu asking to be added to the maintainers' group. Please state which package(s) you plan to install or modify. (If you don't know yet, that's OK.)
The /uns coordinator will add you to the group, put you on the mailing list uns@cs, and grant you write access to the /uns partitions. You will receive a welcome email when your request is processed; within about two hours of receiving this mail, you should be able to write to /uns.
If you're leaving the department or don't want maintainer access any longer, send email to unsadmin@cs.washington.edu asking to be removed from the group. Your request will be processed similarly to add requests as described above, except that you won't get a confirming email.
Note that you will still own any files you've created in /uns until your CSE account is deleted, which means that if a package you maintained breaks, you'll still get mail about it. Hence, you should arrange to pass on maintenance of your packages to someone else and preferably give them ownership of the packages' files. Please note that the /uns coordinator is unlikely to take over maintenance of your packages.
The Lab is in charge of granting write access to the Windows /uns partition. Send mail to support@cs asking to be added to the group. Note that joining one maintainers' group (Windows or UNIX) does not automatically grant you write access to the other's partition.
Mail sent to the list address uns@cs is forwarded to everyone in the UNIX package maintainers' group. If your message is of interest to users as well as maintainers, consider instead posting it to the /uns newsgroup, uw-cs.apps.announce.uns, or, equivalently, sending it to the mailing list cs-apps-uns@cs (which is gated to the newsgroup).
Please do not send messages intended for the lists to unsadmin; this alias goes only to the /uns coordinator. Conversely, don't send requests to be added to or removed from the maintainers' group to the lists.
Any software which can legally be installed for department-wide use is OK for /uns. Check your package's license before you install it. Most /uns packages are open-source and are compiled locally, but these are not requirements.
Any type of software is fine for /uns, but please keep installation of games to a minimum unless they're being used for research or instructional purposes. The machines which mount /uns are technically state-owned computing facilities, and folks outside the department tend to frown on the use of such facilities for playing games. We've had some trouble with this issue in past years because anyone with a port scanner can see game servers running on our machines.
Please check before you install a package to make sure that the same or newer version is not already supported (e.g. in /usr or /usr/local). You may supersede a supported package with a newer version in /uns, even if doing so would "shadow" the supported package for people who put /uns in their paths before /usr or /usr/local. For example, installing Tcl 8.3 under the name /uns/bin/tclsh would be OK even if doing so shadows Tcl 8.0 under the name /usr/bin/tclsh.
Before shadowing an older version of a package (either supported or in /uns) with a newer one, please consider carefully whether doing so is likely to cause problems for users of the older version. For example, newer g++ versions frequently fail to compile code that worked fine with older versions but does not strictly comply with the ANSI C++ standard.
If upgrading a package substantially breaks compatibility for users of the older version, you should not immediately shadow the older version. Instead, install the new version under a different name, then plan and announce the migration. After a decently long interval, you can change the newer version's name so as to shadow the older version.
If you want to install or upgrade a package, and you think that the
upgrade might destroy parts of an existing package, do
not simply delete or overwrite the existing files.
Instead, create a directory DELETED and move the old
files there. This is just common courtesy if you're replacing someone
else's files, but it can also save your butt if the new version of the
package doesn't work properly and you need to back out your changes!
Later, if all is well, you can remove the contents of the
DELETED directory.
You should be especially aware of the potential for overwriting files
in the cross-platform shared hierarchy /uns/share. Installing a package
on one platform might inadvertently destroy shared configuration files
from the same package on another platform. To avoid overwriting shared
files, you can rename the shared directory out of the way, install, and
rename it back. (Do this late at night on a weekend when it's unlikely
to annoy the package's users.) Alternatively, some packages allow you
to install only the architecture-specific bits with the
command make install-exec.
/uns is maintained on multiple platforms. Although not all these platforms are in wide use in the department, you should be aware that they exist and plan your installation accordingly. A given package need not be installed on all platforms, and it can have different maintainers on different platforms. Still, if you can install your package for the most commonly-used platforms (Linux, FreeBSD, and Solaris), please consider doing so.
It's up to you. Enable all features that make sense for our environment and are likely to be used. However, don't sweat this issue. If you leave something important out, your users will let you know, at which point you can rebuild the package or dare them to rebuild it themselves.
Installing a package in /uns requires four steps:
For a step-by-step description of the recommended installation and documentation steps, see file /uns/encap/0-ENCAP-HOWTO. The /uns/encap/0-ENCAP-HOWTO file is sufficient in many cases. This document expands on, and explains the rationale for, the procedure described in /uns/encap/0-ENCAP-HOWTO.
Please read the recommendations in this document and in /uns/encap/0-ENCAP-HOWTO at least once and try to follow the guidelines when installing new packages. These guidelines are neither mandatory nor exhaustive; use your own good taste to decide when they should be ignored.
Use the Encap package management system. Encap lets you install each package in its own directory, but it makes symbolic links from (for example) /uns/bin. This simplifies users' environment setup.
In the simplest case, if the package is distributed as a compressed tar file and is built via the standard commands "./configure; make; make install", then you can use Punyashloka Biswal's install_generic shell function, which is defined in /uns/src/generic-builder.sh. For example:
source /uns/src/generic-builder.sh PKG=graphviz-2.20.3 install_generic $PKG http://www.graphviz.org/pub/graphviz/stable/SOURCES/$PKG.tar.gz
If you need/want to perform the steps manually, see /uns/encap/0-ENCAP-HOWTO, which also explains each of the steps of install_generic. If you need more information, see the Encap website and the epkg and mkencap man pages.
Java libraries should be packaged as jarfiles (if they are not, then make a jarfile yourself). All the jarfiles for a single logical package foo version x.xx should be installed in a fresh directory
/uns/encap/foo-x.xx/lib/java-jars/foo-x.xx
If your package has an executable component, you might also want to write a shell script that starts up the application; place this at
/uns/encap/foo-x.xx/bin/appname
where appname is the application name.
Then, use the usual encap installation procedure.
Note that the following two scripts will, if sourced in your startup script automatically add every jar in /uns/lib/java-jars/*/*.jar to your CLASSPATH:
Some packages (e.g., GNOME, KDE) are not encap-friendly. Fortunately, these packages are few. Place each package foo-x.xx in a separate subdirectory /uns/opt/foo-x.xx.
For your convenience, and the convenience of other users, you may wish to create symbolic links and/or shell scripts for starting up these packages in the main /uns tree. This would allow users to use your packages without adding yet more directories to their PATHs. If you'd like to do this, then create an encap-controlled tree under /uns/opt/foo-uns-x.xx, and install it using encap.
All directories created in /uns should be owned by group
uns and should allow write access by this group. These
permissions allow any maintainer to copy, move, or delete your
packages' files (possibly after you're long gone!) but prevent others
from carelessly overwriting these files.
Create a file /uns/src/package-version.BUILDING that documents how you installed the package, including what compiler and flags you used, any flags passed to configuration scripts, and any changes you made to the source to get it to work. Ideally, this file should be able to be executed (or its contents cut-and-pasted into a command shell) in order to exactly duplicate the installation. Store any changes to the source as diffs against the original, in a separate file /uns/srcpackage-version.patch.
To keep track of exactly which commands you typed during installation,
consider using the script program (run man 1
script for details). Emacs users can get the same benefits by
doing the install from shell mode and then saving the shell buffer.
Put the tarball in /uns/src and/or record its URL in the BUILDING file (probably in the form of a wget or curl command). This is important both to allow future maintainers to find the source and to help the department to prove that the software is legitimate if /uns is ever audited.
Please compress the archives you store in /uns/src. The partition has limited space and is shared among all /uns platforms. Also, an installed package should never depend on files in /uns/src for correct operation.
Announce the availability of the new or upgraded package on the /uns newsgroup, uw-cs.apps.announce.uns, or the mailing list cs-apps-announce-uns@cs (which is gated to the newsgroup).
(As of 2007 or so, the cs-apps-announce-uns mailing list has fallen out of use, and maintainers tend to announce new/upgraded packages to uns@cs.washington.edu instead.)
Allowing either devices or setuid binaries could open up serious security holes that would let an attacker compromise all the systems which mount /uns. In short: forget it. On all supported machines, the /uns partitions are mounted with the nodev,nosuid flags.
If you need to create devices or setuid binaries for your own work, consider running your machine as an untrusted host. Ask the CSE Lab staff for details.
You should build a binary that will run correctly on every machine that mounts a given /uns partition. However, /uns partitions are not shared across totally different machine architectures, and currently there are basically two active machine architectures:
-march=pentiumpro should be fine.