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.

The main steps in accessing the code are listed as headings in this page. There is a mu2e setup, several ways to access the code itself, then setting up the code environment, then building the code.

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 to a module, 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 probably check out the entire repository.

Setup (mu2e environment)

These steps are to set up the mu2e environment, before committing to a specific version of the code.

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

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

   If cvmfs is not mounted, ask your local experts where the local copy of this file is.
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

You have to do this every time you log in, if you want the access UPS products or work with mu2e code. You can add these steps to your login scripts, see shells

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 do not support these features. If you need to change a setup, you should log in a new window and perform the alternative setup there.

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

Locate or checkout code

You have the choice of running an executable from a tagged, pre-built release, or building a small part of the code locally in a satellite release, or building the entire code base.

If you run from a tagged release, you need to decide which version to use which is a string like "v6_0_0". Usually which version to chose is clear from the goals of the project, but without any further guidance, you can use the highest numbered release available. You can see the available releases with "ls $MU2E/Offline".

If you want to make small, temporary modifications to an existing release, you probably want to use a satellite release. In this case you might add or change a small piece of the code locally, or modify fcl or geometry files, and take the rest of the code base from the tagged, pre-built release. Working in this style saves the time to build the entire code base. You will need to chose a tagged release to proceed.

If you are making extensive changes or planning to commit changes, then you probably want to checkout and build the entire code base locally, in your area. In this case, you will probably either want to make changes to the current code base (the head) or to the head of a branch. See git for more information about code commits, branches, tags.

In all cases, you have the choice to work in the optimized code build (prof) or in the debug code build. The choices are explained in the subsections below.

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

Satellite (partial) local build

Create a working release area that is derived from a base release and make limited, temporary changes or additions to the mu2e code.

• create the working directory (typically in /mu2e/app/users/$USER, see disks) and cd to it
• 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 cvmfs. Execute the satellite script from that release:

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

  You can see that the path determines the release tag (V6_0_0), the platform (SLF6), and the choice of optimized (prof) or debug.
• see the tutorials or satellite release documentation for examples of how to get pieces of Offline into this area, where you can modify it.

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) and cd to it
• copy the main repository locally
  • 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

• git copies the entire code history locally so now you have the choice of which branch or tag to start with or "checkout". Unless a different choice is specifically required by your project, you should work on the head, which is the latest version

  git checkout -b work

Setup code

At this point you have either selected a tagged release or have a satellite or full release locally. In either case, you will source the setup.sh script in the release area. 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 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 that the path determines the release tag (V6_0_0), 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 made a satellite release, source the setup in that local release directory.

  source Offline/setup.sh

• If you have checked out the full code base locally, you can still chose prof or debug. The prof build is default, but you can chose the debug build with the following command. 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 final step is to source the setup in your local area

  source 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

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 or satellite local release above, then you will need to build it.

cd Offline
scons -j 4 

The "-j 4" 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.

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