>Using the CVS repository

2. Using the CVS repository

We use CVS (Concurrent Version System) to keep track of our sources for various software projects. CVS lets several people work on the same software at the same time, allowing changes to be checked in incrementally.

This section is a set of guidelines for how to use our CVS repository, and will probably evolve in time. The main thing to remember is that most mistakes can be undone, but if there's anything you're not sure about feel free to bug the local CVS meister (namely Jeff Lewis ).

2.1. Getting access to the CVS Repository

You can access the repository in one of two ways: read-only (Section 2.1.1), or read-write (Section 2.1.2).

2.1.1. Remote Read-only CVS Access

Read-only access is available to anyone - there's no need to ask us first. With read-only CVS access you can do anything except commit changes to the repository. You can make changes to your local tree, and still use CVS's merge facility to keep your tree up to date, and you can generate patches using 'cvs diff' in order to send to us for inclusion.

To get read-only access to the repository:

  1. Make sure that cvs is installed on your machine.

  2. Set your $CVSROOT environment variable to :pserver:anoncvs@glass.cse.ogi.edu:/cvs

  3. Run the command

        $ cvs login

    The password is simply cvs. This sets up a file in your home directory called .cvspass, which squirrels away the dummy password, so you only need to do this step once.

  4. Now go to Section 2.2.

2.1.2. Remote Read-Write CVS Access

We generally supply read-write access to folk doing serious development on some part of the source tree, when going through us would be a pain. If you're developing some feature, or think you have the time and inclination to fix bugs in our sources, feel free to ask for read-write access. There is a certain amount of responsibility that goes with commit privileges; we are more likely to grant you access if you've demonstrated your competence by sending us patches via mail in the past.

To get remote read-write CVS access, you need to do the following steps.

  1. Make sure that cvs and ssh are both installed on your machine.

  2. Generate a DSA private-key/public-key pair, thus:

         $ ssh-keygen -d

    (ssh-keygen comes with ssh.) Running ssh-keygen -d creates the private and public keys in $HOME/.ssh/id_dsa and $HOME/.ssh/id_dsa.pub respectively (assuming you accept the standard defaults).

    ssh-keygen -d will only work if you have Version 2 ssh installed; it will fail harmlessly otherwise. If you only have Version 1 you can instead generate an RSA key pair using plain

        $ ssh-keygen

    Doing so creates the private and public RSA keys in $HOME/.ssh/identity and $HOME/.ssh/identity.pub respectively.

    [Deprecated.] Incidentally, you can force a Version 2 ssh to use the Version 1 protocol by creating $HOME/config with the following in it:

       BatchMode Yes
    
       Host cvs.haskell.org
       Protocol 1

    In both cases, ssh-keygen will ask for a passphrase. The passphrase is a password that protects your private key. In response to the 'Enter passphrase' question, you can either:

    • [Recommended.] Enter a passphrase, which you will quote each time you use CVS. ssh-agent makes this entirely un-tiresome.

    • [Deprecated.] Just hit return (i.e. use an empty passphrase); then you won't need to quote the passphrase when using CVS. The downside is that anyone who can see into your .ssh directory, and thereby get your private key, can mess up the repository. So you must keep the .ssh directory with draconian no-access permissions.

    [Windows users.] The programs ssh-keygen1, ssh1, and cvs, seem to lock up bash entirely if they try to get user input (e.g. if they ask for a password). To solve this, start up cmd.exe and run it as follows:
           c:\tmp> set CYGWIN32=tty
           c:\tmp> c:/user/local/bin/ssh-keygen1
           

    [Windows users.] To protect your .ssh from access by anyone else, right-click your .ssh directory, and select Properties. If you are not on the access control list, add yourself, and give yourself full permissions (the second panel). Remove everyone else from the access control list. Don't leave them there but deny them access, because 'they' may be a list that includes you!

  3. Send a message to to the CVS repository administrator (currently Jeff Lewis ), containing:

    • Your desired user-name.

    • Your .ssh/id_dsa.pub (or .ssh/identity.pub).

    He will set up your account.

  4. Set the following environment variables:

    • $HOME: points to your home directory. This is where CVS will look for its .cvsrc file.

    • $CVS_RSH to ssh

      [Windows users.] Setting your CVS_RSH to ssh assumes that your CVS client understands how to execute shell script ("#!"s,really), which is what ssh is. This may not be the case on Win32 platforms, so in that case set CVS_RSH to ssh1.

    • $CVSROOT to :ext:your-username @cvs.haskell.org:/home/cvs/root where your-username is your user name on cvs.haskell.org.

      The CVSROOT environment variable will be recorded in the checked-out tree, so you don't need to set this every time.

    • $CVSEDITOR: bin/gnuclient.exe if you want to use an Emacs buffer for typing in those long commit messages.

    • $SHELL: To use bash as the shell in Emacs, you need to set this to point to bash.exe.

  5. Put the following in $HOME/.cvsrc:

    	  checkout -P
    	  release -d
    	  update -P
    	  diff -u
    	  

    These are the default options for the specified CVS commands, and represent better defaults than the usual ones. (Feel free to change them.)

    [Windows users.] Filenames starting with . were illegal in the 8.3 DOS filesystem, but that restriction should have been lifted by now (i.e., you're using VFAT or later filesystems.) If you're still having problems creating it, don't worry; .cvsrc is entirely optional.

[Experts.] Once your account is set up, you can get access from other machines without bothering Jeff, thus:

  1. Generate a public/private key pair on the new machine.

  2. Use ssh to log in to cvs.haskell.org, from your old machine.

  3. Add the public key for the new machine to the file $HOME/ssh/authorized_keys on cvs.haskell.org. (authorized_keys2, I think, for Version 2 protocol.)

  4. Make sure that the new version of authorized_keys still has 600 file permissions.

2.2. Checking Out a Source Tree

2.3. Committing Changes

This is only if you have read-write access to the repository. For anoncvs users, CVS will issue a "read-only repository" error if you try to commit changes.

2.4. Updating Your Source Tree

It can be tempting to cvs update just part of a source tree to bring in some changes that someone else has made, or before committing your own changes. This is NOT RECOMMENDED! Quite often changes in one part of the tree are dependent on changes in another part of the tree (the mk/*.mk files are a good example where problems crop up quite often). Having an inconsistent tree is a major cause of headaches.

So, to avoid a lot of hassle, follow this recipe for updating your tree:

$ cd fptools
$ cvs update -Pd 2>&1 | tee log

Look at the log file, and fix any conflicts (denoted by a "C" in the first column). If you're using multiple build trees, then for every build tree you have pointing at this source tree, you need to update the links in case any new files have appeared:

$ cd build-tree
$ lndir source-tree

Some files might have been removed, so you need to remove the links pointing to these non-existent files:

$ find . -xtype l -exec rm '{}' \;

To be really safe, you should do

$ gmake all

from the top-level, to update the dependencies and build any changed files.

2.5. GHC Tag Policy

If you want to check out a particular version of GHC, you'll need to know how we tag versions in the repository. The policy (as of 4.04) is:

So, to check out a fresh GHC 4.06 tree you would do:

     $ cvs co -r ghc-4-06 fpconfig
     $ cd fptools
     $ cvs co -r ghc-4-06 ghc hslibs

2.6. General Hints