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
No titles found
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

Testing the recipes

The recipes are tested on state-of-the-art continuous integration (CI) services: Travis (https://travis-ci.org) for GNU/Linux and macOS, Appveyor (https://www.appveyor.com) for Windows, and CircleCI (https://circleci.com) for additional GNU/Linux testing with commercial compilers. The configuration files for the CI services can be found in the repository (https://github.com/dev-cafe/cmake-cookbook/): .travis.yml for Travis, .appveyor.yml for Appveyor, and .circleci/config.yml for CircleCI. Additional installation scripts for Travis and Appveyor can be found in the folder testing/dependencies.

We test the recipes with CMake 3.5.2 and CMake 3.12.1 on the Travis GNU/Linux infrastructure. CMake 3.12.1 is used on the Travis macOS infrastructure. On Appveyor, testing uses CMake 3.11.3. On Circle, CMake 3.12.1 is used.

The testing machinery is a set of Python scripts that are also contained in the testing folder. The script collect_tests.py will run tests and report their statuses. Recipes can be tested in isolation, or in batches; collect_tests.py accepts a regular expression as command-line input, for example:

$ pipenv run python testing/collect_tests.py 'chapter-0[1,7]/recipe-0[1,2,5]'

This command will run tests for Recipes 1, 2, and 5, in Chapters 1 and 7. A sample of the output looks as follows:

To get more verbose output, set VERBOSE_OUTPUT=ON:

$ env VERBOSE_OUTPUT=ON pipenv run python testing/collect_tests.py 'chapter-*/recipe-*'
Previous Section
End of Section 5
Next Section