The Official FVWM Homepage - CVS Procedures

FVWM development uses a CVS server.

Note: the state of code in the CVS repository fluctuates wildly. It will contain bugs, maybe ones that crash the program. It may not even compile for you. Consider it alpha-quality code. You have been warned.

Before You Begin

To know what is going in with the source tree you should be reading mail on the Fvwm Workers List. See the Mailing List Info page for more information.

To build FVWM from the CVS sources, you must have several GNU tools:

Without these tools, you won't be able to build out of the CVS source tree. But don't despair: download one of the daily snapshots instead!

Initial Setup

To make life easier on yourself, create the file `~/.cvsrc', and insert the following lines. These set useful default options for the three most used CVS commands. Do this now before going any further. 

 diff -u -b -B
 checkout -P
 update -d -P

I also recommend a `cvs -q' line which makes cvs operations a little quieter.

Also, if you are on a slow net link (like a dialup), you'll also want a line containing `cvs -z3' in this file. This turns on a useful compression level for all cvs commands. Setting it higher will only waste your CPU time.

Before you can download development source code for the first time, you must login to the server: 

 cvs -d :pserver:anonymous@cvs.fvwm.org:/home/cvs/fvwm login
The password is `guest'. The command outputs nothing if it works, and an error message if it failed. You only need to log in once; all subsequent CVS commands read the password stored in the file `~/.cvspass'.

Checking Out Source Code

Next, you checkout the source code. First you must decide what version you're interested in. The structure of the CVS tree is as follows:

Given these rules, you should be able to translate the version of you want to retrieve to a label for use with the checkout command below (or other CVS commands which might need them).

You use the CVS checkout (or co) command to retrieve an initial copy of the code. The simplest form of this command, for retrieving the latest code, doesn't require any label: 

 cvs -d :pserver:anonymous@cvs.fvwm.org:/home/cvs/fvwm checkout fvwm

This will create a new directory fvwm in your current directory, containing the latest, up-to-the-minute code.

If you want to work on the latest code in the 2.2.x branch of the code, you can use the branch label on the checkout command line: 

 cvs -d :pserver:anonymous@cvs.fvwm.org:/home/cvs/fvwm co -r branch-2_2 fvwm

This will put a copy of the very latest code on the 2.2.x branch into a subdirectory fvwm. If you're going to be working on multiple branches at the same time, or just feel like it, you can tell CVS to use a different name for the directory with the checkout -d option: 

 cvs -d :pserver:anonymous@cvs.fvwm.org:/home/cvs/fvwm co -r branch-2_2 -d fvwm-2.2.x fvwm

Now the code will be checked out into a directory fvwm-2.2.x rather than fvwm. In this way you can keep multiple copies of the source around and "active" simultaneously. (It is also permissible to just checkout into fvwm and rename the directory yourself.)

Finally, if you want to see a particular version of the sources you can use a version label instead of a branch label on the checkout command: 

 cvs -d :pserver:anonymous@cvs.fvwm.org:/home/cvs/fvwm co -r version-2_1_10 -d fvwm-2.1.10 fvwm

Please note that if you check out a specific version, the update command will be useless in that copy: after all, the code for that version hasn't changed so there's nothing to update...

The version and branch labels "stick" to your copy of the tree, so that if you check out a branch, all update commands will be handled with respect to that branch. These are called "sticky tags"; please see the CVS documentation for more details on these and how they work, or how to "un-stick" a checked out version if you need to.

Note that when you are inside the working directory, you no longer need the "-d :pserver:..." argument when issuing CVS commands.

CVS commands work from anywhere inside the source tree, and recurse downwards. So if you happen to issue an update from inside the `docs' subdirectory it will work fine, but only update the docs. In all of the following command examples, we assume that you have cd'd to the top of the source tree.

Building the Tree

So, you now have a copy of the code. Get in there and get to work!

The first thing you need to do is create a configure script. The configure script will also need the Makefile.in files in order to generate the Makefiles. The autoconf and automake tools do this for you (you did remember to install autoconf and automake, right?)

So, when you have a newly checked-out source tree the first thing to do is: 

 cd fvwm
 automake --add-missing
 autoreconf

Be careful: the second command is autoreconf, not autoconf! You will get some warning messages from automake and autoreconf. As long as you end up with a working configure script, you should ignore them.

Once that's done, you can proceed to build the code as discussed in the INSTALL.fvwm and INSTALL scripts: 

 ./configure
 make
 make install

with appropriate options and arguments, as you like.

Code Updates

From time to time, the dedicated FVWM Workers will make changes to the CVS repository. Announcements of this are automatically sent to the fvwm-workers list. You will want to be subscribed to this list!

You can update your copy of the sources to match the master repository with the update command. Note it's not necessary to check out a new copy! Using update is significantly faster and simpler, as it will download only patches instead of entire files, only update files that have changed since your last update, and it will automatically merge any changes in the CVS repository with any local changes you may have made. 

 cvs update

If you didn't use a tag when you checked out, this will update your sources to the latest version on the main branch. If you used a branch tag, it will update to the latest version on that branch. If you used a version tag, it won't do anything (see above).

Starting a Project

Discuss your ideas on the workers list before you start. Someone may be working on the same thing you have in mind. Or they may have good ideas about how to go about it.

If you just have a small patch you want to make, you may just commit it to the main branch. If the change is large, and lots of other work is going on, you may want to do your changes on a "side branch" which will get merged into the main branch later on. Before creating a branch, you discuss the matter with the other workers. If you are new to CVS, you should read the CVS documentation several times, and ask for help. The documentation is sufficiently large and confusing that it is rather difficult to get right the first few times.

Hacking the Code

So you've found a bug you want to fix? Want to implement a feature from the TODO list? Got a new feature to implement? Hacking the code couldn't be easier. Just edit your copy of the sources. No need to copy files to `.orig' or anything; CVS has copies of the originals.

When you have the code in a working state, generate a patch against the current sources in the CVS repository. 

 cvs update
 cvs diff -u > patchfile
Mail the patch to the fvwm-workers list with a description of what you did. But read the FAQ file about ChangeLog entries before doing so.

Conflicts

If someone else has been working on the same files as you have, you may find that you have made conflicting modifications. You'll discover this when you try to update your sources. 
 $ cvs update
 RCS file: /home/cvs/fvwm/fvwm/fvwm/icons.c,v
 retrieving revision 1.5
 retrieving revision 1.6
 Merging differences between 1.5 and 1.6 into icons.c
 rcsmerge: warning: conflicts during merge
 cvs server: conflicts found in fvwm/icons.c
 C fvwm/icons.c
Don't Panic! Your working file, as it existed before the update, is saved under the filename `.#icons.c.1.5'; hence you can always recover it, should things go horribly wrong. The file named `icons.c' now contains both the old (i.e. your) version and new version of lines that conflicted. You simply edit the file and resolve each conflict by deleting the unwanted version of the lines involved. 
 <<<<<<< icons.c
    XpmImage    my_image = {0};  /* testing */
 =======
 >>>>>>> 1.6
Don't forget to delete the lines with all the "<", "=", and ">" symbols.

Getting Commit Access

Using the procedures described above, and being on the workers list are a prerequisite to gaining update access. We expect to have heard from you more than once on the fvwm-workers list so that we have some idea who you are.

Doing some testing, submitting some patches, and getting involved in the discussions will help us know about you.

After you have been involved for a while, if we don't suggest it, then ask. The FVWM development team is not a closed environment, we welcome new members. There are no required duties, all work is strictly voluntary.

If there is agreement on the list that you should be given update access, you will need to choose a CVS user ID and provide an encrypted password. The latter can be obtained with the following Perl snippet: 

 perl -e 'print crypt("yourpass",join("",((a..z,A..Z,0..9)[rand(62),rand(62)]))), "\n"'
Change yourpass to whatever you want your password to be.

Once you have update access, re-do the login command above using your CVS user ID in place of anonymous and your password in place of guest, and you are on your way.

Committing Changes

Now that you have write permissions and have logged in with your CVS username, you can commit changes. This is done (surprise!) with the CVS commit command.

Note it's usually a good idea to run a cvs update just before you commit, to make sure you've got the latest code. If you try to commit changes to a file that someone else has changed since you last updated, CVS will complain and not allow the commit. But, changes to other files could indirectly affect your new code, as well. In general if you're doing development it really pays to follow the old(?) adage, "Update early and often".

To commit all the modified files in your workspace, use: 

 cvs commit

CVS will pop up your favorite editor to allow you to enter comments about what changes you've made. These comments will appear in the email sent to fvwm-workers, so please write something useful.

Also, you will see a complete list of files that CVS thinks you have changed. Please sanity-check this list! Make sure there's nothing you don't expect there, and everything you do expect.

If you don't like the all-or-nothing approach, you can specify only certain files to be committed: 

 cvs commit fvwm/fvwm.1 modules/FvwmAuto/FvwmAuto.1

Again, please sanity-check the list to be sure you have everything.

Adding Directories and Files

First create the new directories and files locally. Then, assuming the new directory is named `newdir' and the new file is `newmod.c': 
 cvs add -m  "New directory for ..." newdir
 cd newdir
 cvs add -m "File newmod.c is a module that ..." newmod.c

When adding new directories and files, please be sure to take a look at the relevant Makefile.am files and modify them as appropriate! See the DEVELOPERS file for more details on this.

Deleting Directories and Files

You don't directly delete directories, you delete all the files in a directory and the directory goes away during an `update -dP'. To delete one or more files: 
 cvs remove -f filename...
 cvs commit -m 'deleted files because' filename...

Again, when removing directories or files please be sure to update the appropriate Makefile.am files. See DEVELOPERS.

Renaming/Moving Files

There is no perfect way to rename or move files in CVS. There are a few different methods, each with good and bad points. For FVWM, we've chosen the most straightforward method: remove the old file and add a new file. In order to preserve some kind of link, please include a pointer to the old file in the comments of the new file (and vice versa).

Again, when removing directories or files please be sure to update the appropriate Makefile.am files. See DEVELOPERS.

Creating New Branches

Please contact the fvwm-workers list and discuss any new branch you'd like to create, just so we have an idea about what and why.

When creating a branch it's best to base it off of a previously-existing, labeled checkpoint. Here we'll use the example of creating a new branch for 2.2.x development after the 2.2 release was made. Because of our rules, we know that the new branch name should be branch-2_2, but if you're creating a branch for a new feature you can use any valid label.

Once you know where you want to branch from and what you want to call the new branch, use the cvs rtag command to create the branch (be sure you're in the root of your checkout): 

 cvs rtag -b -r version-2_2_0 branch-2_2 .

The first thing you'll probably want to do on the new branch is edit the configure.in file to change the version number, so people know it's different. See the DEVELOPERS file for information on this.