CVSup's operation is controlled by a configuration file called the "supfile". Beginning with FreeBSD-2.2, there are some sample supfiles in the directory /usr/share/examples/cvsup. These examples are also available from ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/ if you are on a pre-2.2 system.
The information in a supfile answers the following questions for cvsup:
In the following sections, we will construct a typical supfile by answering each of these questions in turn. First, we describe the overall structure of a supfile.
A supfile is a text file. Comments begin with "#" and extend to the end of the line. Lines that are blank and lines that contain only comments are ignored.
Each remaining line describes a set of files that the user wishes to receive. The line begins with the name of a "collection", a logical grouping of files defined by the server. The name of the collection tells the server which files you want. After the collection name come zero or more fields, separated by white space. These fields answer the questions listed above. There are two types of fields: flag fields and value fields. A flag field consists of a keyword standing alone, e.g., "delete" or "compress". A value field also begins with a keyword, but the keyword is followed without intervening white space by "=" and a second word. For example, "release=cvs" is a value field.
A supfile typically specifies more than one collection to receive. One way to structure a supfile is to specify all of the relevant fields explicitly for each collection. However, that tends to make the supfile lines quite long, and it is inconvenient because most fields are the same for all of the collections in a supfile. CVSup provides a defaulting mechanism to avoid these problems. Lines beginning with the special pseudo-collection name "*default" can be used to set flags and values which will be used as defaults for the subsequent collections in the supfile. A default value can be overridden for an individual collection, by specifying a different value with the collection itself. Defaults can also be changed or augmented in mid-supfile by additional "*default" lines.
With this background, we will now proceed to construct a supfile for receiving and updating the main source tree of FreeBSD-current.
As with sup, the files available via CVSup are organized into named groups called "collections". The collections that are available are described here. In this example, we wish to receive the entire main source tree for the FreeBSD system. There is a single large collection "src-all" which will give us all of that, except the export-controlled cryptography support. Let us assume for this example that we are in the USA or Canada. Then we can get the cryptography code with one additional collection, "cvs-crypto". As a first step toward constructing our supfile, we simply list these collections, one per line:
src-all cvs-crypto
With CVSup, you can receive virtually any version of the sources that ever existed. That is possible because the cvsupd server works directly from the CVS repository, which contains all of the versions. You specify which one of them you want using the "tag=" and "date=" value fields.
The "tag=" field names a symbolic tag in the repository. There are two kinds of tags, revision tags and branch tags. A revision tag refers to a specific revision. Its meaning stays the same from day to day. A branch tag, on the other hand, refers to the latest revision on a given line of development, at any given time. Because a branch tag does not refer to a specific revision, it may mean something different tomorrow than it means today.
Here are the branch tags that users might be interested in:
The main line of development, also known as FreeBSD-current. Note: the "." is not punctuation; it is the name of the tag.
The line of development leading up to FreeBSD-2.2.
The line of development for FreeBSD-2.1.x, also known as FreeBSD-stable.
Here are the revision tags that users might be interested in:
FreeBSD-2.1.6.1.
FreeBSD-2.1.6.
FreeBSD-2.1.5.
FreeBSD-2.1.0.
Be very careful to type the tag name exactly as shown. CVSup cannot distinguish between valid and invalid tags. If you misspell the tag, CVSup will behave as though you had specified a valid tag which happens to refer to no files at all. It will delete your existing sources in that case.
When you specify a branch tag, you normally receive the latest versions of the files on that line of development. If you wish to receive some past version, you can do so by specifying a date with the "date=" value field. The cvsup(1) manual page explains how to do that.
For our example, we wish to receive FreeBSD-current. We add this line at the beginning of our supfile:
*default tag=.
There is an important special case that comes into play if you specify neither a "tag=" field nor a "date=" field. In that case, you receive the actual RCS files directly from the server's CVS repository, rather than receiving a particular version. Developers generally prefer this mode of operation. By maintaining a copy of the repository itself on their systems, they gain the ability to browse the revision histories and examine past versions of files. This gain is achieved at a large cost in terms of disk space, however.
We use the "host=" field to tell cvsup where to obtain its updates. Any of the CVSup mirror sites will do, though you should try to select one that's near to you. In this example, we'll use the primary FreeBSD distribution site, "cvsup.FreeBSD.org":
*default host=cvsup.FreeBSD.org
On any particular run of cvsup, you can override this setting on the command line, with "-h hostname".
The "prefix=" field tells cvsup where to put the files it receives. In this example, we will put the source files directly into our main source tree, "/usr/src". The "src" directory is already implicit in the collections we have chosen to receive, so this is the correct specification:
*default prefix=/usr
The cvsup client maintains certain status files in what is called the "base" directory. These files help CVSup to work more efficiently, by keeping track of which updates you have already received. We will use the standard base directory, "/usr/local/etc/cvsup":
*default base=/usr/local/etc/cvsup
This setting is used by default if it is not specified in the supfile, so we actually do not need the above line.
If your base directory does not already exist, now would be a good time to create it. The cvsup client will refuse to run if the base directory does not exist.
There is one more line of boiler plate that normally needs to be present in the supfile:
*default release=cvs delete use-rel-suffix compress
"release=cvs" indicates that the server should get its information out of the main FreeBSD CVS repository. This is virtually always the case, but there are other possibilities which are beyond the scope of this discussion.
"delete" gives CVSup permission to delete files. You should always specify this, so that CVSup can keep your source tree fully up to date. CVSup is careful to delete only those files for which it is responsible. Any extra files you happen to have will be left strictly alone.
"use-rel-suffix" is ... arcane. If you really want to know about it, see the cvsup(1) manual page. Otherwise, just specify it and do not worry about it.
"compress" enables the use of gzip-style compression on the communication channel. If your network link is T1 speed or faster, you probably should not use compression. Otherwise, it helps substantially.
Here is the entire supfile for our example:
*default tag=. *default host=cvsup.FreeBSD.org *default prefix=/usr *default base=/usr/local/etc/cvsup *default release=cvs delete use-rel-suffix compress src-all cvs-crypto