Using depot to manage local software collections

About

On Facilitized Unix/Linux hosts, most Facilities-supported and user-contributed software is located in the directory /usr/local. The contents of this directory are updated nightly, by a cron job, from software repositories in AFS. Depot is the program that does the actual updating of the contents of /usr/local.

Depot uses several configuration files to control such things as whether to copy files to the local disk or just make symlinks to the appropriate files in AFS, how to resolve conflicts (identically named files, etc) between collections, and which software collections to install. The file /usr/local/depot/depot.pref.local is the file one modifies in order to change how software is installed in /usr/local on a particular machine. See the man pages for:

• depot
• depot.pref.local
• depot.pref
• depot.conf

for details about depot and these configuration files. For example, type "man depot" on a Facilitized Unix/Linux host to see the manual page for depot. Also, see the section on configuring depot in the local Unix system administration guide.

Note: Depot will fail to run on a host if its configuration files have typos or other errors. If depot fails to run, a host may not get software updates & fixes for important problems such as security vulnerabilities. It is advised that you make a backup copy of depot.pref.local before you modify it and verify that the host depots successfully after making your changes.

How to make some common depot configuration changes

You will need to be root in order to modify depot configuration files. After you have made your changes to /usr/local/depot/depot.pref.local, you can run

   /usr/local/bin/dosupdepot

to test your changes and update the local software on your machine. If you do not manually run /usr/local/bin/bin/dosupdepot, then your changes will not take effect until the next automatic overnight depot run.

On this page:

• How to make a collection local rather than linked to AFS.
• How to add a new software package to /usr/local.
• How to replace entire collection with your own version.
• How to choose a different release of a collection.
• How to replace a specific file in an existing collection.
• How to resolve conflicts between two collections containing files with the same name.

How to make a collection local rather than linked to AFS

Programs stored in AFS can be slow to start. You can trade local disk space for speed by forcing your favorite collections to be copied, rather than linked. To do this with a whole collection, add the following line to your depot.pref.local file:

   collection.installmethod copy collection-name

To copy a single program, use:

   target.installmethod copy <program-name>

Run /usr/local/bin/dosupdepot to have your changes take effect.

How to add a new software package to /usr/local

If you have a local software package not in /usr/local that you would like to appear there, you can add the following line to depot.pref.local:

  path <name-of-collection> <path-to-collection>

Run /usr/local/bin/dosupdepot to have your changes take effect.

For example, if you had a copy of the PBM image utilities in /usr/foo/pbm, then you would add the following line to /usr/local/depot/depot.pref.local:

   path pbm /usr/foo/pbm

You may have built the collection you are creating in the same directory that contains the sources. Depot will blindly copy the sources, along with the other contents of that directory, into /usr/local too, unless you take steps to prevent it. At the new collection tree's top level (in other words, the directory given in the "path" command in depot.pref.local) create a file called depot.conf and in that file explicitly name each directory that should be copied into /usr/local, omitting the directories with the sources. For example, the following lines in depot.conf would instruct depot to copy only the collection's bin and man directories:

   bin
   man

Note: Do not name a directory in depot.conf if it does not exist. Doing so may cause depot to fail.

How to replace an entire collection with your own version

If you need a different version of a misc collection than the default, send mail to help@cs.cmu.edu and we'll pass the message about getting a different version on to the collectin maintainer. If the default version will not change and you must have a different version, you can replace the collection with your own version, though we strongly advise against doing so without good reason. To replace a collection, follow the procedure for adding a new collection (above), but name the new collection with the name of the collection it is replacing. For example, if you want to replace the default version of GNU Emacs in /usr/local with your own version in /usr/foo/emacs, you could add the following line to depot.pref.local:

   path gnu-emacs /usr/foo/myemacs

Then run /usr/local/bin/dosupdepot to have your changes take effect.

How to choose a different release of a collection

To get a different release of a particular software collection than the default, add the following line to depot.pref.local:

   collection.release <release-level> <collection>

For example, if you want the beta release of Framemaker, add the following line to depot.pref.local:

   collection.release beta frame

You can also change the default release level for all collections on a machine by creating the file /etc/releaselevel. n this file, put a single line that names the desired release. Valid release levels are "alpha", "beta", and "omega".

How to replace a specific file in an existing collection

To replace a specific file in an already-existing collection:

1. Create the directory /usr/local/depot/host (there is no collection called "host", so depot cannot become confused by this name).
2. Under this directory, put any files that you want to override the normal ones. Use the same directory structure found under /usr/local. For example, if a collection "foo" uses the file /usr/local/lib/bar and you want to replace the default version of this file, put your version in /usr/local/depot/host/lib/bar.
3. Add the following lines to depot.pref.local:

      path host /usr/local/depot/host
      override host foo
   

   Where "foo" is the name of the collection you are overriding.

If you need to override additional collections, you can add them to the override line. For example, if you want files in your "host" collection to override files in the "foo" & "tex" collections, you can use the line:

   override host foo, tex

in depot.pref.local.

How to resolve conflicts between two collections containing files with the same name

If you have customized a collection, you may have created a situation where two collections contain files with the same name. Depot needs unique names. The solution is for one collection to take precedence over the other. This is done in similar way as the above procedure to replace a specific file in an existing collection. To have files in "collection-1" take precedence over files in "collection-2", place the following line in depot.pref.local:

   override collection-1 collection-2