Showing changes from revision #9 to #10:
Added | Removed | Changed
Warning: The current and/or previous revision contained markup errors which prevented proper diff analysis. A guess at markup correction has been made but the diff may not be a truly accurate reflection of the real changes.
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.
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 castle/Admin/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.
A quick guide to the commands you’ll mostly be using:
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.
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:
cvs update -RdP
instead of a plain cvs update -R
)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.
For more information about what local changes you’ve made, use:
cvs diff
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)
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.
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
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
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.
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.
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$,/,' {} \;
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.
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.