What Is a ROOT Macro?

Table of Contents

Interactive commands vs macros

In ROOT you can type commands interactively at the ROOT prompt or you can place the same commands in a file and run them as a macro. Both approaches use the same language and the same ROOT classes, but they are useful in different situations.

Interactive commands are what you type directly into the ROOT shell, for example:

cpp

root [0] TH1F h("h", "Example", 100, 0, 1);
root [1] h.Fill(0.3);
root [2] h.Draw();

This style is ideal when you are just exploring. You can try a command, see the effect immediately, correct mistakes on the spot, and build up your understanding step by step. For learning ROOT and testing small pieces of code, interactive commands are very convenient.

However, interactive work has important limitations. Once you close the ROOT session, everything you typed is gone unless you manually copy it somewhere. It also becomes difficult to repeat the exact same sequence of steps with different inputs or on a different machine. If you carefully tune a plotting style or a cut selection at the prompt, reproducing it later can be error prone.

ROOT macros solve these problems by moving your commands into a file that ROOT can execute. A macro is usually a text file with the extension .C containing valid C++ (or C++-like) code that ROOT understands. Instead of repeating commands by hand, you keep them in one place:

cpp

// file: mymacro.C
void mymacro() {
   TH1F h("h", "Example", 100, 0, 1);
   h.Fill(0.3);
   h.Draw();
}

You can then run this macro in ROOT whenever you want the same actions to happen in the same way. This gives you a basic level of automation and reproducibility.

Macros are especially useful when:

You perform the same analysis many times, for example on different data files or with slightly changed parameters.

You want to share your analysis steps with others. Instead of describing what to type, you send the macro.

You want to keep a clear record of your work. The macro documents exactly which ROOT commands you used.

Macros also allow you to use more C++ language features than you would usually type interactively, such as functions, loops, and more complex logic. This makes it easier to build real analysis code that remains readable and maintainable as it grows.

A ROOT macro is simply a text file containing C++ code that ROOT can interpret or compile and execute. Use macros whenever you need your ROOT work to be repeatable, shareable, and documented.

Interactive commands are still very useful for quick tests, but for anything that matters in an analysis, you should move the commands into a macro file once you know what you want to do.

Creating a `.C` file

A ROOT macro is typically stored in a file whose name ends with .C. The simplest form is a free function with no arguments. You define a function and ROOT can call it just like a script entry point.

A minimal example looks like this:

cpp

// Save this as firstMacro.C
void firstMacro() {
   TH1F h("h", "Simple histogram", 50, 0, 5);
   h.Fill(1.2);
   h.Fill(3.4);
   h.Draw();
}

The important points are:

Use a plain text editor. Do not use a word processor that adds formatting. Any editor that can save simple text files is fine.

The file name ends with .C. ROOT uses this extension to recognize the file as a macro.

There is at least one function defined in the file. Here the function is called firstMacro. The function name is what you will use when you ask ROOT to run the macro.

Inside the function, you write exactly the same commands that you would type in the ROOT prompt. You can create objects, fill histograms, draw plots, and call any ROOT or C++ function.

Once you have created the .C file and saved it, you can run it from inside ROOT. While the details of running macros are covered later, conceptually ROOT reads the file, interprets or compiles the C++ code, and then calls the function you defined.

You can also define more than one function in the same .C file. A common pattern is to have one main function that ROOT calls and several helper functions that it uses. For example:

cpp

// Save as analysis.C
double computeWeight(double x) {
   return x * x;
}
void analysis() {
   TH1F h("h", "Weighted values", 100, 0, 10);
   for (int i = 0; i < 1000; ++i) {
      double value = i * 0.01;
      double weight = computeWeight(value);
      h.Fill(value, weight);
   }
   h.Draw();
}

In this example, analysis is the macro entry point, and computeWeight is a helper function living in the same .C file. ROOT will interpret both, but you normally only call analysis as a macro.

It is also possible to write a macro file that contains "bare" statements outside a function, for example:

cpp

// Save as quickplot.C
TH1F h("h", "Quick histogram", 100, 0, 1);
h.FillRandom("gaus", 1000);
h.Draw();

ROOT can execute this as a macro as well, but using a named function is usually clearer and more flexible, especially as your code grows. Named functions also make it easier to call the same code from other macros.

When you start building more involved analyses, it becomes important to keep your macros organized. Give each .C file a descriptive name and keep one main entry function whose name matches the file name or clearly describes the task. This simple convention already helps to keep your ROOT project understandable.

What Is a ROOT Macro?

Interactive commands vs macros

Creating a `.C` file

Comments

Where to Move