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.

Related Content you might be interested in

Current Title:

Small book image
CMake Cookbook
Radovan Bast | Roberto Di Remigio
Sep, 2018 | 606 pages
Small book image
CMake Best Practices
Dominik Berner | Mustafa Kemal Gilor
May, 2022 | 406 pages
Small book image
Modern CMake for C++
Rafał Świdziński
Feb, 2022 | 460 pages
Table of Contents (18 chapters)
Preface
Preface
Who this book is for
What this book covers
To get the most out of this book
Additional reading resources
Get in touch
Free Chapter
1
Setting up Your System
Setting up Your System
Obtaining the code
Docker image
Installing prerequisite software
Testing the recipes
Reporting problems and suggesting improvements
2
From a Simple Executable to Libraries
From a Simple Executable to Libraries
Introduction
Compiling a single source file into an executable
Switching generators
Building and linking static and shared libraries
Controlling compilation with conditionals
Presenting options to the user
Specifying the compiler
Switching the build type
Controlling compiler flags
Setting the standard for the language
Using control flow constructs
3
Detecting the Environment
Detecting the Environment
Introduction
Discovering the operating system
Dealing with platform-dependent source code
Dealing with compiler-dependent source code
Discovering the host processor architecture
Discovering the host processor instruction set
Enabling vectorization for the Eigen library
4
Detecting External Libraries and Programs
Detecting External Libraries and Programs
Introduction
Detecting the Python interpreter
Detecting the Python library
Detecting Python modules and packages
Detecting the BLAS and LAPACK math libraries
Detecting the OpenMP parallel environment
Detecting the MPI parallel environment
Detecting the Eigen library
Detecting the Boost libraries
Detecting external libraries: I. Using pkg-config
Detecting external libraries: II. Writing a find-module
5
Creating and Running Tests
Creating and Running Tests
Introduction
Creating a simple unit test
Defining a unit test using the Catch2 library
Defining a unit test and linking against Google Test
Defining a unit test and linking against Boost test
Using dynamic analysis to detect memory defects
Testing expected failures
Using timeouts for long tests
Running tests in parallel
Running a subset of tests
Using test fixtures
6
Configure-time and Build-time Operations
Configure-time and Build-time Operations
Introduction
Using platform-independent file operations
Running a custom command at configure time
Running a custom command at build time: I. Using add_custom_command
Running a custom command at build time: II. Using add_custom_target
Running custom commands for specific targets at build time
Probing compilation and linking
Probing compiler flags
Probing execution
Fine-tuning configuration and compilation with generator expressions
7
Generating Source Code
Generating Source Code
Introduction
Generating sources at configure time
Generating source code at configure time using Python
Generating source code at build time using Python
Recording the project version information for reproducibility
Recording the project version from a file
Recording the Git hash at configure time
Recording the Git hash at build time
8
Structuring Projects
Structuring Projects
Introduction
Code reuse with functions and macros
Splitting CMake sources into modules
Writing a function to test and set compiler flags
Defining a function or macro with named arguments
Redefining functions and macros
Deprecating functions, macros, and variables
Limiting scope with add_subdirectory
Avoiding global variables using target_sources
Organizing Fortran projects
9
The Superbuild Pattern
The Superbuild Pattern
Introduction
Using the superbuild pattern
Managing dependencies with a superbuild: I. The Boost libraries
Managing dependencies with a superbuild: II. The FFTW library
Managing dependencies with a superbuild: III. The Google Test framework
Managing your project as a superbuild
10
Mixed-language Projects
Mixed-language Projects
Introduction
Building Fortran projects that use C/C++ libraries
Building C/C++ projects that use Fortran libraries
Building C++ and Python projects using Cython
Building C++ and Python projects using Boost.Python
Building C++ and Python projects using pybind11
Mixing C, C++, Fortran, and Python using Python CFFI
11
Writing an Installer
Writing an Installer
Introduction
Installing your project
Generating export headers
Exporting your targets
Installing a superbuild
12
Packaging Projects
Packaging Projects
Introduction
Generating source and binary packages
Distributing a C++/Python project built with CMake/pybind11 via PyPI
Distributing a C/Fortran/Python project build with CMake/CFFI via PyPI
Distributing a simple project as Conda package
Distributing a project with dependencies as Conda package
13
Building Documentation
Building Documentation
Introduction
Building documentation using Doxygen
Building documentation using Sphinx
Combining Doxygen and Sphinx
14
Alternative Generators and Cross-compilation
Alternative Generators and Cross-compilation
Introduction
Building a CMake project using Visual Studio 2017
Cross-compiling a hello world example
Cross-compiling a Windows binary with OpenMP parallelization
15
Testing Dashboards
Testing Dashboards
Introduction
Deploying tests to the CDash dashboard
Reporting test coverage to the CDash dashboard
Using the AddressSanitizer and reporting memory defects to CDash
Using the ThreadSanitizer and reporting data races to CDash
16
Porting a Project to CMake
Porting a Project to CMake
Where to start
Generating files and writing platform checks
Detecting required dependencies and linking
Reproducing compiler flags
Porting tests
Porting install targets
Further steps
Summary and common pitfalls when converting projects to CMake
17
Other Books You May Enjoy
Other Books You May Enjoy
Leave a review - let other readers know what you think

Obtaining the code

The source code for the recipes in this book is available on GitHub, at https://github.com/dev-cafe/cmake-cookbook. The code is licensed under the standard open source MIT license: this is a permissive software license, and you can reuse and remix the code in whatever way you see fit, as long as the original copyright and license notice are included in any copies of the software/source. The full text of the license is available at https://opensource.org/licenses/MIT.

In order to test the recipes by yourself, you will need a working installation of Git, obtained as follows:

  • All major GNU/Linux distributions offer Git prepackaged, via their package managers. If that is not your case, a binary distribution can be downloaded from the Git project website at https://git-scm.com.
  • On macOS, it is possible to use Homebrew or MacPorts to install Git.
  • On Windows, you can download the Git executable from the Git project website at https://git-scm.com.

Alternatively, you can access the examples with the GitHub desktop client at https://desktop.github.com.

Yet another alternative is to download and extract the ZIP file from https://github.com/dev-cafe/cmake-cookbook.

Once you have Git installed, you can clone the repository to your local machine, as follows:

$ git clone https://github.com/dev-cafe/cmake-cookbook.git

This will create a folder named cmake-cookbook. The book and the repository are organized in chapters and recipes. The numbering of chapters and the order of recipes in the repository reflect the order in the text. Each recipe is further organized into example folders. Some of the recipes have more than one example, usually when similar CMake concepts are illustrated in different programming languages.

The recipes are tested on GNU/Linux, macOS, and Windows, using state-of-the-art continuous integration services. We will discuss the testing set up shortly.

We have tagged the precise versions that correspond to the examples printed in this book with the tag v1.0. For maximum overlap with the book text, you can fetch this particular version as follows:

$ git clone --single-branch -b v1.0 https://github.com/dev-cafe/cmake-cookbook.git

We expect to receive bug fixes and the GitHub repository to evolve. To get the latest updates, you may prefer to follow the master branch of the repository, instead.

Previous Section
End of Section 2
Next Section