Book Image

CMake Cookbook

By : Radovan Bast, Roberto Di Remigio
Book Image

CMake Cookbook

By: Radovan Bast, Roberto Di Remigio

Overview of this book

CMake is cross-platform, open-source software for managing the build process in a portable fashion. This book features a collection of recipes and building blocks with tips and techniques for working with CMake, CTest, CPack, and CDash. CMake Cookbook includes real-world examples in the form of recipes that cover different ways to structure, configure, build, and test small- to large-scale code projects. You will learn to use CMake's command-line tools and master modern CMake practices for configuring, building, and testing binaries and libraries. With this book, you will be able to work with external libraries and structure your own projects in a modular and reusable way. You will be well-equipped to generate native build scripts for Linux, MacOS, and Windows, simplify and refactor projects using CMake, and port projects to CMake.
Table of Contents (18 chapters)

What this book covers

We have written this book as a progressive sequence of tasks and recipes. At each point, we introduce enough information about CMake to show how to achieve our goals, without overwhelming you with details. By the end of the book, you will be able to tackle increasingly complex operations and leverage the contents of the recipes in your own real-world projects with confidence.

We will cover these topics:

  • Configure, build, test, and install code projects using CMake
  • Detect operating systems, processors, libraries, files, and programs for conditional compilation
  • Increase the portability of your code
  • Refactor a large code base into modules with the help of CMake
  • Build multi-language projects
  • Know where and how to tweak CMake configuration files written by somebody else
  • Package projects for distribution
  • Port projects to CMake

The workflow of a project managed by CMake happens in a number of stages, which we refer to as times. These can be summarized neatly in the following figure:

  • CMake time or configure time. This is when CMake is running. In this phase CMake will process the CMakeLists.txt files in your project and configure it.
  • Generation time. Upon successful configuration, CMake will generate the scripts needed by the native build tools to perform subsequent steps in the project.
  • Build time. This is when the native build tools are invoked on the platform- and tool-native build scripts previously generated by CMake. At this point, the compiler will be invoked and the targets (executables and libraries) will be built in a specific build directory. Note the recursive CMake-time arrow: this can seem baffling, but it is a mechanism we will use many times throughout the book to achieve a truly platform-independent build.
  • CTest time or test time. This is when we run the test suite of the project to check whether the targets perform as intended.
  • CDash time or report time. This is when the results of testing the project are uploaded to a dashboard to be shared with other developers.
  • Install time. This is when the project's targets, source files, executables, and libraries are installed from the build directory to an install location.
  • CPack time or packaging time. This is when we package our project for distribution, either as source code or binary.
  • Package install time. This is when the newly minted package is installed system-wide.

This book is organized as follows:

Chapter 1, From a Simple Executable to Libraries, shows how to get started configuring and building simple executables and libraries with CMake.

Chapter 2, Detecting the Environment, explains how to interact with the operating system and processor architecture using simple CMake commands.

Chapter 3, Detecting External Libraries and Programs, shows how CMake can simplify the detection of dependencies for your project.

Chapter 4, Creating and Running Tests, explains how to harness the power of CMake and CTest to define and run tests.

Chapter 5, Configure-time and Build-time Operations, shows how to perform custom operations at different stages of the build process with cross-platform CMake commands.

Chapter 6, Generating Source Code, discusses CMake commands to automatically generate source code.

Chapter 7, Structuring Projects, shows powerful CMake syntax for organizing your projects to make them more maintainable.

Chapter 8, The Superbuild Pattern, explains the powerful CMake superbuild pattern for managing critical project dependencies with control over side effects.

Chapter 9, Mixed-language Projects, shows how to build projects mixing different programming languages with the help of CMake.

Chapter 10, Writing an Installer, takes care of the installation of projects with the cross-platform power of CMake.

Chapter 11, Packaging Projects, shows how to use CPack to produce source and platform-native source archives and how to build Python and Conda packages for distribution.

Chapter 12, Building Documentation, shows how to use CMake to also build the documentation for your code.

Chapter 13, Alternative Generators and Cross-compilation, shows how to use CMake to cross-compile projects between platforms.

Chapter 14, Testing Dashboards, shows how to report the results of tests to an online dashboard.

Chapter 15, Porting a Project to CMake, shows best practices, tips, and tricks that will help you port a project to a CMake-based build system.