Cmake
What this book covers
we have written this book as a progressive sequence of task and recipes. at each point, we introduce enough information about Cmake to show how to achiev 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 poerationg system, 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 proejcts
-
Know where and how to tweak CMake configuration files written by domebody else
-
Package proejcts for distribution
-
Port projects to Cmake
The workflow of a project managaed by Cmake happens in a bumber of stages,
which we refer to as tomes.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 CmakeList.txt files in your project and configure it.
-
Generation time: Upon successful configuration, Cmake will ghenerate the scripts needed by the native build tools to perform subsquent 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:
charter 1, from a simple Executable to libraries, shwos how to get started configuring and building simple executables and lubraries with Cmake.
Chater 2 , Detecting the Environment, explains how to interact with the operationg system and proccesor architecture using simple Cmake commands
Chapter 3, Detecting External Libraries and Programs, sohws how Cmake can simplify the detection of dependencies for your project
Charter 4, Creating and Running Tests, explains how to harness the power of Cmake and Ctest to define andrun tests.
Chater 5, Configure-time and Build-time Operations, shows how to perform custom operations at different stages of the build process with cross-playform Cmake commands.
Chapter 6, Generating SOurce code, discusses Cmake commands to automatically generate source code.
Chapter 7, Structuing POroejcts,shows powerful Cmake syntax for organizing your projects to make them more maintainable.
Charter 8, The Superbuild pattern, explains the powerful Cmake superbuild pattern for managing critical project dependencies with control over side effects.
Chapter 9, Mixed-laguage proejcts, 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 proejcts with the cross-plaform 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, Buiding Documentation , shows how to use Cmake to also build the documentation for you
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 Cmake-based build system.
To get the most out of this book
THis is a book written by programmers, for programmers, we have assumed basic knowledge and familiarity with the following:
-
the command line for you favorite operating system
-
Native tools for building software on your favorite operating system
-
The compuled languages c++, c or fortran and the corresponding compulers on youyr favorite operating system
-
the pytohn programming language
Conventions used
There are a number of text convertions used throughout this book.
COdeIntext: indicates code commands in text, folder names, filenames, module names, and target names.
a block of code is set as follows:
1
2
3
cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
proejct(recipe-01 LANGUAGES CXX)
add_executable(hello-world.cpp)
Any command-l;ine input wrtten in bold and contains a $ prompt in front of the command to type
1
2
3
$ mkdir -p build
$ cd build
$ cmake ..
to distinguish command-line input and output, we kkep output non-bold:
1
2
$ ./hello-world
Hello World!
