Help/guide/tutorial/Packaging Debug and Release.rst

   1 Step 12: Packaging Debug and Release
   2 ====================================
   3
   4 **Note:** This example is valid for single-configuration generators and will
   5 not work for multi-configuration generators (e.g. Visual Studio).
   6
   7 By default, CMake's model is that a build directory only contains a single
   8 configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. It is
   9 possible, however, to setup CPack to bundle multiple build directories and
  10 construct a package that contains multiple configurations of the same project.
  11
  12 First, we want to ensure that the debug and release builds use different names
  13 for the libraries that will be installed. Let's use `d` as the
  14 postfix for the debug libraries.
  15
  16 Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level
  17 ``CMakeLists.txt`` file:
  18
  19 .. literalinclude:: Complete/CMakeLists.txt
  20   :caption: CMakeLists.txt
  21   :name: CMakeLists.txt-CMAKE_DEBUG_POSTFIX-variable
  22   :language: cmake
  23   :start-after: project(Tutorial VERSION 1.0)
  24   :end-before: target_compile_features(tutorial_compiler_flags
  25
  26 And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable:
  27
  28 .. literalinclude:: Complete/CMakeLists.txt
  29   :caption: CMakeLists.txt
  30   :name: CMakeLists.txt-DEBUG_POSTFIX-property
  31   :language: cmake
  32   :start-after: # add the executable
  33   :end-before: # add the binary tree to the search path for include files
  34
  35 Let's also add version numbering to the ``MathFunctions`` library. In
  36 ``MathFunctions/CMakeLists.txt``, set the :prop_tgt:`VERSION` and
  37 :prop_tgt:`SOVERSION` properties:
  38
  39 .. literalinclude:: Complete/MathFunctions/CMakeLists.txt
  40   :caption: MathFunctions/CMakeLists.txt
  41   :name: MathFunctions/CMakeLists.txt-VERSION-properties
  42   :language: cmake
  43   :start-after: # setup the version numbering
  44   :end-before: # install libs
  45
  46 From the ``Step12`` directory, create ``debug`` and ``release``
  47 subdirectories. The layout will look like:
  48
  49 .. code-block:: none
  50
  51   - Step12
  52      - debug
  53      - release
  54
  55 Now we need to setup debug and release builds. We can use
  56 :variable:`CMAKE_BUILD_TYPE` to set the configuration type:
  57
  58 .. code-block:: console
  59
  60   cd debug
  61   cmake -DCMAKE_BUILD_TYPE=Debug ..
  62   cmake --build .
  63   cd ../release
  64   cmake -DCMAKE_BUILD_TYPE=Release ..
  65   cmake --build .
  66
  67 Now that both the debug and release builds are complete, we can use a custom
  68 configuration file to package both builds into a single release. In the
  69 ``Step12`` directory, create a file called ``MultiCPackConfig.cmake``. In this
  70 file, first include the default configuration file that was created by the
  71 :manual:`cmake  <cmake(1)>` executable.
  72
  73 Next, use the ``CPACK_INSTALL_CMAKE_PROJECTS`` variable to specify which
  74 projects to install. In this case, we want to install both debug and release.
  75
  76 .. literalinclude:: Complete/MultiCPackConfig.cmake
  77   :caption: MultiCPackConfig.cmake
  78   :name: MultiCPackConfig.cmake
  79   :language: cmake
  80
  81 From the ``Step12`` directory, run :manual:`cpack <cpack(1)>` specifying our
  82 custom configuration file with the ``config`` option:
  83
  84 .. code-block:: console
  85
  86   cpack --config MultiCPackConfig.cmake