Modules/CPackComponent.cmake

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