Mastering CMake
Fifth Edition
Bill
Ken
Martin & Hoffman
With contributions from:
Andy Cedilnik, David Cole, Marcus Hanwell, Julien Jomier, Brad King, Alex Neundorf
Published by Kitware Inc.
Join the CMake community at www.cmake.org
Contents
CHAPTER 1 WHY CMAKE?
1.1
1.2
1.3
1.4
1.5
CHAPTER 2
2.1
2.2
2.3
2.4
2.5
2.6
2.7
2.8
CHAPTER 3
3.1
3.2
3.3
3.4
3.5
3.6
CHAPTER 4
4.1
4.2
4.3
4.4
The History of CMake
Why Not Use Autoconf?
Why Not Use JAM, qmake, SCons, or ANT?
Why Not Script It Yourself?
On What Platforms Does CMake Run?
GETTING STARTED
Getting and Installing CMake an Your Computer
UNIX and Mac Binary Installations
Windows Binary Installation
Building CMake Yourself
Basic CMake Usage and Syntax
Hello World for CMake
How to Run CMake?
Running CMake's Qt Interface
Running the ccmake Curses Interface
Running CMake from the Command Line
Specifting the Compiler to CMake
Dependency Analysis
Editing CMakeLists Files
Setting Initial Values for CMake
Building Your Project
KEY CONCEPTS
Main Structures
Targets
Source Files
Directories, Generators, Tests, and Properties
Variables and Cache Entries
Build Configurations
WRITING CMAKELISTS FILES
CMake Syntax
Basic Commands
Flow Control
Regular Expressions
1
3
3
4
4
5
7
7
7
7
8
8
9
10
11
13
15
15
16
17
17
19
21
21
24
25
26
27
32
33
33
34
35
42
iv
4.5
4.6
4.7
4.8
4.9
4.10
4.11
4.12
CHAPTER 5
5.1
5.2
5.3
5.4
5.5
5.6
5.7
Checking Versions of CMake
Using Modules
Using CMake with SWIG
Using CMake with Qt
Using CMake with FLTK
Policies
Updating a Project For a New Version of CMake
Linking Libraries
Specifying Optimized or Debug Libraries with a Target
Shared Libraries and Loadable Modules
Shared Library Versioning
Installing Files
Installing Prerequisite Shared Libraries
Advanced Commands
SYSTEM INSPECTION
Using Header Files and Libraries
System Properties
Finding Packages
Built-in Find Modules
How to Pass Parameters to a Compilation?
How to Configure a Header File
Creating CMake Package Configuration Files
CHAPTER 6 CUSTOM COMMANDS AND TARGETS
6.1
6.2
6.3
6.4
6.5
6.6
CHAPTER 7
7.1
7.2
7.3
7.4
44
45
48
49
50
50
53
57
59
59
64
66
76
82
85
85
87
92
93
95
97
99
103
Portable Custom Commands
Using add_custom_command an a Target
How to Copy an Executable Once it is Built?
Using add_custom_command to Generate a File
Using an Executable to Build a Source File
Adding a Custom Target
Specifying Dependencies and Outputs
When There Isn't One Rute For One Output
A Single Command Producing Multiple Outputs
Having One Output That Can Be Generated By Different Commands
103
105
106
107
107
108
111
112
112
112
CONVERTING EXISTING SYSTEMS TO CMAKE
115
Source Code Directory Structures
Build Directories
Useful CMake Commands When Converting Projects
Converting UNIX Makefiles
115
I 17
119
120
7.5
7.6
CHAPTER 8
8.1
8.2
8.3
8.4
8.5
8.6
8.7
8.8
CHAPTER 9
9.1
9.2
9.3
9.4
9.5
9.6
9.7
9.8
9.9
9.10
9.11
Converting Autoconf Based Projects
Converting Windows Based Workspaces
CROSS COMPILING WITH CMAKE
125
Toolchain Files
Finding External Libraries, Programs and Other Files
System Inspection
Using Compile Checks
Running Executables Built in the Project
Cross Compiling Hello World
Cross Compiling for a Microcontroller
Cross Compiling an Existing Project
Cross Compiling a Complex Project - VTK
Some Tips and Tricks
126
128
130
131
133
136
140
143
145
147
PACKAGING WITH CPACK
CPack Basics
Simple Example
What Happens When CPack.cmake Is Included?
Adding Custom CPack Options
Options Added by CPack
CPack Source Packages
CPack Installer Commands
CPack for Windows Installer NSIS
CPack Variables Used by CMake for NSIS
Creating Windows Short Cuts in the Start Menu
Advanced NSIS CPack Options
Setting File Extension Associations With NSIS
Installing Microsoft Run Time Libraries
CPack Component Install Support
CPack for Cygwin Setup
CPack for Mac OS X PackageMaker
CPack for Mac OS X Drag and Drop
CPack for Mac OS X X11 Applications
CPack for Debian Packages
CPack for RPM
CPack Files
CHAPTER 10 AUTOMATION & TESTING WITH CMAKE
10.1
10.2
121
123
Testing with CMake, CTest, and CDash
How Does CMake Facilitate Testing?
149
149
150
151
152
153
154
154
156
156
161
161
162
163
163
173
176
178
180
182
183
183
185
185
186
vi
10.3
10.4
10.5
10.6
10.7
10.8
10.9
10.10
10.11
10.12
Additional Test Properties
Testing Using CTest
Using CTest to Drive Complex Tests
Handling a Large Number of Tests
Producing Test Dashboards
Adding CDash Dashboard Support to a Project
Client Setup
Customizing Dashboards for a Project
Dashboard Submissions Settings
Filtering Errors and Warnings
Adding Notes to a Dashboard
Setting up Automated Dashboard Clients
Settings for Continuous Dashboards
Variables Available in CTest Scripts
Advanced CTest Scripting
Limitations of Traditional CTest Scripting
Extended CTest Scripting
Setting up a Dashboard Server
CDash Server
Advanced Server Management
Build Groups
Email
Sites
Graphs
Adding Notes to a Build
Logging
Test Timing
Mobile Support
Backing up CDash
Upgrading CDash
CDash Maintenance
Subprojects
Using ctest_submit with PARTS and FILES
Splitting Your Project into Multiple Subprojects
187
189
191
192
194
196
199
202
202
203
205
206
210
212
212
213
213
218
218
220
223
225
226
227
228
229
229
230
230
231
232
233
236
237
CHAPTER 11 PORTING CMAKE TO NEW PLATFORMS AND LANGUAGES241
11.1
11.2
11.3
11.4
11.5
The Determine System Process
The Enable Language Process
Porting to a New Platform
Adding a New Language
Rule Variable Listing
General Tag Variables
Language Specific Information
241
242
244
246
247
247
248
11.6
11.7
Compiler and Platform Examples
248
Como Compiler
Borland Compiler
248
249
Extending CMake
250
Creating a Loaded Command
Using a Loaded Command
250
251
CHAPTER 12 TUTORIALS
12.1
12.2
12.3
12.4
12.5
12.6
12.7
255
A Basic Starting Point (Step 1)
255
Adding a Version Number and Configured Header File
256
Adding a Library (Step 2)
Installing and Testing (Step 3)
Adding System Introspection (Step 4)
Adding a Generated File and Generator (Step 5)
Building an Installer (Step 6)
Adding Support for a Dashboard (Step 7)
258
260
262
263
267
268
APPENDIX A VARIABLES
-
Variables That Change Behavior
Variables That Describe the System
Variables for Languages
Variables That Control the Build
Variables That Provide Information
APPENDIX B
—
COMMAND LINE REFERENCE
CMake Command Line Options
CMake Generators
CTest Command Line Options
CPack Command Line Options
CPack Generators
APPENDIX C
—
LISTFILE COMMANDS
Current Commands
Compatibility Commands
APPENDIX D
—
SELECTED MODULES
CMake Modules
269
269
272
274
278
280
287
287
292
294
298
299
301
301
366
373
373
VIII
APPENDIX E - PROPERTIES
Properties of Global Scope
Properties on Directories
Properties on Targets
Properties on Tests
Properties on Source Files
Properties on Cache Entries
411
411
414
417
431
431
434
APPENDIX F — CMAKE POLICIES
437
INDEX
447