If you are looking for the legacy svn-based LArSoft site, see https://cdcvs.fnal.gov/redmine/projects/larsoftsvn. If you are looking for the legacy cvs-based LArSoft site, all content has been moved to LArSoft cvs (legacy site).
---------------------------------------------------------------

• Table of contents
• LArSoftWiki
• Getting started
  • Access to Fermilab computing
    • Load balanced access to GPCF VMs
  • Where to find the software
  • Accessing LArSoft
  • Release notes
• Documentation
  • LArSoft
  • How to use and develop LArSoft code
    • Overview of the user environment
    • Overview of the LArSoft developer environment
  • Detailed workflow notes
  • Tools for working with the software
• How to
  • Advanced technical how-to's
  • Release procedures
• Walk-through exercises
• Working areas

This is the beta LArSoft redmine project and the future home of the LArSoft redmine project.

LArSoftWiki¶

Under construction... Will go live when the migration to git/cmake is completed.

The LArSoft software is designed to work for all planned and running liquid argon experiments at Fermilab. It is written in C++ and built on the ROOT data analysis software and the FMWK framework for HEP experiments. The releases of the software are managed using an SRT distribution.

To join the LArSoft mailing list, please follow these instructions using the list name LARSOFT.

Getting started¶

Access to Fermilab computing¶

Load balanced access to GPCF VMs¶

Where to find the software¶

At Fermilab, the software lives in a set of re-locatable ups products, each of which corresponds to the code within a git repository. Each product and associated repository contain LArSoft software components (i.e., SoftRelTool "packages") that are at a similar layer of functionality. The reference products and repository urls are the following:

Product repository name	repository url (all in Redmine)	lxr link (not yet avail)	Redmine browser
larcore	ssh://p-larcore@cdcvs.fnal.gov/cvs/projects/larcore	--
lardata	ssh://p-larcore@cdcvs.fnal.gov/cvs/projects/lardata	--
larevt	ssh://p-larcore@cdcvs.fnal.gov/cvs/projects/larevt	--
larsim	ssh://p-larcore@cdcvs.fnal.gov/cvs/projects/larsim	--
larreco	ssh://p-larcore@cdcvs.fnal.gov/cvs/projects/larreco	--
larana	ssh://p-larcore@cdcvs.fnal.gov/cvs/projects/larana	--
lareventdisplay	ssh://p-larcore@cdcvs.fnal.gov/cvs/projects/lareventdisplay	--
larexamples	ssh://p-larcore@cdcvs.fnal.gov/cvs/projects/larexamples	--
larsoft	(A product that exists only to set up the others with a single command. The larsoft product otherwise has no content.)	--

(The SoftRelTools-based packages in each product/repository can be found here along with the approximate order of dependency.)

You can use the git clone <repository url> command to download a copy of each repository to your local area. Additional steps are needed to use, build or develop the software. These steps are described in the "How to use and develop LArSoft code" section below.

Accessing LArSoft¶

• Repositories
• Browsing the software

Release notes¶

Release	Date	Purpose	Changes / notes	Full release notes
v1.00.00	Jan 2014	First production release	Replica of final svn-based release. Future LArSoft development proceeds from this release.	xxx
v0.0x.0y	12/02/2013	"beta" limited release	Beta suitable for expert testing	N/A
v0.00.09	11/25/2013	"beta" pre-release	Second full release under new system. First full re-factoring of experiment-specific and core LArSoft code in the larcore, lardata, larevt, and larsim products. Preparation for expert user testing of beta release.	N/A
v0.00.04	9/15/2013	"alpha" release	First release of git/cmake/ups-based LArSoft products Used for mrb, configuration and re-factoring development and testing	N/A

Documentation¶

LArSoft¶

How to use and develop LArSoft code¶

Overview of the user environment¶

LArSoft releases are distributed via "re-locatable" ups products. (A "re-locatable" ups product has a simplified structure compared to that of legacy ups products, and does not require that it be "declared" to a ups database. These features simplify distribution, installation and maintenance of re-locatable products.) People interested in using the core LArSoft software, but who have no need to modify or develop that software can in principle simply perform the appropriate ups setup <product> <version> -q <qualifier> commands, then build their code against those products by reference to the corresponding $<PRODUCT_NAME>_INC and $<PRODUCT_NAME>_LIB environment variables. In addition to the individual products, there is a "larsoft" product that can be used to set up all other products with a single command:

setup larsoft <version> -q <qualifiers>

The versions and qualifiers available can be obtained by using the following command:

ups list -aK+ larsoft

The qualifiers will be one of the following:

• debug:e2
• prof:e2
• opt:e2

where:

• debug = debugging symbols available
• opt = compiler optimizations enabled
• prof = compiler optimizations enabled, profiling code generated
• e2 = built witih gcc 4.7.1 and -std=c++0x

In general, only debug and prof will be provided, since there is no run-time performance penalty for code that has the profiling code present.

The recommended way to work with LArSoft is to use mrb, the multi-repository build tool, to check out and build your own code. This build system is based upon cmake and a toolkit of cmake macros in the cetbuildtools product -- the same set of tools that are used to build the art framework that underpins LArSoft. mrb operates above cmake and drives the build procedure across (possibly) multiple repositories within one's working area. It also ensures the integrity and structure of the working area.

Note that all software packages built and installed by mrb will be in the form of a re-locatable ups products. mrb will provide a product template that includes two files that must be modified by the user: a top-level CMakeLists.txt file, that specifies which sub-directories will be included in the build along with any global configuration needed to build the product; and a product_deps file that specifies the dependencies for the package. Although this may sound cumbersome and arcane, it is really no different than following the package structure conventions imposed by SRT, using a GNUmakefile to configure the build, and a global release setup script to configure the global environment. With cmake, the GNUmakefiles are replaced by CMakeLists.txt files, while the "global environment" for the product is managed locally with the product_deps and top-level CMakeLists.txt files for the product. mrb then manages all the details of utilizing ups to configure the build environment, driving the build, and packaging and installing the ups product in the local products area.

There are several common scenarios under which most people using LArSoft will be working. Details of how to operate within several of these will be provided on a separate page. The intent here is only to give a summary of some of the basic steps and philosophies that come into play in one of the most common.

Let's first assume that a user has no need to modify or develop LArSoft code, but wants to work on existing experiment or personal software that depends upon LArSoft. The basic workflow goes something like the following:

1. Create a new working directory, use mrb newDev to create an empty skeleton of an mrb-based working area inside. This working area will have three basic areas:
   • A srcs sub-directory that will contain all the source code. Repositories are cloned or packages are checked out into this area.
   • A build sub-directory, where all build activities take place.
   • A localProducts sub-directory, where all built products are installed. Users run against locally built code that is installed in the localProducts area. A setup script provided by mrb can be used to place this area at the front of the ups PRODUCTS path.
2. Check out the desired software and create a local copy in the srcs directory using the mrb gitCheckout or mrb svnCheckout commands.
3. Modify the code as desired, checking in as appropriate
4. Move to the build area, configure the build environment using source mrb setEnv, then build the code using mrb build
5. Install the built code in the localProducts area using mrb install. Note that further development and builds have no effect on the code installed in the localProducts area. A user can continue to use the installed code while simultaneously fixing an error that breaks the build in the same working area.
6. Set up the newly installed products using the appropriate ups setup commands (e.g., @setup <product_name> <version> -q <qualifiers>. For user code, the product name, version and qualifiers can be set to (almost) arbitrary values.) At this step, any global product instances will be overriden by the local versions.
7. Run the code from a convenient location. The top-level directory in the working directory is an appropriate choice.
8. When ready to commit, use git add, git commit. Bring in any developments on the head using git pull or git fetch and git merge, as appropriate
9. Perform final tests
10. Perform final commits and merges into develop, then git push the results back onto the develop branch of the reference repository.

Another common scenario will involve the type of user (not modifying or developing LArSoft), but who now needs to start from scratch to create a new product. (This could by any new code, even code that is intended for later integration into an existing product or repository.) In this case, a couple of new steps need to be added near the beginning in order to create an empty product skeleton within the srcs area. The first part of the workflow then looks like this:

1. Create a working area and working area skeleton as before using mrb newDev.
2. Create an empty product skeleton in the srcs area using mrb newProduct
3. Attached the product area to an existing git (or svn) repository using git remote add and git pull. Note that the repository could be empty at this point.
4. Develop code on the "develop" branch, or use git flow" to create a new feature branch on which write the new code. Use @git add as needed.
5. Modify the top-level CMakeLists.txt file created for the product by mrb newProduct
6. Modify the ups/product_deps file to include all dependencies.
7. Build the code in the build area using mrb build
8. Install the code using mrb install
9. Run from the top-level work area directory.
10. Test, commit, merge and push as described above.

Overview of the LArSoft developer environment¶

The situation for the LArSoft developer is essentially the same as that of general users, except that the code that is checked out and modified will be that belonging to one or more of the LArSoft git repositories, possibly (perhaps usually) in addition to experiment-specific code. One consequence of this is that developers are expected to follow a specific development workflow in order to maintain the integrity of the main "develop" branch. Git offers many features and capabilities that make it extremely easy to isolate one's work from the rest of the world, to preserve it in the reference repository and to share it with others without affecting the reference develop branch, while at the same time following recent developments in the reference develop branch or in other branches. Consequently, there is little need to push changes to the reference develop branch before they are known to integrate into the build properly.

The LArSoft project has adopted git flow to assist with managing the development workflow. Within this framework, the git repositories have the following branch structure:

• A "main" branch that will have only tagged releases. Used only by the software manager.
• A "develop" branch that will have the working head of the repository. Used by all developers.
• A "release-*" branch for the integration of specific tagged releases. Used or authorized only by the software manager.
• An arbitrary set of "feature" branches on which all on-going work takes place. In most cases, these branches will be in local repositories, although publishing them to the reference repository is allowed. Developers can create as many feature branches as needed.
• A "hotfix" branch that is used to develop patches to tagged releases. Used or authorized only by the software manager.

Detailed workflow notes¶

Tools for working with the software¶

• git
• git flow
• mrb : the multi-repository build tool
• Re-locatable ups
• cmake

• Basic workflow
• Using git
• Multi-repository build

How to¶

Advanced technical how-to's¶

Release procedures¶

Walk-through exercises¶

Working areas¶

Beta re-factoring