Setting up CMake Projects in Eclipse

Integrated Development Environments (IDEs) are fantastic tools to speed up the software development process. However, each IDE seems to have its own custom build system. I, on the other hand, prefer to use CMake and Makefiles to prevent being locked down to one IDE for building. This is great, but at the start of every project I spend an absurd amount of time getting an Eclipse project set up. Here, I’ll document my process for setting up a CMake project in Eclipse and getting started with development of a new project.

Marketplace Packages

First thing’s first, we need to set up Eclipse to play nicely with CMake. Specifically, Eclipse doesn’t have support for CMakeLists.txt files out of the box. You can open them in the editor and modify them, but there is no syntax highlighting. Honestly, it is pretty miserable to work with them like this.

There is an extension from the Eclipse Marketplace (Help -> Eclipse Marketplace) called cmake-editor that can help with this. Search for this extension, install it, and then restart Eclipse. You may need to close and re-open any CMake files, but now you will have proper syntax highlighting for you CMake files!

Creating the Project

Next, we need to create a project. My preferred method for starting from scratch is to create a new repository on Github, and then clone that repository to my local machine. I like doing it this way so that I don’t have to deal with creating a README.md file myself, which I would need to do if I create a git repository locally and then push it to an upstream location on Github.

With the project directory cloned from Github, start Eclipse and choose File -> New -> C/C++ Project. From here choose Empty or Existing CMake Project. This will not create a starting template to work from and so is good for either a clean slate or creating an Eclipse project for existing code. Choose a name and un-check the “Use default location” box so that you can point it at the directory you cloned from Github.

Building

From here, write some code and a CMakeLists.txt file and you will be ready to build! Building is easy with Eclipse, just press the hammer icon to build or go to the Project tab for more build options.

There is one extremely important note here. CMake has an option to specify a “build” location with the “—build” or “-B” options. This is where the build files will be put after calling the cmake command. These build files are then used to compile the program. If this build option isn’t specified, then CMake will do an “in-source build” where build files will be strewn about with the source code. On its own this is fine, if a tad messy. However, Eclipse WILL NOT BUILD if any in-source build files exist. Eclipse will specify “—build” by default, but if you ever run CMake yourself without this option it will prevent Eclipse from building the project until you clean up the rogue build files.

Indexing

Indexing your code is related to building (compiling) your code. Indexing is what gives you syntax highlighting in the editor and is also what gives you the red and yellow squiggly lines to indicate that a certain line will generate a compiler error or warning. This is the main feature that makes using an IDE more useful than writing code in Notepad or VIM.

I have had endless headaches with the indexer in Eclipse when I work with packages like Vulkan or wxWidgets. The main problem is that Eclipse can’t find the headers for these libraries that it needs in order to Index properly. So instead, Eclipse sees numerous warnings and errors during indexing and pollutes the editor with this information even when the program compiles properly.

With a CMake project, Eclipse will grab information about include directories from the CMakeLists.txt files. So, if the compiler can find the headers, the indexer should be able to. However, this is a bit touchy when creating a new project and I have been burned multiple times. First, you need to build the project even if the editor shows errors. This will call CMake and update the include directories based on your CMakeLists.txt file. This might cause a re-index operation to happen, but if it doesn’t just got to Project -> C/C++ Index -> Rebuild. The key here is that you MUST run CMake before you will be able to index your project properly.

Edit: Even after all of this, I had some issues with indexing in Debug builds. The issue ended up being that my include directories were not properly set up for all of the CMake targets for the code with indexing issues. So, if code is used in more than one target, make sure that you set the needed include directories for ALL the targets it is used in!

Enjoy! Hopefully this helps get your project up and running so that you can get to developing.