Skip to end of metadata
Go to start of metadata

This guide will walk you through the process of setting up an Eclipse workspace with an embedded software project using a GNU toolchain.

The instructions have been verified against Eclipse Oxygen running on a GNU/Linux distribution based on Ubuntu 16.04, but they should be applicable to newer versions as well (possibly with minor modifications).



  • A working GNU/Linux OS, preferably in a non-virtualized environment. If you don't have that, you may opt for the Bistromathic VM instead (YMMV).
  • Installed GNU toolchain. If you don't have it yet, read the installation documentation for your toolchain first:
  • Installed Eclipse IDE. You can find the installation guide in a dedicated article

Creating the directory structure

Create a directory named after your project. It is recommended to place this directory in such a way so that its absolute path would not contain any spaces. For example, ~/software/fish/.

Fetch your codebase into a subdirectory inside the created directory. In this example we're going to use an arbitrary git repository for the purposes of demonstration.

Like this
mkdir -p ~/software/fish
cd ~/software/fish
git clone --recursive

This is the resulting directory structure:

Directory structure
pavel@pavel-lt:~/software$ tree -L 2 fish
└── zubax_babel
    └── <...stuff...>

Now it would be a good idea to verify that the toolchain works well. Step into the directory where your codebase is and try to build it. Please do not continue with the guide unless your application builds well from the command line.

Now, the directory ~/software/fish is going to be our workspace, whereas the fetched codebase inside of it is going to contain our project. A workspace may contain an arbitrary number of projects. Furthermore, a workspace may contain projects that reside outside of its sub-directories, although it is a good idea to avoid that unless strictly necessary.

Configuring the workspace

Launch the Eclipse IDE and select the newly created workspace directory. Once this is done, your workspace is created and ready to be configured.

Copying the settings from another workspace

If you have another workspace elsewhere that is already configured, you may copy its settings into your new workspace, but it is entirely optional. If you chose to do so, follow the steps below.

Launch another instance of Eclipse and open the old workspace. In the main menu, select File → Export.... In the displayed window, select General → Preferences, and click Next.

On the next window, ensure that the option Export all is selected. Enter the file name, and click Finish

Now you have exported the essential settings from your old workspace into a file. The newly created file can be imported into your new workspace as shown below.

Switch back to the instance of Eclipse where your new workspace is opened. In the main menu, select File → Import.... In the displayed window, select General → Preferences, and click Next.

On the next window, ensure that the option Import all is selected. Enter the name of the preference file, and click Finish.

You must restart Eclipse after importing the workspace settings, otherwise things may break in obscure ways.

It is a good idea to always keep a reference copy of your preferred workspace settings in a file somewhere, and import the settings from it every time you create a new workspace.

Importing the coding style settings

You may want to import the settings of the C/C++ source code formatter into your workspace. This step would be unnecessary if you have already imported the workspace preferences from a file, because the imported preferences should include your coding style settings.

Select the menu item Window → Preferences. In the window that opened, select the view C/C++ → Code Style → Formatter (you can use the search bar to navigate faster). A window similar to the shown below should appear.

Click Import... and use the opened dialog to select your coding style specification file. Afterwards click Apply and close the window.

Configuring the project property pages

Select the menu item Window → Preferences. In the window that opened, select the view C/C++ → Property Pages Settings (you can use the search bar to navigate faster). A window similar to the shown below should appear.

Select the checkbox Display "Discovery Options" Page. Click Apply and close the window.

Configuring the C++ properties

Select the menu item Window → Preferences. In the window that opened, select the view C/C++ → Build → Settings, and switch to the tab Discovery.

Select your toolchain from the list and append the field Command to get compiler specs with the option that enables the required version of the language:

  • C++11 → -std=c++11
  • C++14 → -std=c++14
  • C++17 → -std=c++17
  • Refer to the GCC documentation for more options and supported language standards.

Repeat the steps for all used toolchains. The result should be similar to the following:

Switch to the view C/C++ → Indexer. Uncheck the checkboxes Index source files not included in the build and Index unused headers. The window should look as follows:

When done, click Apply and close the window.

Configuring spell checking

Create your own dictionary text file and save it on your PC.  Select the menu item Window → PreferencesGeneralEditorsText EditorsSpelling.

Enter the path to your dictionary file in the field User defined dictionary:.

When done, click Apply and close the window.

Setting up the project

Now we're ready to import the first project into our freshly configured workspace. This section will need to be repeated for every embedded project that needs to be used with the workspace.

Importing the project

Select the menu File → New → Makefile Project with Existing Code. The New Project dialog should appear.

Specify the location of the directory where the Makefile is in the field Existing Code Location. Make no mistake: you need to specify not the root directory of the project here, but its subdirectory where the Makefile is located. Sometimes, however, the Makefile is found in the root of the project directory, but that is rather uncommon.

Select the right toolchain in the list Toolchain for Indexer Settings. If you can't see your toolchain here, go back to the article Installing the Eclipse IDE and make sure that all of the dependencies are installed and configured properly.

Specify the project name and click Finish.

The image below shows the dialog where all the fields are configured properly for our test project.

After you clicked Finish, the main window should look similar to the below.

Congratulations, you have imported the project. You can open the source files and look around. However, the project can't be used right away - we need to configure it first.

Configuring the project

Right-click on the project in the Project Explorer panel and select Properties from the opened context menu. Alternatively, you can select the project and then open the main menu Project → Properties. The project properties dialog should appear.

Project build settings

In the project properties dialog, select the view C/C++ Build, tab Builder Settings. Uncheck Use default build command. Type the following line in the field Build command:

Build command

Now, in order to make the Eclipse Indexer work properly, we need to ensure that the build system logs every invocation of the toolchain into stdout (which is then parsed by the Indexer). Many build systems do that by default, but some require an additional parameter to be passed to the make command to enable that feature. If you're using ChibiOS, you will need to pass the variable USE_VERBOSE_COMPILE=yes to the make command. If you were using CMake, the correct variable would be VERBOSE=1. Please consult with your project-specific documentation to determine which options need to be passed, if any.

For example, if we were using the ChibiOS build system, the following build command would have to be specified:

Build command

If necessary, you can configure the directory where the main Makefile is located in the field Build directory.

When done, the window should look similar to this:

Now, switch to the tab Behavior, and, if applicable, enable the parallel build feature (if unsure, don't).

Fun fact

Under unclear circumstances, parallel (multithreaded) builds may cause Eclipse to freeze completely (up to the point of having to terminate the process manually). If you're observing this behavior, you should disable parallel builds.

Now you can click Apply, close the project properties dialog, and try to build it by right-clicking the project in the Project Explorer panel and selecting the item Build Project. If everything was done right, the project should be built successfully. If Eclipse complained about its inability to locate the toolchain, it has been launched incorrectly. You could try to fix that by launching it from an interactive shell. For more information, please read the Eclipse installation manual.

Configuring the Eclipse Indexer

In order to be useful at all, Eclipse needs to be able to index the source code correctly using its component known as Eclipse Indexer. This is a piece of machinery full of deep magic whose distinguishing features are extreme instability and a very difficult setup process. (heart)

Know what we're doing

None of the options configured here affect the build process. All of the changes made to the toolchain settings et al are only needed to make Eclipse index the source code correctly. This means that building the code from Eclipse and building the same code from the command line by running make will always yield the same result, no matter how Eclipse is configured. I just felt like spelling this out because there seem to be a lot of confused users who don't understand that IDE and the build system are two different things. (lightbulb)

Open the project properties dialog that we used earlier, and navigate to the view C/C++ Build → Discovery Options. In the list titled Discovery profiles scope select the item Configuration-wide in order to use shared settings for all indexed languages. Select the check-box Automate discovery of paths and symbols. Ignore the deprecation warning that may appear at the bottom of the window. Save the settings by clicking Apply. The following screenshot is an example of the correct configuration.


The tab Discovery Options is hidden by default. Go to WindowPreferencesC/C++Property Pages Settings and check Display "Discovery options" Page. Then, open your project preferences and enjoy editing the Discovery Options tab.

Now switch to the view C/C++ General → Preprocessor Include Paths, Macros, etc., switch to the tab Providers. Select the item for your cross-compiler from the list, and make sure that its checkbox is active. Append the string in the field Command to get compiler specs with the option that enables the desired C++ standard, for example, -std=c++14. Enable the following items as well:

  • Binary Debug Data Entries
  • CDT Cross GCC Built-in Compiler Settings
  • CDT GCC Built-in Compiler Settings
  • You may add additional options if you believe them to be useful, but ensure that they are located below your toolchain.

The result should look similar to the below demonstrated screenshot.

Now switch to the view Paths and Symbols, tab Includes. Select the item GNU C++ in the list of languages, and click Add.... A window titled like Add directory path should pop up. Enter the path to the include directory of your toolchain in it, which is located at (toolchain)/arm-none-eabi/include/, where (toolchain) is the location where your toolchain is installed. For example, the path may look as follows: /home/pavel/opt/gcc-arm-none-eabi/arm-none-eabi/include/. Select the checkboxes Add to all configurationsAdd to all languages, and click OK. Repeat the process for the following directories of the toolchain:

  • (toolchain)/arm-none-eabi/include/c++/6.3.1/, where 6.3.1 is the version number which is likely to be different in your case.
  • (toolchain)/arm-none-eabi/include/c++/6.3.1/arm-none-eabi, see the note above about the version number.
  • (toolchain)/lib/gcc/arm-none-eabi/6.3.1/include/, see the note above about the version number.
  • Possibly you may need to add additional directories, depending on your toolchain and the target architecture.

The resulting window may look similar to this:

Now open the tab Symbols on the same view. Select the item GNU C++ in the list of languages, and click Add.... A window titled like Add symbol should pop up. Enter the symbol named __cplusplus with one of the following values, depending on what version of C++ you need to work with:

  • C++14201402L
  • C++17201701L
  • Refer to the C++ specification to see other values.

Activate the checkbox Add to all configurations, and click OK.

Technically, the current configuration should be good enough to get things working. However, if you tried to navigate the code you'd probably find a lot of unresolved references highlighted as errors. This is because there is an obscure bug somewhere in the Indexer that prevents it from working unless the set of CDT User Setting Entries is non-empty. In order to fix this, navigate to the properties view under C/C++ General → Preprocessor Include Paths, Macros, etc., select the tab Entries, item CDT User Setting Entries, and click Add.... In the opened window select Preprocessor macro from the drop-down list, and define a preprocessor macro named I_LOVE_ECLIPSE that resolves to 1, as shown below. Ensure that the checkbox Treat as built-in is not selected, this is crucial. Click OK.

If the Indexer breaks again with no apparent reason, try adding more dummy symbols, it usually helps to revive it.

Now everything should be configured correctly. Click Apply and close the window.

Can't touch this

Every time you alter the configuration of the Indexer you run the risk of breaking things irreparably. Remember that it is extremely fragile and unreliable. Do not alter any configuration settings you don't know about, even if they look mostly harmless.

Checking the Eclipse Indexer

Clean the project by right-clicking it and selecting the item Clean Project. Rebuild the project again by clicking Build Project.

Update the index by right-clicking the project and selecting the item Index → Rebuild. A small progress bar should appear on the edge of the main window. When the re-indexing is done, restart Eclipse.

Now the indexer and code navigation should work properly.

You can add additional include directories and preprocessor symbols by repeating the steps above. If Eclipse can't find one of the standard header files, you can fix that by searching the toolchain directory for the missing file, and then adding the directory where the file is located into the list of include directories as shown above.

Hyperlink navigation does not work?

There is a regression in early builds of Eclipse Oxygen that breaks Ctrl+Click navigation (hyperlinking). (heart) In order to fix it, open the workspace preferences, navigate to the view GeneralEditorsText EditorsHyperlinking, and uncheck the item Changelog Detector, as shown on the screenshot below. Gain more info at


If your indexer stops working, you should rebuild it as shown above. If that didn't help, destroy the Eclipse project and reconfigure it from scratch again. Sometimes Eclipse may just get in a bad mood and stop behaving properly; in that case you should try restarting it.