Building BTrk

The BTrk package is a repackaging of the BaBaR tracking code that Mu2e has used for many years. Previously the BaBaR code was maintained in an svn repository at LBL and was used by checking it out on top of Mu2e Offline source and building it as a part of Mu2e Offline.

The BTrk source code is now maintained in github, as a packaged named BTrk, and is distributed as the ups package named BTrk. Mu2e Offline finds the BTrk header files and shared libraries in the ups product. For convenience the BTrk source code is also distributed as part of the ups product (more precisely, the source code found in a version of the ups product is the code used to build that particular version of the product).

This page explains how to build, install and use your own version of the BTrk package.

Overview

To build, install and use your own version of BTrk, follow the steps listed here. Additional details for each step follow.

1. Clone the github repository
2. Intialize your own ups respository (if you already have one, you can reuse it).
3. Build the code and install it in your ups repository.
4. Build the Mu2e Offline against your version of BTrk
   1. Modify the PRODUCTS environment variable to put your repository ahead of the standard Mu2e repository
   2. If necessary edit the setup.sh file in Mu2e Offline to choose your version of BTrk.
   3. Build the Mu2e Offline code normally.

Clone The github Repository

The repository is readable by the public. To clone a copy of the repository:

git clone https://github.com/KFTrack/BTrk.git

Most of us will not have write access to the BTrk repository. Instead we will use a request to pull protocol.

Initializing your own UPS Repository

1. Create an empty directory.
   1. The name of the directory is not important but the usual choice is artexternals.
   2. If you plan to run jobs on Fermgrid, you should put this diretory in your space on /mu2e/app/users.
   3. If you plan only to run interactively, the path to this directory is not important.
   4. In the following we will call this directory your ups repository.
2. cd to your ups repository.
3. Copy the .upsfiles subdirectory from the Mu2e ups respository. For example:

   cp -r  /cvmfs/mu2e.opensciencegrid.org/artexternals/.upsfiles .
   

4. On every login, after you do setup mu2e you need to define the following environment variables

      export PRODUCTS_INSTALL=/absolute/path/to/your/products/directory
      export PRODUCTS=${PRODUCTS_INSTALL}:${PRODUCTS}
   

   It is important that you do the second step after you do setup mu2e.

Build the BTrk Code

When you cloned the BTrk git repository, it created a directory named BTrk. In the following we will refer to this as your source directory.

The build scripts are configured to make two kinds of builds, prof and debug. The prof build is an optimized build with -DNDEBUG and with a partly stripped executable; enough symbols are retained that a code profiler will produce useful information, hence the name.

This build system does out-of-source builds. This means that the source code lives in one directory, you do the prof build in a second directory and, if you want a debug build, you do that build in a third directory. This will be spelled out in detail below. If you need more builds, with more variations, you do each in a separate directory.

In the following, the directories in which you do a build will be called a build directory.

We recommend that you create build directories in your disk space on /mu2e/app/users. Why? This is a large disk that is mounted exec and it is not backed up; we don't want to waste space on backed up disks with binaries that are easily recreated from backed up source.

Here are the steps to build code:

In your source directory do the following:

1. If you want to build a particular tag of BTrk, check it out:

   git checkout -b local_branch_name tag_name
   

   where local_branch_name is ususally something like tag_name_branch. By default you will build the head of the master branch.
2. If you want your build of the BTrk product to have a unique version name, edit the file setup.sh and modify the definition of the environment variable PACKAGE_VERSION. For example;

   export PACKAGE_VERSION=v1_00_08_test
   

The following instructions describe actions you take in your build directory. They will describe how to make a profile build; to make a debug build, change prof to debug everywhere in the instructions.

1. If necessary, initailize the mu2e environment:

   setup mu2e
   

   Or the equivalent at a remote site.
2. Create an empty build directory. I usually choose a name like build_prof for a prof build and build_debug for a debug build. For example:

   mkdir build_prof
   cd build_prof
   

3. Initialize the build directory:

   source <path_to_your_source_directory>/scripts/newBuild.sh prof
         

   If the first argument is neither prof or debug the script will report an error and do nothing. This will create two files in the directory, setup.sh and SConstruct.
4. Source the setup script:

   source setup.sh
         

   This tells the build system where your source directory is; it also tells the build system whether to do a debug or prof build (it remembers the argument that you gave to newBuild.sh).
5. Run the build system:

   scons -j 8
   

   The numerical value of the -j option sets the maximum amount of parallelism in the build.
6. If the build completes successfully, you can install the BTrk product in your ups repository.

   source  <path_to_your_source_directory>/scripts/install.sh
   

   This will create a subdirectory BTrk in your ups repository. Compare your ups repository to the Mu2e artexternals on cvmfs.

If you logout and log in again, you need to:

1. Establish the Mu2e environment

   setup mu2e
   

2. Perform step 4 from "Initializing your ups Repository".

   export PRODUCTS_INSTALL=/absolute/path/to/your/products/directory
   export PRODUCTS=${PRODUCTS_INSTALL}:${PRODUCTS}
   

3. cd to your build directory

4. source setup.sh
   

Building Mu2e Offline agains your version of BTrk

1. Initialize the Mu2e environment:

   setup mu2e
   

2. Perform step 4 from "Initializing your ups Repository".

   export PRODUCTS_INSTALL=/absolute/path/to/your/products/directory
   export PRODUCTS=${PRODUCTS_INSTALL}:${PRODUCTS}
   

3. Clone the Mu2e repository and cd to Offline

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

4. If necessary, edit setup.sh to select the version of BTrk that is installed in your ups repository. If you have resused an existing version number, ups will choose your version in preference to the offical Mu2e version because it accepts the first match and your ups repository is ahead of the Mu2e repository.
5. Setup the required ups products:

   source setup.sh
   

6. Build the Mu2e code:

   scons -j 8
   

Request to Pull Protocol

If you do wish to contribute your changes to BTrk then read the rest of this section.

Mu2e will use BTrk to experiment with a way of contributing code that is new to us but is widely used elsewhere. If we decide that we like this method we will adopt some variation of it for all of our git repositories.

1. If you have not already done so, create an account for yourself on github.com.
2. Log in to your github account.
3. Make a fork of BTrk on your own github account. To do this, go to https://github.com/KFTrack/BTrk and click on fork in the top right.
4. When you clone BTrk, make the clone from your own github BTrk repository:

   git clone git@github.com:<your github username>/BTrk
   

5. Make your edits and add new commits, either onto a new branch or directly onto master
6. Push as normal:

    git push origin 
   

   But now origin will point to your fork and not the main BTrk repository.
7. Create a pull-request from the branch on your fork to the main repository. This sends a message to everyone registered with the main BTrk repository and announces that you have new code to contribute. To do this, go to the webpage for your fork and click the green "compare" button. Instructions can be found here: https://help.github.com/articles/creating-a-pull-request.
8. Anyone who wishes to try out your code can merge the branch from your fork into their clone and give it a try. Git hub has automatic tools for recognizing merge conflicts before you actually do the merge! In this case it will tell you the git commands needed to pull to your local clone, merge locally ( fixing any conflicts ) and push it back.
9. Someone who is assigned to do so can do the appropriate testing and quality control. Probably one of our requirements will be that the pull request be fast-forward mergable into the master branch of the main BTrk repository.
10. Presuming that your code passes these tests, someone with write permission on the main BTrk repository will then merge your code into main BTrk repository.
11. If your code fails the testing or quality control it will be sent back to you to be fixed.
12. We may choose to adopt a policy that no-one should merge their own pull request into the main repository. This ensures that everything has at least two sets of eyes on it.
13. Two other features of this model are:
    1. You can push work-in-progress to your own fork of BTrk in github. This adds another layer of distributed backup for your work-in-progress.
    2. It is straightforward for others to see your work-in-progress and comment on it.

Security, Privacy, Legal