Fermilab


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.

Contents

Creating a "test" release

To create a test release in the current directory follow these steps:
  1. Set up your SRT environment in your usual way.
  2. Create the test release based on the given base release
          newrel -t <BASE_RELEASE> <TEST_RELEASE_NAME>
    
  3. 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

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:

  1. Create a file in your home directory called .srtc
  2. 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.
  3. 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"
    
  4. 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
    
  5. You can retrofit an old test release by doing the following

Adding packages to your "test" release

To add packages to your test release do the following:
  1. Set up your SRT environment as per normal.

  2. Set up your SRT environment to use your test release:
          cd /path/to/your/test/release
          srt_setup -a
    

  3. 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:

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

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:
  1. Set up your environment for this test release

  2. Go to the test release top level directory

  3. Clean out any generated files
          gmake PackageName.clean
    

  4. 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: 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.
  1. cd /path/to/your/test/release

  2. Find out what packages depend on the modified package
          depend PackageName
    

  3. For each package in the output which is not yet in your test release issue this command
          lnkpkg Package1
          lnkpkg Package2
          ...
    

  4. Do a full build of the test release and watch for errors.

  5. 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.

  1. cd /path/to/your/test/release

  2. 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
    
  3. 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.

  4. 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 
    
  5. Redeclare this as your test release (sourcing the base release setup may have cleared this).
      srt_setup -a 
    
  6. Although not compulsory, it might be good to to remind yourself what changes you have made by typing:-
      csv diff
    
  7. 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
      
  8. Clean out your test release
      gmake clean
    
    Don't skip this step!!!! (gmake won't catch dependency changes when switching directories).

  9. 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:
  1. cd /path/to/your/test/release/PackageName

  2. cvsmigrate -o <old-cvsroot> -d <new-cvsroot>

  3. 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:
  1. mkdir mypackage
  2. cd $SRT_PRIVATE_CONTEXT/include
  3. ln -s ../mypackage mypackage
  4. 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.
  5. 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.
  6. 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 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:



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
Fermilab
Security, Privacy, Legal Fermi National Accelerator Laboratory