4 CPack WIX generator specific options
7 Support :variable:`CPACK_COMPONENT_<compName>_DISABLED` variable.
9 Variables specific to CPack WIX generator
10 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12 The following variables are specific to the installers built on
15 .. variable:: CPACK_WIX_UPGRADE_GUID
17 Upgrade GUID (``Product/@UpgradeCode``)
19 Will be automatically generated unless explicitly provided.
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.
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.
30 A GUID shall have the following fixed length syntax::
32 XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
34 (each X represents an uppercase hexadecimal digit)
36 .. variable:: CPACK_WIX_PRODUCT_GUID
38 Product GUID (``Product/@Id``)
40 Will be automatically generated unless explicitly provided.
42 If explicitly provided this will set the Product Id of your installer.
44 The installer will abort if it detects a pre-existing installation that
47 The GUID shall use the syntax described for CPACK_WIX_UPGRADE_GUID.
49 .. variable:: CPACK_WIX_LICENSE_RTF
53 If CPACK_RESOURCE_FILE_LICENSE has an .rtf extension it is used as-is.
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.
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.
63 .. variable:: CPACK_WIX_PRODUCT_ICON
65 The Icon shown next to the program name in Add/Remove programs.
67 If set, this icon is used in place of the default icon.
69 .. variable:: CPACK_WIX_UI_REF
71 This variable allows you to override the Id of the ``<UIRef>`` element
74 The default is ``WixUI_InstallDir`` in case no CPack components have
75 been defined and ``WixUI_FeatureTree`` otherwise.
77 .. variable:: CPACK_WIX_UI_BANNER
79 The bitmap will appear at the top of all installer pages other than the
80 welcome and completion dialogs.
82 If set, this image will replace the default banner image.
84 This image must be 493 by 58 pixels.
86 .. variable:: CPACK_WIX_UI_DIALOG
88 Background bitmap used on the welcome and completion dialogs.
90 If this variable is set, the installer will replace the default dialog
93 This image must be 493 by 312 pixels.
95 .. variable:: CPACK_WIX_PROGRAM_MENU_FOLDER
97 Start menu folder name for launcher.
99 If this variable is not set, it will be initialized with CPACK_PACKAGE_NAME
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
106 .. variable:: CPACK_WIX_CULTURES
108 Language(s) of the installer
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 http://wix.sourceforge.net/manual-wix3/WixUI_localization.htm
116 .. variable:: CPACK_WIX_TEMPLATE
118 Template file for WiX generation
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
124 If this variable is not set, the default MSI template included with CMake
127 .. variable:: CPACK_WIX_PATCH_FILE
129 Optional list of XML files with fragments to be inserted into
130 generated WiX sources.
132 .. versionadded:: 3.5
133 Support listing multiple patch files.
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
139 Patch files understood by the CPack WIX generator
140 roughly follow this RELAX NG compact schema:
144 start = CPackWiXPatch
146 CPackWiXPatch = element CPackWiXPatch { CPackWiXFragment* }
148 CPackWiXFragment = element CPackWiXFragment
150 attribute Id { string },
154 fragmentContent = element * - CPackWiXFragment
156 (attribute * { text } | text | fragmentContent)*
159 Currently fragments can be injected into most
160 Component, File, Directory and Feature elements.
162 .. versionadded:: 3.3
163 The following additional special Ids can be used:
165 * ``#PRODUCT`` for the ``<Product>`` element.
166 * ``#PRODUCTFEATURE`` for the root ``<Feature>`` element.
168 .. versionadded:: 3.7
169 Support patching arbitrary ``<Feature>`` elements.
171 .. versionadded:: 3.9
172 Allow setting additional attributes.
174 The following example illustrates how this works.
176 Given that the WIX generator creates the following XML element:
180 <Component Id="CM_CP_applications.bin.my_libapp.exe" Guid="*"/>
182 The following XML patch file may be used to inject an Environment element
188 <CPackWiXFragment Id="CM_CP_applications.bin.my_libapp.exe">
189 <Environment Id="MyEnvironment" Action="set"
190 Name="MyVariableName" Value="MyVariableValue"/>
194 .. variable:: CPACK_WIX_EXTRA_SOURCES
196 Extra WiX source files
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
202 .. variable:: CPACK_WIX_EXTRA_OBJECTS
204 Extra WiX object files or libraries
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
210 .. variable:: CPACK_WIX_EXTENSIONS
212 This variable provides a list of additional extensions for the WiX
213 tools light and candle.
215 .. variable:: CPACK_WIX_<TOOL>_EXTENSIONS
217 This is the tool specific version of CPACK_WIX_EXTENSIONS.
218 ``<TOOL>`` can be either LIGHT or CANDLE.
220 .. variable:: CPACK_WIX_<TOOL>_EXTRA_FLAGS
222 This list variable allows you to pass additional
223 flags to the WiX tool ``<TOOL>``.
225 Use it at your own risk.
226 Future versions of CPack may generate flags which may be in conflict
229 ``<TOOL>`` can be either LIGHT or CANDLE.
231 .. variable:: CPACK_WIX_CMAKE_PACKAGE_REGISTRY
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.
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.
242 .. variable:: CPACK_WIX_PROPERTY_<PROPERTY>
244 .. versionadded:: 3.1
246 This variable can be used to provide a value for
247 the Windows Installer property ``<PROPERTY>``
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")
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
260 .. variable:: CPACK_WIX_ROOT_FEATURE_TITLE
262 .. versionadded:: 3.7
264 Sets the name of the root install feature in the WIX installer. Same as
265 CPACK_COMPONENT_<compName>_DISPLAY_NAME for components.
267 .. variable:: CPACK_WIX_ROOT_FEATURE_DESCRIPTION
269 .. versionadded:: 3.7
271 Sets the description of the root install feature in the WIX installer. Same as
272 CPACK_COMPONENT_<compName>_DESCRIPTION for components.
274 .. variable:: CPACK_WIX_SKIP_PROGRAM_FOLDER
276 .. versionadded:: 3.7
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.
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.
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.
293 .. variable:: CPACK_WIX_ROOT_FOLDER_ID
295 .. versionadded:: 3.9
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``.
303 When unset generated installers will default installing to
304 ``ProgramFiles<64>Folder``.
306 .. variable:: CPACK_WIX_ROOT
308 This variable can optionally be set to the root directory
309 of a custom WiX Toolset installation.
311 When unspecified CPack will try to locate a WiX Toolset
312 installation via the ``WIX`` environment variable instead.
314 .. variable:: CPACK_WIX_CUSTOM_XMLNS
316 .. versionadded:: 3.19
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/
324 .. variable:: CPACK_WIX_SKIP_WIX_UI_EXTENSION
326 .. versionadded:: 3.23
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.
332 .. variable:: CPACK_WIX_ARCHITECTURE
334 .. versionadded:: 3.24
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``.
339 When unspecified, CPack will default to ``x64`` or ``x86``.