Help/cpack_gen/wix.rst

   1 CPack WIX Generator
   2 -------------------
   3
   4 CPack WIX generator specific options
   5
   6 .. versionadded:: 3.7
   7   Support :variable:`CPACK_COMPONENT_<compName>_DISABLED` variable.
   8
   9 Variables specific to CPack WIX generator
  10 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  11
  12 The following variables are specific to the installers built on
  13 Windows using WiX.
  14
  15 .. variable:: CPACK_WIX_UPGRADE_GUID
  16
  17  Upgrade GUID (``Product/@UpgradeCode``)
  18
  19  Will be automatically generated unless explicitly provided.
  20
  21  It should be explicitly set to a constant generated globally unique
  22  identifier (GUID) to allow your installers to replace existing
  23  installations that use the same GUID.
  24
  25  You may for example explicitly set this variable in your
  26  CMakeLists.txt to the value that has been generated per default.  You
  27  should not use GUIDs that you did not generate yourself or which may
  28  belong to other projects.
  29
  30  A GUID shall have the following fixed length syntax::
  31
  32   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  33
  34  (each X represents an uppercase hexadecimal digit)
  35
  36 .. variable:: CPACK_WIX_PRODUCT_GUID
  37
  38  Product GUID (``Product/@Id``)
  39
  40  Will be automatically generated unless explicitly provided.
  41
  42  If explicitly provided this will set the Product Id of your installer.
  43
  44  The installer will abort if it detects a pre-existing installation that
  45  uses the same GUID.
  46
  47  The GUID shall use the syntax described for CPACK_WIX_UPGRADE_GUID.
  48
  49 .. variable:: CPACK_WIX_LICENSE_RTF
  50
  51  RTF License File
  52
  53  If CPACK_RESOURCE_FILE_LICENSE has an .rtf extension it is used as-is.
  54
  55  If CPACK_RESOURCE_FILE_LICENSE has an .txt extension it is implicitly
  56  converted to RTF by the WIX Generator.
  57  The expected encoding of the .txt file is UTF-8.
  58
  59  With CPACK_WIX_LICENSE_RTF you can override the license file used by the
  60  WIX Generator in case CPACK_RESOURCE_FILE_LICENSE is in an unsupported
  61  format or the .txt -> .rtf conversion does not work as expected.
  62
  63 .. variable:: CPACK_WIX_PRODUCT_ICON
  64
  65  The Icon shown next to the program name in Add/Remove programs.
  66
  67  If set, this icon is used in place of the default icon.
  68
  69 .. variable:: CPACK_WIX_UI_REF
  70
  71  This variable allows you to override the Id of the ``<UIRef>`` element
  72  in the WiX template.
  73
  74  The default is ``WixUI_InstallDir`` in case no CPack components have
  75  been defined and ``WixUI_FeatureTree`` otherwise.
  76
  77 .. variable:: CPACK_WIX_UI_BANNER
  78
  79  The bitmap will appear at the top of all installer pages other than the
  80  welcome and completion dialogs.
  81
  82  If set, this image will replace the default banner image.
  83
  84  This image must be 493 by 58 pixels.
  85
  86 .. variable:: CPACK_WIX_UI_DIALOG
  87
  88  Background bitmap used on the welcome and completion dialogs.
  89
  90  If this variable is set, the installer will replace the default dialog
  91  image.
  92
  93  This image must be 493 by 312 pixels.
  94
  95 .. variable:: CPACK_WIX_PROGRAM_MENU_FOLDER
  96
  97  Start menu folder name for launcher.
  98
  99  If this variable is not set, it will be initialized with CPACK_PACKAGE_NAME
 100
 101  .. versionadded:: 3.16
 102   If this variable is set to ``.``, then application shortcuts will be
 103   created directly in the start menu and the uninstaller shortcut will be
 104   omitted.
 105
 106 .. variable:: CPACK_WIX_CULTURES
 107
 108  Language(s) of the installer
 109
 110  Languages are compiled into the WixUI extension library.  To use them,
 111  simply provide the name of the culture.  If you specify more than one
 112  culture identifier in a comma or semicolon delimited list, the first one
 113  that is found will be used.  You can find a list of supported languages at:
 114  https://wixtoolset.org//documentation/manual/v3/wixui/wixui_localization.html
 115
 116 .. variable:: CPACK_WIX_TEMPLATE
 117
 118  Template file for WiX generation
 119
 120  If this variable is set, the specified template will be used to generate
 121  the WiX wxs file.  This should be used if further customization of the
 122  output is required.
 123
 124  If this variable is not set, the default MSI template included with CMake
 125  will be used.
 126
 127 .. variable:: CPACK_WIX_PATCH_FILE
 128
 129  Optional list of XML files with fragments to be inserted into
 130  generated WiX sources.
 131
 132  .. versionadded:: 3.5
 133   Support listing multiple patch files.
 134
 135  This optional variable can be used to specify an XML file that the
 136  WIX generator will use to inject fragments into its generated
 137  source files.
 138
 139  Patch files understood by the CPack WIX generator
 140  roughly follow this RELAX NG compact schema:
 141
 142  .. code-block:: none
 143
 144     start = CPackWiXPatch
 145
 146     CPackWiXPatch = element CPackWiXPatch { CPackWiXFragment* }
 147
 148     CPackWiXFragment = element CPackWiXFragment
 149     {
 150         attribute Id { string },
 151         fragmentContent*
 152     }
 153
 154     fragmentContent = element * - CPackWiXFragment
 155     {
 156         (attribute * { text } | text | fragmentContent)*
 157     }
 158
 159  Currently fragments can be injected into most
 160  Component, File, Directory and Feature elements.
 161
 162  .. versionadded:: 3.3
 163   The following additional special Ids can be used:
 164
 165   * ``#PRODUCT`` for the ``<Product>`` element.
 166   * ``#PRODUCTFEATURE`` for the root ``<Feature>`` element.
 167
 168  .. versionadded:: 3.7
 169   Support patching arbitrary ``<Feature>`` elements.
 170
 171  .. versionadded:: 3.9
 172   Allow setting additional attributes.
 173
 174  The following example illustrates how this works.
 175
 176  Given that the WIX generator creates the following XML element:
 177
 178  .. code-block:: xml
 179
 180     <Component Id="CM_CP_applications.bin.my_libapp.exe" Guid="*"/>
 181
 182  The following XML patch file may be used to inject an Environment element
 183  into it:
 184
 185  .. code-block:: xml
 186
 187     <CPackWiXPatch>
 188       <CPackWiXFragment Id="CM_CP_applications.bin.my_libapp.exe">
 189         <Environment Id="MyEnvironment" Action="set"
 190           Name="MyVariableName" Value="MyVariableValue"/>
 191       </CPackWiXFragment>
 192     </CPackWiXPatch>
 193
 194 .. variable:: CPACK_WIX_EXTRA_SOURCES
 195
 196  Extra WiX source files
 197
 198  This variable provides an optional list of extra WiX source files (.wxs)
 199  that should be compiled and linked.  The full path to source files is
 200  required.
 201
 202 .. variable:: CPACK_WIX_EXTRA_OBJECTS
 203
 204  Extra WiX object files or libraries
 205
 206  This variable provides an optional list of extra WiX object (.wixobj)
 207  and/or WiX library (.wixlib) files.  The full path to objects and libraries
 208  is required.
 209
 210 .. variable:: CPACK_WIX_EXTENSIONS
 211
 212  This variable provides a list of additional extensions for the WiX
 213  tools light and candle.
 214
 215 .. variable:: CPACK_WIX_<TOOL>_EXTENSIONS
 216
 217  This is the tool specific version of CPACK_WIX_EXTENSIONS.
 218  ``<TOOL>`` can be either LIGHT or CANDLE.
 219
 220 .. variable:: CPACK_WIX_<TOOL>_EXTRA_FLAGS
 221
 222  This list variable allows you to pass additional
 223  flags to the WiX tool ``<TOOL>``.
 224
 225  Use it at your own risk.
 226  Future versions of CPack may generate flags which may be in conflict
 227  with your own flags.
 228
 229  ``<TOOL>`` can be either LIGHT or CANDLE.
 230
 231 .. variable:: CPACK_WIX_CMAKE_PACKAGE_REGISTRY
 232
 233  If this variable is set the generated installer will create
 234  an entry in the windows registry key
 235  ``HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>``
 236  The value for ``<PackageName>`` is provided by this variable.
 237
 238  Assuming you also install a CMake configuration file this will
 239  allow other CMake projects to find your package with
 240  the :command:`find_package` command.
 241
 242 .. variable:: CPACK_WIX_PROPERTY_<PROPERTY>
 243
 244  .. versionadded:: 3.1
 245
 246  This variable can be used to provide a value for
 247  the Windows Installer property ``<PROPERTY>``
 248
 249  The following list contains some example properties that can be used to
 250  customize information under
 251  "Programs and Features" (also known as "Add or Remove Programs")
 252
 253  * ARPCOMMENTS - Comments
 254  * ARPHELPLINK - Help and support information URL
 255  * ARPURLINFOABOUT - General information URL
 256  * ARPURLUPDATEINFO - Update information URL
 257  * ARPHELPTELEPHONE - Help and support telephone number
 258  * ARPSIZE - Size (in kilobytes) of the application
 259
 260 .. variable:: CPACK_WIX_ROOT_FEATURE_TITLE
 261
 262  .. versionadded:: 3.7
 263
 264  Sets the name of the root install feature in the WIX installer. Same as
 265  CPACK_COMPONENT_<compName>_DISPLAY_NAME for components.
 266
 267 .. variable:: CPACK_WIX_ROOT_FEATURE_DESCRIPTION
 268
 269  .. versionadded:: 3.7
 270
 271  Sets the description of the root install feature in the WIX installer. Same as
 272  CPACK_COMPONENT_<compName>_DESCRIPTION for components.
 273
 274 .. variable:: CPACK_WIX_SKIP_PROGRAM_FOLDER
 275
 276  .. versionadded:: 3.7
 277
 278  If this variable is set to true, the default install location
 279  of the generated package will be CPACK_PACKAGE_INSTALL_DIRECTORY directly.
 280  The install location will not be located relatively below
 281  ProgramFiles or ProgramFiles64.
 282
 283   .. note::
 284     Installers created with this feature do not take differences
 285     between the system on which the installer is created
 286     and the system on which the installer might be used into account.
 287
 288     It is therefore possible that the installer e.g. might try to install
 289     onto a drive that is unavailable or unintended or a path that does not
 290     follow the localization or convention of the system on which the
 291     installation is performed.
 292
 293 .. variable:: CPACK_WIX_ROOT_FOLDER_ID
 294
 295  .. versionadded:: 3.9
 296
 297  This variable allows specification of a custom root folder ID.
 298  The generator specific ``<64>`` token can be used for
 299  folder IDs that come in 32-bit and 64-bit variants.
 300  In 32-bit builds the token will expand empty while in 64-bit builds
 301  it will expand to ``64``.
 302
 303  When unset generated installers will default installing to
 304  ``ProgramFiles<64>Folder``.
 305
 306 .. variable:: CPACK_WIX_ROOT
 307
 308  This variable can optionally be set to the root directory
 309  of a custom WiX Toolset installation.
 310
 311  When unspecified CPack will try to locate a WiX Toolset
 312  installation via the ``WIX`` environment variable instead.
 313
 314 .. variable:: CPACK_WIX_CUSTOM_XMLNS
 315
 316  .. versionadded:: 3.19
 317
 318  This variable provides a list of custom namespace declarations that are necessary
 319  for using WiX extensions. Each declaration should be in the form name=url, where
 320  name is the plain namespace without the usual xmlns: prefix and url is an unquoted
 321  namespace url. A list of commonly known WiX schemata can be found here:
 322  https://wixtoolset.org/documentation/manual/v3/xsd/
 323
 324 .. variable:: CPACK_WIX_SKIP_WIX_UI_EXTENSION
 325
 326  .. versionadded:: 3.23
 327
 328  If this variable is set then the inclusion of WixUIExtensions is skipped,
 329  i.e. the ``-ext "WixUIExtension"`` command line is not included during
 330  the execution of the WiX light tool.
 331
 332 .. variable:: CPACK_WIX_ARCHITECTURE
 333
 334  .. versionadded:: 3.24
 335
 336  This variable can be optionally set to specify the target architecture
 337  of the installer. May for example be set to ``x64`` or ``arm64``.
 338
 339  When unspecified, CPack will default to ``x64`` or ``x86``.