Professional CMake: A Practical Guide

Professional CMake: A Practical Guide
Table of Contents
Preface
Acknowledgments
Part I: Fundamentals
Chapter 1. Introduction
Chapter 2. Setting Up A Project
2.1. In-source Builds
2.2. Out-of-source Builds
2.3. Generating Project Files
2.4. Running The Build Tool
2.5. Recommended Practices
Chapter 3. A Minimal Project
3.1. Managing CMake Versions
3.2. The project() Command
3.3. Building A Basic Executable
3.4. Commenting
3.5. Recommended Practices
Chapter 4. Building Simple Targets
4.1. Executables
4.2. Defining Libraries
4.3. Linking Targets
4.4. Linking Non-targets
4.5. Old-style CMake
4.6. Recommended Practices
Chapter 5. Variables
5.1. Variable Basics
5.2. Environment Variables
5.3. Cache Variables
5.4. Scope Blocks
5.5. Potentially Surprising Behavior Of Variables
5.6. Manipulating Cache Variables
5.6.1. Setting Cache Values On The Command Line
5.6.2. CMake GUI Tools
5.7. Printing Variable Values
5.8. String Handling
5.9. Lists
5.9.1. Problems With Unbalanced Square Brackets
5.10. Math
5.11. Recommended Practices
Chapter 6. Flow Control
6.1. The if() Command
6.1.1. Basic Expressions
6.1.2. Logic Operators
6.1.3. Comparison Tests
6.1.4. File System Tests
6.1.5. Existence Tests
6.1.6. Common Examples
6.2. Looping
6.2.1. foreach()
6.2.2. while()
6.2.3. Interrupting Loops
6.3. Recommended Practices
Chapter 7. Using Subdirectories
7.1. add_subdirectory()
7.1.1. Source And Binary Directory Variables
7.1.2. Scope
7.1.3. When To Call project()
7.2. include()
7.3. Project-relative Variables
7.4. Ending Processing Early
7.5. Recommended Practices
Chapter 8. Functions And Macros
8.1. The Basics
8.2. Argument Handling Essentials
8.3. Keyword Arguments
8.4. Returning Values
8.4.1. Returning Values From Functions
8.4.2. Returning Values From Macros
8.5. Overriding Commands
8.6. Special Variables For Functions
8.7. Other Ways Of Invoking CMake Code
8.8. Problems With Argument Handling
8.8.1. Parsing Arguments Robustly
8.8.2. Forwarding Command Arguments
8.8.3. Special Cases For Argument Expansion
8.9. Recommended Practices
Chapter 9. Properties
9.1. General Property Commands
9.2. Global Properties
9.3. Directory Properties
9.4. Target Properties
9.5. Source Properties
9.6. Cache Variable Properties
9.7. Other Property Types
9.8. Recommended Practices
Chapter 10. Generator Expressions
10.1. Simple Boolean Logic
10.2. Target Details
10.3. General Information
10.4. Path Expressions
10.5. Utility Expressions
10.6. Recommended Practices
Chapter 11. Modules
11.1. Checking Existence And Support
11.2. Other Modules
11.3. Recommended Practices
Chapter 12. Policies
12.1. Policy Control
12.2. Policy Scope
12.3. Recommended Practices
Chapter 13. Debugging And Diagnostics
13.1. Log Messages
13.1.1. Log Levels
13.1.2. Message Indenting
13.1.3. Message Contexts
13.1.4. Check Messages
13.2. Color Diagnostics
13.3. Print Helpers
13.4. Tracing Variable Access
13.5. Debugging Generator Expressions
13.6. Profiling CMake Calls
13.7. Discarding Previous Results
13.8. Recommended Practices
Part II: Builds In Depth
Chapter 14. Build Type
14.1. Build Type Basics
14.1.1. Single Configuration Generators
14.1.2. Multiple Configuration Generators
14.2. Common Errors
14.3. Custom Build Types
14.4. Recommended Practices
Chapter 15. Compiler And Linker Essentials
15.1. Target Properties
15.1.1. Compiler Flags
15.1.2. Linker Flags
15.1.3. Sources
15.2. Target Property Commands
15.2.1. Linking Libraries
15.2.2. Linker Options
15.2.3. Header Search Paths
15.2.4. Compiler Defines
15.2.5. Compiler Options
15.2.6. Source Files
15.3. Directory Properties And Commands
15.4. De-duplicating Options
15.5. Compiler And Linker Variables
15.5.1. Compiler And Linker Variables Are Single Strings, Not Lists
15.5.2. Distinguish Between Cache And Non-cache Variables
15.5.3. Prefer Appending Over Replacing Flags
15.5.4. Understand When Variable Values Are Used
15.6. Language-specific Compiler Flags
15.7. Compiler Option Abstractions
15.7.1. Warnings As Errors
15.7.2. System Header Search Paths
15.7.3. Runtime Library Selection
15.7.4. Debug Information Format Selection
15.8. Recommended Practices
Chapter 16. Advanced Linking
16.1. Require Targets For Linking
16.2. Customize How Libraries Are Linked
16.2.1. Link Group Features
16.2.2. Link Library Features
16.2.3. Custom Features
16.2.4. Feature Validity
16.3. Propagating Up Direct Link Dependencies
16.3.1. Link Seaming Example
16.3.2. Static Plugins
16.4. Recommended Practices
Chapter 17. Language Requirements
17.1. Setting The Language Standard Directly
17.2. Setting The Language Standard By Feature Requirements
17.2.1. Detection And Use Of Optional Language Features
17.3. Recommended Practices
Chapter 18. Target Types
18.1. Executables
18.2. Libraries
18.2.1. Basic Library Types
18.2.2. Object Libraries
18.2.3. Imported Libraries
18.2.4. Interface Libraries
18.2.5. Interface Imported Libraries
18.2.6. Library Aliases
18.3. Promoting Imported Targets
18.4. Recommended Practices
Chapter 19. Custom Tasks
19.1. Custom Targets
19.2. Adding Build Steps To An Existing Target
19.3. Commands That Generate Files
19.4. Configure Time Tasks
19.5. Platform Independent Commands
19.6. Combining The Different Approaches
19.7. Recommended Practices
Chapter 20. Working With Files
20.1. Manipulating Paths
20.1.1. cmake_path()
20.1.2. Older Commands
20.2. Copying Files
20.3. Reading And Writing Files Directly
20.4. File System Manipulation
20.5. File Globbing
20.6. Downloading And Uploading
20.7. Recommended Practices
Chapter 21. Specifying Version Details
21.1. Project Version
21.2. Source Code Access To Version Details
21.3. Source Control Commits
21.4. Recommended Practices
Chapter 22. Libraries
22.1. Build Basics
22.2. Linking Static Libraries
22.3. Shared Library Versioning
22.4. Interface Compatibility
22.5. Symbol Visibility
22.5.1. Specifying Default Visibility
22.5.2. Specifying Individual Symbol Visibilities
22.6. Mixing Static And Shared Libraries
22.7. Recommended Practices
Chapter 23. Toolchains And Cross Compiling
23.1. Toolchain Files
23.2. Defining The Target System
23.3. Tool Selection
23.4. System Roots
23.5. Compiler Checks
23.6. Examples
23.6.1. Raspberry Pi
23.6.2. GCC With 32-bit Target On 64-bit Host
23.7. Android
23.7.1. Historical Context
23.7.2. Using The NDK
23.7.3. Android Studio
23.7.4. ndk-build
23.7.5. Visual Studio Generators
23.8. Recommended Practices
Chapter 24. Apple Features
24.1. CMake Generator Selection
24.2. Application Bundles
24.2.1. Bundle Structure
24.2.2. Bundle Info.plist Files
24.2.3. Sources, Resources And Other Files
24.3. Frameworks
24.3.1. Framework Structure
24.3.2. Framework Info.plist Files
24.3.3. Headers
24.4. Loadable Bundles
24.5. Build Settings
24.5.1. SDK Selection
24.5.2. Deployment Target
24.5.3. Device Families
24.5.4. Compiler Test Workarounds
24.6. Code Signing
24.6.1. Signing Identity And Development Team
24.6.2. Provisioning Profiles
24.6.3. Entitlements
24.7. Creating And Exporting Archives
24.8. Universal Binaries
24.8.1. Device-only Bundles
24.8.2. Intel And Apple Silicon Binaries
24.8.3. Combined Device And Simulator Binaries
24.9. Linking Frameworks
24.10. Embedding Frameworks
24.11. Limitations
24.12. Recommended Practices
Part III: The Bigger Picture
Chapter 25. Finding Things
25.1. Finding Files And Paths
25.1.1. Apple-specific Behavior
25.1.2. Cross-compilation Controls
25.1.3. Validators
25.2. Finding Paths
25.3. Finding Programs
25.4. Finding Libraries
25.5. Finding Packages
25.5.1. Package Registries
25.5.2. FindPkgConfig
25.6. Ignoring Search Paths
25.7. Debugging find_…​() Calls
25.8. Recommended Practices
Chapter 26. Testing
26.1. Defining And Executing A Simple Test
26.2. Test Environment
26.3. Pass / Fail Criteria And Other Result Types
26.4. Test Grouping And Selection
26.4.1. Regular Expressions
26.4.2. Test Numbers
26.4.3. Labels
26.4.4. Repeating Tests
26.5. Parallel Execution
26.6. Managing Test Resources
26.6.1. Defining Test Resource Requirements
26.6.2. Specifying Available System Resources
26.6.3. Using Resources Allocated To A Test
26.7. Test Dependencies
26.8. Cross-compiling And Emulators
26.9. Build And Test Mode
26.10. CDash Integration
26.10.1. Key CDash Concepts
26.10.2. Executing Pipelines And Actions
26.10.3. CTest Configuration
26.10.4. Test Measurements And Results
26.11. Output Control
26.12. GoogleTest
26.13. Recommended Practices
Chapter 27. Installing
27.1. Directory Layout
27.1.1. Relative Layout
27.1.2. Base Install Location
27.2. Installing Project Targets
27.2.1. Interface Properties
27.2.2. RPATH
27.2.3. Apple-specific Targets
27.3. Installing Exports
27.4. Installing Imported Targets
27.5. Installing Files
27.5.1. File Sets
27.5.2. Explicit Public And Private Headers
27.5.3. Simple Files And Programs
27.5.4. Whole Directories
27.6. Custom Install Logic
27.7. Installing Dependencies
27.7.1. Runtime Dependency Sets
27.7.2. InstallRequiredSystemLibraries Module
27.7.3. BundleUtilities And GetPrerequisites
27.8. Writing A Config Package File
27.8.1. Config Files For CMake Projects
27.8.2. Config Files For Non-CMake Projects
27.9. Executing An Install
27.10. Recommended Practices
Chapter 28. Packaging
28.1. Packaging Basics
28.2. Components
28.3. Multi Configuration Packages
28.3.1. Multiple Build Directories
28.3.2. Pass Multiple Configurations To cpack
28.4. Package Generators
28.4.1. Simple Archives
28.4.2. Qt Installer Framework (IFW)
28.4.3. WIX
28.4.4. NSIS
28.4.5. DragNDrop
28.4.6. productbuild
28.4.7. RPM
28.4.8. DEB
28.4.9. FreeBSD
28.4.10. Cygwin
28.4.11. NuGet
28.4.12. External
28.5. Recommended Practices
Chapter 29. ExternalProject
29.1. High Level Overview
29.2. Directory Layout
29.3. Built-in Steps
29.3.1. Archive Downloads
29.3.2. Repository Download Methods
29.3.3. Configuration Step
29.3.4. Build Step
29.3.5. Install Step
29.3.6. Test Step
29.4. Step Management
29.5. Miscellaneous Features
29.6. Common Issues
29.7. ExternalData
29.8. Recommended Practices
Chapter 30. FetchContent
30.1. Comparison With ExternalProject
30.2. Basic Usage
30.3. Resolving Dependencies
30.4. Integration With find_package()
30.4.1. Try find_package() Before FetchContent
30.4.2. Redirect find_package() To FetchContent
30.4.3. Redirections Directory
30.5. Developer Overrides
30.6. Other Uses For FetchContent
30.7. Restrictions
30.8. Recommended Practices
Chapter 31. Making Projects Consumable
31.1. Use Project-specific Names
31.2. Don’t Assume A Top Level Build
31.3. Avoid Hard-coding Developer Choices
31.4. Avoid Package Variables If Possible
31.5. Use Appropriate Methods To Obtain Dependencies
31.6. Recommended Practices
Chapter 32. Dependency Providers
32.1. Top Level Setup Injection Point
32.2. Dependency Provider Implementation
32.2.1. Accepting find_package() Requests
32.2.2. Accepting FetchContent_MakeAvailable() Requests
32.2.3. Accepting Multiple Request Methods
32.2.4. Wrapping The Built-in Implementations
32.2.5. Preserving Variable Values
32.2.6. Delegating Providers
32.3. Recommended Practices
Chapter 33. Presets
33.1. High Level Structure
33.2. Configure Presets
33.2.1. Essential Fields
33.2.2. Inheritance
33.2.3. Macros
33.2.4. Environment Variables
33.2.5. Toolchains
33.2.6. Conditions
33.3. Build Presets
33.4. Test Presets
33.5. Package Presets
33.6. Workflow Presets
33.7. Recommended Practices
Chapter 34. Project Organization
34.1. Superbuild Structure
34.2. Non-superbuild Structure
34.3. Common Top Level Subdirectories
34.4. IDE Projects
34.5. Defining Targets
34.5.1. Building Up A Target Across Directories
34.5.2. Target Output Locations
34.6. Windows-specific Issues
34.7. Cleaning Files
34.8. Re-running CMake On File Changes
34.9. Injecting Files Into Projects
34.10. Recommended Practices
Chapter 35. Build Performance
35.1. Unity Builds
35.1.1. BATCH Mode
35.1.2. GROUP Mode
35.2. Precompiled Headers
35.3. Build Parallelism
35.3.1. Makefiles Generators
35.3.2. Ninja Generators
35.3.3. Visual Studio Generators
35.3.4. Xcode Generator
35.3.5. Optimizing Build Dependencies
35.4. Compiler Caches
35.4.1. Ccache Configuration
35.4.2. Makefiles And Ninja Generators
35.4.3. Xcode Generator
35.4.4. Visual Studio Generators
35.4.5. Combined Generator Support
35.5. Debug-related Improvements
35.6. Alternative Linkers
35.7. Recommended Practices
Chapter 36. Working With Qt
36.1. Basic Setup
36.2. Build Details
36.2.1. Standard Library Implementation
36.2.2. Position Independent Code
36.2.3. Windows GUI Applications
36.3. Autogen
36.3.1. Moc
36.3.2. Widgets
36.3.3. Resources
36.4. Translations
36.5. Deployment
36.5.1. Qt Deployment Tools
36.5.2. Deploying Translation Files
36.5.3. Linux Considerations
36.6. Transition To Qt 6
36.7. Recommended Practices
Appendix A: Timer Dependency Provider
Appendix B: Full Compiler Cache Example
Index