Computer Club uses collections in AFS for some pieces of software. Usually this software is Computer Club specific, is not available as as a Debian package, or is heavily patched to work in the Computer Club environment.
Creating a New Collection
To create new collection, you will have to create a new AFS volume for the collection's source, and then create a mount point for the volume in the /afs/club.cc.cmu.edu/system/src/local tree. You will also need to create a dest volume for each architecture you're building for that will hold the compiled result.
NOTE: there is a script that will do this for you. However, mdille3 seems to be the only person that knows how to use it, and mkasick doesn't like it because it creates volumes with unlimited quotas. FIXME: how to do this... it really isn't hard. See /afs/club/system/scripts/perl/softmaint.pl.
It is also recommended that you create a SMakefile.
Creating the AFS Volume
AFS volumes for collections have names of the form src.name.revision. The revision will have a "%03d" format. For example, the second revision of the quuxbaz collection would reside on the AFS volume src.quuxbaz.002. Because the maximum length of AFS volume names is 22 as of May 2007, you should keep the name field to a maximum length of 8 characters since dest volume names will contain abbreviated architecture names, some of which are long.
Use the vos create command to create the new volume. The syntax for vos create is included below.
Usage: vos create -server <machine name> -partition <partition name> -name <volume name>
[-maxquota <initial quota (KB)>] [-cell <cell name>] [-noauth] [-localauth] [-verbose] [-encrypt] [-help]
At the present, server should be one of core-afs-0{1,2}.club.cc.cmu.edu and partition will always be /vicepb (the partitions we use for club infrastructure). Name is the name of the volume to be created. Maxquota is typically 50000, although a larger quota may be necessary if the collection software is large.
Creating a Mount Point for the Volume
Collection volumes need to be mounted in the appropriate place in the /afs/club.cc.cmu.edu/system/src/local tree. The mount point for the quuxbaz collection discussed above would be /afs/club.cc.cmu.edu/system/src/local/quuxbaz/002.
Use the fs mkmount command to create the mount point. The syntax for fs mkmount is included below.
Usage: fs mkmount -dir <directory> -vol <volume name> [-cell <cell name>] [-rw] [-fast] [-help]
Next, set the permissions for the mountpoint appropriately. The pts group sysmaint:localboss should have all permissions. If the collection has a commanders pts group, sysmaint:name.commanders, it should also have all permissiosn. Finally, system:anyuser should have read permissions.
SMakefiles
The smake shell script is designed to make building software from collections easier. Smake will read a SMakefile, which contains some variable definitions that instruct smake how to build the collection. The notable variables are:
MFCOMMAND—this tells smake the command it must execute to create a Makefile for the collection (usually "./configure")
INSTCOMMAND—this tells smake the command it must execute to install the collection (usually "make DESTDIR=${DESTDIR} install")
Where do I get this smake script?
There was an admiteddly-very-small-given-everything-else-going-on-in-2020 panic that occurred when the author of this page wanted to re-build a collection and realized at this point he had no idea where to find smake.
This was compounded by the fact find doesn't appear to work correctly in AFS.
But never fear, we did persevere. It's in a collection itself, specifically tools. See /afs/club.cc.cmu.edu/system/src/local/tools/001.
Likely at some point we copied-and-modified some version from /afs/andrew.cmu.edu/system/src/local/tools.
Building a Collection
Building a collection is easy if the collection has a SMakefile.
First, make sure the collection's dest directory exists. The revision 002 of the quuxbaz collection would have the dest directory /afs/club.cc.cmu.edu/system/dest/@sys/local/quuxbaz/002. If the dest directory does not exist, you will need to create a dest AFS volume. Dest volumes have names in the form sys.name.revision. For i386 Linux 2.4 (and higher) builds, sys is x86l24. For x86_64 Linux 2.6 (and higher) builds, sys is x8664l26. For alpha Linux 2.6 (and 2.4) builds, sys is al24. The club-official mapping between these is stored in /afs/club/service/sysnames. Mount the volume in the dest tree, and give it the same ACLs as the source directory.
Build the collection. Smake will create a symlink tree in /usr/obj/local and build the collection there, as disk is much faster than AFS. This is done by running the following commands:
smake init
smake mf
smake mk
Install the collection to the dest directory:
- smake install
Now, tidy up the dest directory, if the INSTCOMMAND in the Smakefile doesn't do the tidying for you. Usually this involves naming directories that should not go in /usr/local root.dir and moving ${DESTDIR}/usr/local/* to ${DESTDIR}.
Installing a Collection
Copy the contents of the collection's dest directory to the stow directory. Eg:
cd /usr/local/stow
rsync -v -rlt /afs/club/system/dest/@sys/quuxbaz/002/ ./quuxbaz-002
Unstow previous revisions if necessary. Eg:
- stow -D quuxbaz-001
Move any directories that should not be in /usr/local to their appropriate locations.
Stow the collection in /usr/local.
- stow quuxbaz-002