How to maintain a misc collection

Responsibilities of a misc maintainer

The basic duties of a misc maintainer are to:

Compile and release the collection for as many of the "Facilities supported" platforms as the maintainer has time to support (usually between 3-6 different systypes).
Update the collection to the latest releases available.
Answer user questions regarding the collection in a timely manner. All questions from users are first sent to help@cs.cmu.edu, and are then forwarded to the maintainer if the facilities staff cannot answer the question. We do this so that users don't inundate maintainers with personal mail.

Getting started

Before starting to maintain a collection, you should have a working familiarity with using AFS. You should also look at our other depot-related documentation, such as the instructions on how to configure depot on your local system, and the depot-related man pages referenced in that document. You may find it useful to look at other collections in /afs/cs/local and see how the directory structure and configuration files are set up. Once you've decided to maintain a misc collection, send mail to help@cs.cmu.edu with the following information:

Your SCS userid as well as those of any co-maintainers.
The name of the collection.
A brief description of the collection.
The desired size of the "common" volume, which contains files that are common to all systypes.
The desired size of the src volume.

If you wish to have a separate account to manage your collection (so that you cannot accidentally overwrite a collection area with your SCS userid), please include that in your request.

Once your collection has been set up, notify us and we will do a quick check for any problems with the way the collection has been set up. Once we've done so, and the collection looks like it's set up correctly, we'll add it to the master collection list.

Setting up your collection

The basics

When you set up your collection in AFS, you will have various release areas. Some of these will be for different platforms and some will be common across platforms. The file:

   /afs/cs/local/<collectionname>/common/conf/coll.conf

controls exactly which release areas are used for each system type and release level. See the coll.conf documentation for details on the use and syntax of coll.conf files. Within each area, the file depot.conf controls which files from that area will be installed in which locations relative to /usr/local.

Do not make symbolic links from a release area to other places, since that may cause depot to fail.

Do's and Dont's for setting up collections

Do configure your software to expect itself to be installed in /usr/local. Make sure the software looks for things in /usr/local, not in some directory in AFS. If the software is in AFS, depot will create the appropriate symlinks; if it is copied locally, you don't want to break that by referring to things in AFS directly. Be sure to remember that scripts have paths embedded in them to specify the interpreter.
Don't make symlinks between release areas. Instead, change your collection's coll.conf file to let depot know that you have a common area. Making symlinks between what depot considers to be independent collections can cause serious problems.
Do create a depot.conf if your collection needs one. Many collections do not need a depot.conf if they are set up properly. One reason why you would need one is if you want files from your collection to appear in /usr/local under names different than they appear in the collection's release areas. For example, if your release area contains a file named bin/myprog, but you want it to appear as /usr/local/bin/othername, you would put a line in your depot.conf like:
```
   bin/myprog bin/othername
```
Another example is if there are files in your release area that you don't want to appear in /usr/local at all. So if you had a file named bin/invisible, you cause it not to be mapped into /usr/local with a depot.conf line like:
```
   ~delete bin/invisible
```
See the man page for depot.pref for details depot.conf syntax. Make sure there are no conflicts with other collections. If neccessary, use depot.conf files to map only the files you intend to be publicly available.
Don't export oddly-named files or directories at the top level of your collection. We'd like to keep the top-level /usr/local directory relatively small, so if your collection has directories named "contrib", "source", or "weird-stuff-that-only-this-collection-has" in the top-level of its release area, please use a depot.conf file to prevent these from appearing as /usr/local/weird-stuff-that-only-this-collection-has or whatever. If the package actually needs to reference these files at runtime, map your entire collection to lib/<collectionname>, and then only export the normal directories like bin, lib, etc and so on to the top level of /usr/local.

Recommended platforms

If the software collection is not platform-specific, you should set up your collection for all "current" platforms. These are:

Redhat Fedora 10 (AFS systype 32-bit i386_f10, 64-bit amd64_f10)
Redhat Fedora 7 (AFS systype 32-bit i386_f7, 64-bit amd64_f7)
Redhat Fedora Core5 (AFS systype 32-bit i386_fc5, 64-bit amd64_fc5)
Redhat Fedora Core 3 (AFS systype 32-bit i386_fc3, 64-bit amd64_fc3)
Solaris 10 (AFS systype sun4x_510)
Solaris 9 (AFS systype sun4x_59)

Unless there is a specific reason to do so, you should not feel obligated to compile your collection for older platforms.

Where to compile collections

There is a general-purpose host available to misc maintainers for all supported platforms. For a particular AFS systype, the name of this general-purpose host is: <afs systype>.sp.cs.cmu.edu with the "_" in the systype replaced with a "-". For example, the general-purpose Redhat 7.1 host is:

   i386-rh71.sp.cs.cmu.edu

Send mail to help@cs.cmu.edu if you need an account on any of these hosts in order to compile your collection.

Testing changes to depot.conf

If you want to test changes to your depot.conf, you can run the following commands:

   mkdir /tmp/mytestlocal /tmp/mytestlocal/depot
   grep -v target /usr/local/depot/depot.pref.global > /tmp/mytestlocal/depot/depot.pref.global
   /usr/local/bin/dosupdepot -targetarea /tmp/mytestlocal

This will cause /tmp/mytestlocal to look like /usr/local will look after depot runs that night. For the test to be valid, you will also need to remove the depot.image file in the top level of your collection's release area(s) if you have added, moved, or removed any files from your collection. These files are regenerated every night, so removing it will never cause any harm.

Testing a new collection

If you want to test a new collection before it is added to the master collection list, run the following commands:

   echo 'mynewcollection' > /usr/tmp/extralist
   /usr/local/bin/dosupdepot -extralist /usr/tmp/extralist

You'll need to be root to run dosupdepot unless you use the "-targetarea" flag as in the previous example.

Releasing a replicated volume

When you create a misc collection, it goes on a read/write AFS volume under the path /afs/.cs.cmu.edu/ (note the "." in front of "cs.cmu.edu". These copies are read-only -- they cannot be modified. When you make a change to the read/write volume, the changes will not appear until the volume is released. This process happens automatically every night, but you can make it happen yourself using the usr/local/etc/miscgen command. Use the -h option to see a list of accepted arguments.