Keeping up to date

CVSup

CVSup is a software package that distributes updates to the repository. You can run the client at regular intervals—for example, with cron (see page 151) to update your repository.

To get started with CVSup, you need the following:

• A source tree or repository, which doesn't have to be up to date. This is not absolutely necessary, but the initial setup will be faster if you do it this way.
• A copy of the cvsup program. Install it with pkg_add from the CD-ROM (/cdrom/packages/Latest/cvsup.tbz).
• A cvsup file, a command file for cvsup. We'll look at this below.
• A mirror site from which you can load or update the repository. We'll discuss this below as well.

The cvsupfile contains a description of the packages you want to download. You can find all the details in the online handbook, but the following example shows a reasonably normal file:

*default  release=cvs
*default  host=cvsup9.freebsd.org
*default  base=/src/cvsup
*default  prefix=/home/ncvs
*default  delete
*default  use-rel-suffix
*default  compress
src-all
ports-all
doc-all

The lines starting with *default specify default values; the lines that do not are collections that you want to track. This file answers these implicit questions:

• Which files do you want to receive? These are the names of the collections in the last three lines: all of the sources, ports and documentation.
• Which versions of them do you want? By default, you get updates to the repository. If you want a specific version, you can write:

*default tag=version

version is a release tag that identifies the version you want, or . (a period) to represent the CURRENTversion. We'll discuss release tags on page 588.

Alternatively, you might ask for a version as of a specific date. For example:

*default date=97.09.13.12.2

This would specify that you want the version as it was on 13 September 1997 at 12:20. In this case, version defaults to . (a period).

• Where do you want to get them from? Two parameters answer this question: host=cvsup9.freebsd.org specifies the name of the host from which to load the files, and release=cvs specifies to use the cvs release. The release option is obsolescent, but it's a good idea to leave it in there until it is officially removed.
• Where do you want to put them on your own machine? This question is answered by the line *default prefix=/home/ncvs. We're tracking the repository in this example, so this is the name of the repository. If we were tracking a particular release, we would use *default prefix=/usr. The collections are called doc, ports and src, so we refer to the parent directory in each case.

Where do you want to put your status files? This question is answered by the line

*default base=/src/cvsup.

In addition, the file contains three other lines. *default delete means that cvsup may delete files where necessary. Otherwise you run the risk of accumulating obsolete files. *default compress enables compression of the data transmitted, and *default use-rel-suffix specifies how cvsup should handle list files. It's not well-documented, but it's necessary. Don't worry about it.

Which CVSup server?

In this example, we've chosen one of the backup US servers, cvsup9.FreeBSD.org. In practice, this may not be the best choice. A large number of servers are spread around the world, and you should choose the one topographically closest to you. This isn't the same thing as being geographically closest—I live in Adelaide, South Australia, and some ISPs in the same city are further away on the Net than many systems in California. Look on the web site http://www.FreeBSD.org for an up-to-date list.

Running cvsup

cvsup is a typical candidate for a cron job. I rebuild the -CURRENT tree every morning at 3 am. To do so, I have the following entry in /root/crontab:

#Get the latest and greatest FreeBSD stuff.
0 3***./extract-updates

The file /root/extract-updates contains, amongst other things,

cvsup -g -L2 /src/cvsup/cvs-cvsupfile

/src/cvsup/cvs-cvsupfile is the name of the cvsupfile we looked at above. The other parameters to cvsup specify not to use the GUI (-g), and -L2 specifies to produce moderate detail about the actions being performed.

Getting individual releases

The example cvsupfile above is useful if you're maintaining a copy of the repository. If you just want to maintain a copy of the sources of one version, say Release 5.0, use the following file instead:

*default tag=RELENG_5_0_0_RELEASE
*default release=cvs
*default host=cvsup9.freebsd.org
*default base=/usr      for /usr/doc, /usr/ports, /usr/src
*default prefix=/home/ncvs
*default delete
*default use-rel-suffix
*default compress
src-all

Be careful with tags. They must exist in the repository, or cvsup will replace what you have with nothing: it will delete all the files. In our original cvsup file, we had two additional sets, ports-all and doc-all. These sets don't have the same release tags, so if you left them in this file, you would lose all the files in the /usr/doc and /usr/ports directory hierarchies.

Creating the source tree

If you're tracking the repository, you're not finished yet. Once you have an up-to-date repository, the next step is to create a source tree. By default, the source tree is called /usr/src, though it's very common for /usr/src to be a symbolic link to a source tree on a different file system. You create the tree with cvs.

Before you check anything out with cvs, you need to know:

1. What do you want to check out? You specify this with a module name, which usually corresponds with a directory name (for example, src). There are a number of top-level modules, including doc, ports, src and www.
2. Which version do you want to check out? By default, you get the latest version, which is FreeBSD-CURRENT. If you want a different version, you need to specify its tag.
3. Possibly, the date of the last update that you want to be included in the checkout. If you specify this date, cvs ignores anymore recent updates. This option is often useful when somebody discovers a recently introduced bug in -CURRENT: you check out the modules as they were before the bug was introduced. You specify the date with the -D option, as we'll see below.