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 first steps in accessing the code are listed as te headings in this page. There is a mu2e setup, several ways to access the code itself, then setup the code environment, then building it.

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 existing release, you probably want to use a satellite release. In this case you might build a small piece of the code locally, or modify fcl and geometry file, and take the rest of the code base from the tagged, pre-built release. Obviously, 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 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 much 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)
• 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

• 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

• git copies the entire code history locally so now you have the choice of which branch or tag to start with. Unless a different choice is specifically required, you will work on the head:

  git checkout -b work

Setup code

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

• run the setup script which points the environment to this location, and selects appropriate version of art, root and geant, amonf others.

  cd Offline

source setups.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

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

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.