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