Base and Test Releases

This web page defines the ideas of Base Release and Test Release and discusses how to use them. Some of you may be familiar with a Fermilab product named SRT. While Mu2e does not use SRT, we have borrowed language from SRT; the concepts of Base Release and Test Release have the same meaning as they do in SRT.

• Introduction
• Running Directly from a Base Release
• Making Run-Time Changes to a Base Release
• Making Test Releases
  • Making a Test Release Using an Existing cvs Package
  • Starting a New CVS Package in a Test Release
  • Making a Test Release For use as a Sandbox

Introduction

Prebuilt, ready-to-run releases of the Mu2e Offline software are available in a directory tree rooted at,

 /grid/fermiapp/mu2e/Offline

 /grid/fermiapp/mu2e/Offline/v0_3_3
 /grid/fermiapp/mu2e/Offline/v0_3_3_SLF5

These are examples of Base Releases: that is, they are prebuilt and ready-to-run. At present all of the .cc files are also present but that may change in the future.

At some time in the future we will make a few changes to this:

• We will do a nightly build of the HEAD of cvs and put it in /grid/fermiapp/mu2e/Offline
• We will change the labeling of the SLF4/SLF5 builds of the same release so that they obey rules like those used by UPS/UPD.

You can also build your own base release by checking out all of Offline and building it in the usual way. When the build procedure is complete, you will have a fully functioning base release. The base releases in /grid/fermiapp/mu2e/Offline are made by this way.

There are several things you can do with a base release:

1. Run mu2e using only files from the base release.
2. Run mu2e overriding some, or all, of the run time configuration files with local versions.
3. Checking out a single package from cvs, editing it and building it against a base release.
4. Creating a new package and building it against a base release.

Running Directly from a Base Release

If you want to run a job directly from a base release, you need not checkout any files from cvs. The main use for this pattern is running example code.

> setup mu2e
> source /grid/fermiapp/mu2e/Offline/v0_3_3/setup.sh
> mu2e -c /grid/fermiapp/mu2e/Offline/v0_3_3/Mu2eG4/test/g4test_01.fcl

A variation on this is that you can copy the .fcl file to your local area and run it from there:

> setup mu2e
> source /grid/fermiapp/mu2e/Offline/v0_3_3/setup.sh
> cp /grid/fermiapp/mu2e/Offline/v0_3_3_SLF5/Mu2eG4/test/g4test_03.fcl myconfig.fcl
  ... edit myconfig.fcl
> mu2e  -c myconfig.fcl

This pattern is used, for example, when doing Monte Carlo production on the grid. In the future, when the experiment has many data files, we will use this same patter to run production reconstruction code on those data files.

Making Run-Time Changes to a Base Release

A much more common use case is:

• setup a base release
• copy a few of the run time configuration files to the local area.
• edit those files
• run mu2e, telling it that run time configuration files from the local area supersede those from the base release.

mygeom.txt:

#include "Mu2eG4/test/geom_01.txt"
bool g4.doCosmicKiller  = true;
int  g4.cosmicKillLevel = 2;

genDYB.txt:

bool   conversionGun.do = false;
bool   cosmicDYB.do     = true;
double cosmicDYB.mean   =  -1;

Then edit myconfig.fcl from the previous section to use these two files in place of geom_01.txt and genconfig_02.txt.

services: {
  user: {
   GeometryService : { inputFile : "mygeom.txt" }
  }
}
physics: {
  producers: {
    generate: {
      module_type   : EventGenerator
      inputfile     : "genDYB.txt"
      seed          : [7789]
    }
  }
}

To run mu2e using the above files:

> setup mu2e
> source /grid/fermiapp/mu2e/Offline/v0_3_3_SLF5/setup.sh
> mu2e  -c myconfig.fcl

The short description of what is going on is that the second line above defines the environment variable MU2E_BASE_RELEASE and third line above defines the environment variable MU2E_TEST_RELEASE. These two elements are part of a search path:

export MU2E_SEARCH_PATH=$MU2E_TEST_RELEASE:$MU2E_BASE_RELEASE:$MU2E_DATA_PATH;

The third element is defined when you execute "setup mu2e" but it is not important for this example. The full details can be found in the discussion about file search paths.

The file search path mechanism does NOT work for the names of event-data input files, for which you must specify a full path, either absolute or relative.

Making Test Releases

There are a few other important use cases:

• Checking out a single package from cvs, editing it and building it against a base release.
• Creating a new package and building it against a base release.
• Creating a sandbox area, indepedent of cvs.

First a big warning. If you plan to checkout a package from cvs, change some header files, and build it against a base release, DO NOT DO IT. Instead you should check out the full Offline software and rebuild it. The issue is that there is no automated way to tell if there are other packages that depend on the header file(s) that you changed; if there are such packages they must be rebuilt but the build system cannot rebuild packages that are not present in your test release.

If you are checking out a package that only has an analyzer module and perhaps a few helper classes/functions used only by that module, then it is safe to use a test release to work on these files. If there is any doubt at all, check out and build the full Offline software.

The main reasons for using a test release is that it is much faster to rebuild a test release than it is to rebuild the full offline software. But there is an intermediate step between the two. Again consider the case that you are working on a package that contains a few modules plus a few helper functions/classes that are only used by those modules. You can check out the full Offline software and do a full build. If you have editted A_module.cc, you can rebuild just that module, plus its dependencies, by:

scons -j 4 lib/libA_module.os

Making a Test Release Using an Existing cvs Package

The following prescription describes how to setup a test release, using the HelloWorld cvs package as an example. The prescription is based on the scripts developed for the Mu2eSoftware workshop in August. Read the section of the workbook that discusses base releases and test releases.

# cd to a clean working directory

setup mu2e

cvs co Offline/HelloWorld
cd Offline

source path_to_base_release/bin/createTestRelease      # Substitute the path to a real base release.
source setup.sh

# edit HelloWorld_module.cc to change the printout to something different.

scons -j 8
mu2e -c HelloWorld/test/hello.fcl

When you log out and log in again, you reestablish the test release environment by:

setup mu2e
# cd to the same working directory as above
cd Offline
source setup.sh

Starting a New CVS Package in a Test Release

We do not have the helper scripts written to start a new cvs package. Here is how to do it.

1. Check out a small subset of Offline. For example,
   • cvs co -P Offline/HelloWorld
2. cd Offline
3. mkdir -p MyPackage/src
4. cd MyPackage/src
5. copy an appropriate SConscript file into MyPackage/src
6. cd ../..
7. cvs add MyPackage
8. cvs add MyPackage/src
9. cvs add MyPackage/src/SConscript
10. cvs commit -m "First release." MyPackage

Making a Test Release For use as a Sandbox

If you want to create a test release for use as a sandbox environment, disconnected from cvs, you can do the following:

# cd to a clean working directory

setup mu2e
source path_to_base_release/bin/createTestRelease      # Substitute the path to a real base release.
source setup.sh

mkdir -p MyPackage/src

# copy an appropriate SConscript file into MyPackage/src
# create some new .cc files in MyPackage/src

scons -j 8

# run mu2e

Security, Privacy, Legal