Review and update CPack variable documentation.

This concerns all variables common to all CPack generators.
Variables mainly used and/or set in CPack.cmake are documented
therein. C++ built-in variables are documented in
cmCPackDocumentVariables.cxx.
This commit is contained in:
Eric NOULARD 2012-02-25 22:57:59 +01:00
parent f3fe73da54
commit 94a269304e
2 changed files with 162 additions and 86 deletions

View File

@ -53,176 +53,198 @@
##end ##end
# #
##variable ##variable
# CPACK_PACKAGE_NAME - The name of the package (or application). If # CPACK_PACKAGE_NAME - The name of the package (or application). If
# not specified, defaults to the project name. # not specified, defaults to the project name.
##end ##end
# #
##variable ##variable
# CPACK_PACKAGE_VENDOR - The name of the package vendor. (e.g., # CPACK_PACKAGE_VENDOR - The name of the package vendor. (e.g.,
# "Kitware"). # "Kitware").
##end ##end
# #
##variable ##variable
# CPACK_PACKAGE_VERSION_MAJOR - Package major Version # CPACK_PACKAGE_VERSION_MAJOR - Package major Version
##end ##end
# #
##variable ##variable
# CPACK_PACKAGE_VERSION_MINOR - Package minor Version # CPACK_PACKAGE_VERSION_MINOR - Package minor Version
##end ##end
# #
##variable ##variable
# CPACK_PACKAGE_VERSION_PATCH - Package patch Version # CPACK_PACKAGE_VERSION_PATCH - Package patch Version
##end ##end
# #
##variable ##variable
# CPACK_PACKAGE_DESCRIPTION_FILE - A text file used to describe the # CPACK_PACKAGE_DESCRIPTION_FILE - A text file used to describe the
# project. Used, for example, the introduction screen of a # project. Used, for example, the introduction screen of a
# CPack-generated Windows installer to describe the project. # CPack-generated Windows installer to describe the project.
##end ##end
# #
##variable ##variable
# CPACK_PACKAGE_DESCRIPTION_SUMMARY - Short description of the # CPACK_PACKAGE_DESCRIPTION_SUMMARY - Short description of the
# project (only a few words). # project (only a few words).
##end ##end
# #
##variable ##variable
# CPACK_PACKAGE_FILE_NAME - The name of the package file to generate, # CPACK_PACKAGE_FILE_NAME - The name of the package file to generate,
# not including the extension. For example, cmake-2.6.1-Linux-i686. # not including the extension. For example, cmake-2.6.1-Linux-i686.
# The default value is
# ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}.
##end ##end
# #
##variable ##variable
# CPACK_PACKAGE_INSTALL_DIRECTORY - Installation directory on the # CPACK_PACKAGE_INSTALL_DIRECTORY - Installation directory on the
# target system, e.g., "CMake 2.5". # target system. This may be used by some CPack generators
# like NSIS to create an installation directory e.g., "CMake 2.5"
# below the installation prefix. All installed element will be
# put inside this directory.
##end ##end
# #
##variable ##variable
# CPACK_PROJECT_CONFIG_FILE - File included at cpack time, once per # CPACK_PROJECT_CONFIG_FILE - CPack-time project CPack configuration
# generator after setting CPACK_GENERATOR to the actual generator # file. This file included at cpack time, once per
# being used. Allows per-generator setting of CPACK_* variables at # generator after CPack has set CPACK_GENERATOR to the actual generator
# cpack time. # being used. It allows per-generator setting of CPACK_* variables at
# cpack time.
##end ##end
# #
##variable ##variable
# CPACK_RESOURCE_FILE_LICENSE - License file for the project, which # CPACK_RESOURCE_FILE_LICENSE - License to be embedded in the installer. It
# will typically be displayed to the user (often with an explicit # will typically be displayed to the user by the produced installer
# "Accept" button, for graphical installers) prior to installation. # (often with an explicit "Accept" button, for graphical installers)
# prior to installation. This license file is NOT added to installed
# file but is used by some CPack generators like NSIS. If you want
# to install a license file (may be the same as this one)
# along with your project you must add an appropriate CMake INSTALL
# command in your CMakeLists.txt.
##end ##end
# #
##variable ##variable
# CPACK_RESOURCE_FILE_README - ReadMe file for the project, which # CPACK_RESOURCE_FILE_README - ReadMe file to be embedded in the installer. It
# typically describes in some detail # typically describes in some detail the purpose of the project
# during the installation. Not all CPack generators uses
# this file.
##end ##end
# #
##variable ##variable
# CPACK_RESOURCE_FILE_WELCOME - Welcome file for the project, which # CPACK_RESOURCE_FILE_WELCOME - Welcome file to be embedded in the
# welcomes users to this installer. Typically used in the graphical # installer. It welcomes users to this installer.
# installers on Windows and Mac OS X. # Typically used in the graphical installers on Windows and Mac OS X.
##end ##end
# #
##variable ##variable
# CPACK_MONOLITHIC_INSTALL - Disables the component-based # CPACK_MONOLITHIC_INSTALL - Disables the component-based
# installation mechanism, so that all components are always installed. # installation mechanism. When set the component specification is ignored
# and all installed items are put in a single "MONOLITHIC" package.
# Some CPack generators do monolithic packaging by default and
# may be asked to do component packaging by setting
# CPACK_<GENNAME>_COMPONENT_INSTALL to 1/TRUE.
##end ##end
# #
##variable ##variable
# CPACK_GENERATOR - List of CPack generators to use. If not # CPACK_GENERATOR - List of CPack generators to use. If not
# specified, CPack will create a set of options (e.g., # specified, CPack will create a set of options CPACK_BINARY_<GENNAME> (e.g.,
# CPACK_BINARY_NSIS) allowing the user to enable/disable individual # CPACK_BINARY_NSIS) allowing the user to enable/disable individual
# generators. # generators. This variable may be used on the command line
# as well as in:
#
# cpack -D CPACK_GENERATOR="ZIP;TGZ" /path/to/build/tree
##end ##end
# #
##variable ##variable
# CPACK_OUTPUT_CONFIG_FILE - The name of the CPack configuration file # CPACK_OUTPUT_CONFIG_FILE - The name of the CPack binary configuration
# for binary installers that will be generated by the CPack # file. This file is the CPack configuration generated by the CPack module
# module. Defaults to CPackConfig.cmake. # for binary installers. Defaults to CPackConfig.cmake.
##end ##end
# #
##variable ##variable
# CPACK_PACKAGE_EXECUTABLES - Lists each of the executables along # CPACK_PACKAGE_EXECUTABLES - Lists each of the executables and associated
# with a text label, to be used to create Start Menu shortcuts on # text label to be used to create Start Menu shortcuts. For example,
# Windows. For example, setting this to the list ccmake;CMake will # setting this to the list ccmake;CMake will
# create a shortcut named "CMake" that will execute the installed # create a shortcut named "CMake" that will execute the installed
# executable ccmake. # executable ccmake. Not all CPack generators use it (at least NSIS and
# OSXX11 do).
##end ##end
# #
##variable ##variable
# CPACK_STRIP_FILES - List of files to be stripped. Starting with # CPACK_STRIP_FILES - List of files to be stripped. Starting with
# CMake 2.6.0 CPACK_STRIP_FILES will be a boolean variable which # CMake 2.6.0 CPACK_STRIP_FILES will be a boolean variable which
# enables stripping of all files (a list of files evaluates to TRUE # enables stripping of all files (a list of files evaluates to TRUE
# in CMake, so this change is compatible). # in CMake, so this change is compatible).
##end ##end
# #
# The following CPack variables are specific to source packages, and # The following CPack variables are specific to source packages, and
# will not affect binary packages: # will not affect binary packages:
# #
##variable ##variable
# CPACK_SOURCE_PACKAGE_FILE_NAME - The name of the source package, # CPACK_SOURCE_PACKAGE_FILE_NAME - The name of the source package. For
# e.g., cmake-2.6.1 # example cmake-2.6.1.
##end ##end
# #
##variable ##variable
# CPACK_SOURCE_STRIP_FILES - List of files in the source tree that # CPACK_SOURCE_STRIP_FILES - List of files in the source tree that
# will be stripped. Starting with CMake 2.6.0 # will be stripped. Starting with CMake 2.6.0
# CPACK_SOURCE_STRIP_FILES will be a boolean variable which enables # CPACK_SOURCE_STRIP_FILES will be a boolean variable which enables
# stripping of all files (a list of files evaluates to TRUE in CMake, # stripping of all files (a list of files evaluates to TRUE in CMake,
# so this change is compatible). # so this change is compatible).
##end ##end
# #
##variable ##variable
# CPACK_SOURCE_GENERATOR - List of generators used for the source # CPACK_SOURCE_GENERATOR - List of generators used for the source
# packages. As with CPACK_GENERATOR, if this is not specified then # packages. As with CPACK_GENERATOR, if this is not specified then
# CPack will create a set of options (e.g., CPACK_SOURCE_ZIP) # CPack will create a set of options (e.g., CPACK_SOURCE_ZIP)
# allowing users to select which packages will be generated. # allowing users to select which packages will be generated.
##end ##end
# #
##variable ##variable
# CPACK_SOURCE_OUTPUT_CONFIG_FILE - The name of the CPack # CPACK_SOURCE_OUTPUT_CONFIG_FILE - The name of the CPack source
# configuration file for source installers that will be generated by # configuration file. This file is the CPack configuration generated by the
# the CPack module. Defaults to CPackSourceConfig.cmake. # CPack module for source installers. Defaults to CPackSourceConfig.cmake.
##end ##end
# #
##variable ##variable
# CPACK_SOURCE_IGNORE_FILES - Pattern of files in the source tree # CPACK_SOURCE_IGNORE_FILES - Pattern of files in the source tree
# that won't be packaged when building a source package. This is a # that won't be packaged when building a source package. This is a
# list of patterns, e.g., /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.* # list of regular expression patterns (that must be properly escaped),
# e.g., /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
##end ##end
# #
# The following variables are for advanced uses of CPack: # The following variables are for advanced uses of CPack:
# #
##variable ##variable
# CPACK_CMAKE_GENERATOR - What CMake generator should be used if the # CPACK_CMAKE_GENERATOR - What CMake generator should be used if the
# project is CMake project. Defaults to the value of CMAKE_GENERATOR; # project is CMake project. Defaults to the value of CMAKE_GENERATOR
# few users will want to change this setting. # few users will want to change this setting.
##end ##end
# #
##variable ##variable
# CPACK_INSTALL_CMAKE_PROJECTS - List of four values that specify # CPACK_INSTALL_CMAKE_PROJECTS - List of four values that specify
# what project to install. The four values are: Build directory, # what project to install. The four values are: Build directory,
# Project Name, Project Component, Directory. If omitted, CPack will # Project Name, Project Component, Directory. If omitted, CPack will
# build an installer that installers everything. # build an installer that installers everything.
##end ##end
# #
##variable ##variable
# CPACK_SYSTEM_NAME - System name, defaults to the value of # CPACK_SYSTEM_NAME - System name, defaults to the value of
# ${CMAKE_SYSTEM_NAME}. # ${CMAKE_SYSTEM_NAME}.
##end ##end
# #
##variable ##variable
# CPACK_PACKAGE_VERSION - Package full version, used internally. By # CPACK_PACKAGE_VERSION - Package full version, used internally. By
# default, this is built from CPACK_PACKAGE_VERSION_MAJOR, # default, this is built from CPACK_PACKAGE_VERSION_MAJOR,
# CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH. # CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
##end ##end
# #
##variable ##variable
# CPACK_TOPLEVEL_TAG - Directory for the installed files. # CPACK_TOPLEVEL_TAG - Directory for the installed files.
##end ##end
# #
##variable ##variable
# CPACK_INSTALL_COMMANDS - Extra commands to install components. # CPACK_INSTALL_COMMANDS - Extra commands to install components.
##end ##end
# #
##variable ##variable
# CPACK_INSTALLED_DIRECTORIES - Extra directories to install. # CPACK_INSTALLED_DIRECTORIES - Extra directories to install.
##end ##end
# #
@ -358,6 +380,12 @@ macro(cpack_optional_append _list _cond _item)
endif(${_cond}) endif(${_cond})
endmacro(cpack_optional_append _list _cond _item) endmacro(cpack_optional_append _list _cond _item)
##variable
# CPACK_BINARY_<GENNAME> - CPack generated options for binary generators. The
# CPack.cmake module generates (when CPACK_GENERATOR is not set)
# a set of CMake options (see CMake option command) which may then be used to
# select the CPack generator(s) to be used when launching the package target.
##end
# Provide options to choose generators # Provide options to choose generators
# we might check here if the required tools for the generates exist # we might check here if the required tools for the generates exist
# and set the defaults according to the results # and set the defaults according to the results

View File

@ -21,12 +21,60 @@ void cmCPackDocumentVariables::DefineVariables(cmake* cm)
"", false, "", false,
"Variables common to all CPack generators"); "Variables common to all CPack generators");
// Subsection: variables defined/used by cpack, cm->DefineProperty
// which are specific to one CPack generator ("CPACK_INCLUDE_TOPLEVEL_DIRECTORY", cmProperty::VARIABLE,
// cm->DefineProperty "Boolean toggle to include/exclude top level directory.",
// ("CPACK_RPM_PACKAGE_NAME", cmProperty::VARIABLE, "When preparing a package CPack installs the item under"
// "RPM specific package name.", " the so-called top level directory. The purpose of"
// "If not specified, defaults to CPACK_PACKAGE_NAME." " is to include (set to 1 or ON or TRUE) the top level directory"
// "", false, " in the package or not (set to 0 or OFF or FALSE).\n"
// "Variables specific to a CPack generator"); "Each CPack generator as a built-in default value for this"
" variable. E.g. Archive generators (ZIP, TGZ, ...) includes"
" the top level whereas RPM or DEB don't. The user may override"
" the default value byt setting this variable.\n"
"There is a similar variable "
"CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY"
"which may be used to override the behavior for the component"
"packaging case which may have different default value for"
"historical (now backward compatibility) reason.", false,
"Variables common to all CPack generators");
cm->DefineProperty
("CPACK_SET_DESTDIR", cmProperty::VARIABLE,
"Boolean toggle to make CPack use DESTDIR mechanism when"
" packaging.", "DESTDIR means DESTination DIRectory."
" It is commonly used by makefile "
"users in order to install software at non-default location. It a"
"basic relocation mechanism. "
"It is usually invoked like this:\n"
" make DESTDIR=/home/john install\n"
"which will install the concerned software using the"
" installation prefix, e.g. \"/usr/local\" prepended with "
"the DESTDIR value which finally gives \"/home/john/usr/local\"."
" When preparing a package CPack first installs the items to be "
"packaged in a local (to the build tree) directory by using the "
"same DESTDIR mechanism. Nevertheless, if "
"CPACK_SET_DESTDIR is set then CPack will set DESTDIR before"
" doing the local install. The most noticeable difference is"
" that without CPACK_SET_DESTDIR, CPack uses "
"CPACK_PACKAGING_INSTALL_PREFIX as a prefix whereas with "
"CPACK_SET_DESTDIR set, CPack will use CMAKE_INSTALL_PREFIX as"
" a prefix.\n"
"Manually setting CPACK_SET_DESTDIR may help (or simply be"
" necessary) if some install rules uses absolute "
"DESTINATION (see CMake INSTALL command)."
"However, starting with"
" CPack/CMake 2.8.3 RPM and DEB installers tries to handle DESTDIR"
" automatically so that it is seldom necessary for the user to set"
" it.", false,
"Variables common to all CPack generators");
cm->DefineProperty
("CPACK_INSTALL_SCRIPT", cmProperty::VARIABLE,
"Extra CMake script provided by the user.",
"If set this CMake script will be executed by CPack "
"during its local [CPack-private] installation "
"which is done right before packaging the files."
" The script is not called by e.g.: make install.", false,
"Variables common to all CPack generators");
} }