From 54d09a2b3fc4da6f0b01a143f7dc1bd67e675d1b Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 20 Mar 2024 17:15:20 -0400 Subject: [PATCH] CPack/WIX: Document WiX Toolset v3 tools Add a dedicated section describing the `candle` and `light` tools. Also improve formatting of some variables' documentation. --- Help/cpack_gen/wix.rst | 75 +++++++++++++++++++++++++++++------------- 1 file changed, 52 insertions(+), 23 deletions(-) diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst index cb56c9d310..4b627e7392 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst @@ -1,10 +1,43 @@ CPack WIX Generator ------------------- -CPack WIX generator specific options +Use the `WiX Toolset`_ to produce a Windows Installer ``.msi`` database. + +.. _`WiX Toolset`: https://wixtoolset.org/ .. versionadded:: 3.7 - Support :variable:`CPACK_COMPONENT__DISABLED` variable. + The :variable:`CPACK_COMPONENT__DISABLED` variable is now + supported. + +WiX Toolset v3 +^^^^^^^^^^^^^^ + +Packaging is performed using the following tools: + +``candle`` + Compiles WiX source files into ``.wixobj`` files. + + Invocations may be customized using tool-specific variables: + + * :variable:`CPACK_WIX_CANDLE_EXTENSIONS _EXTENSIONS>` + * :variable:`CPACK_WIX_CANDLE_EXTRA_FLAGS _EXTRA_FLAGS>` + +``light`` + Links ``.wixobj`` files into a Windows Installer ``.msi`` database. + + Invocations may be customized using tool-specific variables: + + * :variable:`CPACK_WIX_LIGHT_EXTENSIONS _EXTENSIONS>` + * :variable:`CPACK_WIX_LIGHT_EXTRA_FLAGS _EXTRA_FLAGS>` + +CPack invokes both tools as needed. Intermediate ``.wixobj`` files +are considered implementation details. + +WiX extensions must be named with the form ``WixExtension``. + +CPack expects the above tools to be available for command-line +use via the ``PATH``. Or, if the ``WIX`` environment variable is set, +CPack looks for the tools in ``%WIX%`` and ``%WIX%\bin``. Variables specific to CPack WIX generator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -68,8 +101,8 @@ Windows using WiX. .. variable:: CPACK_WIX_UI_REF - This variable allows you to override the Id of the ```` element - in the WiX template. + Specify the WiX ``UI`` extension's dialog set. + This is the Id of the ```` element in the default WiX template. The default is ``WixUI_InstallDir`` in case no CPack components have been defined and ``WixUI_FeatureTree`` otherwise. @@ -107,7 +140,7 @@ Windows using WiX. Language(s) of the installer - Languages are compiled into the WixUI extension library. To use them, + Languages are compiled into the Wix ``UI`` extension library. To use them, simply provide the name of the culture. If you specify more than one culture identifier in a comma or semicolon delimited list, the first one that is found will be used. You can find a list of supported languages at: @@ -196,39 +229,35 @@ Windows using WiX. Extra WiX source files - This variable provides an optional list of extra WiX source files (.wxs) - that should be compiled and linked. The full path to source files is - required. + This variable provides an optional list of extra WiX source files (``.wxs``) + that should be compiled and linked. The paths must be absolute. .. variable:: CPACK_WIX_EXTRA_OBJECTS - Extra WiX object files or libraries + Extra WiX object files or libraries. - This variable provides an optional list of extra WiX object (.wixobj) - and/or WiX library (.wixlib) files. The full path to objects and libraries - is required. + This variable provides an optional list of extra WiX object (``.wixobj``) + and/or WiX library (``.wixlib``) files. The paths must be absolute. .. variable:: CPACK_WIX_EXTENSIONS - This variable provides a list of additional extensions for the WiX - tools light and candle. + Specify a list of additional extensions for WiX tools. + See `WiX Toolset v3`_ for extension naming patterns. .. variable:: CPACK_WIX__EXTENSIONS - This is the tool specific version of CPACK_WIX_EXTENSIONS. - ```` can be either LIGHT or CANDLE. + Specify a list of additional extensions for a specific WiX tool. + See `WiX Toolset v3`_ for possible ```` names. .. variable:: CPACK_WIX__EXTRA_FLAGS - This list variable allows you to pass additional - flags to the WiX tool ````. + Specify a list of additional command-line flags for a specific WiX tool. + See `WiX Toolset v3`_ for possible ```` names. Use it at your own risk. Future versions of CPack may generate flags which may be in conflict with your own flags. - ```` can be either LIGHT or CANDLE. - .. variable:: CPACK_WIX_CMAKE_PACKAGE_REGISTRY If this variable is set the generated installer will create @@ -326,9 +355,9 @@ Windows using WiX. .. versionadded:: 3.23 - If this variable is set then the inclusion of WixUIExtensions is skipped, - i.e. the ``-ext "WixUIExtension"`` command line is not included during - the execution of the WiX light tool. + If this variable is set to true, the default inclusion of the WiX ``UI`` + extension is skipped, i.e., the ``-ext WixUIExtension`` flag is not + passed to WiX tools. .. variable:: CPACK_WIX_ARCHITECTURE