CMake Project Structure and Subdirectories

In the last lesson, we successfully built our first CMake project. It worked, but all our build logic was crammed into a single CMakeLists.txt file.

1# 1. Set the minimum CMake version and project name
2cmake_minimum_required(VERSION 3.16)
3project(Greeter)
4
5# 2. Define the library target
6add_library(GreeterLib src/Greeter.cpp)
7
8# 3. Add usage requirements to the library
9target_include_directories(GreeterLib PUBLIC
10  ${PROJECT_SOURCE_DIR}/include
11)
12target_compile_features(GreeterLib PUBLIC cxx_std_20)
13
14# 4. Define the executable target
15add_executable(GreeterApp src/main.cpp)
16
17# 5. Add usage requirements to the executable
18target_compile_features(GreeterApp PUBLIC cxx_std_20)
19
20# 6. Link the library to the executable
21target_link_libraries(GreeterApp GreeterLib)

For a tiny project, that's fine. But what happens when our project grows? Imagine adding a physics engine, a rendering module, a networking library, and a separate test suite. A single CMakeLists.txt would quickly become a long, unmaintainable file.

There is also a more practical problem - how can we share our library with other projects if the build configuration for our library is mixed with the configuration for a load of other targets within the same CMakeLists.txt file?

A core principle of good software design is modularity. This applies to our build scripts just as much as it does to our C++ code. A scalable project needs a scalable build structure.

In this lesson, we'll learn the two steps for for achieving this:

1. Breaking a project into self-contained, reusable components each with their own CMakeLists.txt file
2. Bringing these components back together into a complete project using add_subdirectory() commands

The goal is to structure our project so that each component (like a library or an executable) is entirely self-contained. All its source code, public headers, and build instructions should live together in a single directory.

This makes the component:

• Maintainable: The logic for a component is in one place.
• Reusable: You could copy the component's directory into a new project and use it instantly.
• Scalable: Adding new components doesn't increase the complexity of existing ones.

To do this, we'll refactor our simple Greeter project into a structure that treats the GreeterLib library and the GreeterApp executable as two distinct, modular components.

Here is the structure for our refactored project:

1greeter/
2 ├─ include/
3 │  └─ greeter
4 │    └─ Greeter.h
5 ├─ src/
6 │  └─ Greeter.cpp
7 └─ CMakeLists.txt
8
9app/
10 ├─ src/
11 │  └─ main.cpp
12 └─ CMakeLists.txt
13 
14CMakeLists.txt

Each major component gets its own dedicated directory and CMakeLists.txt file. In our top level directory, we have three things:

• The /greeter directory for our library.
• The /app directory for our executable
• A top level CMakeLists.txt to orchestrate everything

Each of our two components has its own dedicated CMakeLists.txt file, as well as the usual subfolders like /src, /include, and more can be added as needed.

Within our library's /include directory, we've also add an intermediate greeter directory for our header files. We'll explain the reason for this later in this lesson.

Let's walk through each of our three CMakeLists.txt files.

The Root CMakeLists.txt

The top-level CMakeLists.txt becomes extremely simple. Its only job is to define project-wide settings and then pull in the components using add_subdirectory().

1cmake_minimum_required(VERSION 3.16)
2
3# Name the overall project
4project(Greeter)
5
6# Bring in our components
7add_subdirectory(greeter) # The library 
8add_subdirectory(app)     # The executable

This top level CMakeLists.txt is now extremely high level, which is what we want for a file in such an important location as the root of our project. It simply declares what components our project has, and each new component we add requires a single line, keeping complexity to a minimum.

It doesn't care about the implementation details of how those components are built - those are lower level details stored deeper in our project structure.

The single line that loads these components is the add_subdirectory() command. This command looks for a CMakeLists.txt file in that location, and incorporates it into our build.

The Library's CMakeLists.txt

The greeter/CMakeLists.txt file is responsible for defining the library in its directory.

Let's use it to define our GreeterLib target, alongside its source files, include directories, and it's usage of the C++20 standard:

1cmake_minimum_required(VERSION 3.16)
2
3add_library(GreeterLib src/Greeter.cpp)
4target_include_directories(GreeterLib PUBLIC
5  ${CMAKE_CURRENT_SOURCE_DIR}/include
6)
7target_compile_features(GreeterLib PUBLIC cxx_std_20)

Note that we're now using the CMAKE_CURRENT_SOURCE_DIR variable for our include directories, where previously we were using PROJECT_SOURCE_DIR.

The CMAKE_CURRENT_SOURCE_DIR variable is the directory where the current CMakeLists.txt file. Given we're using this variable in a CMakeLists.txt file stored in the greeter/ directory, then its value will be the path to that directory.

The PROJECT_SOURCE_DIR variable is the directory where the CMakeLists.txt file containing the project() command is. In our case, the only CMakeLists.txt file in our hierarchy containing a project() command is within the top level directory.

So, if we were to use that variable in any CMakeLists.txt file loaded by an add_subdirectory() command in that file, it would contain the path to the root of our project.

With these changes, our library is now completely reusable. If we want to share it with other projects, we just share our entire greeter directory. Any other project that wants to use our library involves three simple steps:

• copy this directory into their project's file structure
• add an add_subdirectory() command to their CMakeLists.txt file to make CMake aware of it
• add a target_link_libraries() command for any target that wants to use the library

The Application's CMakeLists.txt

Finally, let's look at the application's CMakeLists.txt file. Again, it's quite simple - it just needs to define itself, it's C++ standard, and link against the GreeterLib library.

1cmake_minimum_required(VERSION 3.16)
2
3add_executable(GreeterApp src/main.cpp)
4target_compile_features(GreeterApp PUBLIC cxx_std_20)
5target_link_libraries(GreeterApp GreeterLib)

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

1#include <iostream>
2
3// Either of these will work
4#include <greeter/Greeter.h>
5#include <Greeter.h>
6
7int main() {
8  std::cout << get_greeting();
9  return 0;
10}

1target_include_directories(GreeterApp PUBLIC
2  # GreeterApp shouldn't know about this path
3  ${PROJECT_SOURCE_DIR}/greeter/include/greeter 
4)

1cmake ..

1cmake --build .

1./app/GreeterApp

1Hello from the modular Greeter library!