You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
380 lines
12 KiB
380 lines
12 KiB
CPack WIX Generator
|
|
-------------------
|
|
|
|
CPack WIX generator specific options
|
|
|
|
.. versionadded:: 3.7
|
|
Support :variable:`CPACK_COMPONENT_<compName>_DISABLED` variable.
|
|
|
|
Variables specific to CPack WIX generator
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The following variables are specific to the installers built on
|
|
Windows using WiX.
|
|
|
|
.. variable:: CPACK_WIX_UPGRADE_GUID
|
|
|
|
Upgrade GUID (``Product/@UpgradeCode``)
|
|
|
|
Will be automatically generated unless explicitly provided.
|
|
|
|
It should be explicitly set to a constant generated globally unique
|
|
identifier (GUID) to allow your installers to replace existing
|
|
installations that use the same GUID.
|
|
|
|
You may for example explicitly set this variable in your
|
|
CMakeLists.txt to the value that has been generated per default. You
|
|
should not use GUIDs that you did not generate yourself or which may
|
|
belong to other projects.
|
|
|
|
A GUID shall have the following fixed length syntax::
|
|
|
|
XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|
|
|
|
(each X represents an uppercase hexadecimal digit)
|
|
|
|
.. variable:: CPACK_WIX_PRODUCT_GUID
|
|
|
|
Product GUID (``Product/@Id``)
|
|
|
|
Will be automatically generated unless explicitly provided.
|
|
|
|
If explicitly provided this will set the Product Id of your installer.
|
|
|
|
The installer will abort if it detects a pre-existing installation that
|
|
uses the same GUID.
|
|
|
|
The GUID shall use the syntax described for CPACK_WIX_UPGRADE_GUID.
|
|
|
|
.. variable:: CPACK_WIX_LICENSE_RTF
|
|
|
|
RTF License File
|
|
|
|
If CPACK_RESOURCE_FILE_LICENSE has an .rtf extension it is used as-is.
|
|
|
|
If CPACK_RESOURCE_FILE_LICENSE has an .txt extension it is implicitly
|
|
converted to RTF by the WIX Generator.
|
|
The expected encoding of the .txt file is UTF-8.
|
|
|
|
With CPACK_WIX_LICENSE_RTF you can override the license file used by the
|
|
WIX Generator in case CPACK_RESOURCE_FILE_LICENSE is in an unsupported
|
|
format or the .txt -> .rtf conversion does not work as expected.
|
|
|
|
.. variable:: CPACK_WIX_PRODUCT_ICON
|
|
|
|
The Icon shown next to the program name in Add/Remove programs.
|
|
|
|
If set, this icon is used in place of the default icon.
|
|
|
|
.. variable:: CPACK_WIX_UI_REF
|
|
|
|
This variable allows you to override the Id of the ``<UIRef>`` element
|
|
in the WiX template.
|
|
|
|
The default is ``WixUI_InstallDir`` in case no CPack components have
|
|
been defined and ``WixUI_FeatureTree`` otherwise.
|
|
|
|
.. variable:: CPACK_WIX_UI_BANNER
|
|
|
|
The bitmap will appear at the top of all installer pages other than the
|
|
welcome and completion dialogs.
|
|
|
|
If set, this image will replace the default banner image.
|
|
|
|
This image must be 493 by 58 pixels.
|
|
|
|
.. variable:: CPACK_WIX_UI_DIALOG
|
|
|
|
Background bitmap used on the welcome and completion dialogs.
|
|
|
|
If this variable is set, the installer will replace the default dialog
|
|
image.
|
|
|
|
This image must be 493 by 312 pixels.
|
|
|
|
.. variable:: CPACK_WIX_PROGRAM_MENU_FOLDER
|
|
|
|
Start menu folder name for launcher.
|
|
|
|
If this variable is not set, it will be initialized with CPACK_PACKAGE_NAME
|
|
|
|
.. versionadded:: 3.16
|
|
If this variable is set to ``.``, then application shortcuts will be
|
|
created directly in the start menu and the uninstaller shortcut will be
|
|
omitted.
|
|
|
|
.. variable:: CPACK_WIX_CULTURES
|
|
|
|
Language(s) of the installer
|
|
|
|
Languages are compiled into the WixUI 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:
|
|
https://wixtoolset.org/docs/v3/wixui/wixui_localization/
|
|
|
|
.. variable:: CPACK_WIX_TEMPLATE
|
|
|
|
Template file for WiX generation
|
|
|
|
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. 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.
|
|
|
|
.. variable:: CPACK_WIX_PATCH_FILE
|
|
|
|
Optional list of XML files with fragments to be inserted into
|
|
generated WiX sources.
|
|
|
|
.. versionadded:: 3.5
|
|
Support listing multiple patch files.
|
|
|
|
This optional variable can be used to specify an XML file that the
|
|
WIX generator will use to inject fragments into its generated
|
|
source files.
|
|
|
|
Patch files understood by the CPack WIX generator
|
|
roughly follow this RELAX NG compact schema:
|
|
|
|
.. code-block:: none
|
|
|
|
start = CPackWiXPatch
|
|
|
|
CPackWiXPatch = element CPackWiXPatch { CPackWiXFragment* }
|
|
|
|
CPackWiXFragment = element CPackWiXFragment
|
|
{
|
|
attribute Id { string },
|
|
fragmentContent*
|
|
}
|
|
|
|
fragmentContent = element * - CPackWiXFragment
|
|
{
|
|
(attribute * { text } | text | fragmentContent)*
|
|
}
|
|
|
|
Currently fragments can be injected into most
|
|
Component, File, Directory and Feature elements.
|
|
|
|
.. versionadded:: 3.3
|
|
The following additional special Ids can be used:
|
|
|
|
* ``#PRODUCT`` for the ``<Product>`` element.
|
|
* ``#PRODUCTFEATURE`` for the root ``<Feature>`` element.
|
|
|
|
.. versionadded:: 3.7
|
|
Support patching arbitrary ``<Feature>`` elements.
|
|
|
|
.. versionadded:: 3.9
|
|
Allow setting additional attributes.
|
|
|
|
The following example illustrates how this works.
|
|
|
|
Given that the WIX generator creates the following XML element:
|
|
|
|
.. code-block:: xml
|
|
|
|
<Component Id="CM_CP_applications.bin.my_libapp.exe" Guid="*"/>
|
|
|
|
The following XML patch file may be used to inject an Environment element
|
|
into it:
|
|
|
|
.. code-block:: xml
|
|
|
|
<CPackWiXPatch>
|
|
<CPackWiXFragment Id="CM_CP_applications.bin.my_libapp.exe">
|
|
<Environment Id="MyEnvironment" Action="set"
|
|
Name="MyVariableName" Value="MyVariableValue"/>
|
|
</CPackWiXFragment>
|
|
</CPackWiXPatch>
|
|
|
|
.. variable:: CPACK_WIX_EXTRA_SOURCES
|
|
|
|
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.
|
|
|
|
.. variable:: CPACK_WIX_EXTRA_OBJECTS
|
|
|
|
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.
|
|
|
|
.. variable:: CPACK_WIX_EXTENSIONS
|
|
|
|
This variable provides a list of additional extensions for the WiX
|
|
tools light and candle.
|
|
|
|
.. variable:: CPACK_WIX_<TOOL>_EXTENSIONS
|
|
|
|
This is the tool specific version of CPACK_WIX_EXTENSIONS.
|
|
``<TOOL>`` can be either LIGHT or CANDLE.
|
|
|
|
.. variable:: CPACK_WIX_<TOOL>_EXTRA_FLAGS
|
|
|
|
This list variable allows you to pass additional
|
|
flags to the WiX tool ``<TOOL>``.
|
|
|
|
Use it at your own risk.
|
|
Future versions of CPack may generate flags which may be in conflict
|
|
with your own flags.
|
|
|
|
``<TOOL>`` can be either LIGHT or CANDLE.
|
|
|
|
.. variable:: CPACK_WIX_CMAKE_PACKAGE_REGISTRY
|
|
|
|
If this variable is set the generated installer will create
|
|
an entry in the windows registry key
|
|
``HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>``
|
|
The value for ``<PackageName>`` is provided by this variable.
|
|
|
|
Assuming you also install a CMake configuration file this will
|
|
allow other CMake projects to find your package with
|
|
the :command:`find_package` command.
|
|
|
|
.. variable:: CPACK_WIX_PROPERTY_<PROPERTY>
|
|
|
|
.. versionadded:: 3.1
|
|
|
|
This variable can be used to provide a value for
|
|
the Windows Installer property ``<PROPERTY>``
|
|
|
|
The following list contains some example properties that can be used to
|
|
customize information under
|
|
"Programs and Features" (also known as "Add or Remove Programs")
|
|
|
|
* ARPCOMMENTS - Comments
|
|
* ARPHELPLINK - Help and support information URL
|
|
* ARPURLINFOABOUT - General information URL
|
|
* ARPURLUPDATEINFO - Update information URL
|
|
* ARPHELPTELEPHONE - Help and support telephone number
|
|
* ARPSIZE - Size (in kilobytes) of the application
|
|
|
|
.. variable:: CPACK_WIX_ROOT_FEATURE_TITLE
|
|
|
|
.. versionadded:: 3.7
|
|
|
|
Sets the name of the root install feature in the WIX installer. Same as
|
|
CPACK_COMPONENT_<compName>_DISPLAY_NAME for components.
|
|
|
|
.. variable:: CPACK_WIX_ROOT_FEATURE_DESCRIPTION
|
|
|
|
.. versionadded:: 3.7
|
|
|
|
Sets the description of the root install feature in the WIX installer. Same as
|
|
CPACK_COMPONENT_<compName>_DESCRIPTION for components.
|
|
|
|
.. variable:: CPACK_WIX_SKIP_PROGRAM_FOLDER
|
|
|
|
.. versionadded:: 3.7
|
|
|
|
If this variable is set to true, the default install location
|
|
of the generated package will be CPACK_PACKAGE_INSTALL_DIRECTORY directly.
|
|
The install location will not be located relatively below
|
|
ProgramFiles or ProgramFiles64.
|
|
|
|
.. note::
|
|
Installers created with this feature do not take differences
|
|
between the system on which the installer is created
|
|
and the system on which the installer might be used into account.
|
|
|
|
It is therefore possible that the installer e.g. might try to install
|
|
onto a drive that is unavailable or unintended or a path that does not
|
|
follow the localization or convention of the system on which the
|
|
installation is performed.
|
|
|
|
.. variable:: CPACK_WIX_ROOT_FOLDER_ID
|
|
|
|
.. versionadded:: 3.9
|
|
|
|
This variable allows specification of a custom root folder ID.
|
|
The generator specific ``<64>`` token can be used for
|
|
folder IDs that come in 32-bit and 64-bit variants.
|
|
In 32-bit builds the token will expand empty while in 64-bit builds
|
|
it will expand to ``64``.
|
|
|
|
When unset generated installers will default installing to
|
|
``ProgramFiles<64>Folder``.
|
|
|
|
.. variable:: CPACK_WIX_ROOT
|
|
|
|
This variable can optionally be set to the root directory
|
|
of a custom WiX Toolset installation.
|
|
|
|
When unspecified CPack will try to locate a WiX Toolset
|
|
installation via the ``WIX`` environment variable instead.
|
|
|
|
.. variable:: CPACK_WIX_CUSTOM_XMLNS
|
|
|
|
.. versionadded:: 3.19
|
|
|
|
This variable provides a list of custom namespace declarations that are necessary
|
|
for using WiX extensions. Each declaration should be in the form name=url, where
|
|
name is the plain namespace without the usual xmlns: prefix and url is an unquoted
|
|
namespace url. A list of commonly known WiX schemata can be found here:
|
|
https://wixtoolset.org/docs/v3/xsd/
|
|
|
|
.. variable:: CPACK_WIX_SKIP_WIX_UI_EXTENSION
|
|
|
|
.. 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.
|
|
|
|
.. variable:: CPACK_WIX_ARCHITECTURE
|
|
|
|
.. versionadded:: 3.24
|
|
|
|
This variable can be optionally set to specify the target architecture
|
|
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``
|
|
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.
|
|
|
|
This is the default to preserve compatibility with CPack 3.28 and older.
|
|
|
|
.. 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.
|
|
|
|
.. warning::
|
|
|
|
An installation performed by an installer created without any
|
|
``InstallScope`` cannot be cleanly updated or replaced by an
|
|
installer with an ``InstallScope``. In order to transition
|
|
a project's installers from ``NONE`` to ``perMachine``, the
|
|
latter installer should be distributed with instructions to
|
|
first manually uninstall any older version.
|
|
|
|
See https://wixtoolset.org/docs/v3/xsd/wix/package/
|