Remote write access to the ROOL CVS repository

Write access to ROOL’s CVS repository is available via a pserver connection over an SSH tunnel. You will need to provide ROOL with two pieces of information: your public SSH key for authenticating the SSH connection, and a scrambled version of the password that protects your account on the CVS server. Send these to code@riscosopen.org.

We’d also request that you tell us which parts of the repository you’ll be working on, so we can restrict the parts you can write to, to avoid any accidental commits. This list can always be expanded at a later date.

In the following, we’re assuming you have access to a Linux, Unix or MacOS X machine, or a Windows machine running cygwin, to form your end of the tunnel. It may also work under RISC OS ports of the tools, but we haven’t tested these.

If you don’t already have a public SSH key, you can generate it thus:

mkdir ~/.ssh
cd ~/.ssh
ssh-keygen -t rsa

We suggest that you choose an empty passphrase so that some of the automated
steps described below work smoothly. The file we need is ~/.ssh/id_rsa.pub.

To generate a scrambled CVS password, do the following:

perl -e 'print crypt("mypassword", "randomseedchars")'

You’ll need to replace mypassword with your choice of password – as will be required later by the cvs login command, and randomseedchars by two randomly chosen characters which are used in the scrambling process.

Setting up your connection

When ROOL has confirmed that your files have been uploaded to the server, you can set up your connection. The following steps only need to be done once.

1. Create or append the following lines to the file ~/.ssh/config :

Host beta.arachsys.com
Compression yes
CompressionLevel 9
LocalForward 52401 riscosopen.org:2401

You can choose a port other than 52401 for the SSH tunnel on your local machine, but be sure to change the definition of CVSROOT below to match.

2. Since this will be the first time you connect to beta.arachsys.com, SSH will need you to manually confirm that wish to proceed. Enter:

ssh rool@beta.arachsys.com
yes
^C       (control + C)

This updates your ~/.ssh/known_hosts file.

3. Create a bash script as follows:

#!/bin/bash
# Replace fbloggs below with your CVS username, which will usually
# be your initial + surname
export CVSROOT=:pserver:fbloggs@localhost:52401/home/rool/cvsroot
# You need to add an entry to your PATH which contains the
# administrative perl scripts - adjust the below to your requirements
export PATH=$PATH:/home/fbloggs/bin
# EDITOR sets the editor that will be invoked when you need to input
# changelogs. The default is usually vi, but you can override it here
export EDITOR=nano
# Set up SSH tunnel
nohup ssh rool@beta.arachsys.com > /dev/null &
# Invoke a new bash shell that inherits the environment set up above
/bin/bash

Set its permissions to executable and run it.

4. Execute

cvs login

Enter the same password you fed into the perl script earlier. This will update ~/.cvspass and you will remain logged into the CVS server until you explicitly do cvs logout.

5. Execute

cvs co -d bin apache/Admin/bin

This will retrieve a set of perl scripts used as wrappers to CVS, such as “checkout”. The parameter after “-d” specifies where they are installed, so if you’re in your home directory when you issue the above command, it will put them in ~/bin (as the bash script above assumes).

Now, each subsequent time you start up your system, you’ll need to run the bash script again to restore the SSH tunnel and give you a shell in which to execute CVS commands.

Note that the SSH tunnel does not grant you shell access to beta.arachsys.com. Instead, the ssh session will actually print “alive” as
a heartbeat once a minute, which we are here redirecting to /dev/null to avoid gradually filling up your nohup.out.

Interacting with CVS

A quick guide to the commands you’ll mostly be using:

Checking out a build tree

To check out a build, use the ‘checkout’ script. E.g.:

checkout TungstenDev

This will populate the current directory with the relevant files/folders from CVS. Once it’s finished, copy the files over to your RISC OS machine and run !EraseCVS and Prepare as normal.

Updating a build tree

To update individual components, a simple cvs update -R from within the right directory is often all that’s needed.

To see what cvs update would do without actually performing the action, use cvs -nq update

For updating an entire build tree, the following short script is recommended (where the first argument to the script is the name of the product you are updating):

#!/bin/bash
mkdir $1
cd $1
checkout $1
grep -o ^[^#[:space:]]\\\+ < Products/$1/modules | xargs cvs update -RdP

Unlike a simple cvs update -R, the above script will correctly deal with:

• All changes to the Products file, including components being added/removed or switched to different sticky tags
• Addition and removal of files & folders within components (although this can be covered by using cvs update -RdP instead of a plain cvs update -R)
• It can also be used to initialise fresh build trees

The script assumes all the files for the product are within a folder with the same name as the product; if this is unsuitable for you (e.g. you only work on one product at a time) just remove the ‘mkdir’ and ‘cd’ commands from the script.

Information about local changes

For more information about what local changes you’ve made, use:

cvs diff

Commiting changes

To commit changes to a component, ensure you’re in the directory containing the VersionNum file and do:

srccommit

This will provide a template for your log message. Browse the repository in the CVS viewer to get an idea of the format of the log messages – note that we’ve recently stopped using the first line “Summary:” so that summary provided by the list of recent commits is more meaningful.

Note that for most components you’ll also be asked if you want to increase the version number. Generally speaking the only time when you don’t want to increase the version number is if your changes don’t result in any changes to the compiled binary that the component produces (i.e. the two binaries are identical in every way). Increasing the version number also causes the files to be tagged, which allows the checkout script to get specific versions of components (e.g. for official ROM releases)

Updating products files

To commit changes to a Products file, use prodcommit. You can normally respond “ok” to accept the auto-generated log message.

Note that if you are working with a modified products file, you will likely have to pass the -localfile option to checkout to force it to use your local version of the products file instead of grabbing the latest version from CVS.

Adding new files

New files are not brought under source control by default, on the assumption that your sandbox contains temporary or object files. If you have a new source file or directory, change into its containing directory and do:

cvs add newfile

You will still need to do srccommit afterwards.

For various reasons, CVS needs to know which files are binary files rather than text files. You can do this when adding files using:

cvs add -kb newbinaryfile

Or for existing files using:

cvs admin -kb existingbinaryfile

There is also a script which will recursively search the current directory and automatically mark files with certain common RISC OS filetypes as binaries – this is especially useful after you’ve just added a new component:

cvsbinaries

Manual checkouts

On occasions you may want to check out components or individual files independently of the checkout script, for this, use

cvs co -r RevisionOrBranchNameOrHEAD path/within/repository

Experimenting with CVS

The top-level directory Test in the repository is available for CVS experimentation – but be aware that the logs of all commits here will still be publicly visible in the “latest changes in CVS” page.

Dealing with CVS’s quirks

Commiting changes to HEAD

If you want to commit changes to a component that has been checked out against HEAD (as specified in the products file) then you’ll need to remove the HEAD ‘sticky tag’ before CVS will allow you to submit your changes. Execute the following from within the component’s folder:

cvs update -AR

Note that you do not want to perform this command on a component that was checked out from a specific branch, because it will remove the branch tags from the files and make CVS think that you checked them out from head.

Adding files to HEAD

Before you start adding any files using cvs add, make sure that you remove the sticky flags with cvs update -AR. Or, if you forgot to do that, you can use the following command to remove the tags (which will work on your pending additions, unlike the cvs update command):

find . -type f -name Entries -exec sed -i -e 's,/THEAD$,/,' {} \;

Locating your changed files

Before you can commit your changes, you need to work out what files you’ve changed, and where they are. The best way of doing this is to diff your entire build tree against the original sandbox you obtained from CVS. Even if you’ve kept a list of any files you’ve changed, diffing against the originals is a wise idea to avoid accidentally checking in any unwanted test or debug code. From RISC OS, an obeyfile similar to the following can be used to diff the two trees:

gnu.diff -ur PathToCVS PathToBuildTree > temp
unix.sed -f sedscript < temp > diffout
delete temp

Note that the script relies on the following sed script (saved as the file called sedscript) to strip much of the cruft from the diff output:

:t
/^Only in [^ ]\+ \(CVS\|\/cvstag\|o\|rm\|linked\|aof\|oz\|aif\|gpa\|od\)$/d
/^Only in \(^.]\+\.\)\+\(o\|rm\|oz\|m_o\|m_o_rl\|o_rl\|rm_o\|rm_o_rl\|aof\|linked\|z\|sn\|sz\): .\+$/d
/^Only in \([^.]\+\.\)*RiscOS\(\.Export\.APCS-32.*\|: .*\)$/d
/^diff .\+$/ {
 N
 N
 N
 N
 N
 N
 / # Dynamic dependencies:$/ {
  h
  s/.*/++/
  :x
  /^+/ {
   N
   s/^+[^\n]\+\n//
  }
  tx
  bt
 }
}

A similar script can also be run from a Unix environment if your RISC OS machine doesn’t have direct access to the original CVS tree.

More information

For more information about working on a RISC OS build, see the Developer's guide to RISC OS builds.

If in doubt, you can always ask on the forums.