The Mercury Project: Remote CVS Access

Using the CVS client to remotely access the Mercury CVS archive

Author: Tyson Dowd -- trd@cs.mu.oz.au

Almost all work in the Mercury project is under revision control using CVS. The sources, documentation, test-cases, webpages and samples are all stored under various modules of the CVS repository on filesystems here at the University of Melbourne. CVS allows client-server access to this repository. This document describes how to use the CVS archive remotely.

You need:

A version of CVS with client server support (1.9 works fine) installed at the remote end. Probably anything newer than 1.5 will work OK.
A TCP/IP connection to the Internet.

Anonymous Access:

The CVS server is running on cvs.mercury.cs.mu.oz.au, and the repository is in the directory /home/mercury/mercury1/repository
The anonymous access account is called guest with a password of guest

To login (you need to do this just once)

	cvs -d :pserver:guest@cvs.mercury.cs.mu.oz.au:/home/mercury/mercury1/repository login

The password is guest

To checkout a module

	cvs -d :pserver:guest@cvs.mercury.cs.mu.oz.au:/home/mercury/mercury1/repository checkout mercury

There is a list of modules later in this page.
You will have read-only access to the repository. If you want to commit something you will need to get someone with read-write access to do it for you. If you send your patch to the mercury-developers mailing list you should be able to get this done.
You almost certainly want to add the following lines to your .cvsrc (in your home directory).
```
	cvs -z6
	diff -u -N
	update -Pd
```
This turns on compression in client/server transfers, uses the preferred Mercury diff format (unified diff with new files shown as diffs), prunes empty directories and picks up new directories.
Please remember that if you want to track the latest releases, you may run into incompatibility problems unless you update very regularly. The Mercury compiler often relies on a very recent version of the Mercury compiler to build from scratch. If you get out of date, it might be worth downloading the latest release-of-the-day and installing it.

Getting Write Access:

The preferred method for remote write access to the CVS repository is through ssh (using version 2 of the ssh protocol) using public key authentication. You will need to install an ssh client on your machine if you do not already have one.
If you do not have an ssh version 2 key pair on your machine you will need to generate one using
```
	ssh-keygen -t rsa
	
```
Send your public key .ssh/id_rsa.pub to a member of the Mercury team and get them to do the following steps:
1. Create an account for the new user on cvs.mercury.cs.mu.oz.au (a.k.a jupiter). The password field in /etc/passwd should contain only an asterisk (*) to prevent the user logging in. A good place for the user's home directory is /home/jupiter/username.
2. Create a file .ssh/authorized_keys in the user's home directory and add the user's public key to that file. The key should be all on one line, and at the start of the line you should add the string
```
	command="cvs server",no-port-forwarding
			
```
  This prevents the user from doing anything with their account except using the CVS server.
Access via Windows should work just fine. Most firewalls are setup to allow ssh access through. You can get a free binary (and source) CVS for Windows from www.cyclic.com. Also there is a product called WinCVS that should work (although we haven't tried it ourselves). CVS and OpenSSH are also both included in Cygwin.

Then (once your account is set up):

Set your CVSROOT environment variable to
```
	:ext:username@cvs.mercury.cs.mu.oz.au:/home/mercury/mercury1/repository
	
```
Make sure this environment variable is exported (in sh based shells, "export CVSROOT", in csh based shells, use "setenv" to set the environment variable in the first place).
Set your CVS_RSH environment variable to "ssh".
There are some checks that are done via questions. In particular, our CVS repository does checks for up-to-date copyright messages on all files. For remote users this requires an X connection so you will probably want to turn on X forwarding by adding the following to your ~/.ssh/config file:
```
	Host cvs.mercury.cs.mu.oz.au
	ForwardX11 yes
	
```
If you are not running an X server and you are having problems committing changes because of this, please contact us.
You can do "cvs co mercury" to check out the main mercury module. This can take a while over a slow connection, but you should see pretty steady progress messages, eg:
```
	  	U mercury/.INSTALL.in
		U mercury/.README.in
		U mercury/.cvsignore
		U mercury/BUGS
		U mercury/COPYING
		U mercury/COPYING.LIB
		etc
	  
```
The CVS modules you might need access to are:

mercury
the mercury compiler, runtime, library, extras and documentation (big)
mercury-gcc
the mercury-gcc distribution; this contains part of the source for the native code back-end
tests
test cases for the compiler (big)
w3
the www page (several Mb - lots of papers)
CVS should compress most of this stuff while sending it.

NOTE:

All developers should subscribe to the mercury-developers mailing list. Serious developers should also subscribe to the mercury-reviews mailing list, to keep up-to-date on development discussion, and to be able to participate in discussions about code they want to change. The mercury-developers list is a forum to ask questions about how to change something, discuss design trade-offs, and report on any development that you suspect will influence others. The mercury-reviews list is used for posting and reviewing diffs, although it often also contains design discussions about issues that have arisen during code review. (Traffic on mercury-reviews is moderately high - between 100 and 300 messages per month, so you should filter into a separate folder if possible).
Before committing any code, read the policy on reviews for the Mercury system. This can be found in the mercury CVS module:
- mercury/compiler/notes/reviews.html
or
- on the web
Basically, we don't commit broken code into the repository, and we don't commit un-reviewed code.
You'll need to be familiar with CVS to keep up to date with the development tree. If you haven't used it before, read the info pages on CVS and the documentation that comes with it. There is a free book on CVS at cvsbook.red-bean.com
If you have any questions, just ask.

Comments? Mail mercury@cs.mu.oz.au, or see our contact page.
Last update was $Date: 2007-07-25 06:59:31 $ by $Author: zs $@cs.mu.oz.au