This is supposed to be a brief introduction to using the Concurrent Versioning System (CVS), which is used by the WarpIN and XWorkplace projects (and many others too) to access and manage source codes.

WarpIN and XWorkplace are hosted on the CVS server at the OS/2 Netlabs [netlabs.org], where you will also find the sources of the other Netlabs projects such as Odin [netlabs.org].

You will be interested in this if you want to look at the source codes of these projets, or even better, if you want to contribute. In other words, this is for people familiar with C/C++ programming. If you have never written a C program before, you will probably not be interested in this document.

Essentially, this document is a formatted version of the cvs.txt file which resides in the xworkplace repository.

Introduction To CVS

CVS stands for "Concurrent Versioning System". It is a tool which allows several developers to work on the same source code at the same time.

For those of you that have never dealt with anything like this... just imagine a word processor document on a shared network directory that several people work on at the same time. There has to be some coordination of all the changes going on and checks whether the changes conflict with each other.

CVS does exactly that, except that it can handle large directory trees with many files of any type — text or binary.

The concept of a client/server CVS setup is that the server maintains a "repository" with the entire source code, including all changes that were ever made. Each developer then creates a local copy of the sources on his hard disk. So each developer can safely work on the local sources until he thinks that everyone else should get the changes (once they're halfway stable), and can then put the changes on the server, and all other developers can then update their local copy.

While your local copy will always be at a certain code/revision level (and only updated from the server if you request this), the server maintains all changes that were ever made. You can, for example, even retrieve the sources in the state were in in the middle of 1999, if you want.

Maybe the nicest thing about CVS is that with text files, it can merge code changes. CVS has GNU "diff" built in so even if two people work on the same source file, CVS in most cases can automatically keep the changes in sync. See "Terminology" below.

Netlabs has set up a CVS server on which all the Netlabs projects reside. This document should give you all the information about how to access that repository. ftp://ftp.netlabs.org/pub/nosa/archives.lst [netlabs.org] is frequently updated and lists all repositories presently hosted on Netlabs.

Which CVS Version to Use

CVS is a GPL'ed Unix program that was ported to OS/2. At the time of writing, there are several CVS versions on Hobbes [nmsu.edu] I strongly recommend to use 1.10.6, which is the most bug-free of them all. While 1.10 might still work OK, 1.10.7 causes tons of problems. Do not use it. — Update: CVS 1.11 appears to be working fine here too.

Setup

You can use the Netlabs Open Source Archive Client (NOSAC) [netlabs.org] instead of running CVS from the command line. However, I have found the command line much more practical, so I am going to explain the basics here. Please refer to the CVS documentation for details.

As with most Unix programs, CVS expects you to have a "home" directory. If you don't have one, create an empty directory somewhere and set the HOME environment variable to that directory through CONFIG.SYS.

In any case, I strongly recommend to create a file in $(HOME) called .cvsrc (mind the unixish leading dot, so FAT won't work) and add put a single line with
```
    cvs -z9
```
in there to enable maximum compression during transfers. This greatly speeds up things if you have a slow internet connection. Otherwise CVS will do all network transfers with uncompressed data, which can be terribly slow.
The most practical way to use CVS is to have a common parent directory for all code repositories (i.e. projects). So create one (for example, F:\cvs), which will become the parent directory for all CVS projects (e.g. F:\cvs\xworkplace, F:\cvs\warpin, F:\cvs\xwphelpers). If you later check out repositories from sources other than Netlabs (e.g. from SourceForge [sourceforge.net]), they can go into this root as well.
Next, CVS needs you to have a user name and a password. Unless you have been assigned one by the server administrator, use guest and readonly, which will give you read-only access to all Netlabs projects. (Other servers will have different conventions here.)
Set the current project environment. This is done via another environment variable CVSROOT, so for XWorkplace, set:
```
    CVSROOT=:pserver:guest@www.netlabs.org:/netlabs.cvs/xworkplace 
```
For WarpIN, use:
```
    CVSROOT=:pserver:guest@www.netlabs.org:/netlabs.cvs/warpin 
```
For the "XWorkplace helpers", which are needed by both XWorkplace and WarpIN, use:
```
    CVSROOT=:pserver:guest@www.netlabs.org:/netlabs.cvs/xwphelpers 
```
and so on. Currently, Netlabs holds over a dozen projects which can all be retrieved that way.

Update: The CVSROOT path was changed in February 2002 for all Netlabs projects. From your old CVSROOT variables, simply remove the "e:" before "/netlabs.cvs". You will need to run "cvs login" again to have CVS pick up the change (see below).
Create a local subdirectory in your CVS root directory with the same name (e.g. F:\cvs\xworkplace).
Change to that directory.
Set USER=guest in your environment.
Fire up your internet connection.
To log on to a project, use the cvs login command. Enter readonly when you are prompted for the password. (Note that you will need to enter cvs login separately for each repository. CVS will then store the data in $(HOME)\.cvspass so you only need to do this once per project.)

You are now ready to download ("check out") a project.

CVS Terminology

The following terms should be known when working with CVS (or even reading the documentation):

A "repository" is the unit CVS uses for managing projects. For example, "xworkplace", "warpin", and "xwphelpers" are three repositories on the Netlabs CVS server. Repositories are mirrored locally in a subdirectory of your CVS root directory, if you followed the above setup.

Repositories are usually equivalent to projects. However, repositories are just a directory on the server and can be created in any way. For example, we created the "xwphelpers" repository for code that is shared between XWorkplace and WarpIN.

Again, ftp://ftp.netlabs.org/pub/nosa/archives.lst [netlabs.org] lists all repositories presently hosted on Netlabs.
"Checkout": "Checking out" code means that you retrieve (or update) a local copy of files in a repository. You can check out an entire repository or single files from it.

To check out code, use the cvs checkout command. Details follow in the next section.
"Commit": If you have write access to the CVS server (which requires that you have been given a user name and password by the server administrator), you can change the repository by "committing" your local copy back onto the server. Once the code has been committed, all other developers can check it out again and will have the updates.

To commit code to the server, use the cvs commit command. See the CVS reference for details. Again, this requires that you have been granted write access by the server administrator.

With most projects, only a limited number of people have write access to the server, for obvious reasons. Contributors will then usually send patches to one of the people with write access, which then commit those changes if they consider them useful. For example, with Linux development, those people are the well-known kernel maintainers, which can be very restrictive in allowing changes in. But this is a "project policy" issue and not a CVS restriction.

With XWorkplace, I am the only one with write access presently.
"Merge": Merging might be necessary if you have checked out your local copy of a repository already and do another "checkout" later.

If CVS then finds that a file has been changed on the server and your local copy needs to be updated, it "merges" all changes into the local copy. That is, it does not simply overwrite the local copy with the new version on the server, but will compare (diff) the two files and patch the local copy! As a result, you will not lose changes you made to your local copy when you check out updates.

CVS has GNU "diff" built in for this, so this is pretty powerful.

This happens automatically if you do cvs checkout after your initial checkout. Note that you can also use cvs update; the difference is that "update" will not retrieve new files, but only update existing local files. See the CVS reference for details.
"Conflicts": These occur if CVS cannot successfully merge changes into your local copy. Most frequently, this happens when two developers have modified the same lines in the same source file. Of course, CVS cannot resolve these conflicts by itself, so it will put two versions into the file marked with special characters. (With C files, this will cause compilation to fail, which is intentional so that you have to manually resolve the conflict.)

See the CVS reference for details.

Checking Out the Code

We'll use the XWorkplace main repository as an example here.

Change to your local XWorkplace root directory (e.g. F:\cvs\xworkplace), set the XWorkplace environment as described above (HOME, USER, CVSROOT), and do a cvs logon if you haven't logged on yet.

The command for getting source from the server is cvs checkout. With checkout, you need to specify the module to check out. For the purpose of this explanation, we will consider a "module" a directory name. Note that CVS normally operates on directories recursively! So if you use

    cvs checkout .

(mind the dot) from the XWorkplace root directory, this will retrieve the entire current code tree and create new local files if they don't exist yet. This can take a while for bigger projects. Again, use maximum compression (see "Setup" above).

cvs checkout allows you to specify file masks as well. For example, if you type

    cvs checkout src/shared/*.c

only those files are checked out. Mind the forward slashes.

Update: You can also retrieve a specific revision of the source tree or certain parts of it by using the -r option. This is most useful with tags, which are symbolic names assigned to a state of the tree at a given point of time. I am now tagging the source trees with each release so that you can retrieve the tree in the exact state that it was in when the release version was compiled. On the XWorkplace "download" page, I am listing the tags to use to retrieve a specific version. For example,

    cvs checkout -r umoeller_0007_0-9-19 .

will retrieve the sources for V0.9.19.

By contrast, cvs update only updates local files which have been changed on the server. It does not create new files. Since I frequently create new files on the server, using "checkout" will probably be the better general choice.

Note that to compile XWorkplace, you will also need the "XWorkplace Helpers" code, which is in a separate repository called xwphelpers. So create a new empty project directory (e.g. F:\cvs\xwphelpers), set CVSROOT accordingly, change to the new directory, and do a cvs checkout . again.

CVS Messages

You will see while your CVS client is running, it throws tons of cryptic messages at you with information about the files that are currently being worked on.

I strongly recommend redirecting standard output when using "update" or "checkout" so you know what CVS has done, since these lines scroll of the screen very quickly. You can simply use

    cvs checkout . > checkout.log

An even better choice is tee, another GNU program, which prints the output to the screen and logs it into a file at the same time.

A typical CVS output from "update" or "checkout" looks like this:

? doc/progref.ipf

M makefile

M include/build.h

M include/filesys/program.h

M src/classes/xcenter.c

In each such line, the first letter tells you what CVS has done to the file:

?: CVS does not know the file. It is in your local tree, but not in the repository. This happens if you have added files to your local copy yourself — most frequently with files created by the build process.
U: This is the most frequent one. It means that CVS has "U"pdated a local file with a new copy from the server and occurs during "checkout" or "update".
P: Similar to "U", except that the server has only sent a "P"atch instead of the entire file. The result isn't any different from "U"; the file has been updated.
M: This means that CVS detected that your local file was "M"odified before the update, i.e. it is different from the one on the server. This happens if you have edited files in your local copy. You get the "M" no matter if the file was updated (i.e. changes were merged successfully) or not.
C: This happens if merge failed and a "C"onflict occured. You will need to manually edit all files which have been marked with "C"; if they are C source files, CVS has modified them on purpose and marked the conflicting sections, so they will no longer compile.
R: A local file has been removed because it is no longer in the repository (i.e. has been removed by someone with write access).

Project Policies

At present, I am the project maintainer (in other words, contact person) for three repositories on Netlabs:

xworkplace has the main XWorkplace code. At present I am the only one who has write access to that repository.
warpin has the main WarpIN code. Besides myself, Cornelis Bockemühl and Teemu Ahola have write access.
xwphelpers has lots of helpers code that is shared between WarpIN and XWorkplace, but could be used by other projects too. Essentially, all code in this repository has been isolated to be independent of any single project and could be used anywhere. It's all plain C code and can be linked into a LIB. At present only I have write access.

More information (most importantly, how to compile and link) can be found in the respective readme files in each repository.

If you'd like to contribute to any of these projects, the easiest way to do it is produce a diff file between your modified local sources and the CVS version. Then send me the diffs so I can see what you changed and possibly commit your changes.

GNU diff is available at Hobbes [nmsu.edu]. Please use diff -u to give me two lines of context for each change.

CVS also has a diff option which will produce the diff between the server repository and your local changes. Again, please use the -u option as well.

More Information

This was only a quick introduction to give you access to the source codes of my projects on the Netlabs CVS server. The CVS packages contain two INF books, one titled "Introduction to CVS", the other one being the (mostly) complete CVS command reference, which should contain most of what's needed to work with CVS.

At times, CVS can be pretty stubborn too and will refuse to do what you are telling it to do. It should also be said that the CVS error messages are not always optimal, and it can be difficult to guess what CVS is really complaining about. If you have problems getting my sources from CVS, feel free to ask on one of the developer mailing lists (see contact), and we'll try to help.

CVS

Site Map

Main Text