KAHIBARO
3.2. Running ROOT Macros
Table of Contents
Running macros from ROOT
Once you have a .C file that contains a ROOT macro, you can execute it directly from the ROOT interactive shell. This is usually the first and most convenient way to test and develop your analysis code.
The ROOT shell understands a few special syntaxes for running macros. They all start from the ROOT prompt, typically shown as root [0].
The simplest form is to load and run a macro once by typing its filename in the ROOT prompt, including the .C extension and surrounding it with quotation marks. ROOT will interpret the file and execute any code that is configured as a macro entry point. Usually this means a function whose name matches the file name, for example myMacro.C containing a function void myMacro(). When you type ".x myMacro.C" ROOT interprets the file and immediately calls that function.
There are three closely related commands for running macros from within ROOT: .x, .L, and .X. The .x command reads, interprets, and immediately executes the macro each time you call it. This is very convenient while you are editing the macro, since every .x call will use the latest version on disk. The .L command only loads and compiles or interprets the macro without executing it. After .L myMacro.C you can call any functions defined inside the file with ordinary C++ syntax, for example myMacro();. The .X command forces ROOT to reload the macro from disk before executing it, even if it was already loaded. This can be useful if you recompile or significantly modify the file while ROOT is running.
The basic pattern is to start ROOT, then load and run the macro. You can, for instance, start ROOT and then at the prompt type .L myMacro.C to load it, followed by myMacro(); to execute. Alternatively, typing .x myMacro.C combines loading and running into one step. If your macro accepts arguments, you can pass them directly when calling it. With .x this uses a function-style syntax inside the quotes, for example .x myMacro.C(100, 0.0, 10.0) to call void myMacro(int n, double xmin, double xmax). If you use .L, you then call myMacro(100, 0.0, 10.0); as a normal function at the prompt.
Important rule:
Use .x macro.C to load and run a macro in one step, .L macro.C to load it and then call its functions manually, and .X macro.C to force reloading and then execute with the latest version from disk.
When you run a macro from ROOT, any histograms, graphs, canvases, or other objects you create will normally remain available at the prompt after the macro finishes, as long as they are not created as local variables inside functions that go out of scope. This makes it easy to inspect results, redraw plots, or try further commands interactively. If you notice that objects disappear immediately, it often means they were created as local variables inside a function and destroyed when the function returned, a topic that connects to ROOT object ownership which is discussed elsewhere.
It is also common to run macros that produce graphical output. If your macro creates a TCanvas and draws histograms or graphs, running it with .x will open a graphics window while the ROOT prompt remains interactive. You can then zoom, modify drawing options or run more commands. If you modify the macro and run .x again, the new version will execute without restarting ROOT.
If you want ROOT to report more detailed error messages when running macros, you can enable compilation instead of pure interpretation. A simple way from the prompt is to use .x myMacro.C+. The plus sign tells ROOT to compile the macro into a shared library and then run it. The first call will take longer due to compilation, but repeated calls are faster and type checking is stricter. For quick tests and simple examples you usually start with pure .x macro.C, then move to the compiled form when performance or stricter checking becomes necessary.
Running macros from the command line
You do not always need to start the ROOT interactive shell first. ROOT can execute macros directly from your system shell, for example from bash or zsh, which is useful for batch processing, automated scripts, or running many jobs without manual interaction.
The most common pattern is to call the root program with the -l option to suppress the ROOT splash screen and the -q option to quit ROOT immediately after the macro finishes. You then pass the macro call as an additional argument. For example, you can run a macro from the terminal with
root -l -q 'myMacro.C'. This starts ROOT in batch mode, interprets myMacro.C, runs it as a macro, and exits when it is done.
If your macro is a function that takes arguments, you can specify them directly in the command line call, using exactly the same syntax that you would use at the ROOT prompt. For example, if you have void myMacro(int n, double xmin, double xmax);, you can run it from the shell with root -l -q 'myMacro.C(100,0.0,10.0)'. ROOT will interpret the expression in quotes and execute myMacro(100, 0.0, 10.0) before quitting.
Important rule:
To run a macro from your system shell and exit ROOT automatically, use a command like
root -l -q 'macro.C(args)'
with the macro name and any arguments enclosed in single quotes.
You can also request compilation on the command line in the same way as in the interactive shell, by appending a plus sign to the filename. A call such as root -l -q 'myMacro.C+' compiles the macro, runs it, and exits. As in interactive mode, this is helpful when performance matters or when you want stricter C++ checking. ROOT keeps the compiled shared library in the working directory, so subsequent calls can reuse it.
When running macros from the command line it is common that they create output files rather than interactive plots. For example, a macro might open input ROOT files, fill histograms, write new ROOT files, or save plots as PNG or PDF files. Since ROOT will quit at the end of the macro, you cannot interact with any canvases afterward, so macros intended for batch use usually call methods like SaveAs() on canvases before returning. This separation between interactive use and batch use is an important design consideration when you start organizing larger analysis projects.
If you want ROOT to stay open after running a macro from the command line, simply omit the -q option. A call like root -l 'myMacro.C' will start ROOT, run the macro, and leave you at the ROOT prompt with all created objects still available. This is a convenient way to automate some initialization or data loading, then continue to work interactively.
Some environments require careful quoting when passing macro calls with arguments, especially if you use special characters. In simple cases, single quotes around the macro call are usually sufficient. If you run into issues with your shell interpreting characters inside the macro call, you may need to adjust quoting or escape certain characters, but for most beginner use cases the direct form root -l -q 'macro.C(… )' works as expected.
Finally, macros can also be integrated into larger shell scripts. For example, you can write a bash script that loops over a list of input files and calls the same ROOT macro on each of them, passing the file name as a parameter. This is a powerful way to scale up your analyses, while still using the same macro code that you test interactively inside ROOT.
Views: 14