Mastering CMake

Sixth Edition


Ken Bill
Martin & Hoffman


With contributions from:
Andy Cedilnik, David Cole, Marcus Hanwell, J ulien J omier, Brad King, Robert Maynard,
Alex Neundorf



Published by Kitware Inc.


J oin the CMake community at www.cmake.org





ii

2005 - 2013 Kitware, Inc.
http://www.kitware.com



All rights reserved. No part of this book may be reproduced, in any form or by any means,
without the express written permission of the publisher.



The publisher Kitware, Inc. offers discounts on this book when ordered in bulk quantities. For
more information contact Kitware, Inc. at kitware@kitware.com.
You may also order directly from Kitwares electronic store
at http://www.kitware.com/products.



Contributors to this work include those listed on the title page as well as:
Cover Design: Sbastien Barr
Technical Contributors: World-Wide CMake Developer Community at www.cmake.org.



All product names mentioned herein are the trademarks of their respective owners.



Printed and produced in the United States of America.
ISBN: 978-1-930934-26-9


Contents

CHAPTER 1 WHY CMAKE? 1
The History of CMake 3
Why Not Use Autoconf? 3
Why Not Use JAM, qmake, SCons, or ANT? 4
Why Not Script It Yourself? 4
On What Platforms Does CMake Run? 4
How Stable is CMake? 5
CHAPTER 2 GETTING STARTED 7
Getting and Installing CMake on Your Computer 7
UNIX and Mac Binary Installations 7
Windows Binary Installation 7
Building CMake Yourself 8
Basic CMake Usage and Syntax 8
Hello World for CMake 10
How to Run CMake? 11
Running CMakes Qt Interface 11
Running the ccmake Curses Interface 14
Running CMake from the Command Line 16
Specifying the Compiler to CMake 16
Dependency Analysis 17
Editing CMakeLists Files 18
Setting Initial Values for CMake 18
Building Your Project 19
CHAPTER 3 KEY CONCEPTS 21
Main Structures 21
Targets 24
Source Files 25
Directories, Generators, Tests, and Properties 26
Variables and Cache Entries 27
Build Configurations 32
CHAPTER 4 WRITING CMAKELISTS FILES 33
CMake Language 33
Basic Commands 34
Flow Control 34
Regular Expressions 41
iv
Checking Versions of CMake 43
Using Modules 44
Using CMake with SWIG 45
Using CMake with Qt 46
Using CMake with FLTK 47
Policies 48
Updating a Project For a New Version of CMake 51
Linking Libraries 54
Specifying Optimized or Debug Libraries with a Target 56
Advanced Linking 57
Object Libraries 58
Shared Libraries and Loadable Modules 59
Shared Library Versioning 64
Installing Files 66
Installing Prerequisite Shared Libraries 76
Advanced Commands 81
CHAPTER 5 SYSTEM INSPECTION 85
Using Header Files and Libraries 85
System Properties 87
Finding Packages 92
Built-in Find Modules 93
How to Pass Parameters to a Compilation? 95
How to Configure a Header File 97
Creating CMake Package Configuration Files 99
CMake Package Registry 102
CHAPTER 6 CUSTOM COMMANDS AND TARGETS 105
Portable Custom Commands 105
Using add_custom_command on a Target 107
How to Copy an Executable Once it is Built? 108
Using add_custom_command to Generate a File 108
Using an Executable to Build a Source File 109
Adding a Custom Target 110
Specifying Dependencies and Outputs 113
When There Isnt One Rule For One Output 113
A Single Command Producing Multiple Outputs 113
Having One Output That Can Be Generated By Different Commands 114
CHAPTER 7 CONVERTING EXISTING SYSTEMS TO CMAKE 115
Source Code Directory Structures 115
Build Directories 117
v
Useful CMake Commands When Converting Projects 119
Converting UNIX Makefiles 120
Converting Autoconf Based Projects 121
Converting Windows Based Workspaces 122
CHAPTER 8 CROSS-COMPILING WITH CMAKE 125
Toolchain Files 126
Finding External Libraries, Programs and Other Files 128
System Inspection 130
Using Compile Checks 131
Running Executables Built in the Project 133
Cross-Compiling Hello World 136
Cross-Compiling for a Microcontroller 140
Cross Compiling an Existing Project 143
Cross-Compiling a Complex Project - VTK 145
Some Tips and Tricks 147
CHAPTER 9 PACKAGING WITH CPACK 149
CPack Basics 149
Simple Example 150
What Happens When CPack.cmake Is Included? 151
Adding Custom CPack Options 152
Options Added by CPack 153
CPack Source Packages 154
CPack Installer Commands 155
CPack for Windows Installer NSIS 156
CPack Variables Used by CMake for NSIS 156
Creating Windows Short Cuts in the Start Menu 162
Advanced NSIS CPack Options 162
Setting File Extension Associations With NSIS 163
Installing Microsoft Run Time Libraries 164
CPack Component Install Support 164
CPack for Cygwin Setup 174
CPack for Mac OS X PackageMaker 177
CPack for Mac OS X Drag and Drop 179
CPack for Mac OS X X11 Applications 181
CPack for Debian Packages 183
CPack for RPM 184
CPack Files 184
CHAPTER 10 AUTOMATION & TESTING WITH CMAKE 185
Testing with CMake, CTest, and CDash 185
vi
How Does CMake Facilitate Testing? 186
Additional Test Properties 187
Testing Using CTest 189
Using CTest to Drive Complex Tests 191
Handling a Large Number of Tests 192
Managing Test Data 194
Producing Test Dashboards 196
Adding CDash Dashboard Support to a Project 199
Client Setup 203
Customizing Dashboards for a Project 205
Dashboard Submissions Settings 205
Filtering Errors and Warnings 206
Adding Notes to a Dashboard 208
Setting up Automated Dashboard Clients 209
Settings for Continuous Dashboards 213
Variables Available in CTest Scripts 215
Limitations of Traditional CTest Scripting 215
Advanced CTest Scripting 216
Extended CTest Scripting 216
Setting up a Dashboard Server 221
CDash Server 221
Advanced Server Management 223
Build Groups 226
Email 228
Sites 229
Graphs 230
Adding Notes to a Build 231
Logging 232
Test Timing 232
Mobile Support 233
Backing up CDash 233
Upgrading CDash 234
CDash Maintenance 235
Subprojects 236
Using ctest_submit with PARTS and FILES 239
Splitting Your Project into Multiple Subprojects 240
CHAPTER 11 PORTING CMAKE TO NEW PLATFORMS AND LANGUAGES245
The Determine System Process 245
The Enable Language Process 246
Porting to a New Platform 248
Adding a New Language 250
Rule Variable Listing 251
General Tag Variables 251
vii
Language Specific Information 252
Compiler and Platform Examples 252
Como Compiler 252
Borland Compiler 253
Extending CMake 254
Creating a Loaded Command 254
Using a Loaded Command 255
CHAPTER 12 TUTORIALS 259
A Basic Starting Point (Step 1) 259
Adding a Version Number and Configured Header File 260
Adding a Library (Step 2) 262
Installing and Testing (Step 3) 264
Adding System Introspection (Step 4) 266
Adding a Generated File and Generator (Step 5) 267
Building an Installer (Step 6) 271
Adding Support for a Dashboard (Step 7) 272
CHAPTER 13 APPENDIX A - VARIABLES 273
Variables That Change Behavior 273
Variables That Describe the System 280
Variables for Languages 283
Variables That Control the Build 288
Variables That Provide Information 293
CHAPTER 14 APPENDIX B - COMMAND LINE REFERENCE 302
CMake Command Line Options 302
Name 302
Usage 302
Description 302
Options 303
CMake Generators 308
CTest Command Line Options 312
CPack Command Line Options 317
CPack Generators 317
CHAPTER 15 APPENDIX C GENERATOR EXPRESSIONS 318
CMake Generator Expressions 319
viii
CHAPTER 16 APPENDIX D LISTFILE COMMANDS 321
Current Commands 321
Compatibility Commands 399
CHAPTER 17 APPENDIX E SELECTED MODULES 407
Standard CMake Modules 407
CHAPTER 18 APPENDIX F - PROPERTIES 583
CMake Properties - Properties supported by CMake, the Cross-Platform Makefile
Generator. 583
Properties of Global Scope 583
Properties on Directories 587
Properties on Targets 591
Properties on Tests 615
Properties on Source Files 617
Properties on Cache Entries 620
CHAPTER 19 APPENDIX G CMAKE POLICIES 623
CHAPTER 20 INDEX 635


Chapter 12

Tutorials

This chapter provides a step-by-step tutorial that covers common build system issues that
CMake helps address. Many of these topics have been introduced in prior chapters as separate
issues, but seeing how they all work together in an example project can be very helpful. This
tutorial can be found in the Tests/Tutorial directory of the CMake source code tree. Each step
has its own subdirectory containing a complete copy of the tutorial for that step.
A Basic Starting Point (Step 1)
The most basic project is an executable built from source code files. For simple projects, a
two line CMakeLists file is all that is required. This will be the starting point for our tutorial.
The CMakeLists file looks like:
cmake_mi ni mum_r equi r ed ( 2. 6)
pr oj ect ( Tut or i al )

add_execut abl e( Tut or i al t ut or i al . cxx)
Note that this example uses lower case commands in the CMakeLists file. Upper, lower, and
mixed case commands are supported by CMake. The source code for t ut or i al . cxx will
compute the square root of a number and the first version of it is very simple, as follows:
260 Tutorials
/ / A si mpl e pr ogr amt hat comput es t he squar e r oot of a number
#i ncl ude <st di o. h>
#i ncl ude <mat h. h>
i nt mai n ( i nt ar gc, char *ar gv[ ] )
{
i f ( ar gc < 2)
{
f pr i nt f ( st dout , " Usage: %s number \ n" , ar gv[ 0] ) ;
r et ur n 1;
}
doubl e i nput Val ue = at of ( ar gv[ 1] ) ;
doubl e out put Val ue = sqr t ( i nput Val ue) ;
f pr i nt f ( st dout , " The squar e r oot of %g i s %g\ n" ,
i nput Val ue, out put Val ue) ;
r et ur n 0;
}
Adding a Version Number and Configured Header File
The first feature we will add is to provide our executable and project with a version number.
While you can do this exclusively in the source code, doing it in the CMakeLists file provides
more flexibility. To add a version number we modify the CMakeLists file as follows:
cmake_mi ni mum_r equi r ed ( 2. 6)
pr oj ect ( Tut or i al )

# The ver si on number .
set ( Tut or i al _VERSI ON_MAJ OR 1)
set ( Tut or i al _VERSI ON_MI NOR 0)

# conf i gur e a header f i l e t o pass some of t he CMake set t i ngs
# t o t he sour ce code
conf i gur e_f i l e (
" ${PROJ ECT_SOURCE_DI R}/ Tut or i al Conf i g. h. i n"
" ${PROJ ECT_BI NARY_DI R}/ Tut or i al Conf i g. h"
)

# add t he bi nar y t r ee t o t he sear ch pat h f or i ncl ude f i l es
# so t hat we wi l l f i nd Tut or i al Conf i g. h
i ncl ude_di r ect or i es( " ${PROJ ECT_BI NARY_DI R}" )

# add t he execut abl e
add_execut abl e( Tut or i al t ut or i al . cxx)
A Basic Starting Point (Step 1) 261
Since the configured file will be written into the binary tree, we must add that directory to the
list of paths to search for include files. We then create a Tut or i al Conf i g. h. i n file in the
source tree with the following contents:
/ / t he conf i gur ed opt i ons and set t i ngs f or Tut or i al
#def i ne Tut or i al _VERSI ON_MAJ OR @Tut or i al _VERSI ON_MAJ OR@
#def i ne Tut or i al _VERSI ON_MI NOR @Tut or i al _VERSI ON_MI NOR@
When CMake configures this header file, the values for @Tut or i al _VERSI ON_MAJ OR@and
@Tut or i al _VERSI ON_MI NOR@will be replaced by the values from the CMakeLists file.
Next, we modify t ut or i al . cxx to include the configured header file and to make use of the
version numbers. The resulting source code is listed below.
/ / A si mpl e pr ogr amt hat comput es t he squar e r oot of a number
#i ncl ude <st di o. h>
#i ncl ude <mat h. h>
#i ncl ude " Tut or i al Conf i g. h"

i nt mai n ( i nt ar gc, char *ar gv[ ] )
{
i f ( ar gc < 2)
{
f pr i nt f ( st dout , " %s Ver si on %d. %d\ n" ,
ar gv[ 0] ,
Tut or i al _VERSI ON_MAJ OR,
Tut or i al _VERSI ON_MI NOR) ;
f pr i nt f ( st dout , " Usage: %s number \ n" , ar gv[ 0] ) ;
r et ur n 1;
}
doubl e i nput Val ue = at of ( ar gv[ 1] ) ;
doubl e out put Val ue = sqr t ( i nput Val ue) ;
f pr i nt f ( st dout , " The squar e r oot of %g i s %g\ n" ,
i nput Val ue, out put Val ue) ;
r et ur n 0;
}
The main changes are the inclusion of the Tut or i al Conf i g. h header file and printing out a
version number as part of the usage message.
262 Tutorials
Adding a Library (Step 2)
Now we will add a library to our project. This library will contain our own implementation for
computing the square root of a number. The executable can then use this library instead of the
standard square root function provided by the compiler. For this tutorial we will put the
library into a subdirectory called MathFunctions. It will have the following one line
CMakeLists file:
add_l i br ar y( Mat hFunct i ons mysqr t . cxx)
The source file mysqr t . cxx has one function called mysqr t that provides similar
functionality to the compilers sqr t function. To make use of the new library we add an
add_subdi r ect or y call in the top level CMakeLists file so that the library will get built.
We also add another include directory so that the Mat hFunct i ons/ mysqr t . h header file
can be found for the function prototype. The last change is to add the new library to the
executable. The last few lines of the top level CMakeLists file now look like:
i ncl ude_di r ect or i es ( " ${PROJ ECT_SOURCE_DI R}/ Mat hFunct i ons" )
add_subdi r ect or y ( Mat hFunct i ons)

# add t he execut abl e
add_execut abl e ( Tut or i al t ut or i al . cxx)
t ar get _l i nk_l i br ar i es ( Tut or i al Mat hFunct i ons)
Now, let us consider making the MathFunctions library optional. In this tutorial there really
isnt any reason to do so, but with larger libraries or libraries that rely on third party code you
might want to. The first step is to add an option to the top level CMakeLists file.
# shoul d we use our own mat h f unct i ons?
opt i on ( USE_MYMATH
" Use t ut or i al pr ovi ded mat h i mpl ement at i on" ON)
This will show up in the CMake GUI with a default value of ON that the user can change as
desired. This setting will be stored in the cache so that the user does not need to keep setting it
each time they run CMake on this project. The next change is to make the build and linking of
the MathFunctions library conditional. To do this we change the end of the top level
CMakeLists file to look like the following:


Adding a Library (Step 2) 263
# add t he Mat hFunct i ons l i br ar y?
#
i f ( USE_MYMATH)
i ncl ude_di r ect or i es ( " ${PROJ ECT_SOURCE_DI R}/ Mat hFunct i ons" )
add_subdi r ect or y ( Mat hFunct i ons)
set ( EXTRA_LI BS ${EXTRA_LI BS} Mat hFunct i ons)
endi f ( USE_MYMATH)

# add t he execut abl e
add_execut abl e ( Tut or i al t ut or i al . cxx)
t ar get _l i nk_l i br ar i es ( Tut or i al ${EXTRA_LI BS})
This uses the setting of USE_MYMATH to determine if the MathFunctions should be compiled
and used. Note the use of a variable (EXTRA_LI BS in this case) to collect up any optional
libraries to later be linked into the executable. This is a common approach used to keep larger
projects with many optional components clean. The corresponding changes to the source code
are fairly straight forward and leave us with:
/ / A si mpl e pr ogr amt hat comput es t he squar e r oot of a number
#i ncl ude <st di o. h>
#i ncl ude <mat h. h>
#i ncl ude " Tut or i al Conf i g. h"

#i f def USE_MYMATH
#i ncl ude " Mat hFunct i ons. h"
#endi f

i nt mai n ( i nt ar gc, char *ar gv[ ] )
{
i f ( ar gc < 2)
{
f pr i nt f ( st dout , " %s Ver si on %d. %d\ n" , ar gv[ 0] ,
Tut or i al _VERSI ON_MAJ OR,
Tut or i al _VERSI ON_MI NOR) ;
f pr i nt f ( st dout , " Usage: %s number \ n" , ar gv[ 0] ) ;
r et ur n 1;
}

doubl e i nput Val ue = at of ( ar gv[ 1] ) ;

#i f def USE_MYMATH
doubl e out put Val ue = mysqr t ( i nput Val ue) ;
#el se
264 Tutorials
doubl e out put Val ue = sqr t ( i nput Val ue) ;
#endi f

f pr i nt f ( st dout , " The squar e r oot of %g i s %g\ n" ,
i nput Val ue, out put Val ue) ;
r et ur n 0;
}
In the source code we make use of USE_MYMATH as well. This is provided from CMake to the
source code through the Tut or i al Conf i g. h. i n configured file by adding the following
line to it:
#cmakedef i ne USE_MYMATH
Installing and Testing (Step 3)
For the next step we will add install rules and testing support to our project. The install rules
are fairly straight forward. For the MathFunctions library we setup the library and the header
file to be installed by adding the following two lines to MathFunctions CMakeLists file:
i nst al l ( TARGETS Mat hFunct i ons DESTI NATI ON bi n)
i nst al l ( FI LES Mat hFunct i ons. h DESTI NATI ON i ncl ude)
For the application, the following lines are added to the top level CMakeLists file to install the
executable and the configured header file:
# add t he i nst al l t ar get s
i nst al l ( TARGETS Tut or i al DESTI NATI ON bi n)
i nst al l ( FI LES " ${PROJ ECT_BI NARY_DI R}/ Tut or i al Conf i g. h"
DESTI NATI ON i ncl ude)
That is all there is to it. At this point you should be able to build the tutorial, then type make
install (or build the I NSTALL target from an IDE), and it will install the appropriate header
files, libraries, and executables. The CMake variable CMAKE_I NSTALL_PREFI X is used to
determine the root of where the files will be installed. Adding testing is also a fairly straight
forward process. At the end of the top level CMakeLists file we can add a number of basic
tests to verify that the application is working correctly.

Installing and Testing (Step 3) 265
# does t he appl i cat i on r un
add_t est ( Tut or i al Runs Tut or i al 25)

# does i t sqr t of 25
add_t est ( Tut or i al Comp25 Tut or i al 25)

set _t est s_pr oper t i es ( Tut or i al Comp25
PROPERTI ES PASS_REGULAR_EXPRESSI ON " 25 i s 5" )

# does i t handl e negat i ve number s
add_t est ( Tut or i al Negat i ve Tut or i al - 25)
set _t est s_pr oper t i es ( Tut or i al Negat i ve
PROPERTI ES PASS_REGULAR_EXPRESSI ON " - 25 i s 0" )

# does i t handl e smal l number s
add_t est ( Tut or i al Smal l Tut or i al 0. 0001)
set _t est s_pr oper t i es ( Tut or i al Smal l
PROPERTI ES PASS_REGULAR_EXPRESSI ON " 0. 0001 i s 0. 01" )

# does t he usage message wor k?
add_t est ( Tut or i al Usage Tut or i al )
set _t est s_pr oper t i es ( Tut or i al Usage
PROPERTI ES
PASS_REGULAR_EXPRESSI ON " Usage: . *number " )
The first test simply verifies that the application runs, does not segfault or otherwise crash,
and has a zero return value. This is the basic form of a CTest test. The next few tests all make
use of the PASS_REGULAR_EXPRESSI ON test property to verify that the output of the test
contains certain strings, in this case: verifying that the computed square root is what it should
be and that the usage message is printed when an incorrect number of arguments are provided.
If you wanted to add a lot of tests to test different input values you might consider creating a
macro like the following:
#def i ne a macr o t o si mpl i f y addi ng t est s, t hen use i t
macr o ( do_t est ar g r esul t )
add_t est ( Tut or i al Comp${ar g} Tut or i al ${ar g})
set _t est s_pr oper t i es ( Tut or i al Comp${ar g}
PROPERTI ES PASS_REGULAR_EXPRESSI ON ${r esul t })
endmacr o ( do_t est )

# do a bunch of r esul t based t est s
do_t est ( 25 " 25 i s 5" )
do_t est ( - 25 " - 25 i s 0" )
266 Tutorials
For each invocation of do_t est , another test is added to the project with a name, input, and
results based on the passed arguments.
Adding System Introspection (Step 4)
Next let us consider adding some code to our project that depends on features the target
platform may not have. For this example we will add some code that depends on whether or
not the target platform has the l og and exp functions. Of course, almost every platform has
these functions, but for this tutorial assume that they are less common. If the platform has l og
then we will use that to compute the square root in the mysqr t function. We first test for the
availability of these functions using the CheckFunct i onExi st s. cmake macro in the top
level CMakeLists file as follows:
# does t hi s syst empr ovi de t he l og and exp f unct i ons?
i ncl ude ( CheckFunct i onExi st s. cmake)
check_f unct i on_exi st s ( l og HAVE_LOG)
check_f unct i on_exi st s ( exp HAVE_EXP)
Next we modify the Tut or i al Conf i g. h. i n to define those values if CMake found them on
the platform as follows:
/ / does t he pl at f or mpr ovi de exp and l og f unct i ons?
#cmakedef i ne HAVE_LOG
#cmakedef i ne HAVE_EXP
It is important that the tests for l og and exp are done before the conf i gur e_f i l e command
for Tut or i al Conf i g. h. The conf i gur e_f i l e command immediately configures the file
using the current settings in CMake. Finally, in the mysqr t function we can provide an
alternate implementation based on l og and exp if they are available on the system using the
following code:
/ / i f we have bot h l og and exp t hen use t hem
#i f def i ned ( HAVE_LOG) && def i ned ( HAVE_EXP)
r esul t = exp( l og( x) *0. 5) ;
#el se / / ot her wi se use an i t er at i ve appr oach
. . .
Adding a Generated File and Generator (Step 5) 267
Adding a Generated File and Generator (Step 5)
In this section we will show how you can add a generated source file into the build process of
an application. For this example, we will create a table of precomputed square roots as part of
the build process, and then compile that table into our application. To accomplish this we first
need a program that will generate the table. In the MathFunctions subdirectory a new source
file named MakeTabl e. cxx will do just that.
/ / A si mpl e pr ogr amt hat bui l ds a sqr t t abl e
#i ncl ude <st di o. h>
#i ncl ude <mat h. h>

i nt mai n ( i nt ar gc, char *ar gv[ ] )
{
i nt i ;
doubl e r esul t ;

/ / make sur e we have enough ar gument s
i f ( ar gc < 2)
{
r et ur n 1;
}

/ / open t he out put f i l e
FI LE *f out = f open( ar gv[ 1] , " w" ) ;
i f ( ! f out )
{
r et ur n 1;
}

/ / cr eat e a sour ce f i l e wi t h a t abl e of squar e r oot s
f pr i nt f ( f out , " doubl e sqr t Tabl e[ ] = {\ n" ) ;
f or ( i = 0; i < 10; ++i )
{
r esul t = sqr t ( st at i c_cast <doubl e>( i ) ) ;
f pr i nt f ( f out , " %g, \ n" , r esul t ) ;
}

/ / cl ose t he t abl e wi t h a zer o
f pr i nt f ( f out , " 0}; \ n" ) ;
f cl ose( f out ) ;
r et ur n 0;
}
268 Tutorials
Note that the table is produced as valid C++code and that the name of the file to write the
output to is passed in as an argument. The next step is to add the appropriate commands to
MathFunctions CMakeLists file to build the MakeTable executable, and then run it as part of
the build process. A few commands are needed to accomplish this, as shown below.
# f i r st we add t he execut abl e t hat gener at es t he t abl e
add_execut abl e( MakeTabl e MakeTabl e. cxx)

# add t he command t o gener at e t he sour ce code
add_cust om_command (
OUTPUT ${CMAKE_CURRENT_BI NARY_DI R}/ Tabl e. h
COMMAND MakeTabl e ${CMAKE_CURRENT_BI NARY_DI R}/ Tabl e. h
DEPENDS MakeTabl e
)

# add t he bi nar y t r ee di r ect or y t o t he sear ch pat h f or
# i ncl ude f i l es
i ncl ude_di r ect or i es( ${CMAKE_CURRENT_BI NARY_DI R} )

# add t he mai n l i br ar y
add_l i br ar y( Mat hFunct i ons mysqr t . cxx
${CMAKE_CURRENT_BI NARY_DI R}/ Tabl e. h )
First, the executable for MakeTabl e is added as any other executable would be added. Then
we add a custom command that specifies how to produce Tabl e. h by running MakeTable.
Next, we have to let CMake know that mysqr t . cxx depends on the generated file Tabl e. h.
This is done by adding the generated Tabl e. h to the list of sources for the library
MathFunctions. We also have to add the current binary directory to the list of include
directories so that Tabl e. h can be found and included by mysqr t . cxx.
When this project is built, it will first build the MakeTabl e executable. It will then run
MakeTabl e to produce Tabl e. h. Finally, it will compile mysqr t . cxx which includes
Tabl e. h to produce the MathFunctions library.
At this point the top level CMakeLists file with all the features we have added looks like the
following:
cmake_mi ni mum_r equi r ed ( 2. 6)
pr oj ect ( Tut or i al )

# The ver si on number .
set ( Tut or i al _VERSI ON_MAJ OR 1)
set ( Tut or i al _VERSI ON_MI NOR 0)
Adding a Generated File and Generator (Step 5) 269

# does t hi s syst empr ovi de t he l og and exp f unct i ons?
i ncl ude ( ${CMAKE_ROOT}/ Modul es/ CheckFunct i onExi st s. cmake)

check_f unct i on_exi st s ( l og HAVE_LOG)
check_f unct i on_exi st s ( exp HAVE_EXP)

# shoul d we use our own mat h f unct i ons
opt i on( USE_MYMATH
" Use t ut or i al pr ovi ded mat h i mpl ement at i on" ON)

# conf i gur e a header f i l e t o pass some of t he CMake set t i ngs
# t o t he sour ce code
conf i gur e_f i l e (
" ${PROJ ECT_SOURCE_DI R}/ Tut or i al Conf i g. h. i n"
" ${PROJ ECT_BI NARY_DI R}/ Tut or i al Conf i g. h"
)

# add t he bi nar y t r ee t o t he sear ch pat h f or i ncl ude f i l es
# so t hat we wi l l f i nd Tut or i al Conf i g. h
i ncl ude_di r ect or i es ( " ${PROJ ECT_BI NARY_DI R}" )

# add t he Mat hFunct i ons l i br ar y?
i f ( USE_MYMATH)
i ncl ude_di r ect or i es ( " ${PROJ ECT_SOURCE_DI R}/ Mat hFunct i ons" )
add_subdi r ect or y ( Mat hFunct i ons)
set ( EXTRA_LI BS ${EXTRA_LI BS} Mat hFunct i ons)
endi f ( USE_MYMATH)

# add t he execut abl e
add_execut abl e ( Tut or i al t ut or i al . cxx)
t ar get _l i nk_l i br ar i es ( Tut or i al ${EXTRA_LI BS})

# add t he i nst al l t ar get s
i nst al l ( TARGETS Tut or i al DESTI NATI ON bi n)
i nst al l ( FI LES " ${PROJ ECT_BI NARY_DI R}/ Tut or i al Conf i g. h"
DESTI NATI ON i ncl ude)

# does t he appl i cat i on r un
add_t est ( Tut or i al Runs Tut or i al 25)

# does t he usage message wor k?
add_t est ( Tut or i al Usage Tut or i al )
set _t est s_pr oper t i es ( Tut or i al Usage
PROPERTI ES
270 Tutorials
PASS_REGULAR_EXPRESSI ON " Usage: . *number "
)


#def i ne a macr o t o si mpl i f y addi ng t est s
macr o ( do_t est ar g r esul t )
add_t est ( Tut or i al Comp${ar g} Tut or i al ${ar g})
set _t est s_pr oper t i es ( Tut or i al Comp${ar g}
PROPERTI ES PASS_REGULAR_EXPRESSI ON ${r esul t }
)
endmacr o ( do_t est )

# do a bunch of r esul t based t est s
do_t est ( 4 " 4 i s 2" )
do_t est ( 9 " 9 i s 3" )
do_t est ( 5 " 5 i s 2. 236" )
do_t est ( 7 " 7 i s 2. 645" )
do_t est ( 25 " 25 i s 5" )
do_t est ( - 25 " - 25 i s 0" )
do_t est ( 0. 0001 " 0. 0001 i s 0. 01" )
TutorialConfig.h looks like:
/ / t he conf i gur ed opt i ons and set t i ngs f or Tut or i al
#def i ne Tut or i al _VERSI ON_MAJ OR @Tut or i al _VERSI ON_MAJ OR@
#def i ne Tut or i al _VERSI ON_MI NOR @Tut or i al _VERSI ON_MI NOR@
#cmakedef i ne USE_MYMATH

/ / does t he pl at f or mpr ovi de exp and l og f unct i ons?
#cmakedef i ne HAVE_LOG
#cmakedef i ne HAVE_EXP
and the CMakeLists file for MathFunctions looks like:
# f i r st we add t he execut abl e t hat gener at es t he t abl e
add_execut abl e( MakeTabl e MakeTabl e. cxx)
# add t he command t o gener at e t he sour ce code
add_cust om_command (
OUTPUT ${CMAKE_CURRENT_BI NARY_DI R}/ Tabl e. h
DEPENDS MakeTabl e
COMMAND MakeTabl e ${CMAKE_CURRENT_BI NARY_DI R}/ Tabl e. h
)
# add t he bi nar y t r ee di r ect or y t o t he sear ch pat h
Building an Installer (Step 6) 271
# f or i ncl ude f i l es
i ncl ude_di r ect or i es( ${CMAKE_CURRENT_BI NARY_DI R} )

# add t he mai n l i br ar y
add_l i br ar y( Mat hFunct i ons mysqr t . cxx
${CMAKE_CURRENT_BI NARY_DI R}/ Tabl e. h)

i nst al l ( TARGETS Mat hFunct i ons DESTI NATI ON bi n)
i nst al l ( FI LES Mat hFunct i ons. h DESTI NATI ON i ncl ude)
Building an Installer (Step 6)
Next, suppose that we want to distribute our project to other people so that they can use it. We
want to provide both binary and source distributions on a variety of platforms. This is a little
different from the install we did previously in section 0, where we were installing the binaries
that we had built from the source code. In this example, we will be building installation
packages that support binary installations and package management features as found in
cygwin, debian, RPMs etc. To accomplish this we will use CPack to create platform specific
installers as described in Chapter 9. Specifically, we need to add a few lines to the bottom of
our toplevel CMakeLists.txt file.
# bui l d a CPack dr i ven i nst al l er package
i ncl ude ( I nst al l Requi r edSyst emLi br ar i es)
set ( CPACK_RESOURCE_FI LE_LI CENSE
" ${CMAKE_CURRENT_SOURCE_DI R}/ Li cense. t xt " )
set ( CPACK_PACKAGE_VERSI ON_MAJ OR " ${Tut or i al _VERSI ON_MAJ OR}" )
set ( CPACK_PACKAGE_VERSI ON_MI NOR " ${Tut or i al _VERSI ON_MI NOR}" )
i ncl ude ( CPack)
That is all there is to it. We start by including InstallRequiredSystemLibraries. This module
will include any runtime libraries that are needed by the project for the current platform. Next,
we set some CPack variables to where we have stored the license and version information for
this project. The version information makes use of the variables we set earlier in this tutorial.
Finally, we include the CPack module which will use these variables and some other
properties of the system you are on to setup an installer.
The next step is to build the project in the usual manner and then run CPack on it. To build a
binary distribution, you would run:
cpack C CPackConf i g. cmake
272 Tutorials
To create a source distribution, you would type
cpack C CPackSour ceConf i g. cmake
Adding Support for a Dashboard (Step 7)
Adding support for submitting our test results to a dashboard is very easy. We already defined
a number of tests for our project in the earlier steps of this tutorial. We just have to run those
tests and submit them to a dashboard. To include support for dashboards, we include the
CTest module in our toplevel CMakeLists file.
# enabl e dashboar d scr i pt i ng
i ncl ude ( CTest )
We also create a CTest Conf i g. cmake file where we can specify the name of this project for
the dashboard.
set ( CTEST_PROJ ECT_NAME " Tut or i al " )
CTest will read in this file when it runs. To create a simple dashboard you can run CMake on
your project, change directory to the binary tree, and then run ctest -D Experimental. The
results of your dashboard will be uploaded to Kitware's public dashboard at:
ht t p: / / www. cdash. or g/ CDash/ i ndex. php?pr oj ect =Publ i cDashboar d



Index

Index
A
ALL_BUILD target, 14, 110
ANT, 4
assert, 40
autoconf, 3
converting to CMake, 121
B
batch commands, 105
binary packages, 150
Borland compiler, 5, 21, 23, 253
build
configurations, 32, 67
build platform, 125
building your project, 19
C
cache
advanced entries, 19, 30
documentation, 29
entries, 27, 29
find_* commands, 86
FORCE option, 19, 31
intializing, 18
predefined options, 30
purpose, 30
set command, 29
variable behavior, 31
case sensitivity, 9
ccmake. See running CMake
CDash, 197
adding notes, 208
automatic submissions, 209
backup, 233
client setup, 203
creating a new project, 199
email, 228
expected builds, 227
filtering errors/warnings, 206
logging, 232
mobile support, 233
server setup, 221
636 Index
sites, 229
specifying the server, 205
submitting results, 199
subprojects, 236
timing, 232
tutorial, 272
upgrading, 234
CMake
benefits, 1
command line, 302
compiler selection, 16
extending, 254
history, 3
plugin, 254
porting, 245
Structure, 21
syntax, 8, 33
tutorial, 259
versions, 43
CMake Commands, 8, 10, 34, 321
add_custom_command, 62, 10710, 111, 112,
113, 123
add_custom_target, 24, 110, 111, 112, 123
add_definitions, 88, 95, 96
add_dependencies, 81
add_executable, 10, 11, 24, 25, 34, 120, 193
add_library, 24, 25, 34, 120
add_subdirectory, 28, 34, 115, 116, 121
add_test, 38, 186, 187, 188, 192, 193
cmake_minimum_required, 43, 49, 217
cmake_policy, 49
configure_file, 97, 98, 121, 122
create_test_sourcelist, 192, 193
else, 10, 35
elseif, 35
endif, 10, 11, 35
exec_program, 119, 221
export, 81
file, 89, 116, 119
find_file, 29, 85
find_library, 11, 40, 85, 86
find_package, 46, 85, 92, 94, 95
find_path, 85, 86, 87
find_program, 85, 106
fltk_wrap_ui, 47
foreach, 29, 34, 37, 38, 39
function, 37, 39
get_filename_component, 193
get_property, 25, 26
get_source_file_property, 25
get_target_property, 24
if, 10, 11, 27, 34, 35, 36, 37, 40, 41
include, 28, 44, 94, 95
include_directories, 86, 99, 256
include_regular_expression, 82
install, 66, 68
link_libraries, 25, 62
load_command, 256
macro, 34, 37, 39, 40, 220
make_directory, 119
mark_as_advanced, 19, 30
message, 29, 121
option, 29, 95, 121
output_required_files, 82
project, 10, 34, 82, 119, 122, 246
remove, 193
return, 41
set, 10, 11, 19, 24, 27, 28, 29, 31, 34, 35
set_property, 25, 26
set_source_files_properties, 25, 46, 62
set_target_properties, 24, 65
set_tests_properties, 187, 188
source_group, 123
string, 41, 62
subdirs, 189
target_link_libraries, 25, 56, 60
try_compile, 85, 88, 89, 92, 122, 131
try_run, 85, 88, 89, 92
while, 34, 37, 38, 39
CMake Properties, 26
ADDITIONAL_MAKE_CLEAN_FILES, 26
COMPILE_DEFINITIONS, 96
COMPILE_DEFINITIONS_<CONFIG>, 97
COMPILE_FLAGS, 25
EXCLUDE_FROM_ALL, 26
GENERATED, 26
LABELS, 243
LINK_FLAGS, 25
list of, 27
LISTFILE_STACK, 26

OBJ ECT_DEPENDS, 26
CMake Variables
BUILD_SHARED_LIBS, 24
CMAKE_BUILD_TYPE, 32
CMAKE_BUILD_TYPE, 67
CMAKE_C_COMPILER, 17, 253
CMAKE_C_COMPILER_WORKS, 89
CMAKE_C_CREATE_SHARED_LIBRARY,
253
CMAKE_C_FLAGS, 17, 256
CMAKE_C_LINK_EXECUTABLE, 82
CMAKE_CFG_INTDIR, 32, 62
CMAKE_COMMAND, 106, 108, 209
CMAKE_CONFIGURATION_TYPES, 32
CMAKE_CROSSCOMPILING, 127
CMAKE_CTEST_COMMAND, 192
CMAKE_CURRENT_BINARY_DIR, 270, 271
CMAKE_CXX_COMPILE_OBJ ECT, 254
CMAKE_CXX_COMPILER, 17, 248, 249, 252,
253, 254
CMAKE_CXX_CREATE_SHARED_LIBRAR
Y, 248, 252, 253
CMAKE_CXX_CREATE_SHARED_MODUL
E, 253
CMAKE_CXX_CREATE_STATIC_LIBRARY,
249, 253, 254
CMAKE_CXX_FLAGS, 17, 32, 255
CMAKE_CXX_FLAGS_DEBUG, 249
CMAKE_CXX_FLAGS_DEBUG_INIT, 249
CMAKE_CXX_FLAGS_INIT, 249
CMAKE_CXX_FLAGS_MINSIZEREL, 249
CMAKE_CXX_FLAGS_MINSIZEREL_INIT,
249
CMAKE_CXX_FLAGS_RELEASE, 249
CMAKE_CXX_FLAGS_RELEASE_INIT, 249
CMAKE_CXX_FLAGS_RELWITHDEBINFO,
250
CMAKE_CXX_FLAGS_RELWITHDEBINFO_
INIT, 250
CMAKE_CXX_LINK_EXECUTABLE, 82, 253
CMAKE_DL_LIBS, 249
CMAKE_END_TEMP_FILE, 253, 254
CMAKE_FIND_ROOT_PATH, 129
CMAKE_GENERATOR, 192, 210
CMAKE_HOST_*, 130
CMAKE_INSTALL_COMPONENT, 75
CMAKE_INSTALL_PREFIX, 16, 67, 75
CMAKE_INSTALL_RPATH, 148
CMAKE_LIBRARY_PREFIX, 106
CMAKE_MAJ OR_VERSION, 43
CMAKE_MAKE_PROGRAM, 192
CMAKE_RANLIB, 252, 253
CMAKE_ROOT, 95, 256, 269
CMAKE_SHARED_LIBRARY_C_FLAGS, 253
CMAKE_SHARED_LIBRARY_CREATE_C_F
LAGS, 249
CMAKE_SHARED_LIBRARY_CREATE_CX
X_FLAGS, 248, 249, 252
CMAKE_SHARED_LIBRARY_RUNTIME_C_
FLAG, 249
CMAKE_SHARED_LIBRARY_RUNTIME_C_
FLAG_SEP, 249
CMAKE_SHARED_MODULE_PREFIX, 106
CMAKE_SKIP_RPATH, 64
CMAKE_START_TEMP_FILE, 253, 254
CMAKE_SYSTEM_NAME, 127, 245, 246, 249
CMAKE_SYSTEM_PROCESSOR, 127, 142
CMAKE_SYSTEM_VERSION, 127, 245
CMAKE_TOOLCHAIN_FILE, 126
CMAKE_VERSION, 43
LIBRARY_EXPORT, 61
PROJ ECT_BINARY_DIR, 119, 256
PROJ ECT_SOURCE_DIR, 37, 111, 256, 257,
262
WIN32, 10, 24, 61, 122
cmake-gui, 12, 14, 16, 30
pulldown option, 30
CMakeSetup. See cmake-gui
cmMakefile, 23, 24
code coverage, 199, 204
comments, 33
comparison, 36
compile flags, 25
compiler specification, 16
compilers, 5, 247
compiling CMake, 8
conditional statements, 34
configured header, 260, 264
converting autoconf projects to CMake, 121
converting Makefiles to CMake, 120
638 Index
converting Visual Studio projects, 122
copying files. See file
CPack, 149
command line, 317
components, 164
DESTDIR, 155
escape characters, 152
generators, 153
tutorial, 271
variables, 151
cross compiling, 125
hello world, 136
systemintrospection, 130
CTest, 189
advanced, 216
building tests, 191
command line, 312
options, 190
properties, 187
regular expressions, 188
running the tests, 189
tutorial, 264
variables, 215
CTest Commands
ctest_build, 217
ctest_build_command, 216
ctest_configure, 217
ctest_empty_binary_directory, 217
ctest_start, 217
ctest_submit, 217
ctest_test, 217
ctest_update, 217
customcommands, 105, 107
customtargets, 110
CVS, 212
cygwin, 150, 174
D
DART. See CDash
dashboards, 18, 185, 196, 198
Debian, 150, 183
declspec, 61
dependencies, 82
dependency analysis, 17, 26
DESTDIR, 75, 149, 155
directory installation, 72
directory structures, 11, 115
creating, 119
properties, 26
E
editing CMakeLists files, 18
Emacs modes, 18
embedded devices, 125
environment variables, 2, 10, 17, 64, 220
escape character, 33
executing programs, 120
F
file
COMPONENT, 67
copying, 106
exclude, 73
globbing, 119
installing, 66
OPTIONAL, 68
permissions, 67
properties, 25
regular expressions, 74
remove, 106
rename, 71
filtering errors and warnings, 206
final pass, 24
find modules. See modules
flags, 17, 25, 64
FLTK, 47, 143
fortran, 246
function, 34
functions, 39

G
generator, 16, 21, 23, 32, 210, 267
generator expressions, 107, 318, 319, 323, 329, 393,
394, 396, 594, 601, 605, 607, 632
Generator expressions, 318, 319
H
header files, configured, 97
hello world, 10, 136
history of CMake, 3
I
initial pass, 23
in-source build, 117
installation scripts, 75
installer, 271
installing CMake
Mac OS X, 7
UNIX, 7
Windows, 7
installing files. See files
J
J AM, 4
K
KDE, 3
L
languages, 34, 246, 251
LaTeX customtarget, 111
libraries, 59
API changes, 64
exporting, 80
importing, 78
installing prerequisites, 76
modules, 24
pitfalls, 63
rpath, 64
shared, 24
shared vs static, 59
soname, 64
static, 24, 25
versions, 64
library configurations, 56
linking
libraries, 54
systemlibraries, 55
Windows, 56
loaded commands, 254, 258
looping constructs, 34
M
Mac OS X
drag and drop installer, 179
Package Maker, 150, 177
relocatable applications, 76
Xcode. See Xcode
macros, 39
Makefiles, 21, 23, 32
build configurations, 32
microcontroller, 140
MinGW, 14, 143
modules, 44
find, 93
find <Package>Config.cmake, 93
find conventions, 93
systemintrospection, 87
modules, loadable. See libraries
N
NMake, 23
not found, 86
640 Index
NSIS, 150, 153, 156
Nullsoft Installer, 150
numeric comparison, 36
O
out-of-source build, 117
P
package configuration file, 99
platforms, 4, 246
PLEASE_FILL_OUT, 131
plugins, 59, 254, 255
policies, 48
scope, 50
setting, 48
support multiple versions, 53
portability issues, 105
portability of code, 87
porting CMake, 245
POSIX systems, 245
project
languages, 34
name, 34
properties. See CMake Properties
proxies, 206
purify, 82, 204, 207
Q
qmake, 4
Qt, 2, 46
Qt CMake user interface. See cmake-gui
R
regression testing, 185
regular expressions, 36, 4143, 82, 190
relocatable packages, 76, 150
removing files. See file
required package, 101
RPATH, 64, 148
RPM, 150, 184
rule variables, 251
running CMake, 11
ccmake, 14
cmake-gui, 11
command line, 16
S
SCons, 4
shared library. See libraries
shell commands, 105
source files, 25
generated, 109
source packages, 150, 154
subprojects, 240
SWIG, 2, 4546
syntax of CMake, 8, 33
systemintrospection, 266, See modules
T
target platform, 126
targets, 24
custom, 110
customcommands, 107
exporting, 79
importing, 78
properties, 25
testing, 185
toolchain file, 126
tutorial, 259
U
unit testing, 186
UNIX
libraries, 63

Makefiles. See Makefiles
symbols, 60
utility modules. See modules
V
valgrind, 204, 207
variable argument lists, 40
variable scope, 28
variables, 9, 27, 273
cache, 29
interaction with cache, 31
list, 29
PARENT_SCOPE, 28
rule, 251
scope, 39
types, 29
versions, 43
Vimmode, 18
Visual Studio, 3, 5, 14, 16, 18, 21, 23, 32, 34, 66,
107, 109, 110, 114, 117
converting to CMake, 122
file groups, 123
header files, 123
W
white space, 33
Windows
build directory, 119
CDash, 211
dllexport, 61
executables, 122
installers. See NSIS
linking, 56
manifest files, 164
registry entries, 2, 86
registry values, 10
relocatable applications, 76
run time libraries, 164
symbols, 60
WinMain, 24, 122
wrapping C/C++. See SWIG
X
Xcode, 3, 66