23.3. Using Header Files
Table of Contents
Why Use Header Files in ROOT Analyses
Using header files in ROOT analyses is mainly about separating declarations from implementations, improving code organization, and making your analysis easier to maintain and reuse. When your ROOT code grows beyond a single short macro, header files become essential.
In a typical C++ ROOT project, you place function and class declarations in .h (or .hh, .hpp) files and keep the actual code in .C or .cc files. ROOT can interpret and compile both, so the structure is the same as in standard C++.
Rule: Put interfaces (function declarations, class definitions, configuration structures) in header files, and put implementations (function bodies, analysis logic) in source files.
This separation helps ROOT’s C++ interpreter and compiler understand your code, avoids repeated declarations, and gives you a cleaner project layout.
Basic Structure: Headers and Source Files
A minimal ROOT analysis that uses header files usually contains at least three categories of files:
- One or more header files, for example
Analysis.h,Histograms.h,Cuts.h. - One or more source files with implementations, for example
Analysis.C,Histograms.C. - A main macro or main function that calls your analysis, for example
runAnalysis.C.
A very simple example looks like this:
Analysis.h:
#ifndef ANALYSIS_H
#define ANALYSIS_H
void RunMyAnalysis(const char *inputFile, const char *outputFile);
#endif
Analysis.C:
#include "Analysis.h"
#include "TFile.h"
#include "TH1F.h"
void RunMyAnalysis(const char *inputFile, const char *outputFile) {
// analysis code here
}
runAnalysis.C:
#include "Analysis.h"
void runAnalysis() {
RunMyAnalysis("data.root", "result.root");
}You then execute in ROOT:
.x runAnalysis.C
ROOT will read runAnalysis.C, see the #include "Analysis.h", and load the declaration of RunMyAnalysis. When ROOT parses or compiles Analysis.C, it also includes Analysis.h, so the declarations are consistent.
Important: Always include the corresponding header in every source or macro file that uses a function or class. Do not rely on implicit knowledge of function signatures.
Typical Contents of a Header File in ROOT
In a ROOT analysis, your header file usually contains:
Function declarations for reusable analysis tasks:
#ifndef HISTUTILS_H
#define HISTUTILS_H
class TH1;
void SetupStandardStyle();
TH1 *CreateEnergyHistogram(const char *name, const char *title);
#endif
Simple helper class or struct definitions that you want to share across multiple .C files:
#ifndef EVENTDATA_H
#define EVENTDATA_H
struct EventData {
float energy;
float time;
int detectorId;
};
#endifConfiguration containers and constants, for example cut values or detector constants that should be visible everywhere.
ROOT classes and functions from the ROOT libraries themselves are already declared in ROOT’s own headers, such as TH1.h, TFile.h, or TTree.h. Your custom header files extend this by declaring your own analysis interface.
Rule: Only put declarations in headers, not executable code. Do not define large functions in headers unless you know exactly why you need them inline.
Include Guards and Why They Matter
ROOT’s interpreter will encounter your headers multiple times if they are included in several .C files. Without protection, this leads to duplicate definition errors. Include guards prevent that.
A typical include guard has the form:
#ifndef ANALYSIS_H
#define ANALYSIS_H
// declarations
#endifYou should use a unique macro name. A common pattern is the uppercase file name with non-alphanumeric characters replaced by underscores.
For example:
File name | Recommended guard macro
---------|-------------------------
Analysis.h | ANALYSIS_H
MyProjectConfig.h | MYPROJECTCONFIG_H
EventData.hh | EVENTDATA_HH
ROOT’s C++ interpreter understands include guards exactly as any C++ compiler does, so the protection works both for interpreted macros and for compiled code.
If you forget include guards, you may run into errors such as “redefinition of class” or “redefinition of function” after including the same header from multiple source files.
Including ROOT Headers and Your Own Headers
When you use header files, you regularly include two kinds of headers:
- ROOT or standard library headers, for example:
#include "TH1F.h"
#include "TTree.h"
#include <vector>- Your own headers, for example:
#include "Analysis.h"
#include "EventData.h"For ROOT headers, you usually use double quotes as well because they are installed in ROOT’s include path:
#include "TFile.h"
#include "TH1F.h"For standard C++ headers, you use angle brackets:
#include <iostream>
#include <vector>
For your project headers, use double quotes, and keep them in a known location such as the project root or an include directory. A typical small analysis project may have this structure:
| Path | Content |
|---|---|
analysis/ | Project root |
analysis/include/Analysis.h | Public analysis declarations |
analysis/include/EventData.h | Structs and configuration |
analysis/src/Analysis.C | Implementation of analysis functions |
analysis/src/Helpers.C | Extra helper functions |
analysis/runAnalysis.C | Entry macro |
When you run ROOT from analysis/, you can include your headers directly:
#include "include/Analysis.h"If you often use the same include path, you can choose a shorter layout and keep headers next to their source files for very small projects.
Rule: Never include a .C file from another .C or .C-style macro. Always include the corresponding .h header instead.
Forward Declarations vs Including Headers
Sometimes you only need to mention a type without using its full definition in a header. To avoid unnecessary includes, you can use a forward declaration. This is useful when you want to reduce dependencies between headers and speed up compilation.
For example, if you only need pointers or references to ROOT classes in a header, you can write:
#ifndef MYMODULE_H
#define MYMODULE_H
class TH1;
class TTree;
void FillHistogramFromTree(TH1 *hist, TTree *tree);
#endif
In the corresponding .C file you include the full ROOT headers:
#include "MyModule.h"
#include "TH1.h"
#include "TTree.h"
void FillHistogramFromTree(TH1 *hist, TTree *tree) {
// implementation that uses the full TH1 and TTree interface
}Forward declarations are a C++ feature that ROOT understands. They help keep headers small and reduce the number of ROOT headers that every file must parse.
Use forward declarations when:
You only need pointers or references to a class in the header.
The implementation that uses the class lives in a .C file, not in the header.
Do not use forward declarations if you need to declare a member variable of that type directly in a struct or class, or if you need to use the full interface in the header itself. In that case, you must include the correct header.
Using Header Files with Interpreted Macros
ROOT can interpret both .C and .h files. For small analyses, you often run:
.x mymacro.CHeader files fit into this workflow naturally. You:
Write headers with declarations.
Write macros or .C files with implementations that include those headers.
Execute the entry macro with .x or let ROOT load compiled code.
For example, if you have:
Helpers.h:
#ifndef HELPERS_H
#define HELPERS_H
double InvariantMass(double e1, double px1, double py1, double pz1,
double e2, double px2, double py2, double pz2);
#endif
Helpers.C:
#include "Helpers.h"
#include <cmath>
double InvariantMass(double e1, double px1, double py1, double pz1,
double e2, double px2, double py2, double pz2) {
double e = e1 + e2;
double px = px1 + px2;
double py = py1 + py2;
double pz = pz1 + pz2;
return std::sqrt(e*e - px*px - py*py - pz*pz);
}
run.C:
#include "Helpers.h"
void run() {
double m = InvariantMass(10, 1, 2, 3,
20, -1, -2, -3);
std::cout << "Invariant mass: " << m << std::endl;
}If you now run:
.x Helpers.C
.x run.C
ROOT reads the header in both cases, so the function signature is shared and consistent. In interactive workflows, it is common to .L (load) a file with implementations, then run a simple macro that calls those functions.
For example:
root [0] .L Helpers.C
root [1] .x run.CThe pattern is the same as for compiled programs, you just use ROOT’s interactive loader instead of building a binary.
Using Header Files with Compiled ROOT Code
When your analysis gets heavier, you will use ROOT’s compilation features. You may use ACLiC or build a standalone executable with a build system, but in both cases header files are necessary.
A common interactive pattern is:
root [0] .L Analysis.C+
root [1] runAnalysis()
The + tells ROOT to compile the code. When Analysis.C includes Analysis.h and both are in your project, ROOT compiles and links them with proper C++ rules. If you later modify only the implementation in Analysis.C, ROOT can often reuse compiled headers and only recompile what changed.
If you later move to a full build system, such as CMake, the same header files and source files can be used without change. That is one of the main reasons to adopt header files early in your ROOT projects.
Rule: If you plan to compile your ROOT code, any function or class that is used from outside its source file must have its declaration in a header file that is included where it is used.
Organizing Headers for Larger Analyses
As your analysis grows, it is helpful to split your headers by responsibility. For example:
Config.h
Contains constants, configuration structures, and simple helpers related to configuration and cuts.
HistDefs.h
Contains declarations of functions that create and configure histograms, or small structs that group histograms.
Analysis.h
Contains the main analysis function declarations, for example RunAnalysis, ProcessEvent, or higher level routines.
PhysicsUtils.h
Contains physics related helper functions, for example invariant mass calculations, kinematic transformations, or simple algorithms.
This modular organization lets you:
Include only what is needed in each source file.
Avoid long header chains that pull in unneeded dependencies.
Reuse modules across different analyses or projects.
You can also have a single general header for very small projects, then split it later without changing the rest of the code much, because all uses already include headers rather than .C files.
Common Pitfalls When Using Header Files in ROOT
There are a few typical problems beginners encounter when they start using header files with ROOT:
Forgetting include guards.
This leads to redefinition errors when a header is included multiple times. Always add guards as soon as you create the file.
Defining functions in headers unintentionally.
If you put a full function definition in a header and include it in more than one .C file, you may get multiple definition linker errors when compiling. For analysis helper functions this often appears as vague errors from ACLiC. Keep implementations in .C unless you use small inline functions intentionally.
Including macros instead of headers.
If you write #include "OtherMacro.C" from a macro, ROOT will jumble declarations and definitions together, which becomes hard to manage and compile. Use #include "OtherMacro.h" and keep OtherMacro.C only for implementations.
Using headers that depend on ROOT classes without including the ROOT headers.
If you use a class in a header and you do not provide a forward declaration or the necessary include, ROOT can interpret the macro but compilation will fail. Either include the correct ROOT header in your header file, or use a forward declaration when appropriate.
Changing headers without recompiling.
When using compiled code, if you change a header, you must trigger a recompilation. In ROOT with ACLiC, that usually means calling .L YourFile.C+ again. When using a build system, you must rebuild. If there is a mismatch between compiled code and headers, you may see confusing errors.
Being explicit about these rules and patterns makes your ROOT analysis code more robust and easier to debug.
Summary
Header files are a key element of writing better ROOT analysis code. By moving declarations of functions, classes, and configuration structures into headers, and keeping implementations in .C files, you:
Create a clear and reusable interface for your analysis.
Enable straightforward compilation with ROOT and with external build systems.
Reduce duplication and mismatches of function signatures.
Organize your code into logical modules that are easier to maintain.
If you start using header files early in your ROOT projects, you will have less work when your analysis scales up, and you will be much closer to standard, maintainable C++ practices.
Views: 0
Where to Move
Move chapter:
- ☰ 1. Introduction to ROOT
- ☰ 1.1. What Is ROOT?
- ☰ 1.2. Installing ROOT
- ☰ 1.3. Starting ROOT
- ☰ 1.4. Your First ROOT Session
-
- ☰ 2. C++ Basics for ROOT
- ☰ 2.1. Why ROOT Uses C++
- ☰ 2.2. Variables and Data Types
- ☰ 2.3. Operators
- ☰ 2.4. Conditional Statements
- ☰ 2.5. Loops
- ☰ 2.6. Functions
- ☰ 2.7. Arrays and Vectors
-
- ☰ 3. ROOT Macros
- ☰ 3.1. What Is a ROOT Macro?
- ☰ 3.2. Running ROOT Macros
- ☰ 3.3. Functions Inside ROOT Macros
- ☰ 3.4. Compiling ROOT Macros
- ☰ 3.5. Organizing a ROOT Project
-
- ☰ 4. ROOT Objects and the ROOT Object Model
- ☰ 4.1. Introduction to ROOT Classes
- ☰ 4.2. Object Names and Titles
- ☰ 4.3. ROOT Collections
- ☰ 4.4. Inspecting ROOT Objects
-
- ☰ 5. Histograms
- ☰ 5.1. Introduction to Histograms
- ☰ 5.2. Creating a 1D Histogram
- ☰ 5.3. Filling Histograms
- ☰ 5.4. Drawing Histograms
- ☰ 5.5. Histogram Properties
- ☰ 5.6. Accessing Histogram Bins
- ☰ 5.7. Histogram Errors
- ☰ 5.8. Normalizing Histograms
- ☰ 5.9. Combining Histograms
-
- ☰ 6. Two-Dimensional Histograms
- ☰ 6.1. Creating 2D Histograms
- ☰ 6.2. Filling 2D Histograms
- ☰ 6.3. Drawing 2D Histograms
- ☰ 6.4. Projections
- ☰ 6.5. Profiles
-
- ☰ 7. Graphs
- ☰ 7.1. Introduction to TGraph
- ☰ 7.2. Creating a TGraph
- ☰ 7.3. Graph Styling
- ☰ 7.4. TGraphErrors
- ☰ 7.5. TGraphAsymmErrors
- ☰ 7.6. MultiGraph
-
- ☰ 8. Canvases and Plotting
- ☰ 8.1. TCanvas
- ☰ 8.2. Dividing a Canvas
- ☰ 8.3. Drawing Multiple Objects
- ☰ 8.4. Legends
- ☰ 8.5. Text and Annotations
- ☰ 8.6. Logarithmic Axes
- ☰ 8.7. Saving Plots
-
- ☰ 9. Styling ROOT Plots
- ☰ 9.1. ROOT Plot Styles
- ☰ 9.2. Axis Configuration
- ☰ 9.3. Line Styles
- ☰ 9.4. Marker Styles
- ☰ 9.5. Publication-Quality Figures
-
- ☰ 10. Mathematical Functions
- ☰ 10.1. Introduction to TF1
- ☰ 10.2. Built-in Functions
- ☰ 10.3. Custom Functions
- ☰ 10.4. Evaluating Functions
- ☰ 10.5. Function Integrals
-
- ☰ 11. Curve Fitting
- ☰ 11.1. Introduction to Fitting
- ☰ 11.2. Gaussian Fits
- ☰ 11.3. Polynomial Fits
- ☰ 11.4. Custom Fit Functions
- ☰ 11.5. Fit Parameters
- ☰ 11.6. Goodness of Fit
- ☰ 11.7. Fit Residuals
- ☰ 11.8. Fitting Graphs
-
- ☰ 12. ROOT Files
- ☰ 12.1. Introduction to ROOT Files
- ☰ 12.2. Creating ROOT Files
- ☰ 12.3. Writing Objects
- ☰ 12.4. Reading ROOT Files
- ☰ 12.5. Exploring ROOT Files
- ☰ 12.6. Directories Inside ROOT Files
-
- ☰ 13. TTrees
- ☰ 13.1. Introduction to TTrees
- ☰ 13.2. Creating a TTree
- ☰ 13.3. Filling a TTree
- ☰ 13.4. Writing a TTree to a File
- ☰ 13.5. Reading a TTree
- ☰ 13.6. Inspecting TTrees
- ☰ 13.7. Drawing Data from TTrees
- ☰ 13.8. Applying Selection Cuts
- ☰ 13.9. Branch Addresses
-
- ☰ 14. Event-Based Data Analysis
- ☰ 14.1. Understanding Event Data
- ☰ 14.2. Event Loops
- ☰ 14.3. Event Selection
- ☰ 14.4. Derived Quantities
- ☰ 14.5. Analysis Workflow
-
- ☰ 15. Working with Real Experimental Data
- ☰ 15.1. Importing Text Data
- ☰ 15.2. Converting Data to ROOT
- ☰ 15.3. Data Cleaning
- ☰ 15.4. Data Calibration
- ☰ 15.5. Signal and Background
-
- ☰ 16. Random Numbers and Simulations
- ☰ 16.1. Random Number Generation
- ☰ 16.2. Common Distributions
- ☰ 16.3. Simple Monte Carlo Simulation
- ☰ 16.4. Detector Resolution Simulation
- ☰ 16.5. Efficiency Simulation
-
- ☰ 17. Statistical Analysis with ROOT
- ☰ 17.1. Basic Statistics
- ☰ 17.2. Probability Distributions
- ☰ 17.3. Statistical Uncertainties
- ☰ 17.4. Chi-Square Tests
- ☰ 17.5. Confidence Intervals
-
- ☰ 18. Modern ROOT with RDataFrame
- ☰ 18.1. Introduction to RDataFrame
- ☰ 18.2. Loading Data
- ☰ 18.3. Filtering Data
- ☰ 18.4. Defining New Columns
- ☰ 18.5. Creating Histograms
- ☰ 18.6. Statistical Operations
- ☰ 18.7. Saving Results
- ☰ 18.8. Multithreading
-
- ☰ 19. ROOT and Python
- ☰ 19.1. Introduction to PyROOT
- ☰ 19.2. ROOT Objects in Python
- ☰ 19.3. Reading ROOT Files with Python
- ☰ 19.4. PyROOT and NumPy
- ☰ 19.5. PyROOT and Matplotlib
- ☰ 19.6. Choosing Between C++ and Python
-
- ☰ 20. Advanced TTree Techniques
- ☰ 20.1. Trees with Multiple Branches
- ☰ 20.2. Storing std::vector Objects
- ☰ 20.3. TChain
- ☰ 20.4. Friends
- ☰ 20.5. Efficient TTree Analysis
-
- ☰ 21. ROOT for Particle and Nuclear Physics
- ☰ 21.1. Four-Vectors
- ☰ 21.2. Particle Kinematics
- ☰ 21.3. Invariant Mass
- ☰ 21.4. Angular Distributions
- ☰ 21.5. Detector Spectra
-
- ☰ 22. Debugging and Common ROOT Problems
- ☰ 22.1. ROOT Object Ownership
- ☰ 22.2. Null Pointers
- ☰ 22.3. Segmentation Faults
- ☰ 22.4. Missing Histograms
- ☰ 22.5. ROOT File Problems
- ☰ 22.6. TTree Branch Problems
- ☰ 22.7. Histogram Range Problems
- ☰ 22.8. Fit Failures
- ☰ 22.9. Debugging ROOT Macros
-
- ☰ 23. Writing Better ROOT Analysis Code
- ☰ 23.1. Separating Analysis and Plotting
- ☰ 23.2. Using Functions
- ☰ 23.3. Using Header Files
- ☰ 23.4. Naming Conventions
- ☰ 23.5. Avoiding Hard-Coded Values
- ☰ 23.6. Configuration Parameters
- ☰ 23.7. Reproducible Analysis
- ☰ 23.8. Version Control with Git
-
- ☰ 24. Final Project
- ☰ 24.1. Project Overview
- ☰ 24.2. Analyze a complete scientific dataset using ROOT.
- ☰ 24.3. Import the Data
- ☰ 24.4. Explore the Dataset
- ☰ 24.5. Apply Data Selection
- ☰ 24.6. Create Histograms
- ☰ 24.7. Fit the Data
- ☰ 24.8. Calculate Physical Quantities
- ☰ 24.9. Estimate Statistical Uncertainties
- ☰ 24.10. Create Publication-Quality Figures
- ☰ 24.11. Save the Analysis Results
- ☰ 24.12. Write a Short Analysis Report
-
- ☰ 25. Appendices
- ☰ 25.1. A. ROOT Command Cheat Sheet
- ☰ 25.2. B. ROOT Histogram Classes
- ☰ 25.3. C. ROOT Graph Classes
- ☰ 25.4. D. Common TTree Commands
- ☰ 25.5. E. Common Drawing Options
- ☰ 25.6. F. Common Fit Functions
- ☰ 25.7. G. ROOT C++ Cheat Sheet
- ☰ 25.8. H. PyROOT Cheat Sheet
- ☰ 25.9. I. Common ROOT Errors and Solutions
- ☰ 25.10. J. Recommended ROOT Analysis Workflow
-
Comments
Please login to add a comment.
Don't have an account? Register now!