CMake – Out-of-source build – Learning by Coding

CMake generates a lot of files (that is what its supposed to do, right?).
In most cases you have your source code under some kind of version control system e.g. git.
The generated files are usually not meant to be for the rest of your team and thus should not be checked in.

Of course you can maintain an ignore list for every generated file and folder, but an alternative is to generate them outside your source folder from the start. This gives you the ability to have multiple configurations in parallel (Release, Debug, cross-compilation) while working on the same code base.

For demonstrating how to generate an CMake out-of-source build, I will use cmake-gui. I like CMake’s graphical front-end when it comes to bigger projects, as it helps to keep an overview during the configuration step. But you can do everything described here via command line too.

Startup

At startup you need to specify two things:

The folder of your (root) CMakeLists – “Where is the source code” – CMAKE_SOURCE_DIR
A folder to generate the project files – “Where to build the binaries” – CMAKE_BINARY_DIR

startup cmake-gui — CMake-GUI – out-of-source build

Next click “Configure”. If the specified build directory does not exist, CMake will ask if it should create it. Confirm or choose another one.

Generator and Compiler

CMake will ask for a generator and lets you pick from a list of detected generators.
You may want to choose the generator for your IDE from the drop down list. For more information on generators see the CMake documentation. In this example I choose the Eclipse CDT generator and leave the radio button with “Use default native compilers”.
If you want to cross-compile your project, specify the option to “Specify a toolchain file for cross-compiling” and proceed.

CMake-choosing a generator — CMake – Choose a generator

Configure

After you specified the generator, the configuration process will start.
CMake-gui will output log information and Name-Value pairs of parameters for the project will be added.
You can check the “Grouped” box to have a better overview.
If you want to see advanced variables, check that as well. Keep in mind though that they were marked as advanced for some reason, so before tinkering with these, its always good to take a look at the CMake code first.

CMake - Inspect the Configuration — CMake – Inspect the Configuration

After you modified values, you can click Configure again to see if everything still works fine.

Generate

Click the Generate button to complete the process.
If you want to safe a second or two, click Generate from the start. It will Configure and Generate in one click.

reconfigured cmake-gui — Reconfigured and Generated CMake project

Build

Finally build the project.
How you import the project into the IDE of your choice depends on the generator you chose.
In Eclipse CDT you open the generated folder.
To build via command line, navigate to the binary folder and your project will be build with:

cmake --build .

CMake and Eclipse CDT

One thing to mention: Choosing Eclipse CDT and using in-source (!) build may issue the following warning:

CMake Warning in CMakeLists.txt:
The build directory is a subdirectory of the source directory.
This is not supported well by Eclipse. It is strongly recommended to use a
build directory which is a sibling of the source directory.

The message already tells you what to do. Build out-of-source in case you use Eclipse CDT like we did above.
If you see that, you may likely have made a mistake when specifying the output directory.