Setting up Eclipse IDE for your CERN ROOT project with existing GNU Makefile

7 min readJan 31, 2019

The use of Integrated Development Environment (IDE) is a must-have item on your agenda. Most important tools that IDEs provides to developers are Code completion and graphical debugging possibilities.

Speaking of C++ development — there are three main cross-platform IDEs on the market. Code::Blocks, Eclipse and NetBeans. Everybody has his own preferences with respect to selecting the right IDE. Generally speaking they all offer same functionality with minor discrepancies. In this article I will demonstrate how to set up a CERN ROOT project with custom GNU Makefile in the most popular IDE, namely Eclipse.

There is some specificity in compilation CERN ROOT’s programs that take advantage of the ROOT’s GUI or custom RooFit PDFs. Namely, user has to generate so-called dictionary, then shared library and finally link against it. The only legit way to accomplish this procedure is to write a custom Makefile. The topic is covered in my previous article here.

Install Java

Eclipse IDE is written in Java. On Macintosh computer go to official Java download webpage and install Java Runtime Environment (JRE). On Linux just type sudo apt-get install default-jre in Terminal instead.

Tip: you might consider installing Java Development Kit (JDK) instead if you planning on writing software with Java.

Install GDB debugger

You cannot experience a complete development experience without being able to debug your code. GDB is a conventional debugger used on Unix-like operation systems. Eclipse IDE will act as a front-end for GDB.

On macOS installing GDB must be installed from Hombrew. Additionally it will require a code signing procedure. A comprehensive documentation on how to setup GDB on macOS can be found here.

On Linux simply install gdb in Terminal: sudo apt-get install gdb gdb-multiarch. Either one of these debuggers worked well for me on Linux.

Installing Eclipse

On macOS download and install Eclipse IDE from the official website. Recently they introduced an all-in-one installer that can install Eclipse for any environment you need (Java, C++, PHP etc). In the installer dialog window select “Eclipse IDE for C/C++ Developers”.

Ubuntu-based (v.18.04) Linux distributions include a very outdated Eclipse version in official repositories. It refused to launch. Therefore on Ubuntu-based Linux you should download a fresh Eclipse version online.

On Fedora 31 in the Eclipse install requires enabling a module:

sudo dnf module enable eclipse:latest
sudo dnf install eclipse

Increasing Eclipse heap

Default eclipse heap settings are quite moderate and Eclipse indexer freezes when trying to process all the ROOT source files. In order to increase Eclipse memory locate and edit eclipse.ini in the Eclipse root install directory. Depending on the amount of the RAM on your computer set corresponding values to be:

-Xms2048m
-Xmx2048m

Restart Eclipse and go to Preferences → C/C++ → Indexer. Set the limits to 50% and 2048.

I usually provide Eclipse half of the available RAM that is available after the system start up.

Now you can go ahead and index your project. Right click your project and select Index → Rebuild.

Configuring Eclipse environment (macOS)

Due to certain reasons Eclipse installed on MacOS cannot access user’s environment variables set in ~/.bash_profile. Therefore we need to explicitly set them in Eclipse Preferences.

Add $ROOTSYS, $PATH, $DYLD_LIBRARY_PATH ($LD_LIBRARY_PATH) environment variables to Eclipse

Go to Preferences → C/C++ → Build → Environment.

Add $ROOTSYS variable and its value.
Add $PATH variable. Eclipse needs this path because it will run gdb and commands from the Makefile, including root-config and rootcling.
Add $DYLD_LIBRARY_PATH on macOS or $LD_LIBRARY_PATH on Linux. When running the project Eclipse needs to know where ROOT’s shared libraries are located.

Tip. The easiest way to avoid typos is to echo $ROOTSYS and other variables in Terminal and copy their values to Eclipse interface.

Import your project

Here I assume you do have an existing ROOT C++ project with a Makefile. Open Eclipse and on the Welcome Screen select “Import a project with a working Makefile”.

In the modal dialog specify project name and source code location. Check only C++ under the Languages selection. On macOS I used “MacOSX GCC” under Toolchain for Indexer…; fo Linux use “Linux GCC”. Click Finish button.

Now we need to add include headers path. Right-click your project in the left column, go to Properties → C/C++ General → Paths and Symbols. On the “Includes” tab select “GNU C++” in languages column and add ROOT’s include directory ${ROOTSYS}/include:

Add ROOT’s headers to the include search path.

Click “Apply and Close”, then right-click your project and select Index → Rebuild.

Create Build Configurations

In my previous article we discussed how to create a Makefile for a CERN ROOT application. In our makefile there are targets for building both — debug and release binaries.

In Eclipse we will create two build configurations. First configuration Release will build the release target. Another build configuration Debug will compile a binary that includes debug symbols. This build configuration will utilize the debug makefile target. Opposed to the Debug target, Release is built with -O3 compiler flag which stands for the compilers most optimization level. This results in a binary that performs calculations faster which is very important for ROOT.

Right-click your project in Eclipse, go to Properties → C/C++ Build. Click on “Manage Configurations”. Create two configurations “Release” and “Debug”. On the second tab named “Behavior” make sure each configuration has the correspondent target in “Build (Incremental build)” input box, namely “release” (or “all”) and “debug” respectively.

Setting up Release and Debug build configurations

Now in the Eclipse C/C++ prespective view we will have two options under the 🔨 build dropdown: Release and Debug (see picture below). Go ahead and try building the program.

We are done specifying the build targets for the project. Clean target is added automatically. Right-click the project in the explorer and select “Clean” to clean it.

Apparently, in order to run the program we need to tell Eclipse where the executable is located. Let’s go ahead and set the launch configuration.

Set Launch Configuration

Notice the Run Configurations dropdown ▶️ on the toolbar. Click it and select “Run Configurations…”.

In the modal dialog double-click “C/C++ Application” in the left panel. Specify the location of executable in your project (depending on your Makefile configuration).

I recommend selecting “Disable auto build” option. Otherwise Eclipse will rebuild the project every time you run it2

In order to be able to debug the program a new Debug Configuration needs to be created. Click the 🐞 dropdown on the toolbar. Same as for the Run configuration, specify the location of the exectable. On the “Debugger” tab make sure gdb command is specified in the “GDB debugger” field. Tip: if the field is empty, click “Browse” and locate gdb on the filesystem. In Terminal which gdb will reveal the location of the debugger.

Boom. Now the can click 🐞 Debug on the toolbar to debug your app.

For the sake of simplicity my demo Makefile outputs binary and shared library under the dist/ folder for both — debug and release configurations.

Please make sure you keep track if you have compiled the right executable yourself. When you switch between compiling the release and debug executables please make sure you run make clean target.

In order to be able to debug the ROOT classes you need to compile ROOT in Debug mode.

Adding Source Files

It is important to connect the ROOT source files to the project. They not only provide useful documentation, but additionally allow more in-depth debugging capabilities.

In Eclipse right click your project and go to Properties → C/C++ General → Paths and Symbols. Open “Source Location” tab and click “Link Folder…” button. In modal dialog select checkbox “Link to folder on the file system”. Specify the location of your ROOT source files.

Tip: if you did not compile ROOT from sources you would have to download source files from official webpage. After unpacking the source it’s a good idea to restrict writing permissions to the source files recursively:

chmod 555 /path-to-source/

This way you won’t accidentally change source files while debugging or reading.

Summary

In this article we learned how to set up a CERN ROOT C++ project with existing GNU makefile in Eclipse — one of the most popular cross-platform IDEs on the market.

We learned how to set up separate build configurations for Release and Debug binaries, and debug executable with GDB.

Additionally we’ve learned how to attach ROOT source to the project and increase Eclipse memory to be able to index larger C++ projects.

On newer macOS systems they introduced some security changes (system integrity protection, code signing) that make debuging with GDB more complicated. I honestly feel like setting up an xCode with LLDB debugger might be a better idea rather than using Eclipse and GDB as a development environment.

Thanks for your interest and good luck with your research!