CPack.d dropin' directory

Introduction

cpack.d is a dropin directory for cmake/cpack, decoupling os specific packaging rules from project code development.

Every CPack template file (postfixed with '*.cmake.in') in the directory, is automatically configured during the usual cmake project building.

The resulting CPack files will be available in the corresponding binary directory (postfixed with '*.cpack') and usable as cpack configs.

cd «build root»
cpack --config cpack.d/«config-name.cpack»

The existing templates will produce packages in «build root» with:

• package names compliant with the target OS rules
• build number equal to the number of commits on the current branch
• stripped binaries
• support for runtime, development and documentation components

The commons.cmake.in extracts CMake project specific attributes and prepare them to be used by the os specific package configs through the invocation of the macro 'config_package'.

Project specific settings, like the description summary, are fetched from an external directory passed during the invocation of the 'config_package' macro via the DATA argument.

Build status report

If the CMake list PACKAGE_OPTIONS is filled with options names used in the project, their status will be reported in a file named:

build-options.txt

that is added to the runtime package.

The following cmake helper function can be used in the client project for adding the options:

function(report_prepare)
  set(multiValueArgs IF_APPLE IF_WIN32)
  cmake_parse_arguments(REPORT "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} )
  if (REPORT_IF_APPLE AND APPLE)
    list(APPEND res ${REPORT_IF_APPLE})
  endif()
  if (REPORT_IF_WIN32 AND WIN32)
    list(APPEND res ${REPORT_IF_WIN32})
  endif()
  list(APPEND res ${REPORT_UNPARSED_ARGUMENTS})
  list(APPEND PACKAGE_OPTIONS ${res})
  set(PACKAGE_OPTIONS "${PACKAGE_OPTIONS}" PARENT_SCOPE)
endfunction(report_prepare)

invoked like in the example:

report_prepare(
  SIMAGE_BUILD_SHARED_LIBS
  SIMAGE_BUILD_DOCUMENTATION
  SIMAGE_USE_QIMAGE
  SIMAGE_USE_QT5
  SIMAGE_LIBSNDFILE_SUPPORT
  SIMAGE_OGGVORBIS_SUPPORT
  SIMAGE_QIMAGE_SUPPORT
  SIMAGE_EPS_SUPPORT
  SIMAGE_MPEG2ENC_SUPPORT
  SIMAGE_PIC_SUPPORT
  SIMAGE_RGB_SUPPORT
  SIMAGE_TGA_SUPPORT
  SIMAGE_XWD_SUPPORT
  IF_WIN32
    SIMAGE_USE_AVIENC SIMAGE_USE_GDIPLUS SIMAGE_AVIENC_SUPPORT SIMAGE_GDIPLUS_SUPPORT
  IF_APPLE
    SIMAGE_USE_CGIMAGE SIMAGE_USE_QUICKTIME SIMAGE_CGIMAGE_SUPPORT SIMAGE_QUICKTIME_SUPPORT
)

will produce a report like the following:

CMAKE_BUILD_TYPE=RelWithDebInfo
OPTION_PKG_DEBUGINFO=ON
SIMAGE_BUILD_DOCUMENTATION=OFF
SIMAGE_BUILD_SHARED_LIBS=ON
SIMAGE_EPS_SUPPORT=ON
SIMAGE_LIBSNDFILE_SUPPORT=ON
SIMAGE_MPEG2ENC_SUPPORT=ON
SIMAGE_OGGVORBIS_SUPPORT=ON
SIMAGE_PIC_SUPPORT=ON
SIMAGE_QIMAGE_SUPPORT=OFF
SIMAGE_RGB_SUPPORT=ON
SIMAGE_TGA_SUPPORT=ON
SIMAGE_USE_QIMAGE=OFF
SIMAGE_USE_QT5=OFF
SIMAGE_XWD_SUPPORT=OFF

DWARF debuginfo

The debuginfo support for Debian and RedHat systems is available through a CMake option OPTION_PKG_DEBUGINFO that is disabled by default. When enabled a new package will be produced conforming the conventions of the target distro.

In order to use this feature:

• OPTION_PKG_DEBUGINFO must be enabled;
• CMake build mode must be Debug or RelWithDebInfo since source code must be compiled with debug options turned on;

When these condition are met, cpack will post-process the resulting binaries using an additional tool that essentially:

1. moves the debuginfo hunks from the binary targets into separate .debug shared objects (one for each target binary)
2. creates an additional debuginfo package containing the .debug files with the 'moved' DWARF debuginfo, and the source files used for compiling;
3. modifies the referred source code paths inside the .debug files (originally targeting sources at compile-time) according to their position at install-time.

The resulting packages are now stripped and eventually optimized (if CMake RelWithDebInfo mode used). In case of issues requiring a source level debug session, just installs the additional debuginfo package (it will add source files and debug symbols to the hosting system).

Nothing needs to be changed in the client software and the code running in the debug session is the same that rised the issues. When finished, the debuginfo package can be unistalled.

Drawbacks:

• not optimal debugger sessions when code optimizations are enabled (as in case of a RelWithDebInfo build);
• DWARF debuginfo are a modified copy of the original ones produced during compilation, concretely altering the file path of the sources to their install-time path. This means that install-time path of the sources must be not longer then the compile-time path.

Workaround in case of problems with the file path length

Just move your project to a longer path.