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 '*.cmake') and usable as cpack configs.

`cpack --config <build root>/cpack.d/<config-name>.cmake`

The existing templates will produce packages 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.

Currently supported OSes
========================

Below a list of the OSes currently supported and their status:

	+------------+-------------+------------+------------------+
	| Name       |  Version    | Format     | Config           |
	+============+=============+============+==================+
	| CentOS     | 7           | rpm        | centos.cmake     |
	+------------+-------------+------------+------------------+
	| Debian     | 8           | deb        | debian.cmake     |
	+------------+-------------+------------+------------------+
	| MacOS X    | 10.12,10.14 | dmg        | darwin-dmg.cmake |
	|            |             | pkg        | darwin-pkg.cmake |
	+------------+-------------+------------+------------------+
	| Fedora     | 28,29,30    | rpm        | fedora.cmake     |
	+------------+-------------+------------+------------------+
	| *RHEL      | 7           | rpm        | rhel.cmake       |
	+------------+-------------+------------+------------------+
	| Ubuntu     | 14          | deb        | debian.cmake     |
	+------------+-------------+------------+------------------+
	| Windows    | 10          | NSIS       | windows.cmake    |
	+------------+-------------+------------+------------------+

** RHEL is still untested

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 raised the issues. When finished, the
debuginfo package can be uninstalled.

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.
