CPackComponent.cmake 20.7 KB
Newer Older
1 2 3
#.rst:
# CPackComponent
# --------------
4
#
5 6
# Build binary and source package installers
#
7 8
# Variables concerning CPack Components
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9 10 11
#
# The CPackComponent module is the module which handles the component
# part of CPack.  See CPack module for general information about CPack.
12 13 14
#
# For certain kinds of binary installers (including the graphical
# installers on Mac OS X and Windows), CPack generates installers that
15 16 17 18 19 20 21
# allow users to select individual application components to install.
# The contents of each of the components are identified by the COMPONENT
# argument of CMake's INSTALL command.  These components can be
# annotated with user-friendly names and descriptions, inter-component
# dependencies, etc., and grouped in various ways to customize the
# resulting installer.  See the cpack_add_* commands, described below,
# for more information about component-specific installations.
22 23
#
# Component-specific installation allows users to select specific sets
24 25 26
# of components to install during the install process.  Installation
# components are identified by the COMPONENT argument of CMake's INSTALL
# commands, and should be further described by the following CPack
27
# commands:
28
#
29
# .. variable:: CPACK_COMPONENTS_ALL
30
#
31
#  The list of component to install.
32
#
33 34 35
#  The default value of this variable is computed by CPack and contains all
#  components defined by the project.  The user may set it to only include the
#  specified components.
36
#
37
# .. variable:: CPACK_<GENNAME>_COMPONENT_INSTALL
38
#
39
#  Enable/Disable component install for CPack generator <GENNAME>.
40
#
41 42 43 44
#  Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc...) has a legacy
#  default behavior.  e.g.  RPM builds monolithic whereas NSIS builds
#  component.  One can change the default behavior by setting this variable to
#  0/1 or OFF/ON.
45
#
46
# .. variable:: CPACK_COMPONENTS_GROUPING
47
#
48 49
#  Specify how components are grouped for multi-package component-aware CPack
#  generators.
50
#
51 52 53
#  Some generators like RPM or ARCHIVE family (TGZ, ZIP, ...) generates
#  several packages files when asked for component packaging.  They group
#  the component differently depending on the value of this variable:
54
#
55 56 57
#  * ONE_PER_GROUP (default): creates one package file per component group
#  * ALL_COMPONENTS_IN_ONE : creates a single package with all (requested) component
#  * IGNORE : creates one package per component, i.e. IGNORE component group
58
#
59 60
#  One can specify different grouping for different CPack generator by
#  using a CPACK_PROJECT_CONFIG_FILE.
61
#
62
# .. variable:: CPACK_COMPONENT_<compName>_DISPLAY_NAME
63
#
64
#  The name to be displayed for a component.
65
#
66
# .. variable:: CPACK_COMPONENT_<compName>_DESCRIPTION
67
#
68
#  The description of a component.
69
#
70
# .. variable:: CPACK_COMPONENT_<compName>_GROUP
71
#
72
#  The group of a component.
73
#
74
# .. variable:: CPACK_COMPONENT_<compName>_DEPENDS
75
#
76
#  The dependencies (list of components) on which this component depends.
77
#
78
# .. variable:: CPACK_COMPONENT_<compName>_REQUIRED
79
#
80
#  True is this component is required.
81
#
82
# .. command:: cpack_add_component
83
#
84
# Describes a CPack installation
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
# component named by the COMPONENT argument to a CMake INSTALL command.
#
# ::
#
#   cpack_add_component(compname
#                       [DISPLAY_NAME name]
#                       [DESCRIPTION description]
#                       [HIDDEN | REQUIRED | DISABLED ]
#                       [GROUP group]
#                       [DEPENDS comp1 comp2 ... ]
#                       [INSTALL_TYPES type1 type2 ... ]
#                       [DOWNLOADED]
#                       [ARCHIVE_FILE filename])
#
#
#
# The cmake_add_component command describes an installation component,
# which the user can opt to install or remove as part of the graphical
# installation process.  compname is the name of the component, as
# provided to the COMPONENT argument of one or more CMake INSTALL
# commands.
#
# DISPLAY_NAME is the displayed name of the component, used in graphical
# installers to display the component name.  This value can be any
# string.
#
# DESCRIPTION is an extended description of the component, used in
# graphical installers to give the user additional information about the
113
# component.  Descriptions can span multiple lines using ``\n`` as the
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
# line separator.  Typically, these descriptions should be no more than
# a few lines long.
#
# HIDDEN indicates that this component will be hidden in the graphical
# installer, so that the user cannot directly change whether it is
# installed or not.
#
# REQUIRED indicates that this component is required, and therefore will
# always be installed.  It will be visible in the graphical installer,
# but it cannot be unselected.  (Typically, required components are
# shown greyed out).
#
# DISABLED indicates that this component should be disabled (unselected)
# by default.  The user is free to select this component for
# installation, unless it is also HIDDEN.
#
# DEPENDS lists the components on which this component depends.  If this
# component is selected, then each of the components listed must also be
# selected.  The dependency information is encoded within the installer
# itself, so that users cannot install inconsistent sets of components.
#
# GROUP names the component group of which this component is a part.  If
# not provided, the component will be a standalone component, not part
# of any component group.  Component groups are described with the
# cpack_add_component_group command, detailed below.
#
# INSTALL_TYPES lists the installation types of which this component is
# a part.  When one of these installations types is selected, this
# component will automatically be selected.  Installation types are
# described with the cpack_add_install_type command, detailed below.
#
# DOWNLOADED indicates that this component should be downloaded
# on-the-fly by the installer, rather than packaged in with the
# installer itself.  For more information, see the
# cpack_configure_downloads command.
#
# ARCHIVE_FILE provides a name for the archive file created by CPack to
# be used for downloaded components.  If not supplied, CPack will create
# a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of
# the component.  See cpack_configure_downloads for more information.
#
155 156 157
# .. command:: cpack_add_component_group
#
# Describes a group of related CPack installation components.
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
#
# ::
#
#   cpack_add_component_group(groupname
#                            [DISPLAY_NAME name]
#                            [DESCRIPTION description]
#                            [PARENT_GROUP parent]
#                            [EXPANDED]
#                            [BOLD_TITLE])
#
#
#
# The cpack_add_component_group describes a group of installation
# components, which will be placed together within the listing of
# options.  Typically, component groups allow the user to
# select/deselect all of the components within a single group via a
# single group-level option.  Use component groups to reduce the
# complexity of installers with many options.  groupname is an arbitrary
# name used to identify the group in the GROUP argument of the
# cpack_add_component command, which is used to place a component in a
# group.  The name of the group must not conflict with the name of any
# component.
#
# DISPLAY_NAME is the displayed name of the component group, used in
# graphical installers to display the component group name.  This value
# can be any string.
#
# DESCRIPTION is an extended description of the component group, used in
# graphical installers to give the user additional information about the
# components within that group.  Descriptions can span multiple lines
188
# using ``\n`` as the line separator.  Typically, these descriptions
189 190 191 192 193 194 195 196 197 198 199 200
# should be no more than a few lines long.
#
# PARENT_GROUP, if supplied, names the parent group of this group.
# Parent groups are used to establish a hierarchy of groups, providing
# an arbitrary hierarchy of groups.
#
# EXPANDED indicates that, by default, the group should show up as
# "expanded", so that the user immediately sees all of the components
# within the group.  Otherwise, the group will initially show up as a
# single entry.
#
# BOLD_TITLE indicates that the group title should appear in bold, to
201 202 203
# call the user's attention to the group.
#
# .. command:: cpack_add_install_type
204
#
205
# Add a new installation type containing
206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224
# a set of predefined component selections to the graphical installer.
#
# ::
#
#   cpack_add_install_type(typename
#                          [DISPLAY_NAME name])
#
#
#
# The cpack_add_install_type command identifies a set of preselected
# components that represents a common use case for an application.  For
# example, a "Developer" install type might include an application along
# with its header and library files, while an "End user" install type
# might just include the application's executable.  Each component
# identifies itself with one or more install types via the INSTALL_TYPES
# argument to cpack_add_component.
#
# DISPLAY_NAME is the displayed name of the install type, which will
# typically show up in a drop-down box within a graphical installer.
225 226 227
# This value can be any string.
#
# .. command:: cpack_configure_downloads
228
#
229
# Configure CPack to download
230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265
# selected components on-the-fly as part of the installation process.
#
# ::
#
#   cpack_configure_downloads(site
#                             [UPLOAD_DIRECTORY dirname]
#                             [ALL]
#                             [ADD_REMOVE|NO_ADD_REMOVE])
#
#
#
# The cpack_configure_downloads command configures installation-time
# downloads of selected components.  For each downloadable component,
# CPack will create an archive containing the contents of that
# component, which should be uploaded to the given site.  When the user
# selects that component for installation, the installer will download
# and extract the component in place.  This feature is useful for
# creating small installers that only download the requested components,
# saving bandwidth.  Additionally, the installers are small enough that
# they will be installed as part of the normal installation process, and
# the "Change" button in Windows Add/Remove Programs control panel will
# allow one to add or remove parts of the application after the original
# installation.  On Windows, the downloaded-components functionality
# requires the ZipDLL plug-in for NSIS, available at:
#
# ::
#
#   http://nsis.sourceforge.net/ZipDLL_plug-in
#
#
#
# On Mac OS X, installers that download components on-the-fly can only
# be built and installed on system using Mac OS X 10.5 or later.
#
# The site argument is a URL where the archives for downloadable
# components will reside, e.g.,
266
# https://cmake.org/files/2.6.1/installer/ All of the archives
267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284
# produced by CPack should be uploaded to that location.
#
# UPLOAD_DIRECTORY is the local directory where CPack will create the
# various archives for each of the components.  The contents of this
# directory should be uploaded to a location accessible by the URL given
# in the site argument.  If omitted, CPack will use the directory
# CPackUploads inside the CMake binary directory to store the generated
# archives.
#
# The ALL flag indicates that all components be downloaded.  Otherwise,
# only those components explicitly marked as DOWNLOADED or that have a
# specified ARCHIVE_FILE will be downloaded.  Additionally, the ALL
# option implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).
#
# ADD_REMOVE indicates that CPack should install a copy of the installer
# that can be called from Windows' Add/Remove Programs dialog (via the
# "Modify" button) to change the set of installed components.
# NO_ADD_REMOVE turns off this behavior.  This option is ignored on Mac
285
# OS X.
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300

#=============================================================================
# Copyright 2006-2009 Kitware, Inc.
#
# Distributed under the OSI-approved BSD License (the "License");
# see accompanying file Copyright.txt for details.
#
# This software is distributed WITHOUT ANY WARRANTY; without even the
# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the License for more information.
#=============================================================================
# (To distribute this file outside of CMake, substitute the full
#  License text for the above reference.)

# Define var in order to avoid multiple inclusion
301 302
if(NOT CPackComponent_CMake_INCLUDED)
set(CPackComponent_CMake_INCLUDED 1)
303

304
# Argument-parsing macro from https://cmake.org/Wiki/CMakeMacroParseArguments
305 306 307 308
macro(cpack_parse_arguments prefix arg_names option_names)
  set(${prefix}_DEFAULT_ARGS)
  foreach(arg_name ${arg_names})
    set(${prefix}_${arg_name})
309
  endforeach()
310 311
  foreach(option ${option_names})
    set(${prefix}_${option} FALSE)
312
  endforeach()
313

314 315 316 317 318 319 320 321 322
  set(current_arg_name DEFAULT_ARGS)
  set(current_arg_list)
  foreach(arg ${ARGN})
    set(larg_names ${arg_names})
    list(FIND larg_names "${arg}" is_arg_name)
    if (is_arg_name GREATER -1)
      set(${prefix}_${current_arg_name} ${current_arg_list})
      set(current_arg_name ${arg})
      set(current_arg_list)
323
    else ()
324 325 326 327
      set(loption_names ${option_names})
      list(FIND loption_names "${arg}" is_option)
      if (is_option GREATER -1)
        set(${prefix}_${arg} TRUE)
328
      else ()
329
        set(current_arg_list ${current_arg_list} ${arg})
330 331 332
      endif ()
    endif ()
  endforeach()
333
  set(${prefix}_${current_arg_name} ${current_arg_list})
334
endmacro()
335 336 337 338 339

# Macro that appends a SET command for the given variable name (var)
# to the macro named strvar, but only if the variable named "var"
# has been defined. The string will eventually be appended to a CPack
# configuration file.
340 341 342 343 344
macro(cpack_append_variable_set_command var strvar)
  if (DEFINED ${var})
    set(${strvar} "${${strvar}}set(${var}")
    foreach(APPENDVAL ${${var}})
      set(${strvar} "${${strvar}} ${APPENDVAL}")
345
    endforeach()
346
    set(${strvar} "${${strvar}})\n")
347 348
  endif ()
endmacro()
349 350 351 352 353

# Macro that appends a SET command for the given variable name (var)
# to the macro named strvar, but only if the variable named "var"
# has been defined and is a string. The string will eventually be
# appended to a CPack configuration file.
354 355 356 357 358
macro(cpack_append_string_variable_set_command var strvar)
  if (DEFINED ${var})
    list(LENGTH ${var} CPACK_APP_VALUE_LEN)
    if(${CPACK_APP_VALUE_LEN} EQUAL 1)
      set(${strvar} "${${strvar}}set(${var} \"${${var}}\")\n")
359 360 361
    endif()
  endif ()
endmacro()
362 363 364 365 366

# Macro that appends a SET command for the given variable name (var)
# to the macro named strvar, but only if the variable named "var"
# has been set to true. The string will eventually be
# appended to a CPack configuration file.
367 368 369 370 371
macro(cpack_append_option_set_command var strvar)
  if (${var})
    list(LENGTH ${var} CPACK_APP_VALUE_LEN)
    if(${CPACK_APP_VALUE_LEN} EQUAL 1)
      set(${strvar} "${${strvar}}set(${var} TRUE)\n")
372 373 374
    endif()
  endif ()
endmacro()
375 376

# Macro that adds a component to the CPack installer
377
macro(cpack_add_component compname)
378 379
  string(TOUPPER ${compname} _CPACK_ADDCOMP_UNAME)
  cpack_parse_arguments(CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}
380 381 382 383 384
    "DISPLAY_NAME;DESCRIPTION;GROUP;DEPENDS;INSTALL_TYPES;ARCHIVE_FILE"
    "HIDDEN;REQUIRED;DISABLED;DOWNLOADED"
    ${ARGN}
    )

385 386
  if (CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_DOWNLOADED)
    set(_CPACK_ADDCOMP_STR "\n# Configuration for downloaded component \"${compname}\"\n")
387
  else ()
388
    set(_CPACK_ADDCOMP_STR "\n# Configuration for component \"${compname}\"\n")
389 390
  endif ()

391
  if(NOT CPACK_MONOLITHIC_INSTALL)
392 393 394 395
    # If the user didn't set CPACK_COMPONENTS_ALL explicitly, update the
    # value of CPACK_COMPONENTS_ALL in the configuration file. This will
    # take care of any components that have been added after the CPack
    # moduled was included.
396
    if(NOT CPACK_COMPONENTS_ALL_SET_BY_USER)
397 398 399 400
      get_cmake_property(_CPACK_ADDCOMP_COMPONENTS COMPONENTS)
      set(_CPACK_ADDCOMP_STR "${_CPACK_ADDCOMP_STR}\nSET(CPACK_COMPONENTS_ALL")
      foreach(COMP ${_CPACK_ADDCOMP_COMPONENTS})
       set(_CPACK_ADDCOMP_STR "${_CPACK_ADDCOMP_STR} ${COMP}")
401
      endforeach()
402
      set(_CPACK_ADDCOMP_STR "${_CPACK_ADDCOMP_STR})\n")
403 404
    endif()
  endif()
405 406

  cpack_append_string_variable_set_command(
407 408
    CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_DISPLAY_NAME
    _CPACK_ADDCOMP_STR)
409
  cpack_append_string_variable_set_command(
410 411
    CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_DESCRIPTION
    _CPACK_ADDCOMP_STR)
412
  cpack_append_variable_set_command(
413 414
    CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_GROUP
    _CPACK_ADDCOMP_STR)
415
  cpack_append_variable_set_command(
416 417
    CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_DEPENDS
    _CPACK_ADDCOMP_STR)
418
  cpack_append_variable_set_command(
419 420
    CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_INSTALL_TYPES
    _CPACK_ADDCOMP_STR)
421
  cpack_append_string_variable_set_command(
422 423
    CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_ARCHIVE_FILE
    _CPACK_ADDCOMP_STR)
424
  cpack_append_option_set_command(
425 426
    CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_HIDDEN
    _CPACK_ADDCOMP_STR)
427
  cpack_append_option_set_command(
428 429
    CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_REQUIRED
    _CPACK_ADDCOMP_STR)
430
  cpack_append_option_set_command(
431 432
    CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_DISABLED
    _CPACK_ADDCOMP_STR)
433
  cpack_append_option_set_command(
434 435
    CPACK_COMPONENT_${_CPACK_ADDCOMP_UNAME}_DOWNLOADED
    _CPACK_ADDCOMP_STR)
436 437 438 439
  # Backward compatibility issue.
  # Write to config iff the macros is used after CPack.cmake has been
  # included, other it's not necessary because the variables
  # will be encoded by cpack_encode_variables.
440
  if(CPack_CMake_INCLUDED)
441
    file(APPEND "${CPACK_OUTPUT_CONFIG_FILE}" "${_CPACK_ADDCOMP_STR}")
442 443
  endif()
endmacro()
444 445

# Macro that adds a component group to the CPack installer
446
macro(cpack_add_component_group grpname)
447 448
  string(TOUPPER ${grpname} _CPACK_ADDGRP_UNAME)
  cpack_parse_arguments(CPACK_COMPONENT_GROUP_${_CPACK_ADDGRP_UNAME}
449
    "DISPLAY_NAME;DESCRIPTION;PARENT_GROUP"
450 451 452 453
    "EXPANDED;BOLD_TITLE"
    ${ARGN}
    )

454
  set(_CPACK_ADDGRP_STR "\n# Configuration for component group \"${grpname}\"\n")
455
  cpack_append_string_variable_set_command(
456 457
    CPACK_COMPONENT_GROUP_${_CPACK_ADDGRP_UNAME}_DISPLAY_NAME
    _CPACK_ADDGRP_STR)
458
  cpack_append_string_variable_set_command(
459 460
    CPACK_COMPONENT_GROUP_${_CPACK_ADDGRP_UNAME}_DESCRIPTION
    _CPACK_ADDGRP_STR)
461
  cpack_append_string_variable_set_command(
462 463
    CPACK_COMPONENT_GROUP_${_CPACK_ADDGRP_UNAME}_PARENT_GROUP
    _CPACK_ADDGRP_STR)
464
  cpack_append_option_set_command(
465 466
    CPACK_COMPONENT_GROUP_${_CPACK_ADDGRP_UNAME}_EXPANDED
    _CPACK_ADDGRP_STR)
467
  cpack_append_option_set_command(
468 469
    CPACK_COMPONENT_GROUP_${_CPACK_ADDGRP_UNAME}_BOLD_TITLE
    _CPACK_ADDGRP_STR)
470 471 472 473
  # Backward compatibility issue.
  # Write to config iff the macros is used after CPack.cmake has been
  # included, other it's not necessary because the variables
  # will be encoded by cpack_encode_variables.
474
  if(CPack_CMake_INCLUDED)
475
    file(APPEND "${CPACK_OUTPUT_CONFIG_FILE}" "${_CPACK_ADDGRP_STR}")
476 477
  endif()
endmacro()
478 479

# Macro that adds an installation type to the CPack installer
480
macro(cpack_add_install_type insttype)
481 482
  string(TOUPPER ${insttype} _CPACK_INSTTYPE_UNAME)
  cpack_parse_arguments(CPACK_INSTALL_TYPE_${_CPACK_INSTTYPE_UNAME}
483 484 485 486 487
    "DISPLAY_NAME"
    ""
    ${ARGN}
    )

488
  set(_CPACK_INSTTYPE_STR
489
    "\n# Configuration for installation type \"${insttype}\"\n")
490 491
  set(_CPACK_INSTTYPE_STR
    "${_CPACK_INSTTYPE_STR}list(APPEND CPACK_ALL_INSTALL_TYPES ${insttype})\n")
492
  cpack_append_string_variable_set_command(
493 494
    CPACK_INSTALL_TYPE_${_CPACK_INSTTYPE_UNAME}_DISPLAY_NAME
    _CPACK_INSTTYPE_STR)
495 496 497 498
  # Backward compatibility issue.
  # Write to config iff the macros is used after CPack.cmake has been
  # included, other it's not necessary because the variables
  # will be encoded by cpack_encode_variables.
499
  if(CPack_CMake_INCLUDED)
500
    file(APPEND "${CPACK_OUTPUT_CONFIG_FILE}" "${_CPACK_INSTTYPE_STR}")
501 502
  endif()
endmacro()
503

504
macro(cpack_configure_downloads site)
505 506 507 508 509 510
  cpack_parse_arguments(CPACK_DOWNLOAD
    "UPLOAD_DIRECTORY"
    "ALL;ADD_REMOVE;NO_ADD_REMOVE"
    ${ARGN}
    )

511
  set(CPACK_CONFIG_DL_STR
512
    "\n# Downloaded components configuration\n")
513 514
  set(CPACK_UPLOAD_DIRECTORY ${CPACK_DOWNLOAD_UPLOAD_DIRECTORY})
  set(CPACK_DOWNLOAD_SITE ${site})
515 516 517 518 519 520 521 522 523
  cpack_append_string_variable_set_command(
    CPACK_DOWNLOAD_SITE
    CPACK_CONFIG_DL_STR)
  cpack_append_string_variable_set_command(
    CPACK_UPLOAD_DIRECTORY
    CPACK_CONFIG_DL_STR)
  cpack_append_option_set_command(
    CPACK_DOWNLOAD_ALL
    CPACK_CONFIG_DL_STR)
524 525
  if (${CPACK_DOWNLOAD_ALL} AND NOT ${CPACK_DOWNLOAD_NO_ADD_REMOVE})
    set(CPACK_DOWNLOAD_ADD_REMOVE ON)
526
  endif ()
527
  set(CPACK_ADD_REMOVE ${CPACK_DOWNLOAD_ADD_REMOVE})
528 529 530 531 532 533 534
  cpack_append_option_set_command(
    CPACK_ADD_REMOVE
    CPACK_CONFIG_DL_STR)
  # Backward compatibility issue.
  # Write to config iff the macros is used after CPack.cmake has been
  # included, other it's not necessary because the variables
  # will be encoded by cpack_encode_variables.
535 536
  if(CPack_CMake_INCLUDED)
    file(APPEND "${CPACK_OUTPUT_CONFIG_FILE}" "${CPACK_CONFIG_DL_STR}")
537 538 539
  endif()
endmacro()
endif()