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

@ -88,61 +88,82 @@
##variable
# CPACK_PACKAGE_FILE_NAME - The name of the package file to generate,
# 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
#
##variable
# 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
#
##variable
# CPACK_PROJECT_CONFIG_FILE - File included at cpack time, once per
# generator after setting CPACK_GENERATOR to the actual generator
# being used. Allows per-generator setting of CPACK_* variables at
# CPACK_PROJECT_CONFIG_FILE - CPack-time project CPack configuration
# file. This file included at cpack time, once per
# generator after CPack has set CPACK_GENERATOR to the actual generator
# being used. It allows per-generator setting of CPACK_* variables at
# cpack time.
##end
#
##variable
# CPACK_RESOURCE_FILE_LICENSE - License file for the project, which
# will typically be displayed to the user (often with an explicit
# "Accept" button, for graphical installers) prior to installation.
# CPACK_RESOURCE_FILE_LICENSE - License to be embedded in the installer. It
# will typically be displayed to the user by the produced installer
# (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
#
##variable
# CPACK_RESOURCE_FILE_README - ReadMe file for the project, which
# typically describes in some detail
# CPACK_RESOURCE_FILE_README - ReadMe file to be embedded in the installer. It
# typically describes in some detail the purpose of the project
# during the installation. Not all CPack generators uses
# this file.
##end
#
##variable
# CPACK_RESOURCE_FILE_WELCOME - Welcome file for the project, which
# welcomes users to this installer. Typically used in the graphical
# installers on Windows and Mac OS X.
# CPACK_RESOURCE_FILE_WELCOME - Welcome file to be embedded in the
# installer. It welcomes users to this installer.
# Typically used in the graphical installers on Windows and Mac OS X.
##end
#
##variable
# 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
#
##variable
# 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
# 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
#
##variable
# CPACK_OUTPUT_CONFIG_FILE - The name of the CPack configuration file
# for binary installers that will be generated by the CPack
# module. Defaults to CPackConfig.cmake.
# CPACK_OUTPUT_CONFIG_FILE - The name of the CPack binary configuration
# file. This file is the CPack configuration generated by the CPack module
# for binary installers. Defaults to CPackConfig.cmake.
##end
#
##variable
# CPACK_PACKAGE_EXECUTABLES - Lists each of the executables along
# with a text label, to be used to create Start Menu shortcuts on
# Windows. For example, setting this to the list ccmake;CMake will
# CPACK_PACKAGE_EXECUTABLES - Lists each of the executables and associated
# text label to be used to create Start Menu shortcuts. For example,
# setting this to the list ccmake;CMake will
# 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
#
##variable
@ -156,8 +177,8 @@
# will not affect binary packages:
#
##variable
# CPACK_SOURCE_PACKAGE_FILE_NAME - The name of the source package,
# e.g., cmake-2.6.1
# CPACK_SOURCE_PACKAGE_FILE_NAME - The name of the source package. For
# example cmake-2.6.1.
##end
#
##variable
@ -176,22 +197,23 @@
##end
#
##variable
# CPACK_SOURCE_OUTPUT_CONFIG_FILE - The name of the CPack
# configuration file for source installers that will be generated by
# the CPack module. Defaults to CPackSourceConfig.cmake.
# CPACK_SOURCE_OUTPUT_CONFIG_FILE - The name of the CPack source
# configuration file. This file is the CPack configuration generated by the
# CPack module for source installers. Defaults to CPackSourceConfig.cmake.
##end
#
##variable
# CPACK_SOURCE_IGNORE_FILES - Pattern of files in the source tree
# 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
#
# The following variables are for advanced uses of CPack:
#
##variable
# 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.
##end
#
@ -358,6 +380,12 @@ macro(cpack_optional_append _list _cond _item)
endif(${_cond})
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
# we might check here if the required tools for the generates exist
# and set the defaults according to the results

View File

@ -21,12 +21,60 @@ void cmCPackDocumentVariables::DefineVariables(cmake* cm)
"", false,
"Variables common to all CPack generators");
// Subsection: variables defined/used by cpack,
// which are specific to one CPack generator
// cm->DefineProperty
// ("CPACK_RPM_PACKAGE_NAME", cmProperty::VARIABLE,
// "RPM specific package name.",
// "If not specified, defaults to CPACK_PACKAGE_NAME."
// "", false,
// "Variables specific to a CPack generator");
cm->DefineProperty
("CPACK_INCLUDE_TOPLEVEL_DIRECTORY", cmProperty::VARIABLE,
"Boolean toggle to include/exclude top level directory.",
"When preparing a package CPack installs the item under"
" the so-called top level directory. The purpose of"
" is to include (set to 1 or ON or TRUE) the top level directory"
" in the package or not (set to 0 or OFF or FALSE).\n"
"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");
}