1CPack WIX Generator 2------------------- 3 4CPack WIX generator specific options 5 6.. versionadded:: 3.7 7 Support :variable:`CPACK_COMPONENT_<compName>_DISABLED` variable. 8 9Variables specific to CPack WIX generator 10^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11 12The following variables are specific to the installers built on 13Windows 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 http://wix.sourceforge.net/manual-wix3/WixUI_localization.htm 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