IncludeFiles

Introduction

This page discusses where to find the source for files that are #include'ed into Mu2e files. There are separate discussions for include directives in C++ files, in .fcl files and in auxilliary files, such as the geometry files and the Magnetic Field map files. The section on source code files also discusses the namespaces associated with each repository.

This page was originally written for UPS based environments, which were retired at the transition of operating systems from SL7 to AL9. The successor is Spack based environments. To ease the transition to spack all of the UPS standard environment variables discussed below are defined when you issue the command muse setup in spack based environment. Therefore the instructions below should be work both in UPS and spack based environments. Please let Mu2e computing management know if that is not so.

C++ Code

This section discusses where to find header files specified by include directives in C++ files. It will not discuss finding source for system and compiler supplied headers; those headers are well documented in the standard literature, to which you can find references in Mu2e C++ FAQ.

Such header files fall into 4 categories

1. From a Mu2e repository, such as Offline, Production, Tutorial, TrkAna, Stuntple ..
2. From an external product other than ROOT, such as art, geant4, clhep ...
3. ROOT
4. Exceptions to the above patterns

Files from Mu2e Muse-Ready Repositories

A typical include directive referencing a header file from the Mu2e Offline repository looks like:

#include "Offline/DataProducts/inc/PDGCode.hh"

From the leading element of the path, you learn that this file comes from the Offline repository. In your Muse working environment you can find this file at:

 $OFFLINE_INC/Offline/DataProducts/inc/PDGCode.hh

This is true whether Offline is in a local clone or in a backing release. Similarly, if the leading element of the path is Tutorial, then you can find the file relative to path defined in the environment variable TUTORIAL_INC. And so on for other Mu2e Muse-ready repositories.

These environment variables are created when you issue the muse setup command and they are only defined for repositories that are present in your Muse environment, either via a local clone or by a backing release. This guarantees that the file you are looking at is the correction version of the file.

With very few exceptions, the code in the Mu2e repositories is in the namespace mu2e::. Some code is also in a namespace nested under mu2e::.

There is a second way to find the source code for Mu2e repositories. Go to the Mu2e GitHub organization, https://github.com/Mu2e and click on the name of a repository, which will bring you to a source code brower. But there is a catch: it will bring you to the development head from that repository, not to the version that you are actually using. It is your responsibility to navigate to the source for the correct version of Offline. To learn the version to select, you can find it in the output of

 echo $OFFLINE_INC

Then see section #Selecting Source for a Tag in GitHub for instructions on how to choose that version in the GitHub browser.

Files from External Products

The same pattern holds, but only approximately, for the second case, external products (ie UPS products) other than ROOT. A typical include directive might look like one of the following:

 #include "art/Framework/Principal/Event.h"
 #include "fhiclcpp/types/OptionalAtom.h"
 #include "art_root_io/TFileService.h"
 #include "Geant4/G4Box.hh"

In each case, the first element of the path tells you the name of the repository that holds the code. You can find the files from the above examples in:

  $ART_INC/art/Framework/Principal/Event.h
  $FHICLCPP_INC/fhiclcpp/types/OptionalAtom.h
  $ART_ROOT_IO_INC/art_root_io/TFileService.h
  $G4INCLUDE/Geant4/G4Box.hh

Note that, in the last line, the _INC environment variable has a non-standard form; the reason is historical.

The table below summarizes information about each external product that is explicitly referenced in a recent version of Mu2e Offline. The first column specifies the UPS package name. Second column gives the first element in an include path; it is often but not always, the same as the UPS package name; note that there are some differences in capitalization and dash (-) vs underscore (_). The third column gives the environment variable used to locate the source file; in most, but not all cases, it follows the pattern of capitalizing the UPS package name and adding _INC. Note that include directives for ROOT files are just filenames with no additional path information. The fourth column gives the name of the namespace used within that packages; this is irregular and you just need to look it up as needed. Note that some repositories do not use a namespace and their symbols are in the global namespace; in all cases, these packages name their files with a distinct prefix, such as gsl_, G4 or T, which serves as proxy for a namespace. The final column gives the url of the repository; if you use these urls, it's your responsibility to navigate to the correct version of the files you wish to view. See section #Selecting Source for a Tag in GitHub to see how to do that.

Note that several of the repositories listed in the table have their source in the Mu2e GitHub organziation. There are in this table because they are delivered as UPS products and are never in your Muse environment. This is a choice made by the developers of those packages; most users of the Mu2e offline software will never develop these packages and will always see them as external packages.

UPS Package Name	Include Prefix	Environment Variable	Namespace	Source - Be careful to use the correct tag!
art	art	ART_INC	art::	https://github.com/art-framework-suite/art
artdaq-core	artdaq-core	ARTDAQ_CORE_INC	artdaq::	https://github.com/art-daq/artdaq_core
artdaq-core-mu2e	artdaq-core-mu2e	ARTDAQ_CORE_MU2E_INC	mu2e::	https://github.com/Mu2e/artdaq_core_mu2e
art_root_io	art_root_io	ART_ROOT_IO_INC	art::	https://github.com/art-framework-suite/art-root-io
boost	boost	BOOST_INC	boost::	https://github.com/boostorg/boost
BTrk	BTrk	BTRK_INC	(global)	https://github.com/KFTrack/BTrk
canvas	canvas	CANVAS_INC	art::	https://github.com/art-framework-suite/canvas
cetlib	cetlib	CETLIB_INC	cet::	https://github.com/art-framework-suite/cetlib
cetlib_except	cetlib_except	CETLIB_EXCEPT_INC	cet::	https://github.com/art-framework-suite/cetlib-except
clhep	CLHEP	CLHEP_INC	CLHEP::	https://gitlab.cern.ch/CLHEP/CLHEP
fhiclepp	fhiclcpp	FHICLCPP_INC	fhicl::	https://github.com/art-framework-suite/fhicl-cpp
geant4	Geant4	G4INCLUDE	(global)	https://gitlab.cern.ch/geant4/geant4
gsl	gsl	GSL_INC	(global)	https://github.com/ampl/gsl
KinKal	KinKal	KINKAL_INC	KinKal::	https://github.com/KFTrack/KinKal]
mu2e_pcie_utils	mu2e_pcie_utils	MU2E_PCIE_UTILS_INC	DTCLib::	https://github.com/Mu2e/mu2e_pcie_utils
messagefaciltiy	messagefacility	MESSAGEFACILITY_INC	mf::	https://github.com/art-framework-suite/messagefacility
tbb	tbb	TBB_INC	tbb::
xercesc	xercesc	XERCES_C_INC	xercesc::	https://github.com/apache/xerces-c
root	(none)	ROOT_INC	(global)	https://github.com/root-project/root

Files Included from ROOT

The syntax to include a root header file is to specify a path relative to $ROOT_INC. Because of the way that the root repository is structured, this results in most include directives containing only the filename. In almost all cases, the filename starts with a capital letter T, for example

 #include "TH1F.h"

There are a small number of exceptional cases in which the filename starts with a capital letter R. Two cases that occur in the Mu2e code base are:

 #include "Rtypes.h"
 #include "Riostream.h" 

Finally, some header files live in subdirectories under $ROOT_INC. The two subdirectories that occur in the Mu2e code base are Math and TVMA, for example

 #include "Math/Vector3D.h"
 #include "TMVA/Factory.h"

Exceptions

One other exception was found in a recent scan of Offline. The file included with,

 #include "dtcInterfaceLib/DTC_Packets.h"

is found in the repository mu2e_pcie_utils, which can be found in the above table.

.fcl Files

When the include directives within a .fcl file are expanded, the parser searches for the included files relative to the search path FHICL_FILE_PATH. For general details about search paths see SearchPaths and for details about FHICL_FILE_PATH in particular see SearchPaths#FHICL_FILE_PATH.

The rules for finding the source for files referenced by #include directives in fcl are much the same as for C++ files. The first element of the path specifies the repository name, usually Offline or Production, but possibly another Mu2e repository. You can find the file at, for example:

 $OFFLINE_INC/path/to/file.txt
 $PRODUCTION_INC/path/to/file.txt

You can also find the file in the appropriate GitHub repository as described above. Be sure the select the correct tag of the repository.

Auxillary Files

Auxillary files are described at SearchPaths#MU2E_SEARCH_PATH. When include directives within auxillary files are expanded, the parser searches for the included files relative to the search path MU2E_SEARCH_PATH. For general details about search paths see SearchPaths and for details about MU2E_SEARCH_PATH in particular see SearchPaths#MU2E_SEARCH_PATH.

With one exception, the rules for finding the source for files referenced by #include directives in fcl are much the same as for C++ files. The first element of the path specifies the repository name, usually, Offline or Production, but possibly another Mu2e repository. You can find the file at, for example:

 $OFFLINE_INC/Offline/fcl/standardProducers.fcl 
 $PRODUCTION_INC/Production/Validation/ceSimReco.fcl 

You can also find the file in the appropriate GitHub repository as described above. Be sure the select the correct tag of the repository.

The exception is for some large files, such as magnetic field maps. For these files, the path specified in the include directive does not start with the name of Mu2e repository. These files can be found at, for example

  $MU2E_DATA_PATH/BFieldMaps/Mau13/DSMap.txt

IDES vim and emacs

Add a discussion about how to program vim and emacs to make include filenames hot.

vim

The vim editor can be configured to make the paths specified in include directives into links to the source. An example .vimrc file can be found in:

https://github.com/Mu2e/Bootstrap/blob/4212ddc82b04234d01bea9e0a63e4a985dabbaf0/dotFiles/.vimrc

and can be downloaded with:

 curl -O https://raw.githubusercontent.com/Mu2e/Bootstrap/main/dotFiles/.vimrc

Look for the lines following the comment:

" Tell vim where to look for #include files 

Among other things it enables this feature for include files that can be found relative to your Muse working directory.

emacs

This link describes how to setup emacs for use as a C++ IDE: https://askubuntu.com/questions/839852/emacs-c-ide-gnu-global-helm-gtags. It's not a point and click solution but it's a step in the correct direction.

Selecting Source for a Tag in GitHub

This section explains how to choose the source for a given tag of Offline using the GitHub code browser. Go to the Mu2e Offline web page, https://github.com/Mu2e/Offline. It will look like the figure below. In the figure, the branch/tag selector button is circled in red.

1. Click on this button and a menu will pop up.
2. Choose the "Tags" tab
3. Scroll to the tag of interest and double click on it.

The same method will work for all of the GitHub-hosted repositories. You will have to poke around to find the equivalent for CERN GitLab hosted repositories.