CodeRecipe

Introduction

This page shows the basic steps in setting up, checking out and building the mu2e code base. If you haven't read the computing overview and tried the tutorials, please do that first.

You have the choice of running code from a tagged, pre-built release, building the code locally, or building a small part of the code locally in a satellite release. You will need to pick one before working though this page. If you only need to modify a geometry file, modify a fcl file, add a print statement, or add a private analysis module, but otherwise can use a tagged release, then you can use a satellite release. If you are doing extensive development work, in particular modifying existing header files, or you plan to commit your work back to the repository, you probably need to check out the entire repository.

Setup (environment)

There are three basic steps, plus options, to setting up the code environment.

1. Locate the non-mu2e UPS utility packages (python, ifdh, jobsub). If cvmfs is mounted (as it is on the mu2egpvm machines, the grid, and most other places) you can source this setup file. If cvmfs is not mounted, ask your local experts where is. The main point here is to point the PRODUCTS environmental to the UPS products area.

   source /cvmfs/fermilab.opensciencegrid.org/products/common/etc/setups

2. The next step is to setup general mu2e environmental variables. This is a UPS product which you located in the first step. The main point here is to add the directory of mu2e-specific products to the PRODUCTS path and setup a version of git.

   setup mu2e

3. source a setup.sh file in a specific code release. This will point environmentals to this specific build of code so when you run an executable, the shared libraries, fcl control files, and data come from this build. It also determines which version of art, geant and root you will use. If you are
   • if you are using a tagged release, pre-built on the cvmfs disk (or possibly other places) you will source the setup file from that release. You can see the path determines the release tag, the platform (SLF6), and the choice of optimized (prof) or debug.

      source /cvmfs/mu2e.opensciencegrid.org/Offline/v6_0_0/SLF6/prof/Offline/setup.sh

   • If you are building the code locally, you will have to checkout the code first (see below). In a local build, you have more control. The optimized (prof) build is default, but you can chose to chose the debug build with the following. buildopts is a script with a --help switch to see other options.

     ./buildopts --build=debug

     The buildopts setting is sticky - it is saved locally and applied automatically in subsequent setups. The setup then looks like

     source /path/Offline/setup.sh

If you log out and back in, you can follow the same procedure (except buildopts) to recover the environment.

The setup procedures are the same on the grid node, where cvmfs is mounted

Warning: UPS products have the ability to unsetup and resetup, basically overwriting a previous setup. This procedure can be ambiguous and difficult to maintain, so we have a rule that you do step 3 (sourcing a release setup.sh) only once in a session. If you need to switch to a different release, or switch between prof and debug, then open a new window and execute the new setup there.

There are plenty of other packages we use for various purposes, which can be added to these setups, such as "setup mu2egrid" or "setup sam_web_client", for example.

Checkout

You have the choice of running a tagged, pre-built release, building the code locally, or building a small part of the code locally in a satellite release. To run in a pre-built release, you only need to perform the above setup steps. If you can use a tagged release, and only need to modify a geometry file, modify a fcl file, add a print statement, or add an analysis module, you can use a satellite release. If you are doing extensive development work, in particular modifying existing headed files, you probably want to check out the entire repository.

See git for much more information about tools, commits, branches, tags.

You should never need to checkout or build code in a grid job, please see workflows.

Satellite (partial) local build

Create a working release area, that is tied to a base release.

• create the working directory (typically in /mu2e/app/users/$USER, see disks)
• since you will be working on a part of a release locally, you will need a base release where the rest of the code comes from. This would typically be a tagged release from cvfms, but may be any existing full (non-satellite) release. Execute the satellite script from that release:

  /cvmfs/mu2e.opensciencegrid.org/Offline/v6_0_0/SLF6/prof/Offline/bin/createSatelliteRelease

• cd Offline and use this local setups.sh in the setup procedure above
• see the tutorials for examples of how to get pieces of Offline into this area

Please see the satellite release documentation for details of how it works.

Full local build

Checking out the entire repository. If you will only modify this code locally, then you can check it out with readonly. If you will need to commit the code back to the repository, you will need to check the code with kerberos authentication.

• create the working directory (typically in /mu2e/app/users/$USER, see disks)
• checking out the main repository
  • readonly:

    git clone http://cdcvs.fnal.gov/projects/mu2eofflinesoftwaremu2eoffline/Offline.git

  • with kerberos authentication for committing code

    git clone ssh://p-mu2eofflinesoftwaremu2eoffline@cdcvs.fnal.gov/cvs/projects/mu2eofflinesoftwaremu2eoffline/Offline.git

• cd Offline and use this local setups.sh in the setup procedure above

Build

If you are running an executable out of a pre-built tagged release, then you do not need to build, of course. If you have assembled a full of satellite local release above, then you need to build it.

cd /path/Offline
scons -j 4 

The "j" switch says to run 4 parallel threads, which is recommended for the mu2egpvm interactive machines. You can also clean a release (delete object files):

scons -c -j 4

Please see the scons documentation for a more detailed discussion of the scons options, including how to force build of a subset of dependencies.