Merge topic 'cpack-wix'

03884f4f32 CPack/WIX: Add support for WiX Toolset v4
cfe5bbdc54 ci: Add scripts to provide WiX 4 package on Windows
c8e2694679 ci: Add script to repackage WiX .NET tool for our needs
e7f5ad8df2 Tests: Prepare RunCMake.CPack_WIX to cover multiple WiX versions

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9369

2 files changed, 95 insertions, 9 deletions

diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst
index 4b627e7..dfa3434 100644
--- a/Help/cpack_gen/wix.rst
+++ b/Help/cpack_gen/wix.rst
@@ -9,8 +9,68 @@ Use the `WiX Toolset`_ to produce a Windows Installer ``.msi`` database.
   The :variable:`CPACK_COMPONENT_<compName>_DISABLED` variable is now
   supported.
 
+WiX Toolsets
+^^^^^^^^^^^^
+
+CPack selects one of the following variants of the WiX Toolset
+based on the :variable:`CPACK_WIX_VERSION` variable:
+
+* `WiX .NET Tools`_
+* `WiX Toolset v3`_
+
+WiX .NET Tools
+""""""""""""""
+
+Packaging is performed using the following tools:
+
+``wix build``
+  Build WiX source files directly into a Windows Installer ``.msi`` database.
+
+  Invocations may be customized using tool-specific variables:
+
+  * :variable:`CPACK_WIX_BUILD_EXTENSIONS <CPACK_WIX_<TOOL>_EXTENSIONS>`
+  * :variable:`CPACK_WIX_BUILD_EXTRA_FLAGS <CPACK_WIX_<TOOL>_EXTRA_FLAGS>`
+
+WiX extensions must be named with the form ``WixToolset.<Name>.wixext``.
+
+CPack expects the ``wix`` .NET tool to be available for command-line use
+with any required WiX extensions already installed.  Be sure the ``wix``
+version is compatible with :variable:`CPACK_WIX_VERSION`, and that WiX
+extension versions match the ``wix`` tool version.  For example:
+
+1. Install the ``wix`` command-line tool using ``dotnet``.
+
+  To install ``wix`` globally for the current user:
+
+  .. code-block:: bat
+
+    dotnet tool install --global wix --version 4.0.4
+
+  This places ``wix.exe`` in ``%USERPROFILE%\.dotnet\tools`` and adds
+  the directory to the current user's ``PATH`` environment variable.
+
+  Or, to install ``wix`` in a specific path, e.g., in ``c:\WiX``:
+
+  .. code-block:: bat
+
+    dotnet tool install --tool-path c:\WiX wix --version 4.0.4
+
+  This places ``wix.exe`` in ``c:\WiX``, but does *not* add it to the
+  current user's ``PATH`` environment variable.  The ``WIX`` environment
+  variable may be set to tell CPack where to find the tool,
+  e.g., ``set WIX=c:\WiX``.
+
+2. Add the WiX ``UI`` extension, needed by CPack's default WiX template:
+
+  .. code-block:: bat
+
+    wix extension add --global WixToolset.UI.wixext/4.0.4
+
+  Extensions added globally are stored in ``%USERPROFILE%\.wix``, or if the
+  ``WIX_EXTENSIONS`` environment variable is set, in ``%WIX_EXTENSIONS%\.wix``.
+
 WiX Toolset v3
-^^^^^^^^^^^^^^
+""""""""""""""
 
 Packaging is performed using the following tools:
 
@@ -45,6 +105,19 @@ Variables specific to CPack WIX generator
 The following variables are specific to the installers built on
 Windows using WiX.
 
+.. variable:: CPACK_WIX_VERSION
+
+ .. versionadded:: 3.30
+
+ Specify the version of WiX Toolset for which the configuration
+ is written.  The value must be one of
+
+ ``4``
+   Package using `WiX .NET Tools`_.
+
+ ``3``
+   Package using `WiX Toolset v3`_.  This is the default.
+
 .. variable:: CPACK_WIX_UPGRADE_GUID
 
  Upgrade GUID (``Product/@UpgradeCode``)
@@ -101,8 +174,13 @@ Windows using WiX.
 
 .. variable:: CPACK_WIX_UI_REF
 
- Specify the WiX ``UI`` extension's dialog set.
- This is the Id of the ``<UIRef>`` element in the default WiX template.
+ Specify the WiX ``UI`` extension's dialog set:
+
+ * With `WiX .NET Tools`_, this is the Id of the
+   ``<ui:WixUI>`` element in the default WiX template.
+
+ * With `WiX Toolset v3`_, this is the Id of the
+   ``<UIRef>`` element in the default WiX template.
 
  The default is ``WixUI_InstallDir`` in case no CPack components have
  been defined and ``WixUI_FeatureTree`` otherwise.
@@ -234,7 +312,7 @@ Windows using WiX.
 
 .. variable:: CPACK_WIX_EXTRA_OBJECTS
 
- Extra WiX object files or libraries.
+ Extra WiX object files or libraries to use with `WiX Toolset v3`_.
 
  This variable provides an optional list of extra WiX object (``.wixobj``)
  and/or WiX library (``.wixlib``) files.  The paths must be absolute.
@@ -242,17 +320,17 @@ Windows using WiX.
 .. variable:: CPACK_WIX_EXTENSIONS
 
  Specify a list of additional extensions for WiX tools.
- See `WiX Toolset v3`_ for extension naming patterns.
+ See `WiX Toolsets`_ for extension naming patterns.
 
 .. variable:: CPACK_WIX_<TOOL>_EXTENSIONS
 
  Specify a list of additional extensions for a specific WiX tool.
- See `WiX Toolset v3`_ for possible ``<TOOL>`` names.
+ See `WiX Toolsets`_ for possible ``<TOOL>`` names.
 
 .. variable:: CPACK_WIX_<TOOL>_EXTRA_FLAGS
 
  Specify a list of additional command-line flags for a specific WiX tool.
- See `WiX Toolset v3`_ for possible ``<TOOL>`` names.
+ See `WiX Toolsets`_ for possible ``<TOOL>`` names.
 
  Use it at your own risk.
  Future versions of CPack may generate flags which may be in conflict
@@ -356,8 +434,8 @@ Windows using WiX.
  .. versionadded:: 3.23
 
  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.
+ extension is skipped, i.e., the ``-ext WixUIExtension`` or
+ ``-ext WixToolset.UI.wixext`` flag is not passed to WiX tools.
 
 .. variable:: CPACK_WIX_ARCHITECTURE
 
@@ -386,6 +464,9 @@ Windows using WiX.
  ``NONE``
    Create an installer without any ``InstallScope`` attribute.
 
+   This is not supported if :variable:`CPACK_WIX_VERSION` is set
+   to any value other than ``3``.
+
    .. deprecated:: 3.29
 
      This value is only for compatibility with the inconsistent behavior used
diff --git a/Help/release/dev/cpack-wix.rst b/Help/release/dev/cpack-wix.rst
new file mode 100644
index 0000000..020dfeb
--- /dev/null
+++ b/Help/release/dev/cpack-wix.rst
@@ -0,0 +1,5 @@
+cpack-wix
+---------
+
+* The :cpack_gen:`CPack WIX Generator` gained support for WiX Toolset v4.
+  See the :variable:`CPACK_WIX_VERSION` variable.