Writing a CMakeLists File

This command officially starts the project. It sets the project's name and enables support for programming languages.

project(Greeter) sets the name of our project to "Greeter". This name is also stored in the PROJECT_NAME variable, which we'll see how to use later. By default, this command also enables support for C and C++.

With just these two commands, we have a valid, albeit empty, CMake project. It doesn't build anything yet, but we've laid the foundation.

Now let's tell CMake to actually build something. In CMake, anything that gets built - such as an executable or library - is called a target.

The command to create an executable is add_executable(). Let's add it to our file.

1cmake_minimum_required(VERSION 3.16)
2project(Greeter)
3
4add_executable(GreeterApp src/main.cpp)

The add_executable() command takes two main arguments:

1. The Target Name: The first argument is the name we want to give our executable target. In simple projects, the primary executable of our project often matches the project name, but it doesn't have to. Here, we've called our project Greeter and the executable GreeterApp.
2. The Source Files: The remaining arguments are the source files needed to build that executable. We've provided a single source file for now - src/main.cpp.

And that's it! With these three lines, you have a complete, working CMake project that can build an executable.

We have described what we want - an executable named GreeterApp built from main.cpp - and CMake will figure out how to do it on any platform.

We'll run the build in the next lesson, but first, let's make our project a little more complex.

Real-world projects are rarely a single file. As we've discussed, good design involves breaking code into logical, reusable components. In C++, we do this with libraries.

This project is obviously too simple to warrant such separation, but let's run with the contrivance to learn the process. We'll refactor our project into a simple library called Greeter that includes a header and source file, and provides a get_greeting() function. Our main executable will then use this library.

Updating the Project Structure

First, let's create the files for our library. We'll follow the convention of putting the public header in an include directory and the source file in src.

1Greeter/
2├─ include/
3│ └─ Greeter.h
4└─ src/
5  ├─ Greeter.cpp
6  └─ main.cpp

Here's the content for our new library files, and we'll also update main.cpp to use it:

Now, we need to update our CMakeLists.txt to tell CMake about this new library and how it relates to our executable.

We'll use two new commands: add_library() to define our library target, and target_link_libraries() to create the dependency. We can also add comments to our CMakeLists.txt file using the # token:

1cmake_minimum_required(VERSION 3.16)
2project(Greeter)
3
4# Create a library target named "GreeterLib"
5add_library(GreeterLib src/Greeter.cpp) 
6
7# Add our executable target like before
8add_executable(GreeterApp src/main.cpp)
9
10# Link the "GreeterLib" library to our executable
11target_link_libraries(GreeterApp GreeterLib)

Let's break down the new additions.

add_library()

The add_library(GreeterLib src/Greeter.cpp) command works just like add_executable(). It creates a new library target, where we provide the name we want to use (GreeterLib in this example) and the source files it is built from (a single file - src/Greeter.cpp - in this example).

By default, this creates a static library (.a or .lib). We'll learn how to change this to a shared library later in the course.

In real-world projects, libraries are generally going to have more sensible names based on their specific purpose. They might have names such as "Renderer" or "PhysicsEngine".

In our contrived example, we'll call our target GreeterLib, to distinguish it from the overall project (which we called Greeter) and the executable target (which we called GreeterApp).

target_link_libraries()

The target_link_libraries(GreeterApp GreeterLib) command connects the library to the executable. It tells CMake, that the GreeterApp target depends on the GreeterLib target. This single command does several things for us automatically:

• It ensures GreeterLib is built before GreeterApp.
• It tells the linker to link the compiled GreeterLib library with the GreeterApp executable.
• As we'll see later, it can also transitively pass on configuration options and usage requirements, like include directories.

We still have one problem. The main.cpp file includes Greeter.h, but the compiler doesn't know to look in our include directory for this header file. Let's fix that:

1cmake_minimum_required(VERSION 3.16)
2project(Greeter)
3
4add_library(GreeterLib src/Greeter.cpp)
5
6# Tell our GreeterLib library where its public headers are
7target_include_directories(GreeterLib PUBLIC 
8  ${PROJECT_SOURCE_DIR}/include 
9) 
10
11add_executable(GreeterApp src/main.cpp)
12
13target_link_libraries(GreeterApp GreeterLib)

The target_include_directories() command adds include search paths to a target. Let's break down the three arguments we provided here.

The GreeterLib Argument

The include directory we want to provide relates to our GreeterLib library, so we provide this target as the first argument.

Our GreeterApp target also needs this include directory for the #include directive in it's main.cpp file, so you might think we need a second target_include_directories() for that target.

We could add that, but one of the benefits of CMake is that we don't need to. As long as our library makes this include directory PUBLIC and we then link to the library using target_link_libraries(), CMake can take care of it for us. This management of interconnected targets is a major feature of CMake and something we've dedicated a chapter to later in the course.

The PUBLIC Argument

The PUBLIC keyword effectively makes this dependency known to any other target that might be interested. It means: "Anyone who links to me (GreeterLib) also needs this include directory to compile."

In our case, the GreeterApp also needs to know about this include directory. Because we made this relationship PUBLIC, and we later we link GreeterApp to GreeterLib, then GreeterApp automatically inherits the include directory, solving our compilation problem.

We'll fully explain the PUBLIC keyword and the other options - PRIVATE and INTERFACE - later in the course.

The Include Directory

Finally, as our third argument, we need to provide the actual path to our /include directory.

We do this using the ${PROJECT_SOURCE_DIR}/include expression, which is our first example of using a variable within CMake. We'll cover variables in much more detail soon, but PROJECT_SOURCE_DIR a one of the many variables that CMake automatically defines for us.

It's value is the path on our file system to our project directory - that is, the location where our CMakeLists.txt file is. The ${PROJECT_SOURCE_DIR}/include interpolates this variable into a string to generate the full path to our /include folder within our project's directory.

If the header files for our GreeterLib library were instead located in /greeter/include within our project directory, then our expression would look like this:

1target_include_directories(GreeterLib PUBLIC
2  ${PROJECT_SOURCE_DIR}/greeter/include 
3)

If our library had multiple include directories, we can add additional arguments to our target_include_directories() command:

1target_include_directories(GreeterLib PUBLIC
2  ${PROJECT_SOURCE_DIR}/include
3  ${PROJECT_SOURCE_DIR}/headers
4  ${PROJECT_SOURCE_DIR}/more-headers
5)

The final piece of our basic puzzle is telling CMake which version of the C++ standard we want to use.

Modern CMake provides a target-based way to do this with target_compile_features(). We should do this for both of our library and executable targets. We'll use C++20 in this example, but not for any specific reason beyond it being a relatively modern and widely supported baseline:

1cmake_minimum_required(VERSION 3.16)
2project(Greeter)
3
4add_library(GreeterLib src/Greeter.cpp)
5target_compile_features(GreeterLib PUBLIC cxx_std_20) 
6target_include_directories(GreeterLib PUBLIC
7  ${PROJECT_SOURCE_DIR}/include
8)
9
10add_executable(GreeterApp src/main.cpp)
11target_compile_features(GreeterApp PUBLIC cxx_std_20) 
12target_link_libraries(GreeterApp GreeterLib)

The command target_compile_features(MyTarget PUBLIC cxx_std_20) tells CMake: "The target MyTarget requires compiler features associated with the C++20 standard."

CMake will then automatically add the correct compiler flag (e.g., -std=c++20 for GCC/Clang or /std:c++20 for MSVC) when compiling that target.

Just like with target_include_directories(), the PUBLIC keyword makes this requirement propagate between targets. We'll fully explain this propagation process, the PUBLIC keyword, target_compile_features() and managing compiler flags later in the course.

We now have a complete, modern CMakeLists.txt file documenting the full configuration of a simple project with both a library and an executable.

Let's review our final CMakeLists.txt for this lesson:

We've learned the five most fundamental commands for any CMake project:

• cmake_minimum_required(): Sets the required version and policies.
• project(): Names the project.
• add_library(): Creates a library target.
• add_executable(): Creates an executable target.
• target_link_libraries(): Creates a dependency between targets.

And we've seen how to add requirements like include paths and C++ standards using modern, target-based commands.