Migrating from ROOT5 to ROOT6

Backwards compatibility

Migrating from art 1.x to 2.x

The locations of product-reading libraries and headers have migrated to canvas. In order to update your source code and (if using cetbuildtools) the link lines in your CMakeLists.txt files, please use the following scripts:

  • canvas/tools/canvas_refactor/ - updates #include paths in source code.
  • canvas/tools/canvas_refactor/ - updates link lines in CMakeLists.txt files.
  • canvas/tools/canvas_refactor/ - performs both steps above.

See NuTools update script for additional instructions for nutools.

cetbuildtools version

  • For experiments with a cetbuildtools / MRB-based build system, cetbuildtools >= 4.19.04 is required.
  • cetbuildtools >= 5.04.02 is recommended.

Dictionary notes

  • For experiments with other build systems, there are some important changes to how "dictionaries" and related files required by ROOT 6 are generated relative to those for ROOT 5, and your build system will need to incorporate these changes:
    • genreflex is still the appropriate tool for generating introspection information, despite the misleading name. Recommended invocation:
      genreflex <path>/classes.h -s <path>/classes_def.xml -I... \
      --fail_on_warnings -l <libdir>/libXXX_dict.<shared-lib-suffix> \
      --rootmap-lib=libXXX_dict.<shared-lib-suffix> --root-map=<libdir>libXXX_dict.rootmap
      genreflex will also produce a file <libdir>/libXXX_dict_rdict.pcm. Other options previously recommended for use such as --iocomments, --capabilities, and --gccxmlopt. The slate of -D definitions previously recommended are also no longer required.
    • If you wish to take advantage of the art-provided checkClassVersion tool for maintaining and updating class versions and checksums in selection XML files, you should ensure that no checkClassVersion invocation occurs until all dictionary shared libraries have been built, otherwise in a parallel build it is possible that pyROOT will attempt to read a .rootmap file or dictionary library that is in the process of being re-written by a different dictionary target. If you need advice on how to achieve this with your build tools, please let us know.
    • As a result of ROOT6's new "autoparse" technology, header files corresponding to the running code must be available at runtime.

GDML breaking change

  • Root 6 does not parse mathematical expressions in GDML (!??)
    • These were used throughout the GDML fles used by the LArSoft experiments
    • Root 6 silently ignores mathematical expressions and just takes the first number it encounters, resulting in some odd geometry definitions.
    • Complaints about illegal geometry most likely mean that an expression was not translated.
  • LArSoft corrected their GDML files by using root 5 to generate translated GDML files.


  • Root 6 needs to find all classes and enums defined by included headers at runtime. This is handled by defining ROOT_INCLUDE_PATH.
  • cetbuildtools v4_19_04 or later is required.


  • Root 6 recognizes enums as explicit types. This means that they must be included in the dictionaries.
  • This error message most likely means that an enum has not been specified.
    ---- DictionaryNotFound BEGIN
      No dictionary found for the following classes:
      Most likely they were never generated, but it may be that they were generated in the wrong package.
      Please add (or move) the specification
           <class name="MyClassName"/>
      to the appropriate classes_def.xml file.
      If the class is a template instance, you may need
      to define a dummy variable of this type in classes.h.
      Also, if this class has any transient members,
      you need to specify them in classes_def.xml.
    ---- DictionaryNotFound END
  • Add the line to the appropriate dictionary:
    <enum name="geo::_plane_sigtype"                                         />

art::Assns #12247

  • For art::Assns, the dictionary must include BOTH art::Assns of a, b AND art::Assns of b, a.
  • Unfortunately, this problem is not spotted during dictionary generation and will result in a segfault.
  • art 2.00.01 has a fix to report the error as early as possible.
  • LArSoft provides a script to look for problems.

Template instantiations

With root 6, it is no longer necessary to include template instantiations in classes.h.
The templates are instantiated when they are used.
Removing all template instantiations from the classes.h files results in much faster loading of root dictionaries.

TFormula discovered integral math

ROOT 6 implementation of TFormula performs integral math evaluation in a fashion more similar to the C language. For example, "1/2" evaluates to 0., while "1./2." evaluates to 0.5.
ROOT 5 used to convert all operands to floating point and then perform floating point math: both "1/2" and "1./2." did evaluate to 0.5.
TFormula is internally used in many ROOT classes (e.g. TTree::Draw, TTree::Scan, TF1, etc.). All the instances should be checked to make sure that they yield the expected result.
This new feature has been reported as JIRA issue 8110.

TFormula bug on missing parameter in expression

See JIRA issue 8182.
In short, if your expression omits a parameter, parameters gets assigned as if you hadn't. This means that some parameters are assigned values that some others should have been assigned.
For example:

wrong formula interpreted as bad effects
"[0]*x**[2]" "[0]*x**[1]" SetParameters(0., 1., 2.) results in [2] <== 1.
SetParameter(2, 2.) has no effect (there is no parameter 2)
gaus(0) + [4]**[5] gaus(0) + [3]**[4] SetParameters(0., 1., 2., 3., 4., 5.) results in [4] <== 3., [5] <== 4.
SetParameter(4, 4.) results in [5] <== 4.
@SetParameter(5, 5.) has no effect (there is no parameter 5)

TFormula gaus

  • TFormula gaus is now gaus(x), where the default value of x is 0.
  • Root 6 is meant to be backwards compatible and translate all existing calls to "gaus" to "gaus(0)".
  • However, there is a bug:
  • LArSoft provides to translate calls to gaus in fcl files.

Reference pages