CMake, an overview. D. Arrivault 1. 24th November, 2014 / Talep presentation. Aix Marseille Université. CMake, an overview.

Transcription

1 CMake, an overview. D. Arrivault 1 1 Laboratoire d Excellence Archimède Aix Marseille Université 24th November, 2014 / Talep presentation

2 Outline Credits Build sytems What problems does it solve? The good old days... Features of a build system Introduction CMake project compilation workflow The CMake files Configuration step Writing a CMakeLists.txt Dependencies Adding Cache variables Adding subdirectories Include and build Install Tests integration About CTest CTest in practice Packaging About CPack CPack in practice Conclusion

3 Credits Outline Credits Build sytems What problems does it solve? The good old days... Features of a build system Introduction CMake project compilation workflow The CMake files Configuration step Writing a CMakeLists.txt Dependencies Adding Cache variables Adding subdirectories Include and build Install Tests integration About CTest CTest in practice Packaging About CPack CPack in practice Conclusion

4 Credits Credits Cédric Castagnède s presentation done at Inria Bordeaux Sud Ouest in June 19th, 2012 : CMake documentation

5 Build sytems Outline Credits Build sytems What problems does it solve? The good old days... Features of a build system Introduction CMake project compilation workflow The CMake files Configuration step Writing a CMakeLists.txt Dependencies Adding Cache variables Adding subdirectories Include and build Install Tests integration About CTest CTest in practice Packaging About CPack CPack in practice Conclusion

6 Build sytems What problems does it solve? What problems does it solve? For developpers: manage all the cycle edit/compile/test in a single place compile only what is necessary in the source code For a development team: For a user: generate packages run tests generate documentation install software easily manage dependen cies tune installation

7 Build sytems The good old days... The good old days... Example Writting personal Makefile... CC= gcc IDIR=include CFLAGS=-I$(IDIR) ODIR=obj LIBS=-lm _DEPS = hellosin.h DEPS = $(patsubst %,$(IDIR)/%,$(_DEPS)) _OBJ = hellosin.o main.o OBJ = $(patsubst %,$(ODIR)/%,$(_OBJ))

8 Build sytems The good old days... The good old days... Example $(ODIR)/%.o: hellosin:.phony: clean: Writting personal Makefile... %.c $(DEPS) $(CC) -c -o $< $(CFLAGS) $(OBJ) gcc -o $^ $(CFLAGS) $(LIBS) clean rm -f $(ODIR)/*.o *~ core $(INCDIR)/*~

9 Build sytems The good old days... The good old days... Painfull for the developer. Writing robust Makefiles for big project can be very time consuming. Portability = painfull configurations Installation, tests, packaging have to be done separatly. At the end, it can be very simple to use but a hard work has to be done before.

10 Build sytems Features of a build system Features of a build system Automatic dependency management of source code compile only modified files software portability use native build environment determine available OS/compiler features name correctly the library:.so /.dylib /.dl adaptability according to user environment auto-configuration of the project determine the availability and location of libraries, commands...

11 Build sytems Features of a build system Features of a build system customize installation cross-compiling give some information: help possibility to set information: prefix, libdir, disable-shared... have some target: make all, make install... launch tests without installation: link with generated library after an installation: link with installed library give a report of the build

12 Outline Credits Build sytems What problems does it solve? The good old days... Features of a build system Introduction CMake project compilation workflow The CMake files Configuration step Writing a CMakeLists.txt Dependencies Adding Cache variables Adding subdirectories Include and build Install Tests integration About CTest CTest in practice Packaging About CPack CPack in practice Conclusion

13 Introduction Introduction Open-source, cross-platform build system (New BSD Licence) Develop by Kitware since 2001 Using compiler-independent method Meta-build system : It doesn t do the final build It generates files for other build systems (Eclipse, Makefiles, XCodes, Cygwin... ) Give some extensions to locate libraries, headers... Give some interfaces for generate a test suite and packaging Allow out of source compilation. Notable research softwares using CMake : VXL (C++ Libraries for Computer Vision Research and Implementation), CGAL (Computational Geometry Algorithms Library)... Get form the official web site or from your distribution softwares management application.

14 CMake project compilation workflow CMake project compilation workflow Example Out of source compilation $ mkdir build $ cd build/ # directory for compilation $ cmake path/to/src/ # configuration $ make # compilation $ make install # installation

15 CMake project compilation workflow CMake project compilation workflow Read the CMakeCache.txt if it exists. Read the CMake input files : CMakeLists.txt. Write/create the cache back out : CMakeCache.txt. Generate the Makefiles with appropriate generator.

16 The CMake files The CMake files CMakeLists.txt It describes the project : list of source files, library dependencies... It is machine-independant. CMakeCache.txt It is generated by the cmake <path_to_source> command. It contains the configuration options. It can be modified via commandline, ccmake or cmake-gui (qt). It is machine-specific.

17 The CMake files The CMake files CMakeLists.txt It describes the project : list of source files, library dependencies... It is machine-independant. CMakeCache.txt It is generated by the cmake <path_to_source> command. It contains the configuration options. It can be modified via commandline, ccmake or cmake-gui (qt). It is machine-specific.

18 Configuration step Configuration step $ cmake /path/to/src -DCACHE_VARIABLE=<VALUE> -G "Makefile Generator" Some useful cache variables CMAKE_BUILD_TYPE=<Debug, Release> Control build type CMAKE_INSTALL_PREFIX=<path> Control the install directory CMAKE_VERBOSE_MAKEFILE=<ON, OFF> Control the verbosity of makefiles

19 Configuration step Configuration step $ cmake /path/to/src -DCACHE_VARIABLE=<VALUE> -G "Makefile Generator" Some Makefile generators Unix Makefiles standard Unix makefiles Borland Makefiles Borland makefiles Visual Studio 12 Visual Studio 12 project files Xcodes Xcode project files Eclipse CDT4 - Unix Makefiles Eclipse CDT 4.0 project files with Unix makefiles

20 Configuration step Configuration step ccmake

21 Writing a CMakeLists.txt Writing a CMakeLists.txt MonProjet lib include hellosin.h hellosin.c main.c CMakelists.txt /** hellosin.h */ #ifndef HELLOSIN_H #define HELLOSIN_H #include <stdio.h> #include <math.h> void print_message(); #endif /** hellosin.c */ #include "hellosin.h" void print_message() { printf ("Hello World!\n"); float sinpio4 = sin(m_pi/4.0); printf ("sin(pi/4)=%f\n", sinpio4); } /** main.c */ #include "hellosin.h" int main(int ac, char *av[]) { print_message(); return 0; }

22 Writing a CMakeLists.txt Writing a CMakeLists.txt CMakeList.txt CMAKE_MINIMUM_REQUIRED(VERSION 2.8) PROJECT(hellosin C) SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -lm") INCLUDE_DIRECTORIES("include") SET(SRC hellosin.c main.c) ADD_EXECUTABLE(hellosin ${SRC}) $ mkdir build $ cd build/ $ cmake.. $ make $./hellosin Hello World! sin(pi/4)=

23 Dependencies Dependencies Dependencies management uses cmake modules and find_package command. Some modules are already defined by cmake: #### Find PkConfig find_package( PkgConfig REQUIRED ) if (NOT PKG_CONFIG_FOUND) message (FATAL_ERROR "PkgConfig not found") else() message ("PkgConfig found") endif()

24 Dependencies Dependencies Defining a new module : FindGLIB2.cmake # - Try to find Glib2 # Once done this will define # GLIB2_FOUND - System has Glib2 # GLIB2_INCLUDE_DIRS - The Glib2 include directories # GLIB2_LIBRARIES - The libraries needed to use Glib2 if(glib2_include_dir AND GLIB2_LIBRARIES) # Already in cache, be silent set(glib2_find_quietly TRUE) endif(glib2_include_dir AND GLIB2_LIBRARIES) # find_package(pkgconfig) //Already done before #Use PkgConfig for getting paths if.pc file is known pkg_check_modules(pc_libglib2 glib-2.0>=2.0.0)

25 Dependencies Dependencies Defining a new module : FindGLIB2.cmake #Find include dir find_path(glib2_include_dirs NAMES glib.h HINTS ${PC_LIBGLIB2_INCLUDEDIR} ${ PC_LIBGLIB2_INCLUDE_DIRS} PATH_SUFFIXES glib-2.0 ) #Find library find_library(glib2_libraries NAMES glib-2.0 HINTS ${PC_LIBGLIB2_LIBDIR} ${ PC_LIBGLIB2_LIBRARY_DIRS} ) # handle the QUIETLY and REQUIRED arguments and set # GLIB2_FOUND to TRUE if all listed variables are TRUE include(findpackagehandlestandardargs) find_package_handle_standard_args(glib2 DEFAULT_MSG GLIB2_LIBRARIES GLIB2_INCLUDE_DIRS) # Set variables as advanced mark_as_advanced(glib2_include_dirs GLIB2_LIBRARIES )

26 Adding Cache variables Adding Cache variables set+cache or option set(install_bin_dir bin CACHE PATH "Installation directory for executables") set(install_lib_dir lib CACHE PATH "Installation directory for libraries") set(install_inc_dir include CACHE PATH "Installation directory for headers") set(install_data_dir share/${project_name} CACHE PATH " Installation directory for data files") option(build_documentation "Create and install the HTML based API documentation (requires Doxygen)" OFF)

27 Adding subdirectories Adding subdirectories Each subdirectory must contain a CMakeLists.txt. In the main CMakeLists.txt: #### Add macaon subdirectories add_subdirectory(${cmake_source_dir}/src/maca_common) add_subdirectory(${cmake_source_dir}/src/maca_lex) add_subdirectory(${cmake_source_dir}/src/maca_tags) add_subdirectory(${cmake_source_dir}/src/maca_morpho)

28 Adding subdirectories Adding subdirectories Each subdirectory must contain a CMakeLists.txt. CMakeLists.txt of the maca_morpho subdirectory: #Get the name of the subdirectory in upper case in FNAME_CAP get_filename_component(fname ${CMAKE_CURRENT_SOURCE_DIR} NAME) string(toupper "${FNAME}" FNAME_CAP) #Fill the HEADER_${FNAME_CAP} with headers files and set #its visiblity to parent scope set(headers_${fname_cap} ${CMAKE_CURRENT_SOURCE_DIR}/src/ maca_morpho.h PARENT_SCOPE) #Fill the SOURCES_${FNAME_CAP} with the source files and set #its visiblity to parent scope set(sources_${fname_cap} ${CMAKE_CURRENT_SOURCE_DIR}/src/ maca_morpho.c PARENT_SCOPE) #Add the header directory to HEADERS_MACAON_DIRS set(headers_macaon_dirs ${HEADERS_MACAON_DIRS} ${ CMAKE_CURRENT_SOURCE_DIR}/src PARENT_SCOPE)

29 Include and build Include and build Include headers directories in the main CMakeLists.txt: include_directories(${macaon_install_dir}/include) include_directories(${gfsm_include_dirs}) include_directories(${fst_include_dirs}) include_directories(${libxml2_include_dirs}) include_directories(${glib2_include_dirs}) include_directories(${libxml2_include_dir}) set(cmake_cxx_flags "${CMAKE_CXX_FLAGS} -std=c++0x -fpic") set(cmake_c_flags "${CMAKE_C_FLAGS} -fpic") include_directories(${headers_macaon_dirs})

30 Include and build Include and build Add libraries (object, static or shared) and binaries to build: #Create object library for maca_common_obj add_library(maca_common_obj OBJECT ${SOURCES_MACA_COMMON}) target_compile_definitions(maca_common_obj PUBLIC MACA_COMMON_VERSION=${MACA_COMMON_VERSION} PUBLIC MACAON_DIRECTORY="${INSTALL_DATA_DIR}") #Add txt2macaon target add_executable(txt2macaon $<TARGET_OBJECTS:maca_common_obj> ${ SOURCES_TXT2MACAON} ${CMAKE_CURRENT_SOURCE_DIR}/src/maca_conversions/txt2macaon/ txt2macaon.c) target_link_libraries(txt2macaon ${LIBXML2_LIBRARIES} ${ GLIB2_LIBRARIES} ${GFSM_LIBRARY} ${FST_LIBRARY}) SET_TARGET_PROPERTIES(txt2macaon PROPERTIES LINKER_LANGUAGE CXX) set(macaon_exe_targets ${MACAON_EXE_TARGETS} txt2macaon)

31 Include and build Include and build Add libraries (object, static or shared) and binaries to build: #create macaon library target add_library(macaon SHARED $<TARGET_OBJECTS:maca_common_obj> $< TARGET_OBJECTS:maca_segmenter_obj> ${MyFlexLexer} $< TARGET_OBJECTS:maca_tokenizer_obj> ${maca_tok_lex} $< TARGET_OBJECTS:maca_lex_obj> $<TARGET_OBJECTS: maca_lexer_obj> $<TARGET_OBJECTS:maca_tags_obj> $< TARGET_OBJECTS:maca_tagger_obj> $<TARGET_OBJECTS: maca_crf_tagger_obj> $<TARGET_OBJECTS:maca_morpho_obj> $< TARGET_OBJECTS:maca_anamorph_obj> $<TARGET_OBJECTS: maca_chunker_obj> $<TARGET_OBJECTS:maca_graph_parser_obj>) target_link_libraries(macaon ${LIBM_C_FLAGS} ${LIBXML2_LIBRARIES } ${GLIB2_LIBRARIES} ${GFSM_LIBRARY} ${FST_LIBRARY}) set(macaon_lib_targets ${MACAON_LIB_TARGETS} macaon) target_compile_definitions(macaon PUBLIC MACAON_VERSION=${ MACAON_VERSION})

32 Install Install The installation instructions are given with the CMake install command. Installing binaries and libraries : install(targets ${MACAON_EXE_TARGETS} ${MACAON_LIB_TARGETS} RUNTIME DESTINATION bin LIBRARY DESTINATION lib) Installing headers and other files : install(files ${MACAON_HEADERS} DESTINATION include/macaon) install(files ${CMAKE_CURRENT_BINARY_DIR}/${MACAONLIB_NAME}.pc DESTINATION ${INSTALL_LIB_DIR}/pkgconfig)

33 Install Install The installation instructions are given with the CMake install command. Installing directories : if(build_documentation) install(directory ${CMAKE_CURRENT_BINARY_DIR}/html DESTINATION ${INSTALL_DOC_DIR} ) endif(build_documentation)

34 Tests integration Outline Credits Build sytems What problems does it solve? The good old days... Features of a build system Introduction CMake project compilation workflow The CMake files Configuration step Writing a CMakeLists.txt Dependencies Adding Cache variables Adding subdirectories Include and build Install Tests integration About CTest CTest in practice Packaging About CPack CPack in practice Conclusion

35 Tests integration About CTest About CTest CTest can be used for test automation. CTest not only can manage unit or regression tests but it also can execute advanced tests (coverage, memory checking). CTest is distributed as a part of CMake but can be used alone. CTest uses the same syntaxe than CMake. CTest can be integrated within the CMakeLists.txt or independant with its own scripts. The tests results can be submit to a CDash server.

36 Tests integration CTest in practice CTest in practice In CMakeLists.txt: #### tests ENABLE_TESTING() set(ctest_project_name "MACAON") add_subdirectory (tests) INCLUDE(CTest) In tests/cmakelists.txt: ADD_EXECUTABLE(example example.cpp) ADD_TEST(test1 example)

37 Tests integration CTest in practice CTest in practice Using ctest from bash #Get list of tests $ ctest -N #Launch all tests $ make test # Or $ ctest #Launch one specific test $ ctest -R test1 Two log files : LastTest.log and LastTestsFailed.log

38 Packaging Outline Credits Build sytems What problems does it solve? The good old days... Features of a build system Introduction CMake project compilation workflow The CMake files Configuration step Writing a CMakeLists.txt Dependencies Adding Cache variables Adding subdirectories Include and build Install Tests integration About CTest CTest in practice Packaging About CPack CPack in practice Conclusion

39 Packaging About CPack About CPack CPack is a cross-platform software packaging tool. CPack is distributed as a part of CMake but can be used alone. CPack can be used for generating source distribution archive or architecture dependant binary packages (specified with the CPACK_GENERATOR variable). CPack uses the CMake install commands to fill the binary packages. Source distribution is a copy of the local depository (ignored files has to be explicitly defined).

40 Packaging CPack in practice CPack in practice In CMakeLists.txt: # build a CPack driven installer package include (InstallRequiredSystemLibraries) set (CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/ COPYING") set (CPACK_PACKAGE_VERSION_MAJOR "${MACAON_MAJOR_VERSION}") set (CPACK_PACKAGE_VERSION_MINOR "${MACAON_MINOR_VERSION}") set (CPACK_PACKAGE_DESCRIPTION_SUMMARY "Macaon") set (CPACK_PACKAGE_VENDOR "Talep / LIF") set (CPACK_PACKAGE_DESCRIPTION_FILE ${CMAKE_CURRENT_SOURCE_DIR}/ README) set (CPACK_GENERATOR "DEB") set (CPACK_DEBIAN_PACKAGE_MAINTAINER "Denis Arrivault") # required set (CPACK_SOURCE_PACKAGE_FILE_NAME "Macaon-${ CPACK_PACKAGE_VERSION_MAJOR}.${CPACK_PACKAGE_VERSION_MINOR }-Source" CACHE INTERNAL "tarball basename") set(cpack_source_generator TGZ) set(cpack_source_ignore_files ".project;/.git/;.gitignore;/build /;/install/;${cpack_source_ignore_files}") include (CPack)

41 Packaging CPack in practice CPack in practice Generate package: #Source package $ make package_source #Binary package $ make package

42 Conclusion Outline Credits Build sytems What problems does it solve? The good old days... Features of a build system Introduction CMake project compilation workflow The CMake files Configuration step Writing a CMakeLists.txt Dependencies Adding Cache variables Adding subdirectories Include and build Install Tests integration About CTest CTest in practice Packaging About CPack CPack in practice Conclusion

43 Conclusion Conclusion easy to develop Configure/Build/Install/Test/Package in one tool with the same syntax. Multi-plateform Easy to use can mean reinventing the wheel. As usual, RTFM!