Developing NuTools Code

Below are step by step instructions for developing NuTools Code.

Check out the NuTools repository

First determine a directory in which to develop the code,

mkdir some_working_directory
cd some_working_directory

This directory should be separate from any other code development area, i.e. separate from your experimental code.

Then checkout the head of the repository. If you have write access to the repository do

git clone ssh://

otherwise do

git clone

Instructions for committing changes from a read-only check out are below.

This reference provides a useful quick start guide to git and its commands.

Edit code

We will be following the LArSoft workflow for developing software.

We will be using feature branches for software development that should be based off of the develop branch of the repository. Follow these instructions for creating a feature branch with git flow to setup a new feature branch for your development work. Every time you start work on a new project, it is a good idea to start a feature branch based on the current state of the develop branch.

Build Your Edited Code

First, setup ups and make sure you have the products needed by nutools,

source $EXTERNALS/setup

where $EXTERNALS points to the location of the necessary external products for ART and NuTools. At Fermilab, $EXTERNALS is typically in /grid/fermiapp/products/<experiment>/. For NOvA, the area is /grid/fermiapp/products/nova/externals.

Then, create a build directory,

cd some_working_dir
mkdir nutools_build

and an install directory

mkdir nutools_install

NB nutools_build and nutools_install are suggested names for the build and install directories, you can choose whatever you like.

Then, setup the build

cd nutools_build
source ../nutools/ups/setup_for_development -d (or -p)

The -d option is for a debug build, the -p option is for a prof build. This step sets up the products and establishes the environment.

buildtool -I /full/path/to/nutools_install -b -i

Test Your Build

You will want to test your freshly compiled libraries to be sure they work as expected. To do so, you should really develop test modules that can be run using just ART and put those into a test subdirectory for the package you are editing. If you don't have one of those already, log into your experimental gpvm node from a fresh terminal and setup for your experiment. That will setup the public version of nutools.

You want to be able to use your private version. First copy the .upsfiles directory from /nusoft/app/externals directory into your nutools_install directory

cp -R /nusoft/app/externals/.upsfiles nutools_install

Then un-setup the public version of nutools and add your nutools_install directory to the PRODUCTS environmental variable

unsetup nutools
export PRODUCTS=/full/path/to/nutools_install:$PRODUCTS

It is better if you have not setup your experiment specific code.

Finally, setup your new copy of nutools

setup nutools vX_YY_ZZ -q <build base>:<build type>

where vX_YY_ZZ is the current nutools version and <build base> is the same as the art <build base> you are building against and <build type> is either debug or prof.

The necessary environmental variables have now been set for you to use your local version of nutools.

You will need to rebuild any packages that depend on the NuTools code and run a test job.

The dependencies for nutools are defined in the ups/product_deps file.

Trouble Shooting

If you have an error of the form

ERROR: Version conflict -- dependency tree requires versions conflicting with current setup of product XXX: version vA_B_C vs vD_E_F

That error means that the version of nutools checked out into your private area is set to look for version A_B_C of the external product XXX (i.e. art, genie, etc) and you have already setup version D_E_F. Try an unsetup of the product

unsetup XXX

Then try setting up nutools again.

Committing From A Read-Only Checkout

Open the .git/config file of your cloned repository in a text editor and change the remote URL to the read/write URL indicated above. You will then be able to push your changes to the remote repository. After pushing your changes, please rest the remote URL to the read only version.

Tagging a Release and Building the UPS Product Files - Experts Only

NB Do not attempt to tag a release and build new product files without explicit permission from Brian Rebel.

First check that the code compiles and runs as expected.

Tags are of the form X.YY.ZZ and the value is determined by the previous tag. If you are adding functionality or tagging for a new release of ART, you want to update the minor version number, ie YY. If you are making a patch, update the ZZ.

The version is on the "parent" line of product_deps. You will also need to update the versions for the products that nutools depends on in the product_deps file as well. Once those updates are done, you can should commit them to the repository.

To build a tagged release please use the Jenkins build system.