MINOS Offline Documentation

[home] [installing MINOS software] [supported platforms] [package links] [mailing list] [HyperNews] [FAQ] [computing help] [MINOS glossary] [archives]

Using "test" releases to work on your own or other's code

Test releases are used and maintained by an individual. When created they are associated with an existing base release. (See here for definitions.)

This page describes how to create, build and maintain them.

Creating a "test" release
Re-directing the lib, bin and tmp areas to alternative locations
Adding packages to your "test" release
Resolving proxy files in your "test" release
Removing packages from your "test" release
Building your "test" release
Checking dependent packages
Migrating Test Release from one Base Release to another
Migrating packages from one CVSROOT to another
Creating a new package in your test release
How to tag your code

Creating a "test" release

To create a test release in the current directory follow these steps:

Set up your SRT environment in your usual way.

Create the test release based on the given base release

      newrel -t <BASE_RELEASE> <TEST_RELEASE_NAME>

Set your environment to use this test release
```
      cd <TEST_RELEASE_NAME>
      srt_setup -a
```
This last step must be repeated each time you want to set the SRT environment to use this test release.

Where

<BASE_RELEASE> is the name of the associated base release, i.e., development one of the frozen releases named like RX.Y.Z or a Snapshot Release named like Syy-mm-dd-Rn-mm.
<TEST_RELEASE_NAME> some label, used for the releases label, for this "test" release.

Re-directing the lib, bin and tmp areas to alternative locations

In order to avoid filling up your home area with binaries, libraries and object files that are re-creatable you can tell SRT to use alternative locations for these files. This is particularly useful when your home area is in AFS space. This is done as follows:

Create a file in your home directory called .srtc
Decide where you want to put the lib/bin/tmp areas. The example uses $MINOS_DATA/d80/buckley which is an FNAL AFS data disk. Using the local scratch space on the MINOS Cluster is not a good idea because it limits you to only running on the node in question.

Add the following to the file

extra_dirs=\
"$extra_dirs tmp>$MINOS_DATA/d80/buckley/tmp bin>$MINOS_DATA/d80/buckley/bin \
lib>$MINOS_DATA/d80/buckley/lib"

Now when you create a test release the lib,bin and tmp areas will be links to the alternative areas


-rw-r--r--    1 buckley  e875      154 May 27 18:37 GNUmakefile
lrwxr-xr-x    1 buckley  e875       46 May 27 18:37 bin -> /afs/fnal.gov/files/data/minos/d80/buckley/bin
drwxr-xr-x    2 buckley  e875     2048 May 27 18:37 doc
drwxr-xr-x    2 buckley  e875     2048 May 27 18:37 etc
drwxr-xr-x    2 buckley  e875     2048 May 27 18:37 include
lrwxr-xr-x    1 buckley  e875       46 May 27 18:37 lib -> /afs/fnal.gov/files/data/minos/d80/buckley/lib
drwxr-xr-x    2 buckley  e875     2048 May 27 18:37 macros
drwxr-xr-x    2 buckley  e875     2048 May 27 18:37 man
drwxr-xr-x    2 buckley  e875     2048 May 27 18:37 results
lrwxr-xr-x    1 buckley  e875       46 May 27 18:37 tmp -> /afs/fnal.gov/files/data/minos/d80/buckley/tmp

You can retrofit an old test release by doing the following
- cd into the test release and gmake clean
- Create lib, bin and tmp directories in your chosen alternative location
- Replace the lib,bin and tmp areas in your test release with links to the alternative location.
- Re-run gmake in you test release

Adding packages to your "test" release

To add packages to your test release do the following:

Set up your SRT environment as per normal.

Set up your SRT environment to use your test release:

      cd /path/to/your/test/release
      srt_setup -a

Add the package:
```
      addpkg [options] <PACKAGE_NAME>
```
Where <PACKAGE_NAME> is, obviously, the name of the package you want to add.
The most likely options you will want to use are from this set:
- -h get the code from the head of the CVS repository.
- -d <cvsroot> use the given CVSROOT instead of the one that was used to check out this package in the base release. Since by default base releases are checked out in read-only access mode you will likely want to use this option to have the package accessed in a read-write manner. (Or, you can migrate to a new access method after adding, see below). See here for info on gaining read-write access to the repository. The CVSROOT for read-write access is:
```
    minoscvs@minoscvs.fnal.gov:/cvs/minoscvs/rep1
```

Resolving proxy files in your "test" release

Proxy files are a means of sharing auxillary data files associated with code releases. They contain information about the location and versioned name of the file it proxies for. But they must be processed in order to create a symbolic link or local copy of the desired file.

The most space efficient method is to have the resolved file symlink to a central copy. This should be generally the case if the base release has a central cache. One can check this by looking in the contents of the file $SRT_DIST/setup/.proxyrc for a line starting with SITE_PROXY_CACHE:. If that file doesn't exist or there is no such line then you, the test release owner, can choose to

bug the site manager to create and populate the cache
make local copies of the files in your test release
create your own cache

Using the site cache

If CVS updates are done outside of msrt, simply do:

   cd /path/to/your/test/release
   srt_setup -a
   msrt proxy -r test [pkg1 pkg2]

The optional list of packages can be used to restrict which packages to resolve during this pass. If you use msrt to do your CVS updates then "msrt update -r test" will do both the update and the proxy resolution.

Making local copies

This option makes a copy of the file in the test release and is therefore not very space efficient, but does allow the user control over the contents of the file (i.e. if you need to change it). To force a local copy in the test release use:

   msrt proxy -f -l -r test [pkg1 pkg2]

User cache

If the base releases don't have a central cache or the user of the test release would like to set up their own (perhaps to share files amongst various test releases) then they can setup a cache by doing:

  cd /path/above_cache
  mkdir release_data
  cd /path/to/your/test/release
  srt_setup -a
  echo "SITE_PROXY_CACHE:/path/above_cache/release_data" > .proxyrc
  msrt proxy -r test

Future updates can be then resolved in the same manner as one would with a sitewide cache.

Removing packages from your "test" release

To remove packages following these steps:

Set up your environment for this test release
Go to the test release top level directory
Clean out any generated files
```
      gmake PackageName.clean
```
Remove the source code and any other cruft
```
      rmpkg PackageName
```

Building your "test" release

You can build your test release in one of a few ways:

Per package builds can be done by gmake PackageName.all in the top level release directory
A full release build can be done by just typing gmake in the top level release directory.

Also see this page for how to speed up test release builds.

Checking dependent packages

When you modify a package in your test release, it is good to check that any package which may use this package still builds (at least). To do this follow these steps.

cd /path/to/your/test/release
Find out what packages depend on the modified package
```
      depend PackageName
```
For each package in the output which is not yet in your test release issue this command
```
      lnkpkg Package1
      lnkpkg Package2
      ...
```
Do a full build of the test release and watch for errors.
Any packages needing fixing can have their symlink replaced with actual code via
1. rmpkg Package1
2. addpkg [options] Package1
3. ...
See above for descriptions of the [options].

Migrating Test Release from one Base Release to another

As has already been explained a test release must always be bound to a base release. As calling sequences change between the base releases attempting to use your test release with another base release will almost certainly fail, probably with a SegV.

However, there are times when you want to move your test release to another base release, for example you want to stay close to development but also want some degree of stability so use the latest snapshot release. Then you need to move forward each time another snapshot release comes out.

To do this follow these steps.

cd /path/to/your/test/release

Set up your SRT environment in your usual way to the required new base release. For example at FNAL:-

  source $MINOS_SETUP_DIR/setup_minossoft_FNALU.csh -r  <release >
  e.g. source $MINOS_SETUP_DIR/setup_minossoft_FNALU.csh -r S06-04-15-R1-21

Make sure the correct version of ROOT has been selected for this base release. It will be if you use use the above FNAL script. At other sites check with the local software librarian, or check that ROOTSYS now matches the one specified for the frozen or snapshot release.
Your test release top level directory contains the hidden file
```
  .base_release
```
which SRT uses to warn you if you attempt to use it with the wrong base release. As you are changing base releases you have to change this file to the new release
```
  echo <new base release> > .base_release 
  e.g. echo S06-04-15-R1-21 > .base_release 
```
Redeclare this as your test release (sourcing the base release setup may have cleared this).
```
  srt_setup -a 
```
Although not compulsory, it might be good to to remind yourself what changes you have made by typing:-
```
  csv diff
```
Use CVS to apply all the changes that occurred in moving from the old base release to the new one.
1. First test it by using the -n (no disk changes) option
```
  cvs -n update -r <new base release>
  e.g. cvs -n update -r S06-04-15-R1-21
```
  Caution: Frozen Base Releases have names that include '.', but the corresponding CVS tag replaces each '.' with a '-'.
```
   e.g. cvs -n update -r R1-22
```
  You can move from any base release, including development to any other.
  Where possible CVS will merge all your test release changes as it moves the code to the new base release but watch the CVS output carefully. The leading letter on each file name it prints indicates the action:-
```
  U  Updated (a new file or replaced file)
  P  Patched (a replaced file)
  M  Merged  (merged in your updates)
  C  Conflict (your update conflicts with other updates)
```
  Check that each letter M does indeed indicate a change you made. Any letter C will definitely require your attention! Before applying the changes, you might think about taking a backup copy of your test release if not entirely happy with the CVS output.
2. Now apply the change
```
  cvs update -r <new base release>
  e.g. cvs update -r S06-04-15-R1-21
```
  and fix up any conflicts. Again although not compulsory, it might be good to check you updates in their new base release.
```
  csv diff
```
Clean out your test release
```
  gmake clean
```
Don't skip this step!!!! (gmake won't catch dependency changes when switching directories).
Rebuild
```
  gmake
```

Migrating packages from one CVSROOT to another

If you used addpkg to add a package with out specifying a CVSROOT and the associated base release package was checked out in a read-only access manner then the test release package will also have a read-only access method. If you want to commit changes to this package you need to change this to a read-write access method. You can do this with the SRT script "cvsmigrate" following these steps:

cd /path/to/your/test/release/PackageName
cvsmigrate -o <old-cvsroot> -d <new-cvsroot>
Answer "y" to the questions.

If you want to migrate from read-only to read-write access methods then the command is this long one:

cvsmigrate -o :pserver:anonymous@minoscvs.fnal.gov:/cvs/minoscvs/rep1 -d minoscvs@minoscvs.fnal.gov:/cvs/minoscvs/rep1

(side note, if you are operating on a base release, msrt offers "msrt migrate" which has a slightly simpler usage.)

Creating a new package in your test release

Often the developer may wish to create a new package in their test release. After creating a test release the user needs to cd into the test release and do the following:

mkdir mypackage
cd $SRT_PRIVATE_CONTEXT/include
ln -s ../mypackage mypackage
Create the source and header files and a GNUmakefile for the package. An example of a simple GNUmakefile for a package that only builds a single library. Look at existing MINOS packages for more examples.
When happy with the code, create a CVS module and check the code in. This allows other users to add your package to their test release.
In order for a package to get added to the base release it must be listed in the packages-development file. Please contact Ed Tetteh-Lartey to get your package added once the offline group has agreed that it should be included.

Notes:

If your package includes test code then it should be placed in a test directory which should build a library containing the test code.
The test executables should be added to the tbin target and only get built if the user runs gmake tbin. Examples of GNUmakefiles for packages with test code can be found in the examples.

If you have root macros you can put them in the main package directory or in a macros directory. You need to make sure that the macros get moved to the releases/development/macros directory. There are examples of this on the examples page.

How to tag your code

For your code to be included into frozen releases you need to associate a name with the state of the code at some time. This is called "tagging" a package. For the names we use a convention like "VXX-YY-ZZ" where the major number "XX" represents major changes to the package and starts at "00", the minor number "YY" represents changes in external API and starts at "00" and the tiny number "ZZ" which is incremented for simple bug fixes. A change of one number implies lesser numbers become "00".

You can apply tags in a few different ways:

Tag the state in the repository which is closest to what is in the current directory:
```
      cd /path/to/test/release/PackageName
      cvs tag VXX-YY-ZZ
```
Tag the HEAD of the package (doesn't need any checked out source)
```
      cvs rtag VXX-YY-ZZ PackageName
```

Last Modified: $Date: 2009/01/20 19:47:43 $
Contact: minos_software_discussion@fnal.gov
Page viewed from http://www-numi.fnal.gov/offline_software/srt_public_context/WebDocs/test-release.html


Security, Privacy, Legal

Using "test" releases to work on your own or other's code

Contents

Using the site cache

Making local copies

User cache