Guidelines and HOWTOs/CMake/FirstProject

This tutorial will show you how to create a very simple project in CMake.

Note

You need to make sure you have CMake installed. If you are using Linux, you should be able to get CMake from your distribution's packages. On Windows or OS/X, you can install the packages provided by CMake.

Tutorial

Let's say you have a very simple C++ application. Create a directory and, within it, create a file called main.cpp with the following content:

#include <iostream>
int main(int, char**) {
    std::cout << "Hello world!" << std::endl;
    return 0;
}

Now we need to tell CMake how to build this project. To do this, we will create a file in the same directory called CMakeLists.txt. Open this in a text editor.

First, we tell CMake the minimum version of CMake we require. This not only prints out a helpful error if anyone tries to build with a CMake version that's too old (and may not support features we use), but it also turns off some backwards-compatibility behaviours of CMake.

cmake_minimum_required(VERSION 2.8.12)

VERSION here is a keyword argument. In this case, it says that the next argument (2.8.12) will be the version number. We're saying we want CMake 2.8.12 because this is still the version shipped by a few Linux distributions (so we don't want to set it to a later version), but 2.8.12 has useful features we will want in later tutorials (so we don't set it to an earlier version). You can set it to, say, 3.0 or 3.1 if you like. Don't forget to look at the correct version of the CMake documentation for whatever version you use here.

Now we tell CMake the name of our project. This is used to name the generated Visual Studio solution file, if you use that build environment, for example.

project(FirstProjectTutorial)

The project command does more than just name the project; it also sets up the languages the project will use. You can pass the languages you need to the command, but if you don't, C and C++ will be enabled by default.

That's our initial setup done. Now we need to tell CMake to make an executable. First, we store a list of source files in a variable:

set(tutorial_SRCS
    main.cpp
)

Variables in CMake behave much like variables in a shell: you don't have to worry about types (they are all strings in the end) and you don't have to declare them before you use them (a variable that hasn't been set is empty). If you wanted to add more source files, you just need to separate them with whitespace (such as one on each line).

Now that we have our list of source files, we can tell CMake to turn them into an executable:

add_executable(tutorial ${tutorial_SRCS})

This creates an executable target called tutorial (the first argument). A target can be thought of as an "output" of the build system (that's a simplification, but not a bad starting point). If you wanted to create a library, that would be another type of target. "Documentation" could be another (special kind of) target. Everything in CMake is aimed at describing what targets you want your build system to produce and how to make (and install) them.

After the target name comes the list of sources. This demonstrates how we reference variables - again, much like a shell. If we had provided multiple source files to the set command, this would expand to multiple arguments passed to add_executable.

We could have skipped the variable altogether, and just listed the sources directly in the add_executable command. Having a separate variable is a commonly-used pattern, however, as it makes it easy to have, say, different source files on different platforms.

And that's it! In a handful of lines, we have a project that will allow us to build an executable across multiple compilers and platforms. It won't install anything yet, although that would be a simple addition.

Build

Putting it all together, your file should look like:

cmake_minimum_required(VERSION 2.8.12)
project(FirstProjectTutorial)
set(tutorial_SRCS
    main.cpp
)
add_executable(tutorial ${tutorial_SRCS})

Now you need to run CMake on it. Guidelines and HOWTOs/CMake/Building has all the details, but very briefly, on a Unix system you can run

mkdir build
cd build
cmake ..
make

from the source directory, and on other systems you can use the CMake GUI (just point it at your source directory and create an empty directory for the build directory, then press Configure followed by Generate) to create project files for your favourite build environment (such as XCode), and use that to do the compilation.

You can run the resulting executable, and get the output you would expect from any first programming-related tutorial:

Hello world!

Next steps

Try adding another source file to the project (this will require some C++ knowledge if you want your second source file to actually be used). It should be as simple as adding the name of the new file next to main.cpp (on a new line, for readability).