CPack/WiX: Make InstallScope configurable

Add a new `CPACK_WIX_INSTALL_SCOPE` variable to set the `InstallScope`
when using the default WiX template.  Set the default to the bug-free
value `perMachine`.

Fixes: #20962

2 files changed, 43 insertions, 1 deletions

diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst
index af01252..cb56c9d 100644
--- a/Help/cpack_gen/wix.rst
+++ b/Help/cpack_gen/wix.rst
@@ -119,7 +119,8 @@ Windows using WiX.
 
  If this variable is set, the specified template will be used to generate
  the WiX wxs file.  This should be used if further customization of the
- output is required.
+ output is required. The template contents will override the effect of most
+ ``CPACK_WIX_`` variables.
 
  If this variable is not set, the default MSI template included with CMake
  will be used.
@@ -337,3 +338,31 @@ Windows using WiX.
  of the installer. May for example be set to ``x64`` or ``arm64``.
 
  When unspecified, CPack will default to ``x64`` or ``x86``.
+
+.. variable:: CPACK_WIX_INSTALL_SCOPE
+
+ .. versionadded:: 3.29
+
+ This variable can be optionally set to specify the ``InstallScope``
+ of the installer:
+
+ ``perMachine`` (default)
+   Create an installer that installs for all users and requires
+   administrative privileges.  Start menu entries created by the
+   installer are visible to all users.
+
+ ``perUser``
+   Not yet supported. This is reserved for future use.
+
+ ``NONE``
+   Create an installer without any ``InstallScope`` attribute.
+
+   .. deprecated:: 3.29
+
+     This value is only for compatibility with the inconsistent behavior used
+     by CPack 3.28 and older.  The resulting installer requires administrative
+     privileges and installs into the system-wide ``ProgramFiles`` directory,
+     but the start menu entry and uninstaller registration are created only
+     for the current user.
+
+ See https://wixtoolset.org/docs/v3/xsd/wix/package/
diff --git a/Help/release/dev/wix-installscope.rst b/Help/release/dev/wix-installscope.rst
new file mode 100644
index 0000000..1978698
--- /dev/null
+++ b/Help/release/dev/wix-installscope.rst
@@ -0,0 +1,13 @@
+wix-installscope
+----------------
+
+* The :cpack_gen:`CPack WIX Generator` gained a new variable,
+  :variable:`CPACK_WIX_INSTALL_SCOPE`, to control the
+  ``InstallScope`` property of WiX MSI installers.
+
+* The :cpack_gen:`CPack WIX Generator` now produces WiX MSI installers
+  that create start menu and uninstall entries for all users by default,
+  as documented by the :variable:`CPACK_WIX_INSTALL_SCOPE` variable
+  ``perMachine`` value.  Previously, without a custom WiX template,
+  it produced installers that would only create start menu and uninstall
+  entries for the current user, even though they install for all users.