Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst

   1 CPACK_CUSTOM_INSTALL_VARIABLES
   2 ------------------------------
   3
   4 .. versionadded:: 3.21
   5
   6 CPack variables (set via e.g. :option:`cpack -D`, ``CPackConfig.cmake`` or
   7 :variable:`CPACK_PROJECT_CONFIG_FILE` scripts) are not directly visible in
   8 installation scripts.  Instead, one can pass a list of ``varName=value``
   9 pairs in the ``CPACK_CUSTOM_INSTALL_VARIABLES`` variable.  At install time,
  10 each list item will result in a variable of the specified name (``varName``)
  11 being set to the given ``value``.  The ``=`` can be omitted for an empty
  12 ``value``.
  13
  14 ``CPACK_CUSTOM_INSTALL_VARIABLES`` allows the packaging installation to be
  15 influenced by the user or driving script at CPack runtime without having to
  16 regenerate the install scripts.
  17
  18 Example
  19 """""""
  20
  21 .. code-block:: cmake
  22
  23   install(FILES large.txt DESTINATION data)
  24
  25   install(CODE [[
  26     if(ENABLE_COMPRESSION)
  27       # "run-compressor" is a fictional tool that produces
  28       # large.txt.xz from large.txt and then removes the input file
  29       execute_process(COMMAND run-compressor $ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}/large.txt)
  30     endif()
  31   ]])
  32
  33 With the above example snippet, :manual:`cpack <cpack(1)>` will by default
  34 run the installation script with ``ENABLE_COMPRESSION`` unset, resulting in
  35 a package containing the uncompressed ``large.txt``.  This can be overridden
  36 when invoking :manual:`cpack <cpack(1)>` like so:
  37
  38 .. code-block:: shell
  39
  40   cpack -D "CPACK_CUSTOM_INSTALL_VARIABLES=ENABLE_COMPRESSION=TRUE"
  41
  42 The installation script will then run with ``ENABLE_COMPRESSION`` set to
  43 ``TRUE``, resulting in a package containing the compressed ``large.txt.xz``
  44 instead.