JMRI Code: CVS FAQ

This is a list of Frequently Asked Questions for CVS, particularly regarding how we use it with JMRI.

Note: JMRI code is not maintained in CVS any more. To get the current code, please see the help pages on Accessing the code via the Git repository.

See also the Technical index for more information on maintaining JMRI code.

How do I get a copy of CVS?

Many computers come with CVS installed, including Linux and Mac OS X. If you're using Windows, you will need to install a CVS "client" program like WinCVS. A recent version can be downloaded from: http://prdownloads.sourceforge.net/cvsgui/WinCvs120.zip.

How can I get my own copy of the JMRI code?

To get a copy of the source for your own use, you can use "anonymous checkout". For a command line cvs client, make a new directory for the project, change to it, and tell CVS you exist with

cvs -d:pserver:anonymous@jmri.cvs.sourceforge.net:/cvsroot/jmri login

This "login" line is only needed once; after that, it is remembered on your local machine. You may be asked for a password. If so, just hit return, as the empty password will be accepted. You can then get a copy of the code with

cvs -d:pserver:anonymous@jmri.cvs.sourceforge.net:/cvsroot/jmri co all

If you're using a GUI-based client like WinCVS, pull down the "admin" menu and select "command line" to get a place to type these commands. On other computers, you can type them directly on the command line.

How can I bring my copy of the JMRI code up to date?

People contribute updates to the JMRI code almost every week. Your local copy doesn't get these changes until you ask for them, so that you've got something stable to work with. If you have an existing copy of the code and want to update it to the most recent contents of CVS, the CVS command is:

cvs -d:pserver:anonymous@jmri.cvs.sourceforge.net:/cvsroot/jmri -q update -dA

The "-q" option suppresses a lot of routine messages. The "-d" option is needed to tell CVS to also bring in new directories. The "-A" option, here combined with "-d", means you want the most recent contents.

How can I get the code for a particular release?

CVS uses "tags" to make specific sets of content. We use these to mark the code for each release as we build it. To get the code for a release, you can ask for it with a command like this:

cvs -d:pserver:anonymous@jmri.cvs.sourceforge.net:/cvsroot/jmri -q co -rRelease-2-1-5

In this example, "Release-2-1-5" is the tag for the 2.1.5 release. You can adjust that as needed. If you already have a release checked out and want to update it to a specific release, change the "co" command to "update -d"

What are those lines like $Revision$ and $Id$?

Those are automatically updated by CVS every time a new version of the file is checked-in to the repository. Please don't edit them!!! If you contribute your changes to the project, those line have to be intact in the contributed file.

How do I update an existing copy of the source to the current version?

As the common code changes, you might want to update your copy to contain the lastest version. To do that, use:

cvs -q update

Any changes will be merged into the files on your disk, and you should then be up-to-date with your own changes still present.

The "-q" option removes a lot of informational messages as CVS enters the various directories in the project; the command still works if you omit it, but it will be harder to see any real error messages.

What are these messages about .DS_Store files?

If you're using Mac OS X, CVS may give you messages about ".DS_Store" files. These are used to keep track of window layouts, etc. To suppress these messages, just create a file in your home directory called ".cvsignore" and add a line of ".DS_Store" to it (no quotes). CVS will then ignore all .DS_Store files in all of your checked-out directory trees.

What is the convention for tag names?

Typically, three types of tag names are used:

"Release-1-5-4" - the tag defining a specific released version of the code. These are created during the release builds, and should not be changed.
"Release-1-5-4-branch" - this is the branch-tag defining a "patch branch" for a specific release. This is the only use we make of CVS branches; please note that we do not use branches for normal development.
"rgj20050603a" - of the form "initials" "date" "some letter", these can be used by individual developers to keep track of what they're doing. All we ask is that you start a tag with your initials.

How is JMRI stored in CVS?

JMRI consists of two large code trees, and a number of auxiliary directories. The code is divided into "jmri", the main JMRI code, and "test", the set of automated tests. These are kept separate so that it's easy to build just the distributed software, without including the test code. (If you directly look at the CVS repository, you'll also see "jmrit" and "jmrix" directories; these are obsolete, and kept only for historical reasons.)

Similarly, auxilary information is kept in separate "lib", "xml", "resources", "jython", etc. directories.

Finally, there's a bunch of information that's not part of the application development areas, including the "scripts" directory of tools for building releases, the web site, and others.

We store all these separately in CVS so that you can check out just the ones you need.

To simplify checking out a development tree, we provide a CVS module named "all". This checks out the necessary directories and puts them in the required places for a straight-forward build.

Some files appear to be read-only, why is that?

As the software evolves, sometimes files become obsolete. If they're not needed at all, CVS allows us to delete them from future releases. In that case, they don't show up at all when you check out a current copy.

But sometimes the file needs to remain, but we don't want it to be modified any more. For example, an older schema or DTD file needs to remain around so that older references to it continue to work, but we don't want somebody accidentally modifying the older version instead of the current version of the file.

In cases like that, we use the "cvs watch on" option to effectively lock the file. The checked-out version of the file is write-protected so you can't edit it without noticing the problem, and changes can't be checked back into CVS unless the file watch is turned off.