packtpublishing/cmake-best-practices

CMake Best Practices, by Packt Publishing

CMake Best Practices

This is the code repository for CMake Best Practices , published by Packt.

Discover proven techniques for creating and maintaining programming projects with CMake

What is this book about?

This book is a collection of some excellent techniques that will help you to make the best use of CMake. It shows you how to integrate various development tools into your CMake workflow and covers field-proven best practices for using CMake effectively even in large, complex settings.

This book covers the following exciting features:

• Get to grips with architecting a well-structured CMake project
• Modularize and reuse CMake code across projects
• Integrate various tools for static analysis, linting, formatting, and documentation into a CMake project
• Get hands-on with performing cross-platform builds
• Get started with crafting a well-defined and portable build environment for your project

If you feel this book is for you, get your copy today!

Instructions and Navigations

All of the code is organized into folders. For example, Chapter02.

The code will look like the following:

include(GNUInstallDirs)
install(DIRECTORY dir1 DESTINATION ${CMAKE_INSTALL
  _LOCALSTATEDIR} FILES_MATCHING PATTERN "*.x")
install(DIRECTORY dir2 DESTINATION ${CMAKE_INSTALL
  _LOCALSTATEDIR}
  FILES_MATCHING PATTERN "*.hpp" EXCLUDE PATTERN "*")
install(DIRECTORY dir3 DESTINATION ${CMAKE_INSTALL
  _LOCALSTATEDIR} PATTERN "bin" EXCLUDE)

Following is what you need for this book: This book is for software engineers and build system maintainers working with C or C++ on a regular basis and trying to use CMake to better effect for their everyday tasks. Basic C++ and general programming knowledge will help you to better understand the examples covered in the book.

With the following software and hardware list you can run all code files present in the book (Chapter 1-15).

Software and Hardware List

Chapter	Software required	OS required
1	CMake 3.21	Windows, Mac OS X, and Linux (Any)
1	GCC,Clang or MSVC	Windows, Mac OS X, and Linux (Any)
1	Git	Windows, Mac OS X, and Linux (Any)

We also provide a PDF file that has color images of the screenshots/diagrams used in this book. Click here to download it.

Related products

• AWS Penetration Testing [Packt] [Amazon]

• Free eBook - Learn Kali Linux 2019 [Packt] [Amazon]

Errata

• Page 107 (last line): make -build ./build cmake -install ./build --prefix /tmp/install-test should be make --build ./build cmake --install ./build --prefix /tmp/install-test

Get to Know the Author

Dominik Berner is a software engineer, blogger and conference speaker with 20 years of professional software development under his belt. He codes mainly in C++ and has worked on many software projects, from writing bleeding edge software for surgical simulators in a startup, over maintaining large legacy platforms for large corporations in the MedTech industry to creating IoT solutions for companies in between. He beliefs that well designed and maintained build environments are one of the key elements to enable teams to write software efficiently and excel at creating quality software. When he is not writing code, he occasionally writes articles for his blog or speaks at conferences about software development.

Mustafa Kemal is an experienced professional working in performance-critical software development for the telecommunication, defense industries, and open-source software. His expertise is in high-performance and scalable software design, network technologies, DevOps, and software architecture. His interest in computers emerged very early on in his childhood. He learned programming to hack MMORPG games at around the age of 12, and he has been writing software ever since. His favorite programming language is C++, and he enjoys doing framework design & system programming. He is also a strong advocate of CMake; he maintained many codebases and ported many legacy projects to CMake throughout his career.

Download a free PDF

If you have already purchased a print or Kindle version of this book, you can get a DRM-free PDF version at no cost.
Simply click on the link to claim your free PDF.

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

cmake-best-practices's Issues

Chapter references in book differ from repository

Got my hands on a sample of first chapter. In going through code given, there are noticeable differences in how book refers to chapter code in git repository and existing git repository.

For example, on page 7 is the section Building your first project, which walks user through the basic of CMake usage. The book sample I saw showed chapter code as chapter_1. However, repository uses chapter01.

Also of note is that there are two references to chapter 13 code in repository (both chapter_13 and chapter13). Unknown which reference is used in book.

Lack of consistency detracts from reading.

Variable quoting

cmake-language(7):

Unquoted argument content consists of all text in a contiguous block of allowed or escaped characters. Both Escape Sequences and Variable References are evaluated. The resulting value is divided in the same way Lists divide into elements. Each non-empty element is given to the command invocation as an argument. Therefore an unquoted argument may be given to a command invocation as zero or more arguments.

Emphasis mine. Here is a sort of related bugfix from CMake itself Kitware/CMake@49a5dbc

It's important to always quote arguments that have variable substitution in them, so the receiving function always sees them as a single argument.
Having unquoted variable substitutions be left explicitly for cases where list expansion is intentional makes that very clear.

# command() always gets a single argument
command("${var}")
# command() may see zero or more arguments
command(${var})

I'm making use of this to define project includes as SYSTEM only when vendored and only when requested. Example declaration and usage.

Hardcoded details

I see more and more variables that really ought to be moved out from the CML files. Historically, the developer had no real choice for making this convenient and required additional scripts, however with presets (especially v3) the developer can now nicely bundle variables in a way that makes them easy to use with just CMake. As an example, the config option could be neatly moved out and with the preset you can also ensure that the right generator is used:

{
  "version": 1,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 21,
    "patch": 0
  },
  "configurePresets": [
    {
      "name": "config",
      "hidden": true,
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug"
      }
    },
    {
      "name": "dev-unix",
      "description": "Configure the project on *nix using Unix Make in Debug mode",
      "inherits": "config",
      "generator": "Unix Makefiles",
      "binaryDir": "${sourceDir}/build/unix"
    },
    {
      "name": "dev-win",
      "description": "Configure the project on Windows using NMake in Debug mode",
      "inherits": "config",
      "generator": "NMake Makefiles",
      "binaryDir": "${sourceDir}/build/win"
    }
  ]
}

Then the book may instruct the readers to invoke the preset that matches their operating system.

might be good content but very bad explanation

No basic minimum command explanation is clearly given.
cmake -S . -B ./build
cmake -build ./build
cmake -install ./build -prefix /tmp/install-test
Those commands firstly appears far at p.107 (so far from the 1st page).

Also install commands are described., but not 'uninstall' commands.
How to uninstall when after following this tutorial example ?
Many library is installed and stay ? Nothing explanation. With great care, I can not install without knowing installing effect and uninstalling commands.

Subdirectories should be standalone

As an example, Chapter 1's lists file should contain a call to cmake_minimum_required, so it is buildable on its own.

Usage of target_sources

I have noticed that the code in this repo uses target_sources instead of directly listing the cpp files in the target creation command.
What is the reason for this? If you were to not use target_sources, then you could spare the reader from having to pay attention to another command from the get go and listing cpp files in the add_* calls is equivalent in behavior.

One good usecase for this command is when you have sources files that you want to conditionally compile.

Don't read CMAKE_BUILD_TYPE on multi-config generators

This code won't do what you expect on Ninja Multi-Config or Visual Studio. Using message() without STATUS prints to stderr, rather than stdout, which some CI systems could consider an error.

https://github.com/PacktPublishing/CMake-Tips-and-Tricks/blob/fb5a8f56ed153f874aa66f88cfeb97efd02b1efd/CMakeLists.txt#L25-L31

Since the minimum required version is 3.21, I would recommend simply replacing this with the following:

set(CMAKE_BUILD_TYPE "Debug"
    CACHE STRING "Build configuration for single-config generators")

With CMP0126 enabled, this will honor a normal variable set by a parent project. It will never overwrite a user-defined cache variable. Thus, the if() check is unnecessary.

If you still want to print the message, then you can guard the message with a check that the generator is single-config:

get_property(isMultiConfig GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
if (NOT isMultiConfig)
  message(STATUS "Current build type ${CMAKE_BUILD_TYPE}")
endif ()

Chapter 2 should contain minimal code

https://github.com/PacktPublishing/CMake-Tips-and-Tricks/blob/fb5a8f56ed153f874aa66f88cfeb97efd02b1efd/chapter_2/CMakeLists.txt#L17-L23

CMake has a better way to declare a standard requirement, which is compile features. This also propagates in the properties, which ensures that consuming a project's install interface will correctly set the standard when using find_package(). Not having this hardcoded also allows a project with conditionally compiled code to test each standard it supports. Configuring with cmake --preset=dev -D CMAKE_CXX_STANDARD=XX allows to substitue XX and to trivially create a matrix build in the CI that tests each standard. This also makes a project packageable, since the standard flag contributes to the ABI of the build artifacts.

https://github.com/PacktPublishing/CMake-Tips-and-Tricks/blob/fb5a8f56ed153f874aa66f88cfeb97efd02b1efd/chapter_2/CMakeLists.txt#L30-L35

Besides hardcoding these details, the Windows default of hidden by default is arguably the most correct behavior when symbol visibility is considered. I think shared libraries are a very heavy topic on their own that they could be either left for later. Shared libraries in C++ is a tricky subject, due to the ABI issue.

https://github.com/PacktPublishing/CMake-Tips-and-Tricks/blob/fb5a8f56ed153f874aa66f88cfeb97efd02b1efd/chapter_2/CMakeLists.txt#L48-L59

These install rules could be trimmed down considerably. First off, since CMake 3.14, you are not required to spell out the destinations, because CMake will do the right thing by default. The PUBLIC_HEADER and PRIVATE_HEADER install blocks are only relevant for the MacOS specific FRAMEWORK targets, for which you have to list the headers in the corresponding PUBLIC_HEADER and PRIVATE_HEADER target properties.

It's also missing proper componentization, which is important to properly set up links for .so files on platforms that do use .so files. The component should also be prefixed with a project specific identifier, so the component name does not cause issues in consuming projects when consumed using vendoring. This is something Craig Scott has also mentioned in his CppCon talk.

https://github.com/PacktPublishing/CMake-Tips-and-Tricks/blob/fb5a8f56ed153f874aa66f88cfeb97efd02b1efd/chapter_2/CMakeLists.txt#L61-L78

A bit pedantic, but while I'm here: This could just be moved into the driver's lists file, since there is already a check for the boolean variable.

---

Most of these things I have covered in the past in an educational example repository that contains some explanations for the what and why for each point. You can find it here: https://github.com/friendlyanon/cxx-static-shared-example

Improve cmake-format settings

Here is an example of weird formatting:

https://github.com/PacktPublishing/CMake-Tips-and-Tricks/blob/c4620ded5e17b85e3f940de27fa5e29e5196749d/chapter_3/hello_lib/CMakeLists.txt#L27-L28

I have not used cmake-format a lot so far, because I'm not a fan of such mistakes and they seemed to crop up frequently and custom commands always require a lot of configuring in the style yaml.