Bochs User Manual
Prev | Chapter 3. Installation | Next

# Tracking the source code with CVS

CVS, or Concurrent Version System, is a software development tool that helps to keep track of the different revisions of each file. It is used by many open source (and commercial) projects to allow multiple developers to share their changes to the source code. The Bochs source code and documentation are available using CVS[1].

## Checking out Bochs

When you have CVS installed, the first step is to do a login and checkout. The initial checkout command is long and ugly, but usually you only have to do it once. The example below shows the CVS checkout process in UNIX. On the Windows platform, you can download a CVS client from cvshome.com, or use CVS within Cygwin[2].

Figure 3-1. Checking out Bochs in CVS

      user$ cvs -d:pserver:anonymous@cvs.bochs.sourceforge.net:/cvsroot/bochs login
      (Logging in to anonymous@cvs.bochs.sourceforge.net)
      CVS password:    (there is no password, just press Enter)
      user$ cvs -z3 -d:pserver:anonymous@cvs.bochs.sourceforge.net:/cvsroot/bochs checkout bochs
      cvs server: Updating bochs
      U bochs/.bochsrc
      U bochs/.conf.AIX.4.3.1
      U bochs/.conf.beos-x86-R4
      U bochs/.conf.macos
         .
         .   (This might take a few minutes, depending on your network connection.)
         .
      U bochs/patches/patch.seg-limit-real
      user$ cd bochs
      user$ ls
      Bochs.proj.hqx  bxversion.h   fpu/                osdep.cc
      CHANGES         config.h.in   gui/                osdep.h
      COPYING         configure*    install-x11-fonts*  patches/
      CVS/            configure.in  instrument/         pc_system.cc
      Makefile.in     cpu/          iodev/              pc_system.h
      README          bx_debug/     load32bitOShack.cc  state_file.cc
      TESTFORM.txt    disasm/       logio.cc            state_file.h
      bios/           doc/          macintosh.txt       win32.txt
      bochs.h         docs-html/    main.cc
      bochs.rsrc.hqx  dynamic/      memory/
      build/          font/         misc/
      user$ _

> Tip: If you have write access to the Bochs CVS tree, the checkout command is different for you. See the Developers Guide[3] for details.

> Tip: If you use remote CVS for other projects, you might have already set the environment variable `CVS_RSH` in your configuration files. For the CVS checkout to work as shown above, the `CVS_RSH` variable should either be empty or set to `rsh`.

The CVS checkout process (above) gives you a directory called bochs that contains the very latest source code. I will refer to this directory as `$BOCHS`. In each subdirectory directory there's also a directory called "CVS" which tells the cvs software where the code was checked out, what version you have, and where to go for future updates.

## Getting the Latest Version

Most developers use CVS to always give them the latest source code. The minute that any developer checks in a change, they are available to everyone else through CVS. You just have to type cvs update -d -A in the `$BOCHS` directory, and CVS will retrieve any files and directories that have been changed since you did a checkout. If you update regularly, each update takes a short time because it downloads only the files that changed. The -d option tells cvs to download new directories that have been checked in, not just files. The -A option means to get the most recent version of each file, as opposed to a release version. See Getting a release version Both -d and -A can be omitted in many cases, once you are familiar with the process.

The cvs update -A -d command tells you if any new files have been downloaded from the server, and it also tells you if you have modified any of the CVS-controlled files. As it checks through the source directories, it will list files that have changed, with a single letter before the name that tells the status of that file. The most common status letters are listed below.

Table 3-1. Status letters in a CVS update

Letter | Meaning | Description
--- | --- | ---
? | unknown | This file is in your bochs directory, but CVS does not know anything about it. For example, when you compile Bochs, any files created during the build process appear as ?.
U | update | cvs downloaded a new version of this file because it changed on the server, usually because someone else did a checkin.
P | - | P is the same as U, as far as I can tell
M | modified | You have changed this file on your disk, so it no longer matches the version on the server. This is not a problem; it's just for your information. If you want, you can discard your changes and get a fresh copy by deleting the file and running cvs update again.
C | conflict | You have changed this file on your disk, but this change conflicts with a change that was checked in. Conflicts occur when two people change the same line of code in different ways. You need to edit the conflicting file(s) and clean it up by hand. Or, sometimes it's easiest to discard your own edits and download a fresh copy, by deleting the conflicting file and running cvs update again.

If you have been using cvs update with "sticky tags" to retrieve other versions, as described later, cvs will remember which version you were looking at. In this case, a cvs update will keep your sources consistent with that version. If you want to get back to looking at the latest code again, be sure to use the -A option to clears the sticky tags.

## Getting a Release Version

Once you have a CVS checkout, you can also use the update command to get the Bochs source code for any release since March 2000. The command is cvs update -d -r `tagname`. The tag tells which release you want, and it can be one of the following:

Table 3-2. CVS Release Tags

Bochs version | Release tag for CVS
--- | ---
2.0.2 (bugfix2) | REL_2_0_2_FINAL
2.0.1 (bugfix1) | REL_2_0_1_FINAL
2.0 | REL_2_0_FINAL
1.4.1 (bugfix1) | REL_1_4_1_FINAL
1.4 | REL_1_4_FINAL
1.3 | REL_1_3_FINAL
1.2.1 (bugfix1) | REL_1_2_1_FINAL
1.2 | REL_1_2_FINAL
1.1.2 (bugfix3) | REL_1_1_2_BASE
1.1.1 (bugfix2) | REL_1_1_1_BASE
1.1 (bugfix1) | REL_1_1_BASE
March 25, 2000 | REL-bochs-2000-03-25

> Tip: To get a complete list of allowed tags, type cvs stat -v README. Many of the tags are not generally useful.

Once you have done an update with -r `tagname`, you have made a "sticky tag." The stickiness refers to the fact that CVS remembers which tag you have used most recently. The tag is stored in the CVS subdirectory, so it stays around even if you log off and return later. After creating a sticky tag, any future cvs updates will try to keep your directory in sync with the version you chose. In other words, when developers check in changes you will not see them because your directory is "stuck" looking at an old version. To clear the sticky tag, use cvs update -A.

A variation on the sticky tag concept is a sticky date[4]. If some feature was working at some time in the past, but is no longer working, you can ask CVS to give you the sources from any date. cvs update -D 2001-06-14 will download the Bochs source as they were on June 14, 2001. Again, use -A to clear the sticky date and track the current sources.

## More about CVS

Entire books have been written on CVS, so there's no sense in duplicating it all here in the Bochs documentation. Some sources of additional information are listed below.

- The cvshome.com site has tons of CVS FAQs and documentation, including the official CVS manual by Per Cederqvist.

- Another CVS FAQ is available at University of Utah.

### Notes

[1] | You can download CVS software and documentation from www.cvshome.org.
[2] | Cygwin is an open source UNIX-like environment for Windows platforms, available at www.cygwin.com.
[3] | not written yet. For now, look at http://sourceforge.net/cvs/?group_id=12580 for instructions. See "Developer CVS access using SSH."
[4] | According to some sources, this is when you eat dinner with someone, and accidentally spill a drink on him/her.

Prev | Home | Next
Installation | Up | Installing a Binary