CPack: Implement new variable CPACK_CUSTOM_INSTALL_VARIABLES

The new variable allows projects to define custom key=value pairs of
variables to be set in CPack cmake_install.cmake script invocations.
This allows install(SCRIPT|CODE) to be parameterized at runtime.

1 files changed, 42 insertions, 0 deletions

diff --git a/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst
new file mode 100644
index 0000000..534e2ad
--- /dev/null
+++ b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst
@@ -0,0 +1,42 @@
+CPACK_CUSTOM_INSTALL_VARIABLES
+------------------------------
+
+CPack variables (set via e.g. ``cpack -D``, ``CPackConfig.cmake`` or
+:variable:`CPACK_PROJECT_CONFIG_FILE` scripts) are not directly visible in
+installation scripts.  Instead, one can pass a list of ``varName=value``
+pairs in the ``CPACK_CUSTOM_INSTALL_VARIABLES`` variable.  At install time,
+each list item will result in a variable of the specified name (``varName``)
+being set to the given ``value``.  The ``=`` can be omitted for an empty
+``value``.
+
+``CPACK_CUSTOM_INSTALL_VARIABLES`` allows the packaging installation to be
+influenced by the user or driving script at CPack runtime without having to
+regenerate the install scripts.
+
+Example
+"""""""
+
+.. code-block:: cmake
+
+  install(FILES large.txt DESTINATION data)
+
+  install(CODE [[
+    if(ENABLE_COMPRESSION)
+      # "run-compressor" is a fictional tool that produces
+      # large.txt.xz from large.txt and then removes the input file
+      execute_process(COMMAND run-compressor $ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}/large.txt)
+    endif()
+  ]])
+
+With the above example snippet, :manual:`cpack <cpack(1)>` will by default
+run the installation script with ``ENABLE_COMPRESSION`` unset, resulting in
+a package containing the uncompressed ``large.txt``.  This can be overridden
+when invoking :manual:`cpack <cpack(1)>` like so:
+
+.. code-block:: shell
+
+  cpack -D "CPACK_CUSTOM_INSTALL_VARIABLES=ENABLE_COMPRESSION=TRUE"
+
+The installation script will then run with ``ENABLE_COMPRESSION`` set to
+``TRUE``, resulting in a package containing the compressed ``large.txt.xz``
+instead.