Mastering

CMake

Sixth Edition

Bill

Ken

Martin & Hoffman

With contributions from:

Andy Cedilnik, David Cole, Marcus Hanwell,

Julien

Jomier,

Brad

King, Robert Maynard,

Alex Neundorf

Published

by Kitware Inc.

Join the CMake

community

at

www.cmake.org

Contents

CHAPTER 1
The

WHY CMAKE?

History of CMake

Why Not Use Autoconf?

Why

Not Use

JAM, qmake, SCons,

Why Not Script It Yourself?

or

ANT?

On What Platforms Does CMake Run?

How Stable is CMake?

CHAPTER 2

Getting

GETTING STARTED

and

Building

Installing CMake

on

Your

Computer

UNIX and Mac Binary Installations

Windows

Binary Installation

CMake Yourself

Basic CMake

Usage

and

Syntax

Hello World for CMake

How

10

to Run CMake?

11

Running CMake's Qt Interface

11

Running the

14

ccmake Curses

Interface

Running CMake from the Command Line

Specifying the Compiler to CMake

16
16

Dependency A nalysis
Editing CMakeLists Files

17

Setting Initial Values for CMake

Building Your Proj ect

18

CHAPTER 3

KEY CONCEPTS

18
19

21

Main Structures

21

Targets

24

Source Files

25

Directories, Generators, Tests, and Properties

26

Variables and Cache Entries

27

Build

32

Configurations

CHAPTER 4

CMake

WRITING CMAKELISTS FILES

33

Language

33

Basic Commands

34

Flow Control

34

Regular Expressions

41

iv

Checking
Using

Versions of CMake

43

Modules

44

Using CMake with SWIG

45

CMake with

46

Using
Using

Qt

CMake with FLTK

47

Policies

48

Updating
Linking

Project

For

New Version

of CMake

Libraries

51
54

Specifying Optimized
Linking

Advanced

Object

or

Debug

Libraries with

Target

56
57

Libraries

58

Shared Libraries and Loadable Modules

59

Shared

64

Library Versioning
Installing Files
Installing Prerequisite

66
Shared Libraries

Advanced Commands

CHAPTER 5

76
81

SYSTEM INSPECTION

85

Using Header Files and Libraries

System Properties

87

Finding Packages

92

85

Built-in Find Modules

93

How to Pass Parameters to

How to

Configure a

95

Compilation?

Header File

97

Creating CMake Package Configuration Files

CMake Package Registry

CHAPTER 6

CUSTOM COMMANDS AND TARGETS

Portable Custom Commands

Using add_custom_command
How to

an

an

Target

107

Executable Once it is Built?

Executable

Adding a Custom Target

Specifying Dependencies

to

File

Build a Source File

108
109

Command

113
113

Producing Multiple Outputs

113

Having One Output That Can Be Generated By Different Commands

114

CONVERTING EXISTING SYSTEMS TO CMAKE

115

CHAPTER 7
Source Code

Single

108

110
and

Outputs
When There Isn't One Rule For One Output
A

105
105

on a

Copy
Using add_custom_command to Generate

Using

99
102

Directory

Build Directories

Structures

115

117

Useful CMake Commands When

Converting Projects

119

UNIX Makefiles

120

Converting Autoconf Based Projects

Converting Windows Based Workspaces

121

Converting

CHAPTER 8

122

CROSS-COMPILING WITH

CMAKE

125

Toolchain Files

126

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

128

Some Tips and Tricks

147

CHAPTER 9

PACKAGING WITH CPACK

CPack Basics

131
133

136
140
143

145

149
149

Simple Example

150

What

Happens When CPack.cmake

Adding Custom CPack Options
Options Added by CPack
CPack Source Packages

Is Included?

CPack Installer Commands

151
152

153
154
15 5

CPack for Windows Installer NSIS

156

CPack Variables Used by CMake for NSIS

156

Creating

162

Windows Short Cuts in the Start Menu

Advanced NSIS CPack

Setting File Extension

Options

Associations With NSIS

Installing Microsoft Run

CPack for

13 0

Time Libraries

162
163
164

CPack Component Install Support

164

Cygwin Setup

174

CPack for Mac OS X PackageMaker

177

CPack for Mac OS X

179

Drag and Drop

CPack for Mac OS X X11 Applications

181

CPack for Debian

183

Packages

CPack for RPM

184

CPack Files

184

CHAPTER 10

AUTOMATION & TESTING WITH CMAKE

Testing with CMake, CTest, and CDash

185

185

How Does CMake Facilitate

Additional Test

Testing Using
Using

186

Testing?

187

Properties

189

CTest

CTest to Drive

Complex

191

Tests

Number of Tests

192

Handling a Large
Managing Test Data
Producing Test Dashboards
Adding

194

196

CDash Dashboard

Support

to a

Project

203

Client Setup
Customizing Dashboards for a Project
Dashboard Submissions Settings
Filtering Errors and Warnings
Adding Notes to a Dashboard
Setting up Automated Dashboard Clients

205
205
206

208
209

Settingsfor Continuous Dashboards

Variables Available in CTest Scripts

of Traditional CTest

Limitations
Advanced CTest

Scripting

213

215
215
216

Scripting

Extended CTest Scripting

Setting up

199

216

Dashboard Server

221

CDash Server

221

Advanced Server

Management

223

Build Groups

226

Email

228

Sites

229
230

Graphs
Adding

Notes to

Build

231

Logging
Test Timing

232

Mobile Support

233

Backing up CDash
Upgrading CDash

233

CDash Maintenance

235

232

234

Subprojects
Using ctestjsubmit with PARTS and FILES
Splitting

CHAPTER 11

Project

into

Multiple Subprojects

239
240

PORTING CMAKE TO NEW PLATFORMS AND LANGUAGES245

The Determine
The Enable

Your

236

System Process

Language

Process

245

246

Porting to a New Platform

Adding a New Language

248

Rule Variable

251

Listing

General

Tag Variables

250
251

Compiler

Language Specific Information

Examples
Como Compiler

252

Borland

253

and Platform

Extending

Compiler

CMake

CHAPTER 12

Loaded Command

Loaded Command

TUTORIALS

Starting Point (Step 1)

Adding a Version Number and Configured Header File
Adding a Library (Step 2)
Installing and Testing (Step 3)
Adding System Introspection (Step 4)

Adding

Generated File and Generator (Step 5)

Installer

Building
(Step 6)
Adding Support for a Dashboard (Step 7)
an

CHAPTER 13

APPENDIX A

Variables That

Change

Variables for

VARIABLES

Behavior

Variables That Describe the

254
255

259

A Basic

252

254

Creating
Using a

252

259
260
262

264
266
267
271
272

273
273

System

280
283

Languages

Variables That Control the Build

288

Variables That Provide Information

293

CHAPTER 14 APPENDIX B

CMake Command Line

COMMAND LINE REFERENCE

Options

302
302

Name

302

Usage

302

Description
Options

302

303

CMake Generators

308

CTest Command Line

CPack Command Line

312

Options

317

Options

CPack Generators

CHAPTER 15

317

APPENDIX C

CMake Generator

Expressions

GENERATOR EXPRESSIONS

318

319

viii

CHAPTER 16

APPENDIX D

LISTFILE COMMANDS

Current Commands

Compatibility
CHAPTER 17

321

Commands

APPENDIX E

399

SELECTED MODULES

Standard CMake Modules

CHAPTER 18

APPENDIX F

CMake Properties

321

407
407

PROPERTIES

583

Properties supported by CMake, the Cross-Platform Makefile

Generator.

583

Properties

of Global Scope

Properties
Properties

on

Directories

587

on

Targets

591

on

Tests

615

on

Source Files

617

on

Cache Entries

620

Properties
Properties
Properties

CHAPTER 19

APPENDIX G

CHAPTER 20

INDEX

583

CMAKE POLICIES

623

635