1# Distributed under the OSI-approved BSD 3-Clause License. See accompanying 2# file Copyright.txt or https://cmake.org/licensing for details. 3 4#[=======================================================================[.rst: 5CPackComponent 6-------------- 7 8Configure components for binary installers and source packages. 9 10.. only:: html 11 12 .. contents:: 13 14Introduction 15^^^^^^^^^^^^ 16 17This module is automatically included by :module:`CPack`. 18 19Certain binary installers (especially the graphical installers) generated 20by CPack allow users to select individual application *components* to install. 21This module allows developers to configure the packaging of such components. 22 23Contents is assigned to components by the ``COMPONENT`` 24argument of CMake's :command:`install` command. Components can be 25annotated with user-friendly names and descriptions, inter-component 26dependencies, etc., and grouped in various ways to customize the 27resulting installer, using the commands described below. 28 29To specify different groupings for different CPack generators use 30a CPACK_PROJECT_CONFIG_FILE. 31 32Variables 33^^^^^^^^^ 34 35The following variables influence the component-specific packaging: 36 37.. variable:: CPACK_COMPONENTS_ALL 38 39 The list of component to install. 40 41 The default value of this variable is computed by CPack and contains all 42 components defined by the project. The user may set it to only include the 43 specified components. 44 45 Instead of specifying all the desired components, it is possible to obtain a 46 list of all defined components and then remove the unwanted ones from the 47 list. The :command:`get_cmake_property` command can be used to obtain the 48 ``COMPONENTS`` property, then the :command:`list(REMOVE_ITEM)` command can be 49 used to remove the unwanted ones. For example, to use all defined components 50 except ``foo`` and ``bar``:: 51 52 get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS) 53 list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar") 54 55.. variable:: CPACK_<GENNAME>_COMPONENT_INSTALL 56 57 Enable/Disable component install for CPack generator <GENNAME>. 58 59 Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc...) has a legacy 60 default behavior. e.g. RPM builds monolithic whereas NSIS builds 61 component. One can change the default behavior by setting this variable to 62 0/1 or OFF/ON. 63 64.. variable:: CPACK_COMPONENTS_GROUPING 65 66 Specify how components are grouped for multi-package component-aware CPack 67 generators. 68 69 Some generators like RPM or ARCHIVE (TGZ, ZIP, ...) may generate 70 several packages files when there are components, depending 71 on the value of this variable: 72 73 * ONE_PER_GROUP (default): create one package per component group 74 * IGNORE : create one package per component (ignore the groups) 75 * ALL_COMPONENTS_IN_ONE : create a single package with all requested 76 components 77 78.. variable:: CPACK_COMPONENT_<compName>_DISPLAY_NAME 79 80 The name to be displayed for a component. 81 82.. variable:: CPACK_COMPONENT_<compName>_DESCRIPTION 83 84 The description of a component. 85 86.. variable:: CPACK_COMPONENT_<compName>_GROUP 87 88 The group of a component. 89 90.. variable:: CPACK_COMPONENT_<compName>_DEPENDS 91 92 The dependencies (list of components) on which this component depends. 93 94.. variable:: CPACK_COMPONENT_<compName>_HIDDEN 95 96 True if this component is hidden from the user. 97 98.. variable:: CPACK_COMPONENT_<compName>_REQUIRED 99 100 True if this component is required. 101 102.. variable:: CPACK_COMPONENT_<compName>_DISABLED 103 104 True if this component is not selected to be installed by default. 105 106Commands 107^^^^^^^^ 108 109Add component 110""""""""""""" 111 112.. command:: cpack_add_component 113 114Describe an installation component. 115 116:: 117 118 cpack_add_component(compname 119 [DISPLAY_NAME name] 120 [DESCRIPTION description] 121 [HIDDEN | REQUIRED | DISABLED ] 122 [GROUP group] 123 [DEPENDS comp1 comp2 ... ] 124 [INSTALL_TYPES type1 type2 ... ] 125 [DOWNLOADED] 126 [ARCHIVE_FILE filename] 127 [PLIST filename]) 128 129``compname`` is the name of an installation component, as defined by the 130``COMPONENT`` argument of one or more CMake :command:`install` commands. 131With the ``cpack_add_component`` command one can set a name, a description, 132and other attributes of an installation component. 133One can also assign a component to a component group. 134 135DISPLAY_NAME is the displayed name of the component, used in graphical 136installers to display the component name. This value can be any 137string. 138 139DESCRIPTION is an extended description of the component, used in 140graphical installers to give the user additional information about the 141component. Descriptions can span multiple lines using ``\n`` as the 142line separator. Typically, these descriptions should be no more than 143a few lines long. 144 145HIDDEN indicates that this component will be hidden in the graphical 146installer, so that the user cannot directly change whether it is 147installed or not. 148 149REQUIRED indicates that this component is required, and therefore will 150always be installed. It will be visible in the graphical installer, 151but it cannot be unselected. (Typically, required components are 152shown greyed out). 153 154DISABLED indicates that this component should be disabled (unselected) 155by default. The user is free to select this component for 156installation, unless it is also HIDDEN. 157 158DEPENDS lists the components on which this component depends. If this 159component is selected, then each of the components listed must also be 160selected. The dependency information is encoded within the installer 161itself, so that users cannot install inconsistent sets of components. 162 163GROUP names the component group of which this component is a part. If 164not provided, the component will be a standalone component, not part 165of any component group. Component groups are described with the 166cpack_add_component_group command, detailed below. 167 168INSTALL_TYPES lists the installation types of which this component is 169a part. When one of these installations types is selected, this 170component will automatically be selected. Installation types are 171described with the cpack_add_install_type command, detailed below. 172 173DOWNLOADED indicates that this component should be downloaded 174on-the-fly by the installer, rather than packaged in with the 175installer itself. For more information, see the 176cpack_configure_downloads command. 177 178ARCHIVE_FILE provides a name for the archive file created by CPack to 179be used for downloaded components. If not supplied, CPack will create 180a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of 181the component. See cpack_configure_downloads for more information. 182 183PLIST gives a filename that is passed to pkgbuild with the 184``--component-plist`` argument when using the productbuild generator. 185 186Add component group 187""""""""""""""""""" 188 189.. command:: cpack_add_component_group 190 191Describes a group of related CPack installation components. 192 193:: 194 195 cpack_add_component_group(groupname 196 [DISPLAY_NAME name] 197 [DESCRIPTION description] 198 [PARENT_GROUP parent] 199 [EXPANDED] 200 [BOLD_TITLE]) 201 202 203 204The cpack_add_component_group describes a group of installation 205components, which will be placed together within the listing of 206options. Typically, component groups allow the user to 207select/deselect all of the components within a single group via a 208single group-level option. Use component groups to reduce the 209complexity of installers with many options. groupname is an arbitrary 210name used to identify the group in the GROUP argument of the 211cpack_add_component command, which is used to place a component in a 212group. The name of the group must not conflict with the name of any 213component. 214 215DISPLAY_NAME is the displayed name of the component group, used in 216graphical installers to display the component group name. This value 217can be any string. 218 219DESCRIPTION is an extended description of the component group, used in 220graphical installers to give the user additional information about the 221components within that group. Descriptions can span multiple lines 222using ``\n`` as the line separator. Typically, these descriptions 223should be no more than a few lines long. 224 225PARENT_GROUP, if supplied, names the parent group of this group. 226Parent groups are used to establish a hierarchy of groups, providing 227an arbitrary hierarchy of groups. 228 229EXPANDED indicates that, by default, the group should show up as 230"expanded", so that the user immediately sees all of the components 231within the group. Otherwise, the group will initially show up as a 232single entry. 233 234BOLD_TITLE indicates that the group title should appear in bold, to 235call the user's attention to the group. 236 237Add installation type 238""""""""""""""""""""" 239 240.. command:: cpack_add_install_type 241 242Add a new installation type containing 243a set of predefined component selections to the graphical installer. 244 245:: 246 247 cpack_add_install_type(typename 248 [DISPLAY_NAME name]) 249 250 251 252The cpack_add_install_type command identifies a set of preselected 253components that represents a common use case for an application. For 254example, a "Developer" install type might include an application along 255with its header and library files, while an "End user" install type 256might just include the application's executable. Each component 257identifies itself with one or more install types via the INSTALL_TYPES 258argument to cpack_add_component. 259 260DISPLAY_NAME is the displayed name of the install type, which will 261typically show up in a drop-down box within a graphical installer. 262This value can be any string. 263 264Configure downloads 265""""""""""""""""""" 266 267.. command:: cpack_configure_downloads 268 269Configure CPack to download 270selected components on-the-fly as part of the installation process. 271 272:: 273 274 cpack_configure_downloads(site 275 [UPLOAD_DIRECTORY dirname] 276 [ALL] 277 [ADD_REMOVE|NO_ADD_REMOVE]) 278 279 280 281The cpack_configure_downloads command configures installation-time 282downloads of selected components. For each downloadable component, 283CPack will create an archive containing the contents of that 284component, which should be uploaded to the given site. When the user 285selects that component for installation, the installer will download 286and extract the component in place. This feature is useful for 287creating small installers that only download the requested components, 288saving bandwidth. Additionally, the installers are small enough that 289they will be installed as part of the normal installation process, and 290the "Change" button in Windows Add/Remove Programs control panel will 291allow one to add or remove parts of the application after the original 292installation. On Windows, the downloaded-components functionality 293requires the ZipDLL plug-in for NSIS, available at: 294 295:: 296 297 http://nsis.sourceforge.net/ZipDLL_plug-in 298 299On macOS, installers that download components on-the-fly can only 300be built and installed on system using macOS 10.5 or later. 301 302The site argument is a URL where the archives for downloadable 303components will reside, e.g., 304https://cmake.org/files/2.6.1/installer/ All of the archives 305produced by CPack should be uploaded to that location. 306 307UPLOAD_DIRECTORY is the local directory where CPack will create the 308various archives for each of the components. The contents of this 309directory should be uploaded to a location accessible by the URL given 310in the site argument. If omitted, CPack will use the directory 311CPackUploads inside the CMake binary directory to store the generated 312archives. 313 314The ALL flag indicates that all components be downloaded. Otherwise, 315only those components explicitly marked as DOWNLOADED or that have a 316specified ARCHIVE_FILE will be downloaded. Additionally, the ALL 317option implies ADD_REMOVE (unless NO_ADD_REMOVE is specified). 318 319ADD_REMOVE indicates that CPack should install a copy of the installer 320that can be called from Windows' Add/Remove Programs dialog (via the 321"Modify" button) to change the set of installed components. 322NO_ADD_REMOVE turns off this behavior. This option is ignored on Mac 323OS X. 324#]=======================================================================] 325 326# Define var in order to avoid multiple inclusion 327if(NOT CPackComponent_CMake_INCLUDED) 328set(CPackComponent_CMake_INCLUDED 1) 329 330# Macro that appends a SET command for the given variable name (var) 331# to the macro named strvar, but only if the variable named "var" 332# has been defined. The string will eventually be appended to a CPack 333# configuration file. 334macro(cpack_append_variable_set_command var strvar) 335 if (DEFINED ${var}) 336 string(APPEND ${strvar} "set(${var}") 337 foreach(APPENDVAL ${${var}}) 338 string(APPEND ${strvar} " ${APPENDVAL}") 339 endforeach() 340 string(APPEND ${strvar} ")\n") 341 endif () 342endmacro() 343 344# Macro that appends a SET command for the given variable name (var) 345# to the macro named strvar, but only if the variable named "var" 346# has been defined and is a string. The string will eventually be 347# appended to a CPack configuration file. 348macro(cpack_append_string_variable_set_command var strvar) 349 if (DEFINED ${var}) 350 list(LENGTH ${var} CPACK_APP_VALUE_LEN) 351 if(${CPACK_APP_VALUE_LEN} EQUAL 1) 352 string(APPEND ${strvar} "set(${var} \"${${var}}\")\n") 353 endif() 354 endif () 355endmacro() 356 357# Macro that appends a SET command for the given list variable name (var) 358# to the macro named strvar, but only if the variable named "var" 359# has been defined. It's like add variable, but wrap each item to quotes. 360# The string will eventually be appended to a CPack configuration file. 361macro(cpack_append_list_variable_set_command var strvar) 362 if (DEFINED ${var}) 363 string(APPEND ${strvar} "set(${var}") 364 foreach(_val IN LISTS ${var}) 365 string(APPEND ${strvar} "\n \"${_val}\"") 366 endforeach() 367 string(APPEND ${strvar} ")\n") 368 endif () 369endmacro() 370 371# Macro that appends a SET command for the given variable name (var) 372# to the macro named strvar, but only if the variable named "var" 373# has been set to true. The string will eventually be 374# appended to a CPack configuration file. 375macro(cpack_append_option_set_command var strvar) 376 if (${var}) 377 list(LENGTH ${var} CPACK_APP_VALUE_LEN) 378 if(${CPACK_APP_VALUE_LEN} EQUAL 1) 379 string(APPEND ${strvar} "set(${var} TRUE)\n") 380 endif() 381 endif () 382endmacro() 383 384# Macro that adds a component to the CPack installer 385macro(cpack_add_component compname) 386 string(TOUPPER ${compname} _CPACK_ADDCOMP_UNAME) 387 cmake_parse_arguments(CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME} 388 "HIDDEN;REQUIRED;DISABLED;DOWNLOADED" 389 "DISPLAY_NAME;DESCRIPTION;GROUP;ARCHIVE_FILE;PLIST" 390 "DEPENDS;INSTALL_TYPES" 391 ${ARGN} 392 ) 393 394 if (CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_DOWNLOADED) 395 set(_CPACK_ADDCOMP_STR "\n# Configuration for downloaded component \"${compname}\"\n") 396 else () 397 set(_CPACK_ADDCOMP_STR "\n# Configuration for component \"${compname}\"\n") 398 endif () 399 400 if(NOT CPACK_MONOLITHIC_INSTALL) 401 # If the user didn't set CPACK_COMPONENTS_ALL explicitly, update the 402 # value of CPACK_COMPONENTS_ALL in the configuration file. This will 403 # take care of any components that have been added after the CPack 404 # moduled was included. 405 if(NOT CPACK_COMPONENTS_ALL_SET_BY_USER) 406 get_cmake_property(_CPACK_ADDCOMP_COMPONENTS COMPONENTS) 407 string(APPEND _CPACK_ADDCOMP_STR "\nSET(CPACK_COMPONENTS_ALL") 408 foreach(COMP ${_CPACK_ADDCOMP_COMPONENTS}) 409 string(APPEND _CPACK_ADDCOMP_STR " ${COMP}") 410 endforeach() 411 string(APPEND _CPACK_ADDCOMP_STR ")\n") 412 endif() 413 endif() 414 415 cpack_append_string_variable_set_command( 416 CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_DISPLAY_NAME 417 _CPACK_ADDCOMP_STR) 418 cpack_append_string_variable_set_command( 419 CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_DESCRIPTION 420 _CPACK_ADDCOMP_STR) 421 cpack_append_variable_set_command( 422 CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_GROUP 423 _CPACK_ADDCOMP_STR) 424 cpack_append_variable_set_command( 425 CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_DEPENDS 426 _CPACK_ADDCOMP_STR) 427 cpack_append_variable_set_command( 428 CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_INSTALL_TYPES 429 _CPACK_ADDCOMP_STR) 430 cpack_append_string_variable_set_command( 431 CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_ARCHIVE_FILE 432 _CPACK_ADDCOMP_STR) 433 cpack_append_option_set_command( 434 CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_HIDDEN 435 _CPACK_ADDCOMP_STR) 436 cpack_append_option_set_command( 437 CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_REQUIRED 438 _CPACK_ADDCOMP_STR) 439 cpack_append_option_set_command( 440 CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_DISABLED 441 _CPACK_ADDCOMP_STR) 442 cpack_append_option_set_command( 443 CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_DOWNLOADED 444 _CPACK_ADDCOMP_STR) 445 cpack_append_string_variable_set_command( 446 CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_PLIST 447 _CPACK_ADDCOMP_STR) 448 # Backward compatibility issue. 449 # Write to config iff the macros is used after CPack.cmake has been 450 # included, other it's not necessary because the variables 451 # will be encoded by cpack_encode_variables. 452 if(CPack_CMake_INCLUDED) 453 file(APPEND "${CPACK_OUTPUT_CONFIG_FILE}" "${_CPACK_ADDCOMP_STR}") 454 endif() 455endmacro() 456 457# Macro that adds a component group to the CPack installer 458macro(cpack_add_component_group grpname) 459 string(TOUPPER ${grpname} _CPACK_ADDGRP_UNAME) 460 cmake_parse_arguments(CPACK_COMPONENT_GROUP_${_CPACK_ADDGRP_UNAME} 461 "EXPANDED;BOLD_TITLE" 462 "DISPLAY_NAME;DESCRIPTION;PARENT_GROUP" 463 "" 464 ${ARGN} 465 ) 466 467 set(_CPACK_ADDGRP_STR "\n# Configuration for component group \"${grpname}\"\n") 468 cpack_append_string_variable_set_command( 469 CPACK_COMPONENT_GROUP_${_CPACK_ADDGRP_UNAME}_DISPLAY_NAME 470 _CPACK_ADDGRP_STR) 471 cpack_append_string_variable_set_command( 472 CPACK_COMPONENT_GROUP_${_CPACK_ADDGRP_UNAME}_DESCRIPTION 473 _CPACK_ADDGRP_STR) 474 cpack_append_string_variable_set_command( 475 CPACK_COMPONENT_GROUP_${_CPACK_ADDGRP_UNAME}_PARENT_GROUP 476 _CPACK_ADDGRP_STR) 477 cpack_append_option_set_command( 478 CPACK_COMPONENT_GROUP_${_CPACK_ADDGRP_UNAME}_EXPANDED 479 _CPACK_ADDGRP_STR) 480 cpack_append_option_set_command( 481 CPACK_COMPONENT_GROUP_${_CPACK_ADDGRP_UNAME}_BOLD_TITLE 482 _CPACK_ADDGRP_STR) 483 # Backward compatibility issue. 484 # Write to config iff the macros is used after CPack.cmake has been 485 # included, other it's not necessary because the variables 486 # will be encoded by cpack_encode_variables. 487 if(CPack_CMake_INCLUDED) 488 file(APPEND "${CPACK_OUTPUT_CONFIG_FILE}" "${_CPACK_ADDGRP_STR}") 489 endif() 490endmacro() 491 492# Macro that adds an installation type to the CPack installer 493macro(cpack_add_install_type insttype) 494 string(TOUPPER ${insttype} _CPACK_INSTTYPE_UNAME) 495 cmake_parse_arguments(CPACK_INSTALL_TYPE_${_CPACK_INSTTYPE_UNAME} 496 "" 497 "DISPLAY_NAME" 498 "" 499 ${ARGN} 500 ) 501 502 set(_CPACK_INSTTYPE_STR 503 "\n# Configuration for installation type \"${insttype}\"\n") 504 string(APPEND _CPACK_INSTTYPE_STR 505 "list(APPEND CPACK_ALL_INSTALL_TYPES ${insttype})\n") 506 cpack_append_string_variable_set_command( 507 CPACK_INSTALL_TYPE_${_CPACK_INSTTYPE_UNAME}_DISPLAY_NAME 508 _CPACK_INSTTYPE_STR) 509 # Backward compatibility issue. 510 # Write to config iff the macros is used after CPack.cmake has been 511 # included, other it's not necessary because the variables 512 # will be encoded by cpack_encode_variables. 513 if(CPack_CMake_INCLUDED) 514 file(APPEND "${CPACK_OUTPUT_CONFIG_FILE}" "${_CPACK_INSTTYPE_STR}") 515 endif() 516endmacro() 517 518macro(cpack_configure_downloads site) 519 cmake_parse_arguments(CPACK_DOWNLOAD 520 "ALL;ADD_REMOVE;NO_ADD_REMOVE" 521 "UPLOAD_DIRECTORY" 522 "" 523 ${ARGN} 524 ) 525 526 set(CPACK_CONFIG_DL_STR 527 "\n# Downloaded components configuration\n") 528 set(CPACK_UPLOAD_DIRECTORY ${CPACK_DOWNLOAD_UPLOAD_DIRECTORY}) 529 set(CPACK_DOWNLOAD_SITE ${site}) 530 cpack_append_string_variable_set_command( 531 CPACK_DOWNLOAD_SITE 532 CPACK_CONFIG_DL_STR) 533 cpack_append_string_variable_set_command( 534 CPACK_UPLOAD_DIRECTORY 535 CPACK_CONFIG_DL_STR) 536 cpack_append_option_set_command( 537 CPACK_DOWNLOAD_ALL 538 CPACK_CONFIG_DL_STR) 539 if (${CPACK_DOWNLOAD_ALL} AND NOT ${CPACK_DOWNLOAD_NO_ADD_REMOVE}) 540 set(CPACK_DOWNLOAD_ADD_REMOVE ON) 541 endif () 542 set(CPACK_ADD_REMOVE ${CPACK_DOWNLOAD_ADD_REMOVE}) 543 cpack_append_option_set_command( 544 CPACK_ADD_REMOVE 545 CPACK_CONFIG_DL_STR) 546 # Backward compatibility issue. 547 # Write to config iff the macros is used after CPack.cmake has been 548 # included, other it's not necessary because the variables 549 # will be encoded by cpack_encode_variables. 550 if(CPack_CMake_INCLUDED) 551 file(APPEND "${CPACK_OUTPUT_CONFIG_FILE}" "${CPACK_CONFIG_DL_STR}") 552 endif() 553endmacro() 554endif() 555