diff --git a/share/doc/handbook/cvsup.sgml b/share/doc/handbook/cvsup.sgml new file mode 100644 index 000000000000..fe3b35ec037d --- /dev/null +++ b/share/doc/handbook/cvsup.sgml @@ -0,0 +1,390 @@ + + + +CVSup + +

Contributed by &a.jdp;. + +Introduction + +

CVSup is a software package for distributing and updating source +trees from a master CVS repository on a remote server host. The +FreeBSD sources are maintained in a CVS repository on a central +development machine in California. With CVSup, FreeBSD users can +easily keep their own source trees up to date. + +

CVSup uses the so-called "pull" model of updating. Under the pull +model, each client asks the server for updates, if and when they are +wanted. The server waits passively for update requests from its +clients. Thus all updates are instigated by the client. The server +never sends unsolicited updates. Users must either run the CVSup client +manually to get an update, or they must set up a cron job to run it +automatically on a regular basis. + +

The term "CVSup", capitalized just so, refers to the entire software +package. Its main components are the client "cvsup" which runs on each +user's machine, and the server "cvsupd" which runs at each of the +FreeBSD mirror sites. + +

As you read the FreeBSD documentation and mailing lists, you may +see references to . Sup was the predecessor to CVSup, +and it served a similar purpose. CVSup is in used in much the same +way as sup and, in fact, uses configuration files which are +backward-compatible with sup's. Sup is no longer used in the FreeBSD +project, however, because CVSup is both faster and more flexible. + +Installation + +

The easiest way to install CVSup if you are running FreeBSD 2.2 or +later is to use either from the FreeBSD or the corresponding , depending on whether you prefer to roll your +own or not. + +

If you are running FreeBSD-2.1.6, you unfortunately cannot use the +binary package versions due to the fact that it requires a version of +the C library that did not yet exist in FreeBSD-2.1.6. You can easily +use , however, just as with FreeBSD 2.2. Simply unpack +the tar file, cd to the cvsup subdirectory and type "make install" + +

Because CVSup is written in , both the package and the port require that the +Modula-3 runtime libraries be installed. These are available as the + port and the package. If you follow the same +directions as for cvsup, these libraries will be compiled and/or +installed automatically when you install the CVSup port or package. + +

The Modula-3 libraries are rather large, and fetching and compiling +them is not an instantaneous process. For that reason, a third option +is provided. You can get statically linked FreeBSD +executables for CVSup from: + + + + (client). + + (server). + + +

Most users will need only the client. These executables are entirely +self-contained, and they will run on any version of FreeBSD from +FreeBSD-2.1.0 to FreeBSD-current. + +

In summary, your options for installing CVSup are: + + + FreeBSD-2.2 or later: static binary, port, or package + FreeBSD-2.1.6: static binary or port + FreeBSD-2.1.5 or earlier: static binary + + +Configuration + +

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 . These examples are also available +from 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 . + +Which files do you want to receive? + +

As with sup, the files available via CVSup are organized into named +groups called "collections". The collections making up the FreeBSD +source tree are described in . 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 two additional collections, "src-eBones" and +"src-secure". As a first step toward constructing our supfile, we +simply list these collections, one per line: + + + src-all + src-eBones + src-secure + + +Which version(s) of them do you want? + +

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: + + + + +

Here are the revision tags that users might be interested in: + + + + +

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. + +Where do you want to get them from? + +

This one is easy. We use the "host=" field to tell cvsup to get +its updates from the primary FreeBSD distribution site, +"cvsup.FreeBSD.org": + + + *default host=cvsup.FreeBSD.org + + +

On any particular run of cvsup, we can override this setting on the +command line, with "-h hostname". + +Where do you want to put them on your own machine? + +

The "prefix=" field tells cvsup where to put the files it receives. +In this example, we'll put the source files directly into our main +source tree, "/usr/src". The "src" directory is already implicit in the +collections we've chosen to receive, so this is the correct +specification: + + + *default prefix=/usr + + +Where should cvsup maintain its status files? + +

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've 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's not specified in the +supfile, so we actually don't need the above line. + +

If your base directory doesn't already exist, now would be a good +time to create it. The cvsup client will refuse to run if the base +directory doesn't exist. + +Miscellaneous supfile settings + +

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 +don't 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 shouldn't use compression. Otherwise, it helps +substantially. + +Putting it all together + +

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 + src-eBones + src-secure + + +Running CVSup + +

You are now ready to try an update. The command line for doing this is +quite simple: + + + cvsup supfile + + +

where "supfile" is of course the name of the supfile you've just created. +Assuming you are running under X11, cvsup will display a GUI window with +some buttons to do the usual things. Press the "go" button, and watch +it run. + +

Since you are updating your actual "/usr/src" tree in this example, you +will need to run the program as root so that cvsup has the permissions +it needs to update your files. Having just created your configuration +file, and having never used this program before, that might +understandably make you nervous. There is an easy way to do a trial run +without touching your precious files. Just create an empty directory +somewhere convenient, and name it as an extra argument on the command +line: + + + mkdir /var/tmp/dest + cvsup supfile /var/tmp/dest + + +

The directory you specify will be used as the destination directory +for all file updates. CVSup will examine your usual files in +"/usr/src", but it will not modify or delete any of them. Any file +updates will instead land in "/var/tmp/dest/usr/src". CVSup will also +leave its base directory status files untouched when run this way. +The new versions of those files will be written into the specified +directory. As long as you have read access to "/usr/src", you don't +even need to be root to perform this kind of trial run. + +

If you are not running X11 or if you just don't like GUIs, you +should add a couple of options to the command line when you run cvsup: + + + cvsup -g -L 2 supfile + + +

The "-g" tells cvsup not to use its GUI. This is automatic if you are +not running X11, but otherwise you have to specify it. + +

The "-L 2" tells cvsup to print out the details of all the file updates +it is doing. There are three levels of verbosity, from "-L 0" to "-L 2". +The default is 0, which means total silence except for error messages. + +

There are plenty of other options available. For a brief list of them, +type "cvsup -H". For more detailed descriptions, see the manual page. + +

Once you are satisfied with the way updates are working, you can arrange +for regular runs of cvsup using cron(8). Obviously, you shouldn't let +cvsup use its GUI when running it from cron. + +Announcements, Questions, and Bug Reports + +

Most FreeBSD-related discussion of CVSup takes place on the +&a.hackers;. New versions of the software are announced there, as +well as on the &a.announce;. + +

Questions and bug reports should be addressed to the author of the +program at .