LArSoft

{{>toc}}

h1(count). Developing With LArSoft

h2(count). Quick links for Developing with LArSoft

* " LArSoft repositories packages and dependencies ":https://cdcvs.fnal.gov/redmine/projects/larsoft/wiki/_LArSoft_repositories_packages_and_dependencies_

* "Concepts in LArSoft":http://larsoft.org/important-concepts-in-larsoft/

h2(count). 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.

h3(count). LArSoft architecture and design principles

* "Latest architecture document as PDF download":https://cdcvs.fnal.gov/redmine/projects/larsoft-architecture/repository/revisions/master/raw/output/LArSoftArchitecture.pdf

* "Design principles on larsoft.org":http://larsoft.org/important-concepts-in-larsoft/design/

h3(count). LArSoft repositories

  * [[ LArSoft repositories, packages and dependencies ]]

h3(count). The _art_ framework

  * "_art_ documentation on WordPress":http://art.fnal.gov for general information 

  * "_art_ documentation in Redmine":https://cdcvs.fnal.gov/redmine/projects/art/wiki for code specific information

  * "_art_ workbook":http://art.fnal.gov/art-workbook/ for examples and tutorials

  * [[Using art in LArSoft]]

h3(count). _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/

h3(count). External packages

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

|_.Package|_.Namespace|_.Short description|_.Location of headers|

|"C++":http://www.cplusplus.com/reference/|@std::@|\2. Extensions to base C++ that are part of the standard language|

|"ROOT":https://root.cern.ch|See below|Data-analysis tools|@$ROOT_INC@|

|"CLHEP":http://proj-clhep.web.cern.ch/proj-clhep/|@CLHEP::@|Class Library for High-Energy Physics|@$CLHEP_INC/CLHEP@|

|"Geant4":http://geant4.web.cern.ch/geant4/|See below|Detector simulations|@$G4INCLUDE@|

|"GENIE":http://www.genie-mc.org/|@genie::@|Neutrino Monte-Carlo Generator|@$GENIE_INC/GENIE@|

|"boost":http://www.boost.org/|@boost::@|General programming tools for C++|@$BOOST_INC/boost@|

|[[messagefacility:|Message Facility wiki documentation]]|@mf::@|Service for console messages|@$MESSAGEFACILITY_INC@|

|[[art:wiki#Job-configuration|FHiCL Configuration]]|@fhicl::@|Configuration language and parsing tools|@$FHICLCPP_INC@|

|[[NuSoft and LArSoft|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":http://root.cern.ch/root/html522/TTree.html, "TH1":http://root.cern.ch/root/html522/TH1.html) while "Geant4 classes":http://geant4www.triumf.ca/lxr/ begin with "G4" (e.g., "G4Track":http://geant4www.triumf.ca/lxr/source//track/include/G4Track.hh, "G4Step":http://geant4www.triumf.ca/lxr/source//track/include/G4Step.hh). 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":http://root.cern.ch/root/html522/TLorentzVector.html and "CLHEP":http://proj-clhep.web.cern.ch/proj-clhep/doc/CLHEP_2_1_2_2/doxygen/html/LorentzVector_8h.html. 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.

h2(count). 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.

h3(count). Guidelines

# [[The rules and guidelines|Coding guidelines]]

# [[Code documentation requirements and guidelines]]

# [[Process for contributing code to LArSoft]]

# [[Writing LArSoft service|Guidelines on writing (and using) services in LArSoft]] _(in general)_

# [[Writing LArSoft algorithms|Guidelines on writing (and using) algorithms in LArSoft]] _(not specific to any algorithm)_

# [[Guidelines on using the geometry]]

# [[LArSoft examples|Examples!]]

# [[Some C++ good practices|some C++ suggestions]]

---

h3(count). How to...

* ... [[Use associations|create and use associations]]

---

h3(count). [[Tips on updating your code after LArSoft release]]

---

h3(count). Tools and techniques

h4(count). Documenting and browsing code

* "LArSoft Doxygen":http://nusoft.fnal.gov/larsoft/doxsvn/html/index.html - comments in the code are incorporated into documentation using "the Doxygen tool.":http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html

* "LXR Cross Referencer":http://cdcvs.fnal.gov/lxr/ -  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.

h4(count). git and git flow

* [[LArSoft_git_Guidelines|git guidelines]]

* [[cet-is-public:git flow quick start]]

* [[cet-is-public:GitTipsAndTricks|Git Tips and Tricks]]

_(for the purposes of LArSoft development, please please ignore anything other than how to use various git commands to do specific tasks - and especially ignore the workflow advices)_

h4(count). Profiling

* [[memory profiling tools]]

* [[time profiling tools]]

* [[profiling utilities]]

h4(count). 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]]

---

h2(count). Building

h3(count). Using the build system

  * *[[Quick Links|Look for experiment specific guides to using and developing LArSoft code ]]*

  *  Choose the correct release from the [[LArSoft release list|List of LArSoft Releases and Release Notes]]. 

  * [[UpdatingToNewRelease|What to do when there is a new release ]] (a.k.a. **[[UpdatingToNewRelease|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 larsoft-team@fnal.gov.

h3(count). 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

* [[cet-is-public:AddingProductDependencies|Adding Product Dependencies]]: how to edit the @product_deps@ and @CMakeLists.txt@ files to add dependencies

* [[cet-is-public:CodeTips|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

h3(count). mrb (multi-repository build) tool

* "mrb user guide":https://cdcvs.fnal.gov/redmine/projects/mrb/wiki/MrbUserGuide

* "mrb reference guide":https://cdcvs.fnal.gov/redmine/projects/mrb/wiki/MrbRefereceGuide

* "Documentation for buildtool":https://cdcvs.fnal.gov/redmine/projects/cet-is-public/wiki/Buildtool_script

** mrb calls @buildtool@ (from the @cetbuildtools@ product) to perform the build. 

h3(count). ups

* "Getting Started with UPS":https://cdcvs.fnal.gov/redmine/projects/ups/wiki/Getting_Started_Using_UPS and "About UPS":https://cdcvs.fnal.gov/redmine/projects/cet-is-public/wiki/AboutUPS 

* [[cet-is-public:AboutQualifiers|About qualifiers]]:  the things after "-q" in setup <prod> <ver> -q <qual>

* "More Relocatable UPS Documentation":https://cdcvs.fnal.gov/redmine/projects/ups/wiki/Documentation

h2(count). Testing

High-level description of testing is available at "larsoft.org":http://larsoft.org/larsoft-testing/

h3(count). LArSoft Continuous Integration (CI) system

  * "High-level description of CI":http://larsoft.org/continuous-integration/

  * "CI results display page":http://lar-ci-history.fnal.gov/LarCI/app

  * [[lar_ci:| LAr-Continuous-Integration subproject wiki]]

h2(count). 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]]  _(Procedures and policies for making changes to LArSoft releases)_

Also look at  [[Process for contributing code to LArSoft]].