[Tutorial] How to create ROOT Dictionary for a custom class is a stand-alone C++ project

tutorials/tree/dictionary/CMakeLists.txt

@@ -0,0 +1,47 @@
+# Copyright (C) 1995-2023, Rene Brun and Fons Rademakers.
+# All rights reserved.
+#
+# For the licensing terms see $ROOTSYS/LICENSE.
+# For the list of contributors see $ROOTSYS/README/CREDITS.
+
+#####################################################################################################################
+
+# Details about integrating ROOT into CMake projects:
+#     https://root.cern/manual/integrate_root_into_my_cmake_project/
+
+#####################################################################################################################
+
+# CMakeLists.txt for event package. It creates a library with dictionary and a main program
+cmake_minimum_required(VERSION 3.9 FATAL_ERROR)
+
+project(treeUsingCustomClass)
+
+#---Locate the ROOT package and defines a number of variables (e.g. ROOT_INCLUDE_DIRS)
+find_package(ROOT REQUIRED COMPONENTS MathCore RIO Hist Tree Net Graf3d Graf Gpad Thread TreePlayer)
+
+#---Define useful ROOT functions and macros (e.g. ROOT_GENERATE_DICTIONARY)
+include(${ROOT_USE_FILE})
+
+#---Add include directory of ROOT to the build
+include_directories(${CMAKE_SOURCE_DIR})
+
+# CMake function provided by ROOT, used to generate the dictionary file, G__data2Tree.cxx
+#     See this link for further details:
+#     https://root.cern/manual/io_custom_classes/#using-cmake
+ROOT_GENERATE_DICTIONARY(G__data2Tree data2Tree.hpp LINKDEF data2TreeLinkDef.hpp)
+
+#---Create a shared library from
+#   * the previously generated dictionary, G__data2Tree.cxx
+#   * the class implementation
+add_library(data2TreeLib SHARED data2Tree.cpp G__data2Tree.cxx)
+target_link_libraries(data2TreeLib ${ROOT_LIBRARIES}  ) 
+
+#--- This is needed on Windows in order to export the symbols and create the data2TreeLib.lib file
+if(MSVC)
+  set_target_properties(data2TreeLib PROPERTIES WINDOWS_EXPORT_ALL_SYMBOLS TRUE)
+endif()
+
+#---Create  a main program using the library
+add_executable(treeExample main.cpp readTree.cpp writeTree.cpp)
+target_link_libraries(treeExample ${ROOT_LIBRARIES} data2TreeLib)
+

tutorials/tree/dictionary/README.md

@@ -0,0 +1,40 @@
+How to read and write custom classes in TTree
+=============================================
+
+# Starting steps
+
+1. Build the project, it requires ROOT
+
+```
+cmake -B build -S . 
+cmake --build build 
+```
+
+2. Run the executable
+
+```
+./build/treeExample
+```
+
+3. Inspect the output rootfile, and the source code. 
+
+# Files
+
+The TTree can be seen as a collection of objects (branches), with a number of attributes (leaves). The name of the branch corresponds to the name of the instantiated object. The name of the leaves corresponds to the name of the attributes.
+
+The class that is present in the TTree is declared in the .hpp, and the methods defined in the .cpp. 
+
+The linkdef file contains some instructions for ROOT, to specify which classes will require a dictionary:
+
+```
+#pragma link C++ class myFancyClass+;
+```
+
+If for example `std::vector` of such class is also used in the TTree as well, it should be notified to ROOT as another separated instruction:
+
+```
+#pragma link C++ class std::vector<myFancyClass>+;
+```
+
+# Links: 
+* ROOT documentation: https://root.cern/manual/io_custom_classes/

tutorials/tree/dictionary/data2Tree.cpp

@@ -0,0 +1,23 @@
+// Author: Alvaro Tolosa-Delgado CERN 07/2023
+// Author: Jorge Agramunt Ros IFIC(Valencia,Spain) 07/2023
+
+/*************************************************************************
+ * Copyright (C) 1995-2023, Rene Brun and Fons Rademakers.               *
+ * All rights reserved.                                                  *
+ *                                                                       *
+ * For the licensing terms see $ROOTSYS/LICENSE.                         *
+ * For the list of contributors see $ROOTSYS/README/CREDITS.             *
+ *************************************************************************/
+
+// This file contains the definition of the class method
+// The class method was declared in the corresponding .hpp file
+
+#include "data2Tree.hpp"
+
+void myDetectorData::clear()
+{
+   time = 0;
+   energy = 0;
+   detectorID = 0;
+   correlatedDetectors_v.clear();
+}

tutorials/tree/dictionary/data2Tree.hpp

@@ -0,0 +1,33 @@
+// Author: Alvaro Tolosa-Delgado CERN 07/2023
+// Author: Jorge Agramunt Ros IFIC(Valencia,Spain) 07/2023
+
+/*************************************************************************
+ * Copyright (C) 1995-2023, Rene Brun and Fons Rademakers.               *
+ * All rights reserved.                                                  *
+ *                                                                       *
+ * For the licensing terms see $ROOTSYS/LICENSE.                         *
+ * For the list of contributors see $ROOTSYS/README/CREDITS.             *
+ *************************************************************************/
+
+// This file declares a class, with some members and method
+// The definition of the method is done in the corresponding .cpp file
+
+#ifndef __data2Tree__
+#define __data2Tree__
+
+#include <vector>
+
+class myDetectorData {
+public:
+   //-- Example of method...
+   void clear();
+
+   //-- Class members
+   //-- initialized by construction, C++11
+   double time = 1;
+   double energy = 2;
+   int detectorID = 3;
+   std::vector<double> correlatedDetectors_v = {1, 2, 3};
+};
+
+#endif

tutorials/tree/dictionary/data2TreeLinkDef.hpp

@@ -0,0 +1,19 @@
+// Author: Alvaro Tolosa-Delgado CERN 07/2023
+// Author: Jorge Agramunt Ros IFIC(Valencia,Spain) 07/2023
+
+/*************************************************************************
+ * Copyright (C) 1995-2023, Rene Brun and Fons Rademakers.               *
+ * All rights reserved.                                                  *
+ *                                                                       *
+ * For the licensing terms see $ROOTSYS/LICENSE.                         *
+ * For the list of contributors see $ROOTSYS/README/CREDITS.             *
+ *************************************************************************/
+
+// This file contains a selection of types that will be described in the ROOT dictionary.
+//     Further details in: https://root.cern/manual/io_custom_classes/#selecting-dictionary-entries-linkdefh
+
+#ifdef __CLING__
+
+#pragma link C++ class myDetectorData + ;
+
+#endif

tutorials/tree/dictionary/main.cpp

@@ -0,0 +1,28 @@
+// Author: Alvaro Tolosa-Delgado CERN 07/2023
+// Author: Jorge Agramunt Ros IFIC(Valencia,Spain) 07/2023
+
+/*************************************************************************
+ * Copyright (C) 1995-2023, Rene Brun and Fons Rademakers.               *
+ * All rights reserved.                                                  *
+ *                                                                       *
+ * For the licensing terms see $ROOTSYS/LICENSE.                         *
+ * For the list of contributors see $ROOTSYS/README/CREDITS.             *
+ *************************************************************************/
+
+#include <iostream>
+
+void writeTree();
+void readTree();
+
+int main()
+{
+   std::cout << "Starting writeTree()..." << std::endl;
+   writeTree();
+   std::cout << "Starting writeTree()... Done! " << std::endl;
+   std::cout << "Starting readTree()..." << std::endl;
+   readTree();
+   std::cout << "Starting readTree()... Done! " << std::endl;
+
+   return 0;
+}
+

tutorials/tree/dictionary/readTree.cpp

@@ -0,0 +1,48 @@
+// Author: Alvaro Tolosa-Delgado CERN 07/2023
+// Author: Jorge Agramunt Ros IFIC(Valencia,Spain) 07/2023
+
+/*************************************************************************
+ * Copyright (C) 1995-2023, Rene Brun and Fons Rademakers.               *
+ * All rights reserved.                                                  *
+ *                                                                       *
+ * For the licensing terms see $ROOTSYS/LICENSE.                         *
+ * For the list of contributors see $ROOTSYS/README/CREDITS.             *
+ *************************************************************************/
+
+#include <iostream>
+
+#include <TFile.h>
+#include <TTree.h>
+#include <TTreeReader.h>
+#include <TTreeReaderValue.h>
+
+#include "data2Tree.hpp"
+
+void readTree()
+{
+
+   std::unique_ptr<TFile> ifile { TFile::Open("testFile.root", "read") };
+   if ( !ifile || ifile->IsZombie() )  {
+      std::cerr << "Problem opening the file testFile.root" << std::endl;
+      return;
+   }
+
+   // Create a TTreeReader to read the tree named "myTree"
+   TTreeReader aReader("myTree", ifile.get() );
+
+   // Create TTreeReaderValues for the branches "branch1" and "branch2"
+   TTreeReaderValue<myDetectorData> branch1(aReader, "branch1.");
+   TTreeReaderValue<myDetectorData> branch2(aReader, "branch2.");
+
+   // Loop over the entries of the tree
+   while (aReader.Next()) {
+      if (branch1->time != 0)
+         std::cout << " -Branch1 : time: " << branch1->time << "\t energy: " << branch1->energy << std::endl;
+      else if (branch2->time != 0)
+         std::cout << " +Branch2 : time: " << branch2->time << "\t energy: " << branch2->energy << std::endl;
+      else
+         std::cerr << "WARNING: entry " << aReader.GetCurrentEntry() << " is empty! " << std::endl;
+   }
+
+}
+

tutorials/tree/dictionary/writeTree.cpp

@@ -0,0 +1,59 @@
+// Author: Alvaro Tolosa-Delgado CERN 07/2023
+// Author: Jorge Agramunt Ros IFIC(Valencia,Spain) 07/2023
+
+/*************************************************************************
+ * Copyright (C) 1995-2023, Rene Brun and Fons Rademakers.               *
+ * All rights reserved.                                                  *
+ *                                                                       *
+ * For the licensing terms see $ROOTSYS/LICENSE.                         *
+ * For the list of contributors see $ROOTSYS/README/CREDITS.             *
+ *************************************************************************/
+
+#include <iostream>
+
+#include <TFile.h>
+#include <TTree.h>
+#include <TTreeReader.h>
+#include <TTreeReaderValue.h>
+
+#include "data2Tree.hpp"
+
+void writeTree()
+{
+   std::unique_ptr<TFile> ofile { TFile::Open("testFile.root", "recreate") };
+   if ( nullptr == ofile ) {
+      std::cerr << " File not open." << std::endl;
+      return;
+   }
+
+   std::unique_ptr<TTree> myTree = std::make_unique<TTree>("myTree", "");
+   myDetectorData obj_for_branch1;
+   myTree->Branch("branch1.", &obj_for_branch1);
+
+   myDetectorData obj_for_branch2;
+   myTree->Branch("branch2.", &obj_for_branch2);
+
+   for (int i = 0; i < 10; ++i) {
+      //-- if i is even, fill branch2 and set branch1's entry to zero
+      if (i % 2 == 0) {
+         obj_for_branch1.clear();
+         obj_for_branch2.time = i + 5;
+         obj_for_branch2.energy = 2 * i + 5;
+         obj_for_branch2.detectorID = 3 * i + 5;
+      }
+      //-- if i is odd, we do the opposite
+      else {
+         obj_for_branch2.clear();
+         obj_for_branch1.time = i + 1;
+         obj_for_branch1.energy = 2 * i + 1;
+         obj_for_branch1.detectorID = 3 * i + 1;
+      }
+      myTree->Fill();
+   }
+
+   myTree->Print();
+
+   ofile->Write(); // This write the files and the TTree
+
+}
+