CMake Cross Pla orm Make

h p://www.cmake.org/cmake/help/cmake_tutorial.html

Search

PROJECT

RESOURCES

HELP

OPEN SOURCE

1 de 9

18/ !/" 1! ":18

CMake Cross Pla orm Make

h p://www.cmake.org/cmake/help/cmake_tutorial.html

CMake Tutorial
Step 5 6 Step 7 6 Step 8 6 Step 9 6 Step : 6 Step ; 6 Step < Below is a step-by-step tutorial coveri ! co""o i tro#uce# i buil# syste" issues that C$a%e helps to a##ress& $a y o' these topics have bee a e(a"ple pro)ect ca be very help'ul& This

Mastering CMake as separate issues but seei ! how they all wor% to!ether i

tutorial ca be 'ou # i

the Tests*Tutorial #irectory o' the C$a%e source co#e tree& Each step has its ow

sub#irectory co tai i ! a co"plete

copy o' the tutorial 'or that step&

A Basic Starting Point (Step 1)

The "ost basic pro)ect is a e(ecutable built 'ro" source co#e 'iles& +or si"ple pro)ects a two li e C$a%eLists 'ile is all that is re,uire#& This will be the starti ! poi t 'or our tutorial& The C$a%eLists 'ile loo%s li%ecmake_minimum_required (VERSION 2.6) project (Tutorial) add_executable(Tutorial tutorial.cxx) Note that this e(a"ple uses lower case co""a #s i the C$a%eLists 'ile& Upper. lower. a # "i(e# case co""a #s are supporte# by C$a%e&

The source co#e 'or tutorial&c(( will co"pute the s,uare root o' a u"ber a # the 'irst versio o' it is very si"ple. as 'ollows// A simple program that computes the square root of a number #include <stdio.h> #include <stdlib.h> #include <math.h> int main (int argc, char *argv[]) { if (argc < 2) { fprintf(stdout,"Usage: %s number\n",argv[0]); return 1; } double inputValue = atof(argv[1]); double outputValue = sqrt(inputValue); fprintf(stdout,"The square root of %g is %g\n", inputValue, outputValue); return 0; }

Adding a Version Number and Configured Header File

The 'irst 'eature we will a## is to provi#e our e(ecutable a # pro)ect with a versio co#e. #oi ! it i the C$a%eLists 'ile provi#es "ore 'le(ibility& To a## a versio u"ber& /hile you ca #o this e(clusively i the source

u"ber we "o#i'y the C$a%eLists 'ile as 'ollows-

cmake_minimum_required (VERSION 2.6) project (Tutorial) # The version number. set (Tutorial_VERSION_MAJOR 1) set (Tutorial_VERSION_MINOR 0)

# configure a header file to pass some of the CMake settings # to the source code configure_file ( "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" "${PROJECT_BINARY_DIR}/TutorialConfig.h" )

# add the binary tree to the search path for include files # so that we will find TutorialConfig.h include_directories("${PROJECT_BINARY_DIR}")

# add the executable add_executable(Tutorial tutorial.cxx) Si ce the co 'i!ure# 'ile will be writte the create a TutorialCo 'i!&h&i 'ile i i to the bi ary tree we "ust a## that #irectory to the list o' paths to search 'or i clu#e 'iles& /e

the source tree with the 'ollowi ! co te ts-

// the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ /he C$a%e co 'i!ures this hea#er 'ile the values 'or 0Tutorial12ERS3ON1$4JOR0 a # 0Tutorial12ERS3ON1$3NOR0 will be replace# by

" de 9

18/ !/" 1! ":18

CMake Cross Pla orm Make

h p://www.cmake.org/cmake/help/cmake_tutorial.html

the values 'ro" the C$a%eLists 'ile& Ne(t we "o#i'y tutorial&c(( to i clu#e the co 'i!ure# hea#er 'ile a # to "a%e use o' the versio u"bers& The resulti ! source co#e is liste# below& // A simple program that computes the square root of a number #include <stdio.h> #include <stdlib.h> #include <math.h> #include "TutorialConfig.h"

int main (int argc, char *argv[]) { if (argc < 2) { fprintf(stdout,"%s Version %d.%d\n", argv[0], Tutorial_VERSION_MAJOR, Tutorial_VERSION_MINOR); fprintf(stdout,"Usage: %s number\n",argv[0]); return 1; } double inputValue = atof(argv[1]); double outputValue = sqrt(inputValue); fprintf(stdout,"The square root of %g is %g\n", inputValue, outputValue); return 0; } The "ai cha !es are the i clusio o' the TutorialCo 'i!&h hea#er 'ile a # pri ti ! out a versio u"ber as part o' the usa!e "essa!e&

Adding a Library (Step 2)

Now we will a## a library to our pro)ect& This library will co tai e(ecutable ca the our ow i"ple"e tatio 'or co"puti ! the s,uare root o' a u"ber& The use this library i stea# o' the sta #ar# s,uare root 'u ctio provi#e# by the co"piler& +or this tutorial we will put the library i to a sub#irectory calle# $ath+u ctio s& 3t will have the 'ollowi ! o e li e C$a%eLists 'ileadd_library(MathFunctions mysqrt.cxx) The source 'ile "ys,rt&c(( has o e 'u ctio calle# "ys,rt that provi#es si"ilar 'u ctio ality to the co"piler=s s,rt 'u ctio & To "a%e use o' the top level C$a%eLists 'ile so that the library will !et built& /e also a## a other i clu#e be 'ou # 'or the 'u ctio prototype& The last cha !e is to a## the ew library

the ew library we a## a a##1sub#irectory call i

#irectory so that the $ath+u ctio s*"ys,rt&h hea#er 'ile ca

to the e(ecutable& The last 'ew li es o' the top level C$a%eLists 'ile ow loo% li%einclude_directories ("${PROJECT_SOURCE_DIR}/MathFunctions") add_subdirectory (MathFunctions)

# add the executable add_executable (Tutorial tutorial.cxx) target_link_libraries (Tutorial MathFunctions) Now let us co si#er "a%i ! the $ath+u ctio s library optio al& 3 this tutorial there really is =t a y reaso to #o so. but with lar!er libraries

or libraries that rely o thir# party co#e you "i!ht wa t to& The 'irst step is to a## a optio to the top level C$a%eLists 'ile& # should we use our own math functions? option (USE_MYMATH "Use tutorial provided math implementation" ON) This will show up i the C$a%e >U3 with a #e'ault value o' ON that the user ca ot ee# to %eep setti ! it each ti"e they ru cha !e as #esire#& This setti ! will be store# i the cache

so that the user #oes

C$a%e o this pro)ect& The e(t cha !e is to "a%e the buil# a # li %i !

o' the $ath+u ctio s library co #itio al& To #o this we cha !e the e # o' the top level C$a%eLists 'ile to loo% li%e the 'ollowi !# add the MathFunctions library? # if (USE_MYMATH) include_directories ("${PROJECT_SOURCE_DIR}/MathFunctions") add_subdirectory (MathFunctions) set (EXTRA_LIBS ${EXTRA_LIBS} MathFunctions) endif (USE_MYMATH)

# add the executable add_executable (Tutorial tutorial.cxx) target_link_libraries (Tutorial ${EXTRA_LIBS})

! de 9

18/ !/" 1! ":18

CMake Cross Pla orm Make

h p://www.cmake.org/cmake/help/cmake_tutorial.html

AEBTR41L3BS i

this caseC to collect up a y optio al libraries to later be li %e# i to the e(ecutable& This is a co""o approach use# to %eep
This website is lice se# u #er a Creative Co""o s 4ttributio -No?erivs 8&@ U porte# Lice se& 4##itio al i 'or"atio o this lice se ca be 'ou # here&

lar!er pro)ects with "a y optio al co"po e ts clea & The correspo #i ! cha !es to the source co#e are 'airly strai!ht 'orwar# a # leave us with// A simple program that computes the square root of a number #include <stdio.h> #include <stdlib.h> #include <math.h> #include "TutorialConfig.h" #ifdef USE_MYMATH #include "MathFunctions.h" #endif

int main (int argc, char *argv[]) { if (argc < 2) { fprintf(stdout,"%s Version %d.%d\n", argv[0], Tutorial_VERSION_MAJOR, Tutorial_VERSION_MINOR); fprintf(stdout,"Usage: %s number\n",argv[0]); return 1; }

double inputValue = atof(argv[1]);

#ifdef USE_MYMATH double outputValue = mysqrt(inputValue); #else double outputValue = sqrt(inputValue); #endif

fprintf(stdout,"The square root of %g is %g\n", inputValue, outputValue); return 0; } 3 the source co#e we "a%e use o' USE1$D$4TH as well& This is provi#e# 'ro" C$a%e to the source co#e throu!h the TutorialCo 'i!&h&i

co 'i!ure# 'ile by a##i ! the 'ollowi ! li e to it#cmakedefine USE_MYMATH

Installing and Testing (Step )

+or the e(t step we will a## i stall rules a # testi ! support to our pro)ect& The i stall rules are 'airly strai!ht 'orwar#& +or the $ath+u ctio s library we setup the library a # the hea#er 'ile to be i stalle# by a##i ! the 'ollowi ! two li es to $ath+u ctio s= C$a%eLists 'ileinstall (TARGETS MathFunctions DESTINATION bin) install (FILES MathFunctions.h DESTINATION include) +or the applicatio the 'ollowi ! li es are a##e# to the top level C$a%eLists 'ile to i stall the e(ecutable a # the co 'i!ure# hea#er 'ile# add the install targets install (TARGETS Tutorial DESTINATION bin) install (FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" DESTINATION include) That is all there is to it& 4t this poi t you shoul# be able to buil# the tutorial. the type "a%e i stall Aor buil# the 3NST4LL tar!et 'ro" a

3?EC a # it will i stall the appropriate hea#er 'iles. libraries. a # e(ecutables& The C$a%e variable C$4EE13NST4LL1PRE+3B is use# to #eter"i e the root o' where the 'iles will be i stalle#& 4##i ! testi ! is also a 'airly strai!ht 'orwar# process& 4t the e # o' the top level C$a%eLists 'ile we ca a## a u"ber o' basic tests to veri'y that the applicatio is wor%i ! correctly& # does the application run add_test (TutorialRuns Tutorial 25)

# does it sqrt of 25 add_test (TutorialComp25 Tutorial 25)

set_tests_properties (TutorialComp25

# de 9

18/ !/" 1! ":18

CMake Cross Pla orm Make

h p://www.cmake.org/cmake/help/cmake_tutorial.html

# does it handle negative numbers add_test (TutorialNegative Tutorial -25) set_tests_properties (TutorialNegative PROPERTIES PASS_REGULAR_EXPRESSION "-25 is 0")

# does it handle small numbers add_test (TutorialSmall Tutorial 0.0001) set_tests_properties (TutorialSmall PROPERTIES PASS_REGULAR_EXPRESSION "0.0001 is 0.01")

# does the usage message work? add_test (TutorialUsage Tutorial) set_tests_properties (TutorialUsage PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number") The 'irst test si"ply veri'ies that the applicatio 'or" o' a CTest test& The co tai s certai whe a stri !s& 3 ru s. #oes ot se!'ault or otherwise crash. a # has a Fero retur value& This is the basic

e(t 'ew tests all "a%e use o' the P4SS1RE>UL4R1EBPRESS3ON test property to veri'y that the output o' the test this case veri'yi ! that the co"pute# s,uare root is what it shoul# be a # that the usa!e "essa!e is pri te#

i correct

u"ber o' ar!u"e ts are provi#e#& 3' you wa te# to a## a lot o' tests to test #i''ere t i put values you "i!ht co si#er

creati ! a "acro li%e the 'ollowi !#define a macro to simplify adding tests, then use it macro (do_test arg result) add_test (TutorialComp${arg} Tutorial ${arg}) set_tests_properties (TutorialComp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result}) endmacro (do_test)

# do a bunch of result based tests do_test (25 "25 is 5") do_test (-25 "-25 is 0") +or each i vocatio o' #o1test. a other test is a##e# to the pro)ect with a a"e. i put. a # results base# o the passe# ar!u"e ts&

Adding Syste! Introspection (Step ")

Ne(t let us co si#er a##i ! so"e co#e to our pro)ect that #epe #s o a## so"e co#e that #epe #s o whether or 'eatures the tar!et plat'or" "ay ot have& +or this e(a"ple we will ot the tar!et plat'or" has the lo! a # e(p 'u ctio s& O' course al"ost every plat'or" has we will use that to co"pute the s,uare the top level these 'u ctio s but 'or this tutorial assu"e that they are less co""o & 3' the plat'or" has lo! the root i

the "ys,rt 'u ctio & /e 'irst test 'or the availability o' these 'u ctio s usi ! the Chec%+u ctio E(ists&c"a%e "acro i

C$a%eLists 'ile as 'ollows# does this system provide the log and exp functions? include (CheckFunctionExists.cmake) check_function_exists (log HAVE_LOG) check_function_exists (exp HAVE_EXP) Ne(t we "o#i'y the TutorialCo 'i!&h&i to #e'i e those values i' C$a%e 'ou # the" o the plat'or" as 'ollows-

// does the platform provide exp and log functions? #cmakedefine HAVE_LOG #cmakedefine HAVE_EXP 3t is i"porta t that the tests 'or lo! a # e(p are #o e be'ore the co 'i!ure1'ile co""a # 'or TutorialCo 'i!&h& The co 'i!ure1'ile co""a # i""e#iately co 'i!ures the 'ile usi ! the curre t setti !s i C$a%e& +i ally i the "ys,rt 'u ctio we ca provi#e a alter ate

i"ple"e tatio base# o lo! a # e(p i' they are available o the syste" usi ! the 'ollowi ! co#e// if we have both log and exp then use them #if defined (HAVE_LOG) && defined (HAVE_EXP) result = exp(log(x)*0.5); #else // otherwise use an iterative approach . . .

Adding a #enerated $ile and #enerator (Step %)

3 this sectio we will show how you ca a## a !e erate# source 'ile i to the buil# process o' a applicatio & +or this e(a"ple we will create co"pile that table i to our applicatio & To acco"plish this we ew source 'ile a"e# $a%eTable&c(( will #o )ust a table o' preco"pute# s,uare roots as part o' the buil# process. a # the 'irst that& ee# a pro!ra" that will !e erate the table& 3 the $ath+u ctio s sub#irectory a

$ de 9

18/ !/" 1! ":18

CMake Cross Pla orm Make

h p://www.cmake.org/cmake/help/cmake_tutorial.html

// A simple program that builds a sqrt table #include <stdio.h> #include <stdlib.h> #include <math.h>

int main (int argc, char *argv[]) { int i; double result;

// make sure we have enough arguments if (argc < 2) { return 1; }

// open the output file FILE *fout = fopen(argv[1],"w"); if (!fout) { return 1; }

// create a source file with a table of square roots fprintf(fout,"double sqrtTable[] = {\n"); for (i = 0; i < 10; ++i) { result = sqrt(static_cast<double>(i)); fprintf(fout,"%g,\n",result); }

// close the table with a zero fprintf(fout,"0};\n"); fclose(fout); return 0; } Note that the table is pro#uce# as vali# CGG co#e a # that the a"e o' the 'ile to write the output to is passe# i as a ar!u"e t& The e(t it as part o' the

step is to a## the appropriate co""a #s to $ath+u ctio s= C$a%eLists 'ile to buil# the $a%eTable e(ecutable. a # the ru buil# process& 4 'ew co""a #s are ee#e# to acco"plish this. as show # first we add the executable that generates the table add_executable(MakeTable MakeTable.cxx) below&

# add the command to generate the source code add_custom_command ( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h DEPENDS MakeTable )

# add the binary tree directory to the search path for # include files include_directories( ${CMAKE_CURRENT_BINARY_DIR} )

# add the main library add_library(MathFunctions mysqrt.cxx ${CMAKE_CURRENT_BINARY_DIR}/Table.h ) we a## a custo" co""a # that speci'ies how to the !e erate# 'ile Table&h& This is #o e

+irst the e(ecutable 'or $a%eTable is a##e# as a y other e(ecutable woul# be a##e#& The pro#uce Table&h by ru

i ! $a%eTable& Ne(t we have to let C$a%e % ow that "ys,rt&c(( #epe #s o

by a##i ! the !e erate# Table&h to the list o' sources 'or the library $ath+u ctio s& /e also have to a## the curre t bi ary #irectory to the list o' i clu#e #irectories so that Table&h ca be 'ou # a # i clu#e# by "ys,rt&c((& /he this pro)ect is built it will 'irst buil# the $a%eTable e(ecutable& 3t will the ru $a%eTable to pro#uce Table&h& +i ally. it will co"pile

"ys,rt&c(( which i clu#es Table&h to pro#uce the $ath+u ctio s library& 4t this poi t the top level C$a%eLists 'ile with all the 'eatures we have a##e# loo%s li%e the 'ollowi !cmake_minimum_required (VERSION 2.6)

% de 9

18/ !/" 1! ":18

CMake Cross Pla orm Make

h p://www.cmake.org/cmake/help/cmake_tutorial.html

project (Tutorial)

# The version number. set (Tutorial_VERSION_MAJOR 1) set (Tutorial_VERSION_MINOR 0)

# does this system provide the log and exp functions? include (${CMAKE_ROOT}/Modules/CheckFunctionExists.cmake)

check_function_exists (log HAVE_LOG) check_function_exists (exp HAVE_EXP)

# should we use our own math functions option(USE_MYMATH "Use tutorial provided math implementation" ON)

# configure a header file to pass some of the CMake settings # to the source code configure_file ( "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" "${PROJECT_BINARY_DIR}/TutorialConfig.h" )

# add the binary tree to the search path for include files # so that we will find TutorialConfig.h include_directories ("${PROJECT_BINARY_DIR}")

# add the MathFunctions library? if (USE_MYMATH) include_directories ("${PROJECT_SOURCE_DIR}/MathFunctions") add_subdirectory (MathFunctions) set (EXTRA_LIBS ${EXTRA_LIBS} MathFunctions) endif (USE_MYMATH)

# add the executable add_executable (Tutorial tutorial.cxx) target_link_libraries (Tutorial ${EXTRA_LIBS})

# add the install targets install (TARGETS Tutorial DESTINATION bin) install (FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" DESTINATION include)

# does the application run add_test (TutorialRuns Tutorial 25)

# does the usage message work? add_test (TutorialUsage Tutorial) set_tests_properties (TutorialUsage PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" )

#define a macro to simplify adding tests macro (do_test arg result) add_test (TutorialComp${arg} Tutorial ${arg}) set_tests_properties (TutorialComp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) endmacro (do_test)

# do a bunch of result based tests do_test (4 "4 is 2") do_test (9 "9 is 3") do_test (5 "5 is 2.236") do_test (7 "7 is 2.645")

& de 9

18/ !/" 1! ":18

CMake Cross Pla orm Make

h p://www.cmake.org/cmake/help/cmake_tutorial.html

do_test (25 "25 is 5") do_test (-25 "-25 is 0") do_test (0.0001 "0.0001 is 0.01") TutorialCo 'i!&h loo%s li%e// the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ #cmakedefine USE_MYMATH

// does the platform provide exp and log functions? #cmakedefine HAVE_LOG #cmakedefine HAVE_EXP 4 # the C$a%eLists 'ile 'or $ath+u ctio s loo%s li%e# first we add the executable that generates the table add_executable(MakeTable MakeTable.cxx) # add the command to generate the source code add_custom_command ( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h DEPENDS MakeTable COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h ) # add the binary tree directory to the search path # for include files include_directories( ${CMAKE_CURRENT_BINARY_DIR} )

# add the main library add_library(MathFunctions mysqrt.cxx ${CMAKE_CURRENT_BINARY_DIR}/Table.h)

install (TARGETS MathFunctions DESTINATION bin) install (FILES MathFunctions.h DESTINATION include)

Building an Installer (Step &)

Ne(t suppose that we wa t to #istribute our pro)ect to other people so that they ca #istributio s o use it& /e wa t to provi#e both bi ary a # source sectio 3 stalli ! a # Testi ! AStep 8C. pac%a!es that a variety o' plat'or"s& This is a little #i''ere t 'ro" the i stal we #i# previously i where we were i stalli ! the bi aries that we ha# built 'ro" the source co#e& 3 support bi ary i stallatio s a # pac%a!e "a a!e"e t 'eatures as 'ou # i to create plat'or" speci'ic i stallers as #escribe# i our toplevel C$a%eLists&t(t 'ile& # build a CPack driven installer package include (InstallRequiredSystemLibraries) set (CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") set (CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") set (CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") include (CPack) That is all there is to it& /e start by i clu#i ! 3 stallRe,uire#Syste"Libraries& This "o#ule will i clu#e a y ru ti"e libraries that are ee#e# by the pro)ect 'or the curre t plat'or"& Ne(t we set so"e CPac% variables to where we have store# the lice se a # versio this pro)ect& The versio i 'or"atio "a%es use o' the variables we set earlier i i 'or"atio 'or this e(a"ple we will be buil#i ! i stallatio

cy!wi . #ebia . RP$s etc& To acco"plish this we will use CPac% ee# to a## a 'ew li es to the botto" o'

Chapter Pac%a!i ! with CPac%& Speci'ically we

this tutorial& +i ally we i clu#e the CPac% "o#ule which will

use these variables a # so"e other properties o' the syste" you are o to setup a i staller& The e(t step is to buil# the pro)ect i cpack -C CPackConfig.cmake To create a source #istributio you woul# type cpack -C CPackSourceConfig.cmake the usual "a er a # the ru CPac% o it& To buil# a bi ary #istributio you woul# ru -

Adding Support 'or a (as)board (Step *)

4##i ! support 'or sub"itti ! our test results to a #ashboar# is very easy& /e alrea#y #e'i e# a earlier steps o' this tutorial& /e )ust have to ru the CTest "o#ule i our toplevel C$a%eLists 'ile& u"ber o' tests 'or our pro)ect i the those tests a # sub"it the" to a #ashboar#& To i clu#e support 'or #ashboar#s we i clu#e

8 de 9

18/ !/" 1! ":18

CMake Cross Pla orm Make

h p://www.cmake.org/cmake/help/cmake_tutorial.html

include (CTest) /e also create a CTestCo 'i!&c"a%e 'ile where we ca speci'y the a"e o' this pro)ect 'or the #ashboar#& set (CTEST_PROJECT_NAME "Tutorial") CTest will rea# i tree. a # the ru this 'ile whe it ru s& To create a si"ple #ashboar# you ca ru C$a%e o your pro)ect. cha !e #irectory to the bi ary

ctest H? E(peri"e tal& The results o' your #ashboar# will be uploa#e# to EitwareIs public #ashboar# here&

9 de 9

18/ !/" 1! ":18