wanener / cmake-examples

A collection of as simple as possible, modern CMake projects

Modern CMake Examples

Overview

This repository is a collection of as simple as possible CMake projects (with a focus on installing). The idea is to try and help understand exactly what each part of a CMakeLists.txt file does and why it is needed.

This is basically intended as a series of reminders to help me remember how to use CMake 🤦

Please see the Example README for steps on using the example libraries and the Installing README for an overview of installing CMake libraries.

Disclaimer

I am NOT a CMake expert - these examples may contain gaffs, faux pas, mistakes etc etc.. Please take everything with a pinch of salt and if you recognize a blatant error or mistake please feel free to create an issue or PR.

Background

For the longest time I just didn't grok installing in CMake¹.

I didn't understand why you'd ever want to do it, or what it was useful for. When I started looking into how to do it I could not make head nor tail of all the various install commands. While trying to figure all this stuff out I was immersing myself in trying to learn Modern CMake (targets, targets targets...) and how these two things are related.

The examples in this repo are the culmination of many months of sporadic research to try and understand CMake more fully and write better CMake scripts.

I'm sharing my journey so far to hopefully help some other poor soul who is in the same boat I'm in. With any luck there will be something someone finds useful here.

For an explanation² of what (in the context of CMake) installing is, please see the installing section and take a look at the various example projects for context.

1. I recently discovered a kindred spirit on reddit
2. My interpretation?

CMake Resources

I've been attempting to learn CMake for a while and have built up quite a list of articles/blogs/documentation that have helped inform my understanding up to this point. Please see them listed below (mainly for my benefit so I have them all in one place).

Articles

• CLIUtils
  • An Introduction to Modern CMake
• The Coding Nest
  • Basic CMake usage
  • Basic CMake, part 2: libraries
• Pablo Arias
  • It's Time To Do CMake Right
• steveire
  • Opt-in header-only libraries with CMake
  • Embracing Modern CMake
• GitLab.Kitware - CMake
  • How To Find Libraries
  • Exporting and Importing Targets
  • How to create a ProjectConfig.cmake file
• Foonathan
  • Tutorial: Easily supporting CMake install and find_package()
  • Tutorial: Easy dependency management for C++ with CMake and Git
• Coderwall
  • Use CMake-enabled libraries in your CMake project
  • Use CMake-enabled libraries in your CMake project (II)
  • Use CMake-enabled libraries in your CMake project (III)
• Arne Mertz
  • CMake Project Structure
  • CMake – Properties and Options
• rix0r
  • The Ultimate Guide to Modern CMake
• Crascit
  • Enabling C++11 And Later In CMake
  • CMake targets with detailed dependencies
• Mario Badr
  • Creating a Header-Only Library with CMake
• mbinna
  • Effective Modern CMake
• LLVM
  • CMake Primer
• devdocs
  • CMake
• Jetbrains - CLion
  • Quick CMake Tutorial
• SysProgs - visualgdb
  • Exporting and importing CMake packages with find_package
• ecrafter
  • Exporting and importing CMake packages with find_package
• KDAB
  • Modern CMake with Qt and Boost
• Cognitive Waves
  • CMAKE AND VISUAL STUDIO
• Reddit - How to CMake good
  • New Educational Video Series: How to CMake Good
• Fosdem - Alexander Neundorf
  • Installing and Finding packages, Exporting and Importing targets
• fede.tft
  • CMake part 3: Finding libraries
• Daniel Pfeifer
  • Effictive CMake
• kde
  • How to get CMake find what you want it to

Documentation

• cmake-buildsystem
• cmake-packages
• cmake-properties
• cmake-generator-expressions
• install
• find_package
• target_include_directories
• ExternalProject
• CMAKE_PREFIX_PATH
• CMAKE_INSTALL_PREFIX
• CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT

Stack Overflow

• How to use CMake to find and link to a library using install-export and find_package?
• preferred cmake project structure
• CMake: How to set up source, library and CMakeLists.txt dependencies?
• CMake share library with multiple executables
• Setting CMAKE_INSTALL_PREFIX from CMakeLists.txt file
• Modern way to set compiler flags in cross-platform cmake project
• cmake usefulness of aliases
• Package vs Library
• After CMake install, I can't find a package with find_package
• cmake add_library, followed by install library destination
• CMake install is not installing libraries on Windows
• How to copy DLL files into the same folder as the executable using CMake?
• Path to target output file
• Building of executable and shared library with cmake, runtimelinker does not find dll
• https://stackoverflow.com/questions/28692896/how-to-use-cmake-generator-expression-target-filetgt
• A simple example of using cmake to build a Windows DLL

YouTube

• C++Now 2017: Daniel Pfeifer “Effective CMake"
• CMake for Dummies
• C++Now 2018: Mateusz Pusz “Git, CMake, Conan: How to Ship and Reuse our C++ Projects”
• CppCon 2017: Mathieu Ropert “Using Modern CMake Patterns to Enforce a Good Modular Design”
• Embracing Modern CMake
• C++ Weekly - Ep 78 - Intro to CMake
• How to CMake Good - Recommended Order

Books

• Professional CMake: A Practical Guide
• CMake Cookbook: Building, testing, and packaging modular software with modern CMake
• Mastering CMake (I haven't read this personally)

Other

• Cpplang Slack #cmake channel
  • There's some super helpful people on there, the search functionality is great too (someone likely will have had your problem before 😉).
• vector-of-bool
  • Was incredibly kind in answering some of my dumb CMake questions - thank you!