[OpenBSD]

Anonymous CVS

What is Anonymous CVS?

Anonymous CVS is a method of keeping your local copy of the OpenBSD source tree up to date with respect to changes made to current OpenBSD sources. In addition to following the bleeding edge of development, it is also possible to track the patches for errata of a release.

The major advantage of Anonymous CVS over other source code update techniques is that it works directly against a central source code repository or mirror. This means that you have the full set of CVS commands available to control merging and updating your changes with other source changes and for performing diffs, change histories and other queries against the central repository.

The OpenBSD Project currently has four active and two historic source repositories:

To summarize, the real strength of using Anonymous CVS is that it is a "tolerant" source code control system - it respects changes that you have made to your local sources and makes "best efforts" to update your entire source tree, rather than leaving you a list of arcane problems that have to be resolved before continuing.

What is CVS?

CVS is the source code control system used to manage the OpenBSD source tree. It implements a central repository for all officially released source code and changes, while permitting developers to maintain local copies of the source code with their working changes. There are two levels of source tree access:

The major strength of CVS is that it has the ability to perform intelligent merges of changes to the central repository with changes that you make to your local copy. This means that if you make a change to a module and perform an update, your changes are not "blown away", rather CVS makes best efforts to merge the changes made to the central sources with changes you've made to your local copy.

In the event that the changes can't be completely merged, CVS provides a "soft fallback", providing you with annotated changes to your local copy, preserving an unmodified copy of your version and continuing to update any other source modules you requested.

Getting crypto sources through cvs(1)

IMPORTANT NOTE: There are a few issues relating to cryptographic software that everyone should be aware of:

Getting Started Using Anonymous CVS

While you can download the entire source tree from an AnonCVS server, you can often save a lot of time and bandwidth by "preloading" your source tree with the source files from either the OpenBSD CD or from an FTP server. This is particularly true if you are running -stable, as relatively few files change between the -release and -stable.

To extract the source tree from the CD to /usr/src (assuming the CD is mounted on /mnt): 

    # cd /usr/src
    # tar xzf /mnt/src.tar.gz
    # cd /usr
    # tar xzf /mnt/xenocara.tar.gz
    # tar xzf /mnt/ports.tar.gz
The source files for download from the FTP servers are separated into two files to minimize the time required to download for those wishing to work with only one part of the tree. The two files are sys.tar.gz, which contains the files used to create the kernel, and src.tar.gz which contains all the other "userland" utilities. In general, however, you will usually want both of them installed. Assuming the downloaded files, src.tar.gz, sys.tar.gz and xenocara.tar.gz are in /usr: 
    # cd /usr/src
    # tar xzf ../sys.tar.gz
    # tar xzf ../src.tar.gz
    # cd /usr
    # tar xzf xenocara.tar.gz
    # tar xzf ports.tar.gz

Not all people will wish to unpack all the file sets, but as the system must be kept in sync, you will generally need to set up all trees.

You can also just use cvs(1) to "checkout" the source repository for you. This is discussed in the next section.

After this, /usr/src will be a nice checkout area where all cvs(1) commands will work properly.

Using CVS to Get and Update your Source Tree

CVS was designed to be a simple way to retrieve and update your sources. You must first decide whether you want to track -current or a patch branch. The current tree has all of the up to the minute changes, whereas a patch branch contains a formal release plus the patches from the errata and lesser issues already applied. For more information on these "flavors" of OpenBSD, see here.

Once you have decided which tree to follow, you must choose which Anonymous CVS server you are going to use. A list of these servers is below.

Once you have chosen which Anonymous CVS Server you will use, you can start using cvs. For those of you who have CDs you can start with the CVS checkout that is on the CD by using the method above to get the sources onto your system. If you don't have a CD handy, use the method below to checkout the sources.

To use ports, it is similar to src:

In the above example, -q is optional, only intended to minimize cvs's output. For those who like to see screenfulls of output, it can be omitted.

To make a diff of a locally patched module (here cd.c) to include with a bug report: 

	# cd /usr
	# cvs diff -u src/sys/scsi/cd.c > /tmp/patch

The cvs(1) man page (included with the CVS sources) has much more information about how CVS can be used.

Warning: When using cvs you should take care that your current directory is either the root of the tree you are referencing or in a separate place such as /tmp. Some commands such as "get" can create an arbitrary sub-tree in the current directory, and a subsequent update will recursively flesh out this sub-tree.

The anoncvs service gives fledgling developers a chance to learn CVS operation and get thoroughly involved in the development process before getting "commit" access -- as a result of showing useful skills and high quality results they will naturally later be given developer access. As well, people providing patches can create their "diff"s relative to the CVS tree, which will ease integration.

Example usages for cvs(1)

A sample use of an anoncvs server would be: 

$ cd /tmp
$ cvs -d anoncvs@anoncvs.ca.openbsd.org:/cvs get src/sys/arch/sparc
    [copies the files from the repository to your machine]
$ cd src/sys/arch/sparc
$ cvs log locore.s
    [shows the commit log for the chosen file]
$ cvs diff -bc -r1.1 -r1.5 locore.s
    [shows the changes between revisions 1.1 and rev 1.5]

Available Anonymous CVS Servers

Note: If your server is listed on here with inaccurate or unknown information, please contact beck@openbsd.org

You may want to use traceroute(8) to find out which server is nearest you. Problems with a server should be reported to the maintainer of the server in question.

If local policy prevents outgoing connections to ssh's default port of 22, some servers permit connections on an alternative port (typically 2022). These are noted in the list above. To use a different port, reconfigure your ssh client by adding a "Host" entry to $HOME/.ssh/config, e.g.: 

       Host anoncvs.ca.openbsd.org
           Port 2022

Setting up an anoncvs mirror

If you wish to setup a new anoncvs mirror site and make it available to the general public, please contact the anoncvs maintainer. Anoncvs mirrors currently require about 5GB of disk (and it will grow!), and use up to 32MB of swap per anoncvs user (assuming the user does a large operation; while smaller operations use fewer resources, anoncvs still makes much more of an impact than ftp). Such anoncvs machines should have excellent network connectivity for the area they are expected to serve. A document which describes the setup of anoncvs servers is available.

Final notes

After upgrading your source tree, you should read the comments at the top of /usr/src/Makefile before attempting a build. Also, you should build a new kernel before doing a make build if possible. In some cases it may be necessary to rebuild and install the config utility before you can build the kernel. If config GENERIC fails this is probably the case.

It is important to note that upgrading from a release to the current tree by rebuilding the sources can be rather difficult due to dependencies that are often not obvious. Therefore, it is suggested that you first install the latest snapshot before attempting a tree build from source.