To run the examples in this chapter, you will need a recent C++ compiler that understands C++17. Although the examples are not complex enough to require the functionality of the new standard, the examples have been set up accordingly.

We recommend using any of the compilers listed here to run the examples:

• Linux: GCC 9 or newer, Clang 10 or newer
• Windows: MSVC 19 or newer or MinGW 9.0.0 or newer
• macOS: AppleClang 10 or newer

The complete samples used in this chapter can be found at https://github.com/PacktPublishing/CMake-Best-Practices---2nd-Edition/tree/main/chapter01

Note

To try out any examples in this book, we have provided a ready-made Docker container that contains all the requirements.

You can find it at https://github.com/PacktPublishing/CMake-Best-Practices---2nd-Edition.

CMake is open source and available on many platforms. It is also compiler-independent, making it a very strong tool when it comes to building and distributing cross-platform software. All these features make it a valuable tool for building software in a modern way – that is, by relying heavily on build automation and built-in quality gates.

CMake consists of three command-line tools:

• cmake: CMake itself, which is used to generate build instructions
• ctest: CMake’s test utility, which is used to detect and run tests
• cpack: CMake’s packaging tool, which is used to pack software into convenient installers, such as DEB, RPM, and self-extracting installers

There are also two interactive tools:

• cmake-gui: A GUI frontend to help with configuring projects
• ccmake: An interactive terminal UI for configuring CMake

The cmake-gui tool can be used to conveniently configure a CMake build and select the compiler to...

CMake is freely available to download from https://cmake.org/download/. It is available as either a precompiled binary or as source code. For most use cases, the precompiled binary is fully sufficient, but since CMake itself has very few dependencies, building a version is also possible.

Any major Linux distribution offers CMake over its package repositories. Although the pre-packaged versions of CMake are not usually the latest releases, these installations are often sufficient to use if the system is regularly updated. Another convenient way to install CMake is by using pip, the Python package manager.

Note

The minimum version of CMake to use with the examples in this book is 3.23. We recommend that you download the appropriate version of CMake manually to ensure that you get the correct version.

Building CMake from source

CMake is written in C++ and uses Make to build itself. Building CMake from scratch is possible, but for most use cases, using the...

Now, it’s time to get your hands dirty and see if your installation worked. We have provided an example of a simple hello world project that you can download and build right away. Open a console, type in the following, and you’ll be ready to go:

git clone   https://github.com/PacktPublishing/CMake-Best-Practices---2nd-Edition.git
cd CMake-Best-Practices---2nd-Edition/chapter01/simple_executable
cmake -S . -B build
cmake -–build ./build

This will result in an executable called ch_simple_executable that prints out Welcome to CMake Best Practices on the console.

Let’s have a detailed look at what happened here:

First, the example repository is checked out using Git. The file structure of the example CMake project located in the chapter01/simple_executable subfolder will look like this before the build:

.
├── CMakeLists.txt
└── src
    └...

CMake’s build process works in two steps, as shown in the following diagram. First, if it’s invoked without any special flags, CMake scans the system for any usable toolchains during the configuration process and then decides what its output should be. The second step, which is when cmake --build is invoked, is the actual compilation and building process:

Figure 1.3 – CMake’s two-stage build process

The standard output is Unix Makefiles unless the only detected compiler is Microsoft Visual Studio, in which case a Visual Studio solution (.sln) will be created.

To change the generator, you can pass the -G option to CMake, like this:

cmake .. -G Ninja

This will generate files to be used with Ninja (https://ninja-build.org/), an alternative build generator. Many generators are available for CMake. A list of the ones that are supported natively can be found on CMake’s website...

When you’re writing CMake files, there are a few core concepts and language features that you need to know about. We won’t cover every detail of the language here as CMake’s documentation does a pretty good job at this – especially when it comes to being comprehensive. In the following sections, we will provide an overview of the core concepts and language features. Further chapters will dive into the details of different aspects.

The full documentation for the language can be found at https://cmake.org/cmake/help/latest/manual/cmake-language.7.html.

The CMake language – a 10,000-foot overview

CMake uses configuration files called CMakeLists.txt files to determine build specifications. These files are written in a scripting language, often called CMake as well. The language itself is simple and supports variables, string functions, macros, function definitions, and importing other CMake files.

Apart from lists, there...

The power of CMake comes from the fact that you can use the same build specification – that is, CMakeLists.txt – for various compiler toolchains without the need to rewrite anything. A toolchain typically consists of a series of programs that can compile and link binaries, as well as create archives and similar.

CMake supports a variety of languages that the toolchains can be configured for. In this book, we will focus on C++. Configuring the toolchain for different programming languages is done by replacing the CXX part of the following variables with the respective language tag:

• C
• CXX – C++
• CUDA
• OBJC – Objective C
• OBJCXX – Objective C++
• Fortran
• HIP – HIP C++ runtime API for NVIDIA and AMD GPUs
• ISPC – C-Based SPMD programming language
• ASM – Assembler

If a project does not specify its language, it’s assumed that C and CXX are being used...

A common problem when building software with CMake is how to share good or working configurations to build a project. Often, people and teams have a preferred way of where the build artifacts should go, which generator to use on which platform, or just the desire that the CI environment should use the same settings to build as they do locally. Since CMake 3.19 came out in December 2020, this information can be stored in CMakePresets.json files, which are placed in the root directory of a project. Additionally, each user can superimpose their configuration with a CMakeUserPresets.json file. The basic presets are usually placed under version control, but the user presets are not checked into the version system. Both files follow the same JSON format, with the top-level outline being as follows:

{
"version": 6,
"cmakeMinimumRequired": {
"major": 3,
"minor": 23,
"patch": 0
},
"configurePresets...

In this chapter, we provided you with a brief overview of CMake. First, you learned how to install and run a simple build. Then, you learned about the two-stage build process of CMake and single-configuration and multi-configuration generators.

By now, you should be able to build the examples provided in this book’s GitHub repository at https://github.com/PacktPublishing/CMake-Best-Practices---2nd-Edition. You learned about the core features of the CMake language, such as variables, targets, and policies. We briefly covered functions and macros, as well as conditional statements and loops for flow control. As you continue reading this book, you will use what you have learned so far to discover further good practices and techniques to move from simple one-target projects to complex software projects that keep being maintainable through a good CMake setup.

In the next chapter, we will learn how some of the most common tasks in CMake can be performed and how CMake...

To learn more about the topics that were covered in this chapter, take a look at the following resources:

• The official CMake documentation: https://cmake.org/cmake/help/latest/
• The official CMake tutorial: https://cmake.org/cmake/help/latest/guide/tutorial/index.html

Answer the following questions to test your knowledge of this chapter:

1. How do you start the configure step of CMake?
2. What is the difference between single-configuration and multi-configuration generators?
3. How do you start the build step of CMake?
4. Which executable from CMake can be used to run tests?
5. Which executable from CMake is used for packaging?
6. What are targets in CMake?
7. What is the difference between properties and variables?
8. What are CMake presets used for?

The following are the answers to the preceding questions:

1. You can start the configure step of CMake with the following command:

   cmake -S /path/to/source -B /path/to/build

2. Single-configuration generators will only generate build files for one type of build, such as debug or release builds. Multi-configuration generators will generate build instructions for all available build types in one go.
3. You can start the build step of CMake using:

   cmake -build /path/to/build

4. The following executable from CMake can be used to run tests:

   ctest

5. The following executable from CMake is used for packaging:

   cpack

6. Targets in CMake are logical units around which CMake organizes a build. They can be executables, libraries, or contain custom commands.
7. Unlike variables, properties are attached to a specific object or scope.
8. CMake presets are used to share working configurations for a build.