Modern CMake for C++ E-Book

Rafał Świdziński

• Herausgeber: Packt Publishing
• Kategorie: Fachliteratur
• Sprache: Englisch

Seitenzahl: 522

Veröffentlichungsjahr: 2022

Beschreibung

Creating top-notch software is an extremely difficult undertaking. Developers researching the subject have difficulty determining which advice is up to date and which approaches have already been replaced by easier, better practices. At the same time, most online resources offer limited explanation, while also lacking the proper context and structure.
This book offers a simpler, more comprehensive, experience as it treats the subject of building C++ solutions holistically. Modern CMake for C++ is an end-to-end guide to the automatization of complex tasks, including building, testing, and packaging. You'll not only learn how to use the CMake language in CMake projects, but also discover what makes them maintainable, elegant, and clean. The book also focuses on the structure of source directories, building targets, and packages. As you progress, you’ll learn how to compile and link executables and libraries, how those processes work, and how to optimize builds in CMake for the best results. You'll understand how to use external dependencies in your project – third-party libraries, testing frameworks, program analysis tools, and documentation generators. Finally, you'll get to grips with exporting, installing, and packaging for internal and external purposes.
By the end of this book, you’ll be able to use CMake confidently on a professional level.

Leseprobe

Modern CMake for C++

Discover a better approach to building, testing, and packaging your software

Rafał Świdziński

BIRMINGHAM—MUMBAI

Modern CMake for C++

Copyright © 2022 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.

Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, nor Packt Publishing or its dealers and distributors, will be held liable for any damages caused or alleged to have been caused directly or indirectly by this book.

Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

Associate Group Product Manager: Richa Tripathi

Publishing Product Manager: Rohit Rajkumar

Senior Editor: Mark Dsouza

Content Development Editor: Divya Vijayan

Technical Editor: Joseph Aloocaran

Copy Editor: Safis Editing

Project Coordinator: Rashika Ba

Proofreader: Safis Editing

Indexer: Tejal Daruwale Soni

Production Designer: Jyoti Chauhan

Marketing Coordinator: Elizabeth Varghese

First published: February 2022

Production reference: 3131022

Published by Packt Publishing Ltd.

Livery Place

35 Livery Street

Birmingham

B3 2PB, UK.

ISBN 978-1-80107-005-8

www.packt.com

To my family: my parents, Bożena and Bogdan, my sisters, Ewelina and Justyna, and my wife, Katarzyna, for their ongoing support and advice.

– Rafał Świdziński

Contributors

About the author

Rafał Świdziński works as a staff engineer at Google. With over 10 years of professional experience as a full stack developer, he has been able to experiment with a vast multitude of programming languages and technologies. During this time, he has been building software under his own company and for corporations including Cisco Meraki, Amazon, and Ericsson.

Originally from Łódź, Poland, he now lives in London, UK, from where he runs a YouTube channel, "Smok," discussing topics related to software development. He tackles technical problems, including real-life and work-related challenges encountered by many people in the field. Throughout his work, he explains the technical concepts in detail and demystifies the art and science behind the role of software engineer. His primary focus is on high-quality code and the craftsmanship of programming.

About the reviewers

Sergio Guidi Tabosa Pessoa is a software engineer with more than 30 years of experience in software development and maintenance, from complex enterprise software projects to modern mobile applications. In the early days, he worked primarily with the Microsoft stack, but soon discovered the power of the UNIX and Linux operating systems. Even though he has worked with many languages over the years, C and C++ remain his favorite languages for their power and speed.

He has a bachelor's degree in computer science and an MBA in IT management and is always hungry to learn new technologies, break code, and learn from his mistakes. He currently lives in Brazil with his wife, two Yorkshire Terriers, and two cockatiels.

First and foremost, I would like to thank all the people involved in this project, including the author for crafting such a great piece of work, and Packt Publishing for giving me this opportunity. I also would like to thank my beautiful wife, Lucia, as well as Touché and Lion, for their patience and for allowing me the time needed to help with this book.

Holding an engineering degree from ENSEEIHT and a Ph.D. in computer science from UVSQ in France, Eric Noulard has been writing and compiling source code in a variety of languages for 20 years. A user of CMake since 2006, he has also been an active contributor to the project for several years. During his career, Eric has worked for private companies and government agencies. He is now employed by Antidot, a software vendor responsible for developing and marketing high-end information retrieval technology and solutions.

Mohammed Alqumairi is a software engineer at Cisco Meraki with experience in developing critical and performant backend services using a variety of languages and frameworks, with a particular focus on modern C++, CMake, and the Poco libraries. Mohammed graduated with honors from City, University of London, with a B.Sc. in Computer Science.

Table of Contents

Preface

Section 1: Introducing CMake

Chapter 1: First Steps with CMake

Technical requirements

Understanding the basics

What is CMake?

How does it work?

Installing CMake on different platforms

Docker

Windows

Linux

macOS

Building from the source

Mastering the command line

CMake

CTest

CPack

The CMake GUI

CCMake

Navigating the project files

The source tree

The build tree

Listfiles

CMakeLists.txt

CMakeCache.txt

The Config-files for packages

The cmake_install.cmake, CTestTestfile.cmake, and CPackConfig.cmake files

CMakePresets.json and CMakeUserPresets.json

Ignoring files in Git

Discovering scripts and modules

Scripts

Utility modules

Find-modules

Summary

Further reading

Chapter 2: The CMake Language

Technical requirements

The basics of the CMake Language syntax

Comments

Command invocations

Command arguments

Working with variables

Variable references

Using the environment variables

Using the cache variables

How to correctly use the variable scope in CMake

Using lists

Understanding control structures in CMake

Conditional blocks

Loops

Command definitions

Useful commands

The message() command

The include() command

The include_guard() command

The file() command

The execute_process() command

Summary

Further reading

Chapter 3: Setting Up Your First CMake Project

Technical requirements

Basic directives and commands

Specifying the minimum CMake version – cmake_minimum_required()

Defining languages and metadata – project()

Partitioning your project

Scoped subdirectories

Nested projects

External projects

Thinking about the project structure

Scoping the environment

Discovering the operating system

Cross-compilation – what are host and target systems?

Abbreviated variables

Host system information

Does the platform have 32-bit or 64-bit architecture?

What is the endianness of the system?

Configuring the toolchain

Setting the C++ standard

Insisting on standard support

Vendor-specific extensions

Interprocedural optimization

Checking for supported compiler features

Compiling a test file

Disabling in-source builds

Summary

Further reading

Section 2: Building With CMake

Chapter 4: Working with Targets

Technical requirements

The concept of a target

Dependency graph

Visualizing dependencies

Target properties

What are transitive usage requirements?

Dealing with conflicting propagated properties

Meet the pseudo targets

Build targets

Writing custom commands

Using a custom command as a generator

Using a custom command as a target hook

Understanding generator expressions

General syntax

Types of evaluation

Examples to try out

Summary

Further reading

Chapter 5: Compiling C++ Sources with CMake

Technical requirements

The basics of compilation

How compilation works

Initial configuration

Managing sources for targets

Preprocessor configuration

Providing paths to included files

Preprocessor definitions

Configuring the headers

Configuring the optimizer

General level

Function inlining

Loop unrolling

Loop vectorization

Managing the process of compilation

Reducing compilation time

Finding mistakes

Summary

Further reading

Chapter 6: Linking with CMake

Technical requirements

Getting the basics of linking right

Building different library types

Static libraries

Shared libraries

Shared modules

Position-independent code

Solving problems with the One Definition Rule

Dynamically linked duplicated symbols

Use namespaces – don't count on a linker

The order of linking and unresolved symbols

Separating main() for testing

Summary

Further reading

Chapter 7: Managing Dependencies with CMake

Technical requirements

How to find installed packages

Discovering legacy packages with FindPkgConfig

Writing your own find-modules

Working with Git repositories

Providing external libraries through Git submodules

Git-cloning dependencies for projects that don't use Git

Using ExternalProject and FetchContent modules

ExternalProject

FetchContent

Summary

Further reading

Section 3: Automating With CMake

Chapter 8: Testing Frameworks

Technical requirements

Why are automated tests worth the trouble?

Using CTest to standardize testing in CMake

Build-and-test mode

Test mode

Creating the most basic unit test for CTest

Structuring our projects for testing

Unit-testing frameworks

Catch2

GTest

GMock

Generating test coverage reports

Avoiding the SEGFAULT gotcha

Summary

Further reading

Chapter 9: Program Analysis Tools

Technical requirements

Enforcing the formatting

Using static checkers

Clang-Tidy

Cpplint

Cppcheck

include-what-you-use

Link what you use

Dynamic analysis with Valgrind

Memcheck

Memcheck-Cover

Summary

Further reading

Chapter 10: Generating Documentation

Technical requirements

Adding Doxygen to your project

Generating documentation with a modern look

Summary

Further reading

Other documentation generation utilities

Chapter 11: Installing and Packaging

Technical requirements

Exporting without installation

Installing projects on the system

Installing logical targets

Low-level installation

Invoking scripts during installation

Creating reusable packages

Understanding the issues with relocatable targets

Installing target export files

Writing basic config-files

Creating advanced config-files

Generating package version files

Defining components

How to use components in find_package()

How to use components in the install() command

Packaging with CPack

Summary

Further reading

Chapter 12: Creating Your Professional Project

Technical requirements

Planning our work

Project layout

Object libraries

Shared libraries versus static libraries

Project file structure

Building and managing dependencies

Building the Calc library

Building the Calc Console executable

Testing and program analysis

Preparing the coverage module

Preparing the Memcheck module

Applying testing scenarios

Adding static analysis tools

Installing and packaging

Installation of the library

Installation of the executable

Packaging with CPack

Providing the documentation

Automatic documentation generation

Not-as-technical documents of professional project

Summary

Further reading

Appendix: Miscellaneous Commands

The string() command

Search and replace

Manipulation

Comparison

Hashing

Generation

JSON

The list() command

Reading

Searching

Modification

Ordering

The file() command

Reading

Writing

Filesystem

Path conversion

Transfer

Locking

Archiving

The math() command

Why subscribe?

Other Books You May Enjoy

Preface

Creating top-notch software isn't an easy task. Developers researching this subject online frequently have problems determining which advice is up to date and which approaches have already been superseded by fresher, better practices. At the same time, most resources explain this process chaotically, without the proper background, context, and structure.

Modern CMake for C++ is an end-to-end guide offering a simpler experience, as it treats building C++ solutions in a comprehensive manner. It teaches you how to use CMake in your CMake projects, and also shows you what makes them maintainable, elegant, and clean. It guides you through the automation of complex tasks appearing in many projects, including building, testing, and packaging.

The book instructs you on how to form the source directories, as well as build targets and packages. As you progress, you will learn how to compile and link executables and libraries, how these processes work in detail, and how to optimize all steps to achieve the best results. You'll also understand how to add external dependencies to the project: third-party libraries, testing frameworks, program analysis tools, and documentation generators. Finally, you'll explore how to export, install, and package your solution for internal and external purposes.

After completing this book, you'll be able to use CMake confidently on a professional level.

Who this book is for

Learning the C++ language often isn't enough to prepare you for delivering projects to the highest standards. If you're interested in becoming a professional build engineer, a better software developer, or simply want to become proficient with CMake, if you'd like to understand how projects come together and why, if you're transitioning from a different build environment, or if you're interested in learning modern CMake from the ground up, then this book is for you.

What this book covers

Chapter 1, First Steps with CMake, covers how to install and use CMake's command line, along with what files make up the project.

Chapter 2, TheCMake Language, provides key code information: comments, command invocations and arguments, variables, lists, and control structures.

Chapter 3, Setting Up Your First CMake Project, introduces the basic configuration of a project, the required CMake version, project metadata, and file structure, as well as the toolchain setup.

Chapter 4, Working with Targets, introduces the logical build targets that produce artifacts for executables and libraries.

Chapter 5, Compiling C++ Sources with CMake, explains how the details of compilation process works and how it can be controlled in a CMake project.

Chapter 6, Linking with CMake, provides general information on linking, static, and shared libraries. This chapter also explains how to structure a project so that it can be tested.

Chapter 7, Managing Dependencies with CMake, explains the dependency management methods available in modern CMake.

Chapter 8, Testing Frameworks, describes how to add the most popular testing frameworks to your project, as well as how to use the CTest utility available in the CMake toolset.

Chapter 9, Program Analysis Tools, covers how to perform automatic formatting, as well as static and dynamic analyses, in your project.

Chapter 10, Generating Documentation, explains how to use Doxygen to generate manuals for users straight from the C++ source code.

Chapter 11, Installing and Packaging, shows how to prepare your project to be used in other projects or installed on the system. We'll also see an explanation of the CPack utility.

Chapter 12, Creating Your Professional Project, sets out how to put together all the knowledge you have acquired hitherto in to a fully formed project.

Appendix: Miscellaneous Commands, provides a quick reference of the most popular commands: string(), list(), file(), and math().

To get the most out of this book

Basic familiarity with C++ and Unix-like systems is assumed throughout the book. Although this isn't a strict requirement, it will prove helpful in fully understanding the examples given in this book.

This book targets CMake 3.20, but most of the techniques described should work from CMake 3.15 (features that were added after are usually highlighted).

All examples have been tested on Debian with the following packages installed:

clang-format clang-tidy cppcheck doxygen g++ gawk git graphviz lcov libpqxx-dev libprotobuf-dev make pkg-config protobuf-compiler tree valgrind vim wget

To experience the same environment, it is recommended to use the Docker images, as explained in Chapter 1.

If you are using the digital version of this book, we advise you to type the code yourself or access the code from the book's GitHub repository (a link is available in the next section). Doing so will help you avoid any potential errors related to the copying and pasting of code.

Download the example code files

You can download the example code files for this book from GitHub at https://github.com/PacktPublishing/Modern-CMake-for-Cpp. If there's an update to the code, it will be updated in the GitHub repository.

We also have other code bundles from our rich catalog of books and videos available at https://github.com/PacktPublishing/. Check them out!

Download the color images

We also provide a PDF file that has color images of the screenshots and diagrams used in this book. You can download it here: https://static.packt-cdn.com/downloads/9781801070058_ColorImages.pdf.

Conventions used

There are a number of text conventions used throughout this book.

Code in text: Indicates code words in the text, database table names, folder names, filenames, file extensions, pathnames, dummy URLs, user input, and Twitter handles. Here is an example: "Select Debug, Release, MinSizeRel, or RelWithDebInfo and specify it as follows."

A block of code is set as follows:

cmake_minimum_required(VERSION 3.20)

project(Hello)

add_executable(Hello hello.cpp)

When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold:

cmake_minimum_required(VERSION 3.20)

project(app)

message("Top level CMakeLists.txt")

add_subdirectory(api)

Any command-line input or output is written as follows:

cmake --build <dir> --parallel [<number-of-jobs>]

cmake --build <dir> -j [<number-of-jobs>]

Bold: Indicates a new term, an important word, or words that you see on screen. For instance, words in menus or dialog boxes appear in bold. Here is an example: "If all else fails and we need to use the big guns there is always trace mode."

Tips or Important Notes

Appear like this.

Get in touch

Feedback from our readers is always welcome.

General feedback: If you have questions about any aspect of this book, email us at [email protected] and mention the book title in the subject of your message.

Errata: Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you have found a mistake in this book, we would be grateful if you would report this to us. Please visit www.packtpub.com/support/errata and fill in the form.

Piracy: If you come across any illegal copies of our works in any form on the internet, we would be grateful if you would provide us with the location address or website name. Please contact us at [email protected] with a link to the material.

If you are interested in becoming an author: If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, please visit authors.packtpub.com.

Share Your Thoughts

Once you've read Modern CMake for C++, we'd love to hear your thoughts! Please click here to go straight to the Amazon review page for this book and share your feedback.

Your review is important to us and the tech community and will help us make sure we're delivering excellent quality content.

Download a free PDF copy of this book

Thanks for purchasing this book!

Do you like to read on the go but are unable to carry your print books everywhere?

Is your eBook purchase not compatible with the device of your choice?

Don’t worry, now with every Packt book you get a DRM-free PDF version of that book at no cost.

Read anywhere, any place, on any device. Search, copy, and paste code from your favorite technical books directly into your application.

The perks don’t stop there, you can get exclusive access to discounts, newsletters, and great free content in your inbox daily

Follow these simple steps to get the benefits:

Scan the QR code or visit the link below

https://packt.link/free-ebook/9781801070058

Submit your proof of purchaseThat’s it! We’ll send your free PDF and other benefits to your email directly

Section 1: Introducing CMake

Getting the basics right is critical to understanding the more advanced subjects and avoiding silly mistakes. This is where the majority of CMake users get in trouble: without a proper foundation, it's difficult to achieve the right outcome. No wonder. It's tempting to skip the introductory material and jump right in where the action is and get things done quickly. We address both points in this section by explaining the core topics of CMake and by hacking together a few lines of code to show what the simplest project looks like.

To build an appropriate mental context, we'll explain what CMake is exactly and how it does its job, along with what the command line is like. We'll talk about the different build stages and learn the language used to generate build systems. We'll also discuss CMake projects: what files they contain, how to approach their directory structure, and we'll explore their primary configuration.

This section comprises the following chapters:

Chapter 1, First Steps with CMakeChapter 2, The CMake LanguageChapter 3, Setting Up Your First CMake Project

Chapter 1: First Steps with CMake

There is something magical about turning source code into a working application. It is not only the effect itself, that is, a working mechanism that we devise and bring to life, but the very process or act of exercising the idea into existence.

As programmers, we work in the following loop: design, code, and test. We invent changes, we phrase them in a language that the compiler understands, and we check whether they work as intended. To create a proper, high-quality application from our source code, we need to meticulously execute repetitive, error-prone tasks: invoking the correct commands, checking the syntax, linking binary files, running tests, reporting issues, and more.

It takes great effort to remember each step every single time. Instead, we want to stay focused on the actual coding and delegate everything else to automated tooling. Ideally, this process would start with a single button, right after we have changed our code. It would be smart, fast, extensible, and work in the same way across different OSs and environments. It would be supported by multiple Integrated Development Environments (IDEs) but also by Continuous Integration (CI) pipelines that test our software after a change is submitted to a shared repository.

CMake is the answer to many such needs; however, it requires a bit of work to configure and use correctly. This is not because CMake is unnecessarily complex but because the subject that we're dealing with here is. Don't worry. We'll undergo this whole learning process very methodically; before you know it, you will have become a building guru.

I know you're eager to rush off to start writing your own CMake projects, and I applaud your attitude. Since your projects will be primarily for users (yourself included), it's important for you to understand that perspective as well.

So, let's start with just that: becoming a CMake power user. We'll go through a few basics: what this tool is, how it works in principle, and how to install it. Then, we'll do a deep dive on the command line and modes of operation. Finally, we'll wrap up with the purposes of different files in a project, and we'll explain how to use CMake without creating a project at all.

In this chapter, we're going to cover the following main topics:

Understanding the basicsInstalling CMake on different platformsMastering the command lineNavigating the project filesDiscovering scripts and modules

Technical requirements

You can find the code files that are present in this chapter on GitHub at https://github.com/PacktPublishing/Modern-CMake-for-Cpp/tree/main/examples/chapter01.

To build examples provided in this book always use recommended commands:

cmake -B <build tree> -S <source tree>

cmake --build <build tree>

Be sure to replace placeholders <build tree> and <source tree> with appropriate paths. As a reminder: build tree is the path to target/output directory, source tree is the path at which your source code is located.

Understanding the basics

The compilation of C++ source code appears to be a fairly straightforward process. Let's take a small program, such as a classic hello.cpp application, as follows:

chapter-01/01-hello/hello.cpp

#include <iostream>

int main() {

  std::cout << "Hello World!" << std::endl;

  return 0;

}

Now, all we need to do to get an executable is to run a single command. We call the compiler with the filename as an argument:

$ g++ hello.cpp -o a.out

Our code is correct, so the compiler will silently produce an executable binary file that our machine can understand. We can run it by calling its name:

$ ./a.out

Hello World!

$

However, as our projects grow, you will quickly understand that keeping everything in a single file is simply not possible. Clean code practices recommend that files should be kept small and in well-organized structures. The manual compilation of every file can be a tiresome and fragile process. There must be a better way.

What is CMake?

Let's say we automate building by writing a script that goes through our project tree and compiles everything. To avoid any unnecessary compilations, our script will detect whether the source has been modified since the last time we ran it (the script). Now, we'd like a convenient way to manage arguments that are passed to the compiler for each file – preferably, we'd like to do that based on configurable criteria. Additionally, our script should know how to link all of the compiled files in a binary or, even better, build whole solutions that can be reused and incorporated as modules in bigger projects.

The more features we will add the higher the chance that we will get to a full-fledged solution. Building software is a very versatile process and can span multiple different aspects:

Compiling executables and librariesManaging dependenciesTestingInstallingPackaging Producing documentationTesting some more

It would take a very long time to come up with a truly modular and powerful C++ building application that is fit for every purpose. And it did. Bill Hoffman at Kitware implemented the first versions of CMake over 20 years ago. As you might have already guessed, it was very successful. It now has a lot of features and support from the community. Today, CMake is being actively developed and has become the industry standard for C and C++ programmers.

The problem of building code in an automated way is much older than CMake, so naturally, there are plenty of options out there: Make, Autotools, SCons, Ninja, Premake, and more. But why does CMake have the upper hand?

There are a couple of things about CMake that I find (granted, subjectively) important:

It stays focused on supporting modern compilers and toolchains.CMake is truly cross-platform – it supports building for Windows, Linux, macOS, and Cygwin.It generates project files for popular IDEs: Microsoft Visual Studio, Xcode, and Eclipse CDT. Additionally, it is a project model for others such as CLion.CMake operates on just the right level of abstraction – it allows you to group files in reusable targets and projects.There are tons of projects that are built with CMake and offer an easy way to include them in your project.CMake views testing, packaging, and installing as an inherent part of the build process. Old, unused features get deprecated to keep CMake lean.

CMake provides a unified, streamlined experience across the board. It doesn't matter if you're building your software in an IDE or directly from the command line; what's really important is it takes care of post-build stages as well. Your Continous Integration/Continous Deployment (CI/CD) pipeline can easily use the same CMake configuration and build projects using a single standard even if all of the preceding environments differ.

How does it work?

You might be under the impression that CMake is a tool that reads source code on one end and produces binaries on the other – while that's true in principle, it's not the full picture.

CMake can't build anything on its own – it relies on other tools in the system to perform the actual compilation, linking, and other tasks. You can think of it as the orchestrator of your building process: it knows what steps need to be done, what the end goal is, and how to find the right workers and materials for the job.

This process has three stages:

ConfigurationGeneration Building

The configuration stage

This stage is about reading project details stored in a directory, called the source tree, and preparing an output directory or build tree for the generation stage.

CMake starts by creating an empty build tree and collecting all of the details about the environment it is working in, for example, the architecture, the available compilers, the linkers, and the archivers. Additionally, it checks whether a simple test program can be compiled correctly.

Next, the CMakeLists.txt project configuration file is parsed and executed (yes, CMake projects are configured with CMake's coding language). This file is the bare minimum of a CMake project (source files can be added later). It tells CMake about the project structure, its targets, and its dependencies (libraries and other CMake packages). During this process, CMake stores collected information in the build tree such as system details, project configurations, logs, and temp files, which are used for the next step. Specifically, a CMakeCache.txt file is created to store more stable variables (such as paths to compilers and other tools) and save time during the next configuration.

The generation stage

After reading the project configuration, CMake will generate a buildsystem for the exact environment it is working in. Buildsystems are simply cut-to-size configuration files for other build tools (for example, Makefiles for GNU Make or Ninja and IDE project files for Visual Studio). During this stage, CMake can still apply some final touches to the build configuration by evaluating generator expressions.

Note

The generation stage is executed automatically after the configuration stage. For this reason, this book and other resources often refer to both of these stages when mentioning "configuration" or "generation" of a buildsystem. To explicitly run just the configuration stage, you can use the cmake-gui utility.

The building stage

To produce the final artifacts specified in our project, we have to run the appropriate build tool. This can be invoked directly, through an IDE, or using the CMake command. In turn, these build tools will execute steps to produce targets with compilers, linkers, static and dynamic analysis tools, test frameworks, reporting tools, and anything else you can think of.

The beauty of this solution lies in the ability to produce buildsystems on demand for every platform with a single configuration (that is, the same project files):

Figure 1.1 – The stages of CMake

Do you remember our hello.cpp application from the Understanding the basics section? CMake makes it really easy for you to build it. All we need is the following CMakeLists.txt file next to our source and two simple commands, cmake -B buildtree and cmake --build buildtree, as follows:

chapter01/01-hello/CMakeLists.txt: Hello world in the CMake language

cmake_minimum_required(VERSION 3.20)

project(Hello)

add_executable(Hello hello.cpp)

Here is the output from the Dockerized Linux system (note that we'll discuss Docker in the Installing CMake on different platforms section):

root@5f81fe44c9bd:/root/examples/chapter01/01-hello# cmake -B buildtree.

-- The C compiler identification is GNU 9.3.0

-- The CXX compiler identification is GNU 9.3.0

-- Check for working C compiler: /usr/bin/cc

-- Check for working C compiler: /usr/bin/cc -- works

-- Detecting C compiler ABI info

-- Detecting C compiler ABI info - done

-- Detecting C compile features

-- Detecting C compile features - done

-- Check for working CXX compiler: /usr/bin/c++

-- Check for working CXX compiler: /usr/bin/c++ -- works

-- Detecting CXX compiler ABI info

-- Detecting CXX compiler ABI info - done

-- Detecting CXX compile features

-- Detecting CXX compile features - done

-- Configuring done

-- Generating done

-- Build files have been written to: /root/examples/chapter01/01-hello/buildtree

root@5f81fe44c9bd:/root/examples/chapter01/01-hello# cmake --build buildtree/

Scanning dependencies of target Hello

[ 50%] Building CXX object CMakeFiles/Hello.dir/hello.cpp.o

[100%] Linking CXX executable Hello

[100%] Built target Hello

All that's left is to run it:

root@68c249f65ce2:~# ./buildtree/Hello

Hello World!

Here, we have generated a buildsystem that is stored in the buildtree directory. Following this, we executed the build stage and produced a final binary that we were able to run.

Now you know what the end result looks like, I'm sure you will be full of questions: what are the prerequisites to this process? What do these commands mean? Why do we need two of them? How do I write my own project files? Do not worry – these questions will be answered in the following sections.

Getting Help

This book will provide you with the most important information that is relevant to the current version of CMake (at the time of writing, this is 3.20). To provide you with the best advice, I have explicitly avoided any deprecated and no longer recommended features. I highly recommend using, at the very least, version 3.15, which is considered "the Modern CMake." If you require more information, you can find the latest, complete documentation online at https://cmake.org/cmake/help/.

Installing CMake on different platforms

CMake is a cross-platform, open-source software written in C++. That means you can, of course, compile it yourself; however, the most likely scenario is that you won't have to. This is because precompiled binaries are available for you to download from the official web page at https://cmake.org/download/.

Unix-based systems provide ready-to-install packages directly from the command line.

Note

Remember that CMake doesn't come with compilers. If your system doesn't have them installed yet, you'll need to provide them before using CMake. Make sure to add the paths to their executables to the PATH environment variable so that CMake can find them.

To avoid solving tooling and dependency problems while learning from this book, I recommend choosing the first installation method: Docker.

Let's go through different environments on which CMake can be used.

Docker

Docker (https://www.docker.com/) is a cross-platform tool that provides OS-level virtualization, allowing applications to be shipped in complete packages, called containers. These are self-sufficient bundles that contain a piece of software with all of its libraries, dependencies, and tools required to run it. Docker executes its containers in lightweight environments that are isolated one from another.

This concept makes it extremely convenient to share whole toolchains, which are necessary for a given process, configured and ready to go. I can't stress enough how easy things become when you don't need to worry about minuscule environmental differences.

The Docker platform has a public repository of container images, https://registry.hub.docker.com/, that provides millions of ready-to-use images.

For your convenience, I have published two Docker repositories:

swidzinski/cmake:toolchain: This contains the curated tools and dependencies that are necessary to build with CMake.swidzinski/cmake:examples: This contains the preceding toolchain and all of the projects and examples from this book.

The first option is for readers who simply want a clean-slate image ready to build their own projects, and the second option is for hands-on practice with examples as we go through the chapters.

You can install Docker by following the instructions from its official documentation (please refer to docs.docker.com/get-docker). Then, execute the following commands in your Terminal to download the image and start the container:

$ docker pull swidzinski/cmake:examples

$ docker run -it swidzinski/cmake:examples

root@b55e271a85b2:root@b55e271a85b2:#

Note that all of the examples are available in the directories matching this format:/root/examples/examples/chapter-<N>/<M>-<title>.

Windows

Installing in Windows is straightforward – simply download the version for 32 or 64 bits. You can pick a portable ZIP or MSI package for Windows Installer.

With the ZIP package, you will have to add the CMake bin directory to the PATH environment variable so that you can use it in any directory without any such errors:

'cmake' is not recognized as an internal or external command, operable program or batch file.

If you prefer convenience, simply use the MSI installer:

Figure 1.2 – The installation wizard can set up the PATH environment variable for you

As I mentioned earlier, this is open-source software, so it is possible to build CMake yourself. However, first, you will have to get a binary copy of CMake on your system. So, why use other build tools if you have your own, right? This scenario is used by CMake contributors to generate newer versions.

On Windows, we also require a build tool that can finalize the build process started by CMake. A popular choice here is Visual Studio, for which the Community Edition is available for free from Microsoft's website: https://visualstudio.microsoft.com/downloads/.

Linux

Getting CMake on Linux is the same as getting any other popular package. Simply use your package manager from the command line. Packages are usually kept up to date with fairly recent versions. However, if you are after the latest version, you can download the installation script from the website:

The script for Linux x86_64

$ wget -O - https://github.com/Kitware/CMake/releases/download/v3.20.0/cmake-3.20.0-linux-x86_64.sh | bash

The script for Linux aarch64

$ wget -O - https://github.com/Kitware/CMake/releases/download/v3.20.0/cmake-3.20.0-Linux-aarch64.sh | bash

The package for Debian/Ubuntu

$ sudo apt-get install cmake

The package for Red Hat

$ yum install cmake

macOS

This platform is also strongly supported by CMake developers. The most popular choice of installation is through MacPorts:

$ sudo port install cmake

Alternatively, you can use Homebrew:

$ brew install cmake

Building from the source

If all else fails – or if you're on a special platform – download the source from the official website and compile it yourself:

$ wget https://github.com/Kitware/CMake/releases/download/v3.20.0/cmake-3.20.0.tar.gz

$ tar xzf cmake-3.20.0.tar.gz

$ cd cmake-3.20.0

$ ./bootstrap

$ make

$ make install

Building from source is relatively slow and requires more steps. However, by doing it this way, you're guaranteed to use the latest version of CMake. This is especially apparent when compared to packages that are available for Linux: the older the version of the system, the fewer updates it gets.

Now that we have our CMake readily installed, let's learn how to use it!

Mastering the command line

The majority of this book will teach you how to prepare CMake projects for your users. To cater to their needs, we need to thoroughly understand how users interact with CMake in different scenarios. This will allow you to test your project files and ensure they're working correctly.

CMake is a family of tools and consists of five executables:

cmake: This is the main executable that configures, generates, and builds projects.ctest: This is the test driver program used to run and report test results.cpack: This is the packaging program used to generate installers and source packages.cmake-gui: This is the graphical wrapper around cmake.ccmake: This is the console-based GUI wrapper around cmake.

CMake

This binary provides a few modes of operation (also called actions):

Generating a project buildsystemBuilding a projectInstalling a projectRunning a scriptRunning a command-line toolGetting help

Generating a project buildsystem

This is the first step required to build our project. Here are a few options in terms of how the CMake build action can be executed:

The syntax of the generation mode

cmake [<options>] -S <path-to-source> -B <path-to-build>

cmake [<options>] <path-to-source>

cmake [<options>] <path-to-existing-build>

We'll discuss these options in the upcoming sections. Right now, let's focus on choosing the right form of command. One important feature of CMake is the support for out-of-source builds or the production of artifacts in a separate directory. In contrast to tools such as GNU Make, this ensures the source directory is kept clean from any build-related files and avoids polluting our Version Control Systems (VCS) with unnecessary files or ignore directives. This is why it's best to use the first form of command of generation mode: specify the path to source tree with -S option followed by path to the directory of the produced buildsystem specified with -B:

cmake -S ./project -B ./build

The preceding command will generate a buildsystem in the ./build directory (or create it if it's missing) from the source in the ./project directory.

We can skip one of the arguments and cmake will "guess" that we intended to use the current directory for it. However, watch out. Skipping both will get you an in-source build, and that is messy.

Not Recommended

Do not use the second or third form of the cmake <directory> command. This is because it can produce a messy in-source build (we'll learn how to block that in Chapter 3, Setting Up Your First CMake Project). As hinted in the syntax snippet, the same command behaves differently if a previous build already exists in <directory>: it will use the cached path to the sources and rebuild from there. Since we often invoke the same commands from the Terminal command history, we might get into trouble here: before using this form, always check whether your shell is currently working in the right directory.

Examples

Build in the current directory, but take the source from one directory up (note that -S is optional):

cmake -S ..

Build in the ./build directory, and use a source from the current directory:

cmake -B build

Options for generators

As discussed earlier, you can specify a few options during the generation stage. Selecting and configuring a generator decides which build tool from our system will be used for building, what build files will look like, and what the structure of the build tree will be.

So, should you care? Luckily, the answer is often "no." CMake does support multiple native buildsystems on many platforms; however, unless you have a few of them installed at the same time, CMake will correctly select it for you. This can be overridden by the CMAKE_GENERATOR environment variable or by specifying the generator directly on the command line, such as in the following:

cmake -G <generator-name> <path-to-source>

Some generators (such as Visual Studio) support a more in-depth specification of a toolset (compiler) and platform (compiler or SDK). Additionally, these have respective environment variables that override the default values: CMAKE_GENERATOR_TOOLSET and CMAKE_GENERATOR_PLATFORM. We can specify them directly, as follows:

cmake -G <generator-name>

      -T <toolset-spec> -A <platform-name>

      <path-to-source>

Windows users usually want to generate a buildsystem for their favorite IDE. On Linux and macOS, it's very common to use Unix Makefiles or Ninja generators.

To check which generators are available on your system, use the following command:

cmake --help

At the end of the help printout, you should observe a full list like this one:

There are plenty of generators available on Windows 10

The following generators are available on this platform:

Visual Studio 16 2019

Visual Studio 15 2017 [arch]

Visual Studio 14 2015 [arch]

Visual Studio 12 2013 [arch]

Visual Studio 11 2012 [arch]

Visual Studio 10 2010 [arch]

Visual Studio 9 2008 [arch]

Borland Makefiles

NMake Makefiles

NMake Makefiles JOM

MSYS Makefiles

MinGW Makefiles

Green Hills MULTI

Unix Makefiles

Ninja

Ninja Multi-Config

Watcom Wmake

CodeBlocks - MinGW Makefiles

CodeBlocks - NMake Makefiles

CodeBlocks - NMake Makefiles JOM

CodeBlocks - Ninja

CodeBlocks - Unix Makefiles

CodeLite - MinGW Makefiles

CodeLite - NMake Makefiles

CodeLite - Ninja

CodeLite - Unix Makefiles

Eclipse CDT4 - NMake Makefiles

Eclipse CDT4 - MinGW Makefiles

Eclipse CDT4 - Ninja

Eclipse CDT4 - Unix Makefiles

Kate - MinGW Makefiles

Kate - NMake Makefiles

Kate - Ninja

Kate - Unix Makefiles

Sublime Text 2 - MinGW Makefiles

Sublime Text 2 - NMake Makefiles

Sublime Text 2 - Ninja

Sublime Text 2 - Unix Makefiles

Options for caching

CMake queries the system for all kinds of information during the configuration stage. This information is cached in CMakeCache.txt in the build tree directory. There are a few options that allow you to manage that file more conveniently.

The first thing that is at our disposal is the ability to prepopulate cached information:

cmake -C <initial-cache-script> <path-to-source>

We can provide a path to the CMake script, which (only) contains a list of set() commands to specify variables that will be used to initialize an empty build tree.

The initialization and modification of existing cache variables can be done in another way (for instance, when creating a file is a bit much to only set a few variables). You can simply set them in a command line, as follows:

cmake -D <var>[:<type>]=<value> <path-to-source>

The :<type> section is optional (it is used by GUIs); you can use BOOL, FILEPATH, PATH, STRING, or INTERNAL. If you omit the type, it will be set to the type of an already existing variable; otherwise, it will be set to UNINITIALIZED.

One particularly important variable contains the type of the build: for example, debug and release. Many CMake projects will read it on numerous occasions to decide things such as the verbosity of messages, the presence of debugging information, and the level of optimization for created artifacts.

For single-configuration generators (such as Make and Ninja), you'll need to specify it during the configuration phase with the CMAKE_BUILD_TYPE variable and generate a separate build tree for each type of config: Debug, Release, MinSizeRel, or RelWithDebInfo.

Here's an example:

cmake -S . -B build -D CMAKE_BUILD_TYPE=Release

Note that multi-configuration generators are configured during the build stage.

We can list cache variables with the -L option:

cmake -L[A][H] <path-to-source>

Such a list will contain cache variables that aren't marked as ADVANCED. We can change that by adding the A modifier. To print help messages with variables - add the H modifier.

Surprisingly, custom variables that are added manually with the -D option won't be visible unless you specify one of the supported types.

The removal of one or more variables can be done with the following option:

cmake -U <globbing_expr> <path-to-source>

Here, the globbing expression supports the * wildcard and any ? character symbols. Be careful when using these, as you might break things.

Both of the -U and -D options can be repeated multiple times.

Options for debugging and tracing

CMake can be run with a multitude of options that allow you to peek under the hood. To get general information about variables, commands, macros, and other settings, run the following:

cmake --system-information [file]

The optional file argument allows you to store the output in a file. Running it in the build tree directory will print additional information about the cache variables and build messages from the log files.

In our projects, we'll be using message() commands to report details of the build process. CMake filters the log output of these based on the current log level (by default, this is STATUS). The following line specifies the log level that we're interested in:

cmake --log-level=<level>

Here, level can be any of the following: ERROR, WARNING, NOTICE, STATUS, VERBOSE, DEBUG, or TRACE. You can specify this setting permanently in the CMAKE_MESSAGE_LOG_LEVEL cache variable.

Another interesting option allows you to display log context with each message() call. To debug very complex projects, the CMAKE_MESSAGE_CONTEXT variable can be used like a stack. Whenever your code enters a specific context, you can add a descriptive name to the stack and remove it when leaving. By doing this, our messages will be decorated with the current CMAKE_MESSAGE_CONTEXT variable like so:

[some.context.example] Debug message.

The option to enable this kind of log output is as follows:

cmake --log-context <path-to-source>

We'll discuss logging in more detail in Chapter 2, The CMake Language.

If all else fails – and we need to use the big guns – there is always trace mode. This will print every command with the filename and exact line number it is called from alongside its arguments. You can enable it as follows:

cmake --trace

Options for presets

As you might have gathered, there are many, many options that users can specify to generate a build tree from your project. When dealing with the build tree path, generator, cache, and environmental variable, it's easy to get confused or miss something. Developers can simplify how users interact with their projects and provide a CMakePresets.json file that specifies some defaults. To learn more, please refer to the Navigating the project files section.

To list all of the available presets, execute the following:

cmake --list-presets

You can use one of the available presets as follows:

cmake --preset=<preset>

These values override the system defaults and the environment. However, at the same time, they can be overridden with any arguments that are explicitly passed on the command line:

Figure 1.3 – How presets override CMakeCache.txt and the system environment variables

Building a project

After generating our build tree, we're ready for the next stage: running the builder tool. Not only does CMake know how to generate input files for many different builders, but it can also run them for you with arguments that are specific to our project.

Not Recommended

Many online sources recommend running GNU Make directly after the generation stage: make. This is a default generator for Linux and macOS, and it usually works. However, we prefer the method described in this section, as it is generator-independent and is supported across all platforms. As a result, we don't need to worry about the exact environment of every user of our application.

The syntax of the build mode

cmake --build <dir> [<options>] [-- <build-tool-options>]

In the majority of these cases, it is enough to simply provide the bare minimum to get a successful build:

cmake --build <dir>

CMake needs to know where the build tree is that we generated. This is the same path that we passed with the -B argument in the generation stage.

By providing a few options, CMake allows you to specify key build parameters that work for every builder. If you need to provide special arguments to your chosen, native builder, pass them at the end of the command after the -- token:

cmake --build <dir> -- <build-tool-options>

Options for parallel builds

By default, many build tools will use multiple concurrent processes to leverage modern processors and compile your sources in parallel. Builders know the structure of project dependencies, so they can simultaneously process steps that have their dependencies met to save users' time.

You might want to override that setting if you're building on a powerful machine (or to force a single-threaded build for debugging). Simply specify the number of jobs with either of the following options:

cmake --build <dir> --parallel [<number-of-jobs>]

cmake --build <dir> -j [<number-of-jobs>]

The alternative is to set it with the CMAKE_BUILD_PARALLEL_LEVEL environment variable. As usual, we can always use the preceding option to override the variable.

Options for target

We'll discuss targets in the second part of the book. For now, let's just say that every project is made up of one or more parts, called targets. Usually, we'll want to build all of them; however, on occasion, we might be interested in skipping some or explicitly building a target that was deliberately excluded from normal builds. We can do this as follows:

cmake --build <dir> --target <target1> -t <target2> ...

As you will observe, we can specify multiple targets by repeating the -t argument.

One target that isn't normally built is clean. This will remove all artifacts from the build directory. You can call it like this:

cmake --build <dir> -t clean

Additionally, CMake offers a convenient alias if you'd like to clean first and then implement a normal build:

cmake --build <dir> --clean-first

Options for multi-configuration generators

So, we already know a bit about generators: they come in different shapes and sizes. Some of them offer more features than others, and one of these features is the ability to build both Debug and Release build types in a single build tree.

Generators that support this feature include Ninja Multi-Config, Xcode, and Visual Studio. Every other generator is a single-configuration generator, and they require a separate build tree for that purpose.

Select Debug, Release, MinSizeRel, or RelWithDebInfo and specify it as follows:

cmake --build <dir> --config <cfg>

Otherwise, CMake will use Debug as the default.

Options for debugging

When things go bad, the first thing we should do is check the output messages. However, veteran developers know that printing all the details all of the time is confusing, so they often hide them by default. When we need to peek under the hood, we can ask for far more detailed logs by telling CMake to be verbose:

cmake --build <dir> --verbose

cmake --build <dir> -v

The same effect can be achieved by setting the CMAKE_VERBOSE_MAKEFILE cached variable.

Installing a project

When artifacts are built, users can install them on the system. Usually, this means copying files into the correct directories, installing libraries, or running some custom installation logic from a CMake script.

The syntax of the installation mode

cmake --install <dir> [<options>]

As with other modes of operation, CMake requires a path to a generated build tree:

cmake --install <dir>

Options for multi-configuration generators

Just like in the build stage, we can specify which build type we want to use for our installation (for more details, please refer to the Building a project section). The available types include Debug, Release, MinSizeRel, and RelWithDebInfo. The signature is as follows:

cmake --install <dir> --config <cfg>

Options for components

As a developer, you might choose to split your project into components that can be installed independently. We'll discuss the concept of components in further detail in Chapter 11, Installing and Packaging. For now, let's just assume they represent different parts of the solution. This might be something like application, docs, and extra-tools.

To install a single component, use the following option:

cmake --install <dir> --component <comp>

Options for permissions

If installation is carried on a Unix-like platform, you can specify default permissions for the installed directories, with the following option, using the format of u=rwx,g=rx,o=rx:

cmake --install <dir>

      --default-directory-permissions <permissions>

Options for the installation directory

We can prepend the installation path specified in the project configuration with a prefix of our choice (for example, when we have limited write access to some directories). The /usr/local path that is prefixed with /home/user becomes /home/user/usr/local. The signature for this option is as follows:

cmake --install <dir> --prefix <prefix>

Note that this won't work on Windows, as paths on this platform usually start with the drive letter.

Options for debugging

Similarly, to the build stage, we can also choose to view a detailed output of the installation stage. To do this, use any of the following:

cmake --build <dir> --verbose

cmake --build <dir> -v

The same effect can be achieved if the VERBOSE environment variable is set.

Running a script

CMake projects are configured using CMake's custom language. It's cross-platform, quite powerful, and already present. So, why not make it available for other tasks? Sure enough, you can write standalone scripts (we'll get to that at the end of this chapter).

CMake can run these scripts like so:

Syntax of the script mode

cmake [{-D <var>=<value>}...] -P <cmake-script-file>

      [-- <unparsed-options>...]

Running such a script won't run any configurations or generate stages. Additionally, it won't affect the cache. There are two ways you can pass values to this script:

Through variables defined with the -D option. Through arguments that can be passed after a -- token. CMake will create CMAKE_ARGV<n> variables for all arguments passed to the script (including the -- token).

Running a command-line tool

On rare occasions, we might need to run a single command in a platform-independent way – perhaps copy a file or compute a checksum. Not all platforms were created equal, so not all commands are available in every system, or they have a different name.

CMake offers a mode in which to execute the most common ones in the same way across platforms:

The syntax of the command-line tool mode

cmake -E <command> [<options>]

As the use of this particular mode is fairly limited, we won't cover it in depth. However, if you're interested in the details, I recommend calling cmake -E to list all the available commands. To simply get a glimpse of what's on offer, CMake 3.20 supports the following commands:

capabilities, cat, chdir, compare_files, copy, copy_directory, copy_if_different, echo, echo_append, env, environment, make_directory, md5sum, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, remove, remove_directory, rename, rm, server, sleep, tar, time, touch, touch_nocreate, create_symlink, create_hardlink, true, and false.

If a command you'd like to use is missing, or you need a more complex behavior, consider wrapping it in a script and running it in -P mode.

Getting help

It comes without surprise that CMake offers extensive help that is accessible through its command line.

The syntax of the help mode

cmake ––help[-<topic>]

CTest

Automated testing is very important in order to produce and maintain high-quality code. That's why we devoted an entire chapter to this subject (please refer to Chapter 8, Testing Frameworks), where we do a deep dive into the usage of CTest. It is one of the available command-line tools, so let's briefly introduce it now.

CTest is about wrapping CMake in a higher layer of abstraction, where the building stage becomes just one of the stepping stones in the process of developing our software. Other tasks that CMake can do for us include updating, running all kinds of tests, reporting the state of the project to external dashboards, and running scripts written in the CMake language.

More importantly, CTest standardizes running tests and reporting for solutions built with CMake. This means that as a user, you don't need to know which testing framework the project is using or how to run it. CTest provides a convenient façade to list, filter, shuffle, retry, and timebox test runs. Additionally, it can call CMake for you if a build is required.

The simplest way to run tests for a built project is to call ctest in the generated build tree:

$ ctest

Test project C:/Users/rapha/Desktop/CMake/build

Guessing configuration Debug

    Start 1: SystemInformationNew

1/1 Test #1: SystemInformationNew .........   Passed 3.19 sec

100% tests passed, 0 tests failed out of 1

Total Test time (real) =   3.24 sec

CPack

After we have built and tested our amazing software, we are ready to share it with the world. In a rare few instances, power users are completely fine with the source code, and that's what they want. However, the vast majority of the world is using precompiled binaries because of convenience and to save time.

CMake doesn't leave you stranded here; it comes with batteries included. CPack is built for the exact purpose of creating packages for different platforms: compressed archives, executable installers, wizards, NuGet packages, macOS bundles, DMG packages, RPMs, and more.

CPack works in a very similar way to CMake: it is configured with the CMake language and has many package generators to pick from (just don't confuse them with CMake buildsystem generators). We'll go through all the specific details in Chapter 11, Installing and Packaging, as this is quite a hefty tool that is meant for the final stages of CMake projects.

The CMake GUI

CMake for Windows comes with a GUI version to configure the building process of previously prepared projects. For Unix-like platforms, there is a version built with QT libraries. Ubuntu offers it in the cmake-qt-gui package.

To access the CMake GUI, run the cmake-gui executable:

Figure 1.4 – The CMake GUI – the configuring stage for a buildsystem using a generator for Visual Studio 2019

The GUI application is a convenient tool for users of your application, as the options found there are rather limited. It can be useful for those who aren't familiar with the command line and would prefer a window-based interface.

Not Recommended

I would definitely recommend GUI to end users craving convenience; however, as a programmer, I avoid introducing any manual, blocking steps that would require clicking on forms every time I build my programs. This is especially important for build automation in CI pipelines. These tools require headless applications so that the build can be fully executed without any user interaction.

CCMake

The ccmake executable is the CMake curses interface for Unix-like platforms (it's unavailable for Windows). It's not available as part of the CMake package, so users have to install it separately.

The command for Debian/Ubuntu systems is as follows:

$ sudo apt-get install cmake-curses-gui

Note that the project configuration settings can be specified interactively through this GUI. Brief instructions are provided at the bottom of the Terminal when the program is running:

The syntax of the CCMake command

ccmake [<options>]

ccmake {<path-to-source> | <path-to-existing-build>}

CCMake uses the same set of options as cmake:

Figure 1.5 – The configuring stage in ccmake

As with Graphical User Interfaces (GUIs), this mode is fairly limited and is intended to be used by less experienced users. If you're using a Unix machine, I recommend that you take a quick look and move on even quicker.

This concludes the basic introduction to command line of CMake. It's time to discover what is the structure of a typical CMake project.

Navigating the project files

CMake uses quite a few files to manage its projects. Let's attempt to get a general idea of what each file does before tinkering with the contents. It's important to realize, that even though a file contains CMake language commands, it's not certain that it's meant for developers to edit. Some files are generated to be used by subsequent tools, and any changes made to those files will be written over at some stage. Other files are meant for advanced users to adjust your project to their individual needs. Finally, there are some temporary files that provide valuable information in specific contexts. This section will also specify which of them should be in the ignore file of your version control system.

The source tree

This is the directory where your project will live (it is also called the project root). It contains all of the C++ sources and CMake project files.

Here are the key takeaways of this directory:

It is required that you provide a CMakeLists.txt configuration file in its top directory.It should be managed with a VCS such as git. The path to this directory is given by the user with a -S argument of the cmake command.Avoid hardcoding any absolute paths to the source tree in your CMake code – users of your software can store the project under a different path.

The build tree

CMake uses this directory to store everything that gets generated during the build: the artifacts of the project, the transient configuration, the cache, the build logs, and anything that your native build tool will create. Alternative names for this directory include build root and binary tree.

Here are the key takeaways of this directory:

Your binary files will be created here, such as executables and libraries, along with object files and archives used for final linking.Don't add this directory to your VCS – it's specific to your system. If you decide to put it inside the source tree, make sure to add it to the VCS ignore file.CMake recommends out-of-source builds or builds that produce artifacts in a directory that is separate from all source files. This way, we can avoid polluting our project's source tree with temporary, system-specific files (or in-source builds).It is specified with -B or as a last argument to the cmake command if you have provided a path to the source, for example, cmake -S ../project ./.It's recommended that your projects include an installation stage that allows you to put the final artifacts in the correct place in the system, so all temporary files used for building can be removed.

Listfiles

Files that contain the CMake language are called listfiles and can be included one in another, by calling include() and find_package(), or indirectly with add_subdirectory():

CMake doesn't enforce consistent naming for these files, but usually, they have a .cmake extension.