1Introduction 2============ 3 4cpack.d is a dropin directory for cmake/cpack, decoupling os specific 5packaging rules from project code development. 6 7Every CPack template file (postfixed with '*.cmake.in') in the directory, 8is automatically configured during the usual cmake project building. 9 10The resulting CPack files will be available in the corresponding binary 11directory (postfixed with '*.cmake') and usable as cpack configs. 12 13`cpack --config <build root>/cpack.d/<config-name>.cmake` 14 15The existing templates will produce packages with: 16 17 * package names compliant with the target OS rules 18 * build number equal to the number of commits on the current branch 19 * stripped binaries 20 * support for runtime, development and documentation components 21 22The commons.cmake.in extracts CMake project specific attributes and prepare 23them to be used by the os specific package configs through the invocation of 24the macro 'config_package'. 25 26Project specific settings, like the description summary, are fetched 27from an external directory passed during the invocation of the 'config_package' 28macro via the DATA argument. 29 30Build status report 31=================== 32 33If the CMake list PACKAGE_OPTIONS is filled with options names used in the 34project, their status will be reported in a file named: 35 36 build-options.txt 37 38that is added to the runtime package. 39 40The following cmake helper function can be used in the client project for adding 41the options: 42 43 function(report_prepare) 44 set(multiValueArgs IF_APPLE IF_WIN32) 45 cmake_parse_arguments(REPORT "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} ) 46 if (REPORT_IF_APPLE AND APPLE) 47 list(APPEND res ${REPORT_IF_APPLE}) 48 endif() 49 if (REPORT_IF_WIN32 AND WIN32) 50 list(APPEND res ${REPORT_IF_WIN32}) 51 endif() 52 list(APPEND res ${REPORT_UNPARSED_ARGUMENTS}) 53 list(APPEND PACKAGE_OPTIONS ${res}) 54 set(PACKAGE_OPTIONS "${PACKAGE_OPTIONS}" PARENT_SCOPE) 55 endfunction(report_prepare) 56 57invoked like in the example: 58 59 report_prepare( 60 SIMAGE_BUILD_SHARED_LIBS 61 SIMAGE_BUILD_DOCUMENTATION 62 SIMAGE_USE_QIMAGE 63 SIMAGE_USE_QT5 64 SIMAGE_LIBSNDFILE_SUPPORT 65 SIMAGE_OGGVORBIS_SUPPORT 66 SIMAGE_QIMAGE_SUPPORT 67 SIMAGE_EPS_SUPPORT 68 SIMAGE_MPEG2ENC_SUPPORT 69 SIMAGE_PIC_SUPPORT 70 SIMAGE_RGB_SUPPORT 71 SIMAGE_TGA_SUPPORT 72 SIMAGE_XWD_SUPPORT 73 IF_WIN32 74 SIMAGE_USE_AVIENC SIMAGE_USE_GDIPLUS SIMAGE_AVIENC_SUPPORT SIMAGE_GDIPLUS_SUPPORT 75 IF_APPLE 76 SIMAGE_USE_CGIMAGE SIMAGE_USE_QUICKTIME SIMAGE_CGIMAGE_SUPPORT SIMAGE_QUICKTIME_SUPPORT 77 ) 78 79will produce a report like the following: 80 81 CMAKE_BUILD_TYPE=RelWithDebInfo 82 OPTION_PKG_DEBUGINFO=ON 83 SIMAGE_BUILD_DOCUMENTATION=OFF 84 SIMAGE_BUILD_SHARED_LIBS=ON 85 SIMAGE_EPS_SUPPORT=ON 86 SIMAGE_LIBSNDFILE_SUPPORT=ON 87 SIMAGE_MPEG2ENC_SUPPORT=ON 88 SIMAGE_OGGVORBIS_SUPPORT=ON 89 SIMAGE_PIC_SUPPORT=ON 90 SIMAGE_QIMAGE_SUPPORT=OFF 91 SIMAGE_RGB_SUPPORT=ON 92 SIMAGE_TGA_SUPPORT=ON 93 SIMAGE_USE_QIMAGE=OFF 94 SIMAGE_USE_QT5=OFF 95 SIMAGE_XWD_SUPPORT=OFF 96 97DWARF debuginfo 98=============== 99 100The debuginfo support for Debian and RedHat systems is available through a 101CMake option __OPTION_PKG_DEBUGINFO__ that is disabled by default. When enabled 102a new package will be produced conforming the conventions of the target distro. 103 104In order to use this feature: 105 106 * OPTION_PKG_DEBUGINFO must be enabled; 107 * CMake build mode must be __Debug__ or __RelWithDebInfo__ since source code 108 must be compiled with debug options turned on; 109 110When these condition are met, cpack will post-process the resulting binaries 111using an additional tool that essentially: 112 113 1. moves the debuginfo hunks from the binary targets into separate .debug 114 shared objects (one for each target binary) 115 2. creates an additional debuginfo package containing the .debug files with 116 the 'moved' DWARF debuginfo, __and__ the source files used for compiling; 117 3. modifies the referred source code paths inside the .debug files 118 (originally targeting sources at compile-time) according to their position 119 at install-time. 120 121The resulting packages are now stripped and eventually optimized (if CMake 122RelWithDebInfo mode used). In case of issues requiring a source level debug 123session, just installs the additional debuginfo package (it will add source 124files and debug symbols to the hosting system). 125 126__Nothing needs to be changed in the client software__ and the code running in 127the debug session is the same that rised the issues. When finished, the 128debuginfo package can be unistalled. 129 130Drawbacks: 131 132 * not optimal debugger sessions when code optimizations are enabled (as in 133 case of a RelWithDebInfo build); 134 * DWARF debuginfo are a modified copy of the original ones produced during 135 compilation, concretely altering the file path of the sources to their 136 install-time path. This means that install-time path of the sources __must 137 be not longer then the compile-time path__. 138 139__Workaround in case of problems with the file path length__ 140 141Just move your project to a longer path. 142