Developing With LArSoft

Any collaborator can develop or modify code and contribute it to LArSoft. On this page, we describe the procedures for submitting code (via a GitHub pull request), coding guidelines and policies, and other information that might be of use to LArSoft code developers.

Quick links for Developing with LArSoft

Platforms

LArSoft currently supports the platforms listed here. Users who wish to develop on an unsupported platform are encouraged to use a container approach. Please note important caveats with respect to using Docker.

Designing

To design LArSoft code, it’s important to understand the core LArSoft suite and all the components used by it. Reference the items below when designing new software.

LArSoft architecture and design principles

LArSoft packages and repositories

The art framework

art documentation on WordPress for general information
art documentation in Redmine for code specific information
art workbook for examples and tutorials
Using art in LArSoft

gallery

gallery provides lightweight access to event data in art/ROOT files outside the art event processing framework executable. It is not an alternative framework; rather, it provides a library that can be used to write programs that need to read (but not write) art/ROOT files. Information is available here

Writing code

Whether you are writing new code or modifying existing code, please follow the guidelines listed below. There are also development tools and techniques available that can make coding easier.

Guidelines

Multi-threading in LArSoft

How to…

Tips on updating your code after LArSoft release

Tools and techniques

Documenting and browsing code

LArSoft Doxygen - comments in the code are incorporated into documentation using the Doxygen tool.
LXR Cross Referencer - general purpose source code indexer and cross-referencer that provides web-based browsing of source code with links to the definition and usage of any identifier. Supports multiple languages. Includes LArSoft code. Note, pages may take several seconds to load.

Working with GitHub and contributing code via LArSoft pull requests

Start by reviewing the information on the overview page for using LArSoft with GitHub. Contact your experiment offline management to identify acting Level 2 managers. Send any comments to The Scisoft Team, or via Redmine issues.

git and git flow

NOTE: These are instructions for working with the legacy Redmine-based git repositories, and are recommended for experiments that continue to use Redmine for their experiment code. All LArSoft repositories have been moved to GitHub. Please refer to the instructions on the Working with GitHub page for current instructions on using GitHib and contributing code to LArSoft.

Profiling

Debugging

Debugging LArSoft with Allinea
Debugging LArSoft with RogueWave TotalView. (TotalView is no longer being paid for. Please use Allinea above instead.)
Debugging with gdb

Building

Using the build system

Look for experiment specific guides to using and developing LArSoft code
Choose the correct release from the List of LArSoft Releases and Release Notes.
What to do when there is a new release (a.k.a. update LArSoft version)

To get write access to the repositories, speak to the offline coordinator for your experiment. If you have a question, send email to the SciSoft Team.

Understanding CMakeLists.txt and product_deps files

cet-is-public:Cetbuildtools cmake modules: such as cet_make and cet_add_compiler_flags. Used in CMakeLists.txt files throughout LArSoft
cet-is-public:Art cmake modules: such as art_make and simple_plugin. Used in CMakeLists.txt files throughout LArSoft
cet-is-public:Defining products in the CET build environment: explains the product_deps file
Adding Product Dependencies: how to edit the product_deps and CMakeLists.txt files to add dependencies
Various helpful tips for coding in the CET C environment: things you hope you never need to know
cet-is-public:Building your own code with cmake: pointer to a really simple example
Finding unresolved symbols: automatic library search for symbols

mrb (multi-repository build) tool

mrb user guide
mrb reference guide
Documentation for buildtool
- mrb calls buildtool (from the cetbuildtools product) to perform the build.

ups

Getting Started with UPS and About UPS
About qualifiers: the things after “-q” in setup -q
More Relocatable UPS Documentation

Testing

High-level description of testing is available at larsoft.org

LArSoft Continuous Integration (CI) system

Submitting for next release

After designing, coding, building and testing a piece of software, submit it to the LArSoft development branch so it is included in a new release.

Getting new code into a LArSoft release

Also look at Process for contributing code to LArSoft.

External packages

These are package written and maintained by the general physics and computing communities for

Package	Namespace	Short description	Location of headers
C	`std::`	Extensions to base C that are part of the standard language
ROOT	See below	Data-analysis tools	`$ROOT_INC`
CLHEP	`CLHEP::`	Class Library for High-Energy Physics	`$CLHEP_INC/CLHEP`
Geant4	See below	Detector simulations	`$G4INCLUDE`
GENIE	`genie::`	Neutrino Monte-Carlo Generator	`$GENIE_INC/GENIE`
boost	`boost::`	General programming tools for C	`$BOOST_INC/boost`
Message Facility wiki documentation	`mf::`	Service for console messages	`$MESSAGEFACILITY_INC`
FHiCL Configuration	`fhicl::`	Configuration language and parsing tools	`$FHICLCPP_INC`
nutools and LArSoft	`simb::`	Neutrino platform tools	`$NUTOOLS_INC`

ROOT and Geant4 do not use namespaces. In general, ROOT classes begin with “T” (e.g., TTree, TH1) while Geant4 classes begin with “G4” (e.g., G4Track, G4Step). Exception: Some of the newer ROOT sub-packages have namespaces (such as ROOT::Math::, ROOT::Fit::, ROOT::Minuit2::, Reflex::, TMVA::).

Some of these packages duplicate functionality; e.g., 4-vectors are implemented in both ROOT and CLHEP. Given a choice, use a package that’s higher in the above tables over one that’s lower; e.g., choose ROOT classes over their CLHEP equivalents.

Policy for including new external packages in LArSoft

To include new external software packages into the LArSoft distribution, or to create a new external dependency:

An experiment makes an official request via redmine issue ticket.
LArSoft verifies that it has permission to use the tool for research.
LArSoft verifies that the package will be be used by more than one experiment. Note: if only one experiment intends to use the package, the SciSoft team can help, but the end product would reside in the experiment’s code, not in LArSoft.
LArSoft has to be able to build the tool such that it has binary compatibility with other products which will be used at the same time. This means that any dependencies (e.g., python) must be the same as those used by the matching LArSoft distribution. In addition, if the product contains C or Fortran code, the product must be buildable with the same compiler used by the matching LArSoft release.
If the package is built into LArSoft code, it must not have a license that affects the license of the LArSoft code. We must be able to distribute our LArSoft code without having to add their license to our code or change the way we distribute LArSoft code with it in there. For a package that isn’t linked into any part of the main LArSoft distribution, such as an analysis tool, LArSoft still needs to have permission to use the package for research, but isn’t worried about the licensing affecting LArSoft code.