Developing With LArSoft » History » Version 95
Katherine Lato, 08/21/2019 11:02 AM
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 | 94 | Katherine Lato | * "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.doxygen.nl/helpers.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 | 95 | 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 advice)_ |
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]]. |