Project

General

Profile

Developing With LArSoft

Quick links for Developing with LArSoft

Access

In order to submit changes to larsoft code, you need developer access to the redmine repositories. Please send email to . Please let us know who you are and your institutional association.

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

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 at: http://art.fnal.gov/gallery/

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 packages in LArSoft

LArSoft's policy for including new external software packages in the LArSoft distribution:

  • An experiment makes an official request via redmine.
  • 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.

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

  1. Coding guidelines
  2. Code documentation requirements and guidelines
  3. Process for contributing code to LArSoft
  4. Guidelines on writing (and using) services in LArSoft (in general)
  5. Guidelines on writing (and using) algorithms in LArSoft (not specific to any algorithm)
  6. Guidelines on using the geometry
  7. Error handling policy (under development!)
  8. Examples!
  9. some C++ suggestions
  10. Using git repositories

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.

git and git flow

Profiling

Debugging


Building

Using the build system

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

Understanding CMakeLists.txt and product_deps files

mrb (multi-repository build) tool

ups

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.

Also look at Process for contributing code to LArSoft.