CMake – Cross-Platform, Effective Build System

CMake – Cross-Platform, Effective Build System

King, 2011/4/18

Classification 4/18/2011

1

Build Systems under different OS • Windows – Microsoft Visual Studio – Other IDES ** •

Linux/FreeBSD

– Custom GNU/Makefiles – Autotools (autoconf/automake)

• MacOS – Xcode

GNU Build System Developer

User

source codes autoconf

configure

./configure

autoscan Check necessary libraries and generate Makefile

configure.ac

aclocal

aclocal.m4 Makefile

Makefile.am

autoheader

config.h.in

Use make to build & install

automake

Makefile.in

make install

• • • •

If need to build cross-platform project… MS VS just work on Windows… Makefiles don’t work on Windows… Autotools is a little complicated… Xcode just work for Apple System…

So You have to – Use different build system under different platform?

Or – Other solution?

CMake • Open Source with complete online reference manual • One configuration, run every platform – Windows, Linux/BSD, MacOS

• Can generate build control/project files – Windows: MS VS workspace – Linux/BSD: Makefile/KDevelop – MacOS: XCode

• Simple Script Syntax to allow customization • Used by Many Large Projects – – – –

KDE4 (switch to CMake since 1996) Boost MySQL Others: http://www.cmake.org/Wiki/CMake_Projects

CMake Build System Cmake Build System

CMakeLists.txt

cmake

Executables & Libraries

Native Build System

Native Build Tools

Source Tree Structure Folder to place 3rd package

Folder to place generated executables Folder to place generated libraries Folder to place build script/cache Folder to place source codes

Each module,executable and src folder need CMakeLists.txt file. src/CMakeLists.txt module1/CMakeLists.txt module2/CMakeLists.txt main_executable/CMakeLists.txt

Using CMake -- Command • Create a build directory (“out-of-source-build” concept) – mkdir make ; cd make

• Configure the package for your system: – cmake [options]

• Build the package: – make

• Install it: – make install

• The last 2 steps can be merged into one (just “make install”)

Using CMake -- GUI • Modify configure by UI – Windows: CMakeSetup – Linux/BSD: ccmake

CMakeLists.txt Files • Very simple syntax: – – – – –

# This is a comment Commands syntax: COMMAND( arg1 arg2 ... ) Lists A;B;C # semi-colon separated values Variables ${VAR} Conditional constructs • IF() ... ELSE()/ELSEIF() ... ENDIF() • Very useful: IF( APPLE ); IF( UNIX ); IF( WIN32 )

– WHILE() ... ENDWHILE() – FOREACH() ... ENDFOREACH() – Regular expressions (check CMake FAQ for details...)

CMakeLists.txt Files (Cont.) • • • • • • • • • • • •

INCLUDE_DIRECTORIES( “dir1” “dir2” ... ) AUX_SOURCE_DIRECTORY( “source” ) ADD_EXECUTABLE ADD_LIBRARY ADD_CUSTOM_TARGET ADD_DEPENDENCIES( target1 t2 t3 ) # target1 depends on t2 and t3 ADD_DEFINITIONS( “-Wall -ansi -pedantic”) TARGET_LINK_LIBRARIES( target-name lib1 lib2 ...) # Individual settings for each target LINK_LIBRARIES( lib1 lib2 ...) # All targets link with the same set of libs SET_TARGET_PROPERTIES( ... ) # lots of properties... OUTPUT_NAME, VERSION, .... MESSAGE( STATUS|FATAL_ERROR “message” ) INSTALL( FILES “f1” “f2” “f3” DESTINATION . ) – – DESTINATION relative to ${CMAKE_INSTALL_PREFIX}

CMakeLists.txt Files (Cont.) • • • • • • • • • • •

SET( VAR value [CACHE TYPE DOCSTRING [FORCE]]) LIST( APPEND|INSERT|LENGTH|GET|REMOVE_ITEM|REMOVE_AT|SORT ...) STRING( TOUPPER|TOLOWER|LENGTH|SUBSTRING|REPLACE|REGEX ...) SEPARATE_ARGUMENTS( VAR ) # convert space separated string to list FILE( WRITE | READ | APPEND | GLOB | GLOB_RECURSE | REMOVE | MAKE_DIRECTORY ...) FIND_FILE FIND_LIBRARY FIND_PROGRAM FIND_PACKAGE EXEC_PROGRAM( bin [work_dir] ARGS [OUTPUT_VARIABLE var] [RETURN_VALUE var] ) ● OPTION( OPTION_VAR “description string” *initial value+ )

CMake Tutorial • Set Project Information • Add preprocesser macro and flag for different Platform • Check 3rd Package

• Generate libraries (sub modules) • Generate executable

CMakeList.txt Template (Top Level) • • • •

##-----------------------------------------------------------------------------------## set minimum required version number of cmake ##-----------------------------------------------------------------------------------CMAKE_MINIMUM_REQUIRED(VERSION 2.8)

• • • •

##-----------------------------------------------------------------------------------## set the project name ##-----------------------------------------------------------------------------------PROJECT(TEST_PROJECT)

• • • • •

##-----------------------------------------------------------------------------------## set the version of generated libraries ##-----------------------------------------------------------------------------------SET (PROJECT_LIB_VERSION 1.0) SET (PROJECT_LIB_SOVERSION 1)

• • • • •

##-----------------------------------------------------------------------------------## set the folder to hold target binary/libraries ##-----------------------------------------------------------------------------------SET (PROJECT_OUTPUT_BIN_DIR ${PROJECT_SOURCE_DIR}/../bin) SET (PROJECT_OUTPUT_LIB_DIR ${PROJECT_SOURCE_DIR}/../lib)

• • • • • •

CMakeList.txt Template (Top Level) cont. ##-----------------------------------------------------------------------------------## add preprocesser macro and compile flag for different platform ##-----------------------------------------------------------------------------------IF (CMAKE_SYSTEM_NAME STREQUAL "Windows") ADD_DEFINITIONS(-DDEBUG) SET (CMAKE_CXX_FLAGS "-O2")

• • •

ELSEIF (CMAKE_SYSTEM_NAME STREQUAL "FreeBSD") ADD_DEFINITIONS(-DFreeBSD -DDEBUG) SET (CMAKE_CXX_FLAGS "-g -Wall -O0")

• • •

ELSEIF (CMAKE_SYSTEM_NAME STREQUAL "Linux") ADD_DEFINITIONS(-DLinux -DDEBUG) SET (CMAKE_CXX_FLAGS "-g -Wall -O0")

• •

ELSE (CMAKE_SYSTEM_NAME STREQUAL "Windows") MESSAGE(STATUS "[INFO] Not supported OS: " ${CMAKE_SYSTEM_NAME})

•

ENDIF (CMAKE_SYSTEM_NAME STREQUAL "Windows")

• • • • • • • • • • • • • • • • • • •

CMakeList.txt Template (Top Level) cont. ##-----------------------------------------------------------------------------------## check if exist 3rd package: STLSoft ##-----------------------------------------------------------------------------------INCLUDE(FindSTLSoft.cmake) IF (NOT STLSOFT_FOUND) SET(STLSOFT_MAKE_DIR "${PROJECT_SOURCE_DIR}\\..\\3rd_package\\stlsoft") IF (CMAKE_SYSTEM_NAME STREQUAL "Windows") STRING(REPLACE / \\ STLSOFT_MAKE_DIR "${STLSOFT_MAKE_DIR}") ADD_CUSTOM_COMMAND ( OUTPUT stlsoft COMMAND chdir /d "${STLSOFT_MAKE_DIR}" && make\\build.bat) ADD_CUSTOM_TARGET (stlsoft__TARGET DEPENDS stlsoft) ELSE (CMAKE_SYSTEM_NAME STREQUAL "Windows") ADD_CUSTOM_COMMAND ( OUTPUT stlsoft COMMAND cd STLSOFT_MAKE_DIR && ./make/build.sh) ADD_CUSTOM_TARGET (stlsoft__TARGET ALL DEPENDS stlsoft) ENDIF (CMAKE_SYSTEM_NAME STREQUAL "Windows") ENDIF (NOT STLSOFT_FOUND)

CMakeList.txt Template (Top Level) cont.

• • • • • • • • • • • •

##-----------------------------------------------------------------------------------## add depended modules folders and compile them ##-----------------------------------------------------------------------------------SET (LOCAL_LIB_LIST module1 module2 )

• • • •

##-----------------------------------------------------------------------------------## add executable folder to compile it ##-----------------------------------------------------------------------------------ADD_SUBDIRECTORY(${PROJECT_SOURCE_DIR}/main_executable)

## add local generated libraries to compile FOREACH (LIB_NAME ${LOCAL_LIB_LIST}) ADD_SUBDIRECTORY(${PROJECT_SOURCE_DIR}/${LIB_NAME}) ENDFOREACH(LIB_NAME ${LOCAL_LIB_LIST})

CMakeList.txt Template (Library) • • • •

##-----------------------------------------------------------------------------------## set the module name, the name MUST be same as the folder name ##-----------------------------------------------------------------------------------SET (TARGET_NAME module1)

• • • •

##-----------------------------------------------------------------------------------## add header file folder to compile this module ##-----------------------------------------------------------------------------------INCLUDE_DIRECTORIES(include)

• • • •

##-----------------------------------------------------------------------------------## set the source files list ##-----------------------------------------------------------------------------------AUX_SOURCE_DIRECTORY(src SRC_LIST)

• • • •

##-----------------------------------------------------------------------------------## set the target path for generate library ##-----------------------------------------------------------------------------------SET(LIBRARY_OUTPUT_PATH ${PROJECT_OUTPUT_LIB_DIR})

CMakeList.txt Template (Library) Cont. • • • • • • • • • • • • • • • • • •

##-----------------------------------------------------------------------------------## set the install target and create shared library: .so for non-windows ##-----------------------------------------------------------------------------------IF (CMAKE_SYSTEM_NAME STREQUAL "Windows") ## for windows, just create .lib ADD_LIBRARY(${TARGET_NAME} STATIC ${SRC_LIST}) INSTALL(TARGETS ${TARGET_NAME} ARCHIVE DESTINATION lib) ELSE (CMAKE_SYSTEM_NAME STREQUAL "Windows") ## for non-windows, will create both .a and .so ADD_LIBRARY(${TARGET_NAME}_static STATIC ${SRC_LIST}) SET_TARGET_PROPERTIES(${TARGET_NAME}_static PROPERTIES OUTPUT_NAME ${TARGET_NAME}) ADD_LIBRARY(${TARGET_NAME} SHARED ${SRC_LIST}) SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES VERSION 1.0 SOVERSION 1) INSTALL(TARGETS ${TARGET_NAME} ${TARGET_NAME}_static LIBRARY DESTINATION lib ARCHIVE DESTINATION lib) ENDIF (CMAKE_SYSTEM_NAME STREQUAL "Windows")

CMakeList.txt Template (Executable) • • • • • • • • • •

##-----------------------------------------------------------------------------------## add header file folder to compile this module ##-----------------------------------------------------------------------------------INCLUDE_DIRECTORIES(include) INCLUDE_DIRECTORIES(${PROJECT_SOURCE_DIR}/../3rd_package/stlsoft/include)

• • • • • • • •

##-----------------------------------------------------------------------------------## set the source files. ##-----------------------------------------------------------------------------------AUX_SOURCE_DIRECTORY(src SRC_LIST) ##-----------------------------------------------------------------------------------## set the output folder. ##-----------------------------------------------------------------------------------SET (EXECUTABLE_OUTPUT_PATH ${PROJECT_OUTPUT_BIN_DIR})

## check if set the library folder, if yes, use such folder as link folder IF(DEFINED PROJECT_OUTPUT_LIB_DIR) LINK_DIRECTORIES(${PROJECT_OUTPUT_LIB_DIR}) ENDIF(DEFINED PROJECT_OUTPUT_LIB_DIR)

CMakeList.txt Template (Executable) Cont. • • • •

##-----------------------------------------------------------------------------------## let cmake compile the target ##-----------------------------------------------------------------------------------ADD_EXECUTABLE(${TARGET_NAME} ${SRC_LIST})

• • • •

##-----------------------------------------------------------------------------------## set the link library: -llibrary ##-----------------------------------------------------------------------------------TARGET_LINK_LIBRARIES(${TARGET_NAME} ${LINK_LOCAL_LIB_LIST} ${LINK_SYSTEM_LIB_LIST})

• • • •

##-----------------------------------------------------------------------------------## add dependencies ##-----------------------------------------------------------------------------------ADD_DEPENDENCIES(${TARGET_NAME} ${LINK_LOCAL_LIB_LIST} stlsoft__TARGET)

• • • • •

##-----------------------------------------------------------------------------------## set install parth ##-----------------------------------------------------------------------------------INSTALL(TARGETS ${TARGET_NAME} RUNTIME DESTINATION bin)

Work Together

Demo

Summary  Build System  CMake Introduction  CMake Tutorial

Classification 4/18/2011

23

Q&A

THANK YOU!

Classification 4/18/2011

25

Classification 4/18/2011

26

Reference •

[1] CMake: http://www.cmake.org/ – Include: Document, Wiki, FAQ, etc • [2] CMake Tutorial, Jan Engels, 2007 • [3] 猫也会的CMake, Jim Huang, 2008 • [4] CMake - Cross-Platform Make, R. Douglas Barbieri, 2009 • [5] CMake Practice, Cjacker, 2009 • [6] STLSoft: http://www.stlsoft.org • [7] GNU build system: http://en.wikipedia.org/wiki/GNU_build_system • [8] Build System: http://en.wikipedia.org/wiki/Comparison_of_integrated_development_environments#C.2F C.2B.2B • [9] CMake API: http://www.scintilla.org/cmake.api

Classification 4/18/2011

27