Project

General

Profile

Developing With LArSoft » History » Version 93

Erica Snider, 09/26/2018 02:51 PM

1 3 Lynn Garren
{{>toc}}
2 3 Lynn Garren
3 52 Katherine Lato
h1(count). Developing With LArSoft
4 1 Katherine Lato
5 52 Katherine Lato
h2(count). Quick links for Developing with LArSoft
6 36 Katherine Lato
7 35 Katherine Lato
* " LArSoft repositories packages and dependencies ":https://cdcvs.fnal.gov/redmine/projects/larsoft/wiki/_LArSoft_repositories_packages_and_dependencies_
8 45 Katherine Lato
* "Concepts in LArSoft":http://larsoft.org/important-concepts-in-larsoft/
9 1 Katherine Lato
10 92 Lynn Garren
h2(count). Access
11 92 Lynn Garren
12 92 Lynn Garren
In order to submit changes to larsoft code, you need developer access to the redmine repositories.  Please send email to larsoft-team@fnal.gov.  Please let us know who you are and your institutional association.
13 92 Lynn Garren
14 52 Katherine Lato
h2(count). Designing
15 30 Katherine Lato
16 41 Katherine Lato
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.
17 34 Erica Snider
18 52 Katherine Lato
h3(count). LArSoft architecture and design principles
19 1 Katherine Lato
20 61 Gianluca Petrillo
* "Latest architecture document as PDF download":https://cdcvs.fnal.gov/redmine/projects/larsoft-architecture/repository/revisions/master/raw/output/LArSoftArchitecture.pdf
21 76 Katherine Lato
* "Design principles on larsoft.org":http://larsoft.org/important-concepts-in-larsoft/design/
22 1 Katherine Lato
23 85 Katherine Lato
h3(count). LArSoft packages and repositories
24 1 Katherine Lato
25 1 Katherine Lato
  * [[ LArSoft repositories, packages and dependencies ]]
26 86 Katherine Lato
  * [[Geometry Package]]
27 88 Katherine Lato
  * [[LArSoft art-independent code and repositories]]
28 1 Katherine Lato
29 63 Gianluca Petrillo
h3(count). The _art_ framework
30 29 Katherine Lato
31 66 Katherine Lato
  * "_art_ documentation on WordPress":http://art.fnal.gov for general information 
32 66 Katherine Lato
  * "_art_ documentation in Redmine":https://cdcvs.fnal.gov/redmine/projects/art/wiki for code specific information
33 66 Katherine Lato
  * "_art_ workbook":http://art.fnal.gov/art-workbook/ for examples and tutorials
34 64 Katherine Lato
  * [[Using art in LArSoft]]
35 1 Katherine Lato
36 78 Katherine Lato
h3(count). _gallery_
37 78 Katherine Lato
38 78 Katherine Lato
_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/
39 78 Katherine Lato
40 52 Katherine Lato
h3(count). External packages
41 1 Katherine Lato
42 67 Katherine Lato
These are package written and maintained by the general physics and computing communities for 
43 1 Katherine Lato
44 36 Katherine Lato
|_.Package|_.Namespace|_.Short description|_.Location of headers|
45 36 Katherine Lato
|"C++":http://www.cplusplus.com/reference/|@std::@|\2. Extensions to base C++ that are part of the standard language|
46 36 Katherine Lato
|"ROOT":https://root.cern.ch|See below|Data-analysis tools|@$ROOT_INC@|
47 36 Katherine Lato
|"CLHEP":http://proj-clhep.web.cern.ch/proj-clhep/|@CLHEP::@|Class Library for High-Energy Physics|@$CLHEP_INC/CLHEP@|
48 36 Katherine Lato
|"Geant4":http://geant4.web.cern.ch/geant4/|See below|Detector simulations|@$G4INCLUDE@|
49 36 Katherine Lato
|"GENIE":http://www.genie-mc.org/|@genie::@|Neutrino Monte-Carlo Generator|@$GENIE_INC/GENIE@|
50 36 Katherine Lato
|"boost":http://www.boost.org/|@boost::@|General programming tools for C++|@$BOOST_INC/boost@|
51 65 Katherine Lato
|[[messagefacility:|Message Facility wiki documentation]]|@mf::@|Service for console messages|@$MESSAGEFACILITY_INC@|
52 72 Gianluca Petrillo
|[[art:wiki#Job-configuration|FHiCL Configuration]]|@fhicl::@|Configuration language and parsing tools|@$FHICLCPP_INC@|
53 42 Katherine Lato
|[[NuSoft and LArSoft|nutools and LArSoft]]|@simb::@ ...|Neutrino platform tools|@$NUTOOLS_INC@|
54 20 Katherine Lato
55 42 Katherine Lato
56 36 Katherine Lato
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::@).
57 20 Katherine Lato
58 36 Katherine Lato
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.
59 36 Katherine Lato
60 91 Katherine Lato
h3(count). Policy for including new packages in LArSoft
61 91 Katherine Lato
62 91 Katherine Lato
LArSoft's policy for including new external software packages in the LArSoft distribution:
63 91 Katherine Lato
64 91 Katherine Lato
* An experiment makes an official request via redmine.
65 91 Katherine Lato
* LArSoft verifies that it has permission to use the tool for research.
66 91 Katherine Lato
* 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.
67 91 Katherine Lato
* 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.
68 91 Katherine Lato
* 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.
69 91 Katherine Lato
70 91 Katherine Lato
71 91 Katherine Lato
72 52 Katherine Lato
h2(count). Writing code
73 1 Katherine Lato
74 47 Katherine Lato
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.
75 47 Katherine Lato
76 52 Katherine Lato
h3(count). Guidelines
77 47 Katherine Lato
78 80 Katherine Lato
# [[The rules and guidelines|Coding guidelines]]
79 84 Katherine Lato
# [[Code documentation requirements and guidelines]]
80 80 Katherine Lato
# [[Process for contributing code to LArSoft]]
81 80 Katherine Lato
# [[Writing LArSoft service|Guidelines on writing (and using) services in LArSoft]] _(in general)_
82 80 Katherine Lato
# [[Writing LArSoft algorithms|Guidelines on writing (and using) algorithms in LArSoft]] _(not specific to any algorithm)_
83 80 Katherine Lato
# [[Guidelines on using the geometry]]
84 93 Erica Snider
# [[LArSoft Error Handling|Error handling policy (under development!)]]
85 80 Katherine Lato
# [[LArSoft examples|Examples!]]
86 80 Katherine Lato
# [[Some C++ good practices|some C++ suggestions]]
87 90 Lynn Garren
# [[Using git repositories]]
88 1 Katherine Lato
89 60 Katherine Lato
---
90 60 Katherine Lato
91 83 Gianluca Petrillo
h3(count). How to...
92 83 Gianluca Petrillo
93 83 Gianluca Petrillo
* ... [[Use associations|create and use associations]]
94 87 Gianluca Petrillo
* ... [[From_ROOT_vectors_(TVector3)_to_ROOT_GenVector|use the new ROOT vectors and linear algebra classes in the code]] (GenVector, SMatrix)
95 87 Gianluca Petrillo
96 83 Gianluca Petrillo
97 83 Gianluca Petrillo
---
98 83 Gianluca Petrillo
99 79 Gianluca Petrillo
h3(count). [[Tips on updating your code after LArSoft release]]
100 79 Gianluca Petrillo
101 79 Gianluca Petrillo
---
102 79 Gianluca Petrillo
103 52 Katherine Lato
h3(count). Tools and techniques
104 47 Katherine Lato
105 75 Gianluca Petrillo
h4(count). Documenting and browsing code
106 75 Gianluca Petrillo
107 75 Gianluca Petrillo
* "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
108 75 Gianluca Petrillo
* "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.
109 75 Gianluca Petrillo
110 52 Katherine Lato
h4(count). git and git flow
111 47 Katherine Lato
112 67 Katherine Lato
* [[LArSoft_git_Guidelines|git guidelines]]
113 57 Katherine Lato
* [[cet-is-public:git flow quick start]]
114 67 Katherine Lato
* [[cet-is-public:GitTipsAndTricks|Git Tips and Tricks]]
115 67 Katherine Lato
_(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)_
116 57 Katherine Lato
117 52 Katherine Lato
h4(count). Profiling
118 1 Katherine Lato
119 48 Katherine Lato
* [[memory profiling tools]]
120 48 Katherine Lato
* [[time profiling tools]]
121 48 Katherine Lato
* [[profiling utilities]]
122 48 Katherine Lato
123 52 Katherine Lato
h4(count). Debugging
124 48 Katherine Lato
125 56 Katherine Lato
* [[Debugging LArSoft with Allinea]] 
126 56 Katherine Lato
* [[Debugging LArSoft]] with RogueWave TotalView. (*TotalView is no longer being paid for. Please use Allinea above instead.*)
127 55 Katherine Lato
* [[Debugging with gdb]]
128 60 Katherine Lato
129 60 Katherine Lato
---
130 1 Katherine Lato
131 52 Katherine Lato
h2(count). Building
132 1 Katherine Lato
133 67 Katherine Lato
h3(count). Using the build system
134 1 Katherine Lato
135 36 Katherine Lato
  * *[[Quick Links|Look for experiment specific guides to using and developing LArSoft code ]]*
136 71 Katherine Lato
  *  Choose the correct release from the [[LArSoft release list|List of LArSoft Releases and Release Notes]]. 
137 73 Gianluca Petrillo
  * [[UpdatingToNewRelease|What to do when there is a new release ]] (a.k.a. **[[UpdatingToNewRelease|update LArSoft version]]**)
138 67 Katherine Lato
  
139 67 Katherine Lato
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.
140 44 Lynn Garren
141 67 Katherine Lato
h3(count). Understanding CMakeLists.txt and product_deps files
142 67 Katherine Lato
143 1 Katherine Lato
* [[cet-is-public:Cetbuildtools cmake modules]]:  such as @cet_make@ and @cet_add_compiler_flags@. Used in @CMakeLists.txt@ files throughout LArSoft
144 1 Katherine Lato
* [[cet-is-public:Art cmake modules]]: such as @art_make@ and @simple_plugin@. Used in @CMakeLists.txt@ files throughout LArSoft
145 1 Katherine Lato
* [[cet-is-public:Defining products in the CET build environment]]: explains the @product_deps@ file
146 1 Katherine Lato
* [[cet-is-public:AddingProductDependencies|Adding Product Dependencies]]: how to edit the @product_deps@ and @CMakeLists.txt@ files to add dependencies
147 1 Katherine Lato
* [[cet-is-public:CodeTips|Various helpful tips for coding in the CET C++ environment]]: things you hope you never need to know
148 1 Katherine Lato
* [[cet-is-public:Building your own code with cmake]]:  pointer to a _really_ simple example
149 89 Robert Hatcher
* [[Using find_global_symbol.sh to find unresolved symbols]]: automatic library search for symbols
150 1 Katherine Lato
151 67 Katherine Lato
h3(count). mrb (multi-repository build) tool
152 67 Katherine Lato
153 67 Katherine Lato
* "mrb user guide":https://cdcvs.fnal.gov/redmine/projects/mrb/wiki/MrbUserGuide
154 67 Katherine Lato
* "mrb reference guide":https://cdcvs.fnal.gov/redmine/projects/mrb/wiki/MrbRefereceGuide
155 67 Katherine Lato
* "Documentation for buildtool":https://cdcvs.fnal.gov/redmine/projects/cet-is-public/wiki/Buildtool_script
156 67 Katherine Lato
** mrb calls @buildtool@ (from the @cetbuildtools@ product) to perform the build. 
157 67 Katherine Lato
158 67 Katherine Lato
h3(count). ups
159 67 Katherine Lato
160 77 Katherine Lato
* "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 
161 67 Katherine Lato
* [[cet-is-public:AboutQualifiers|About qualifiers]]:  the things after "-q" in setup <prod> <ver> -q <qual>
162 67 Katherine Lato
* "More Relocatable UPS Documentation":https://cdcvs.fnal.gov/redmine/projects/ups/wiki/Documentation
163 36 Katherine Lato
164 38 Katherine Lato
h2(count). Testing
165 1 Katherine Lato
166 76 Katherine Lato
High-level description of testing is available at "larsoft.org":http://larsoft.org/larsoft-testing/
167 38 Katherine Lato
168 38 Katherine Lato
h3(count). LArSoft Continuous Integration (CI) system
169 36 Katherine Lato
170 52 Katherine Lato
  * "High-level description of CI":http://larsoft.org/continuous-integration/
171 82 Vito Di Benedetto
  * "CI results display page":http://lar-ci-history.fnal.gov/LarCI/app
172 82 Vito Di Benedetto
  * [[lar_ci:| LAr-Continuous-Integration subproject wiki]]
173 1 Katherine Lato
174 67 Katherine Lato
h2(count). Submitting for next release
175 36 Katherine Lato
176 52 Katherine Lato
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.
177 42 Katherine Lato
178 42 Katherine Lato
* [[Getting new code into a LArSoft release]]  _(Procedures and policies for making changes to LArSoft releases)_
179 81 Katherine Lato
180 81 Katherine Lato
Also look at  [[Process for contributing code to LArSoft]].