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.

2 files changed, 162 insertions, 86 deletions

diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake
index e0a5518..b506711 100644
--- a/Modules/CPack.cmake
+++ b/Modules/CPack.cmake
@@ -53,176 +53,198 @@
 ##end
 #
 ##variable
-#   CPACK_PACKAGE_NAME - The name of the package (or application). If
-#   not specified, defaults to the project name.
+#  CPACK_PACKAGE_NAME - The name of the package (or application). If
+#  not specified, defaults to the project name.
 ##end
 #
 ##variable
-#   CPACK_PACKAGE_VENDOR - The name of the package vendor. (e.g.,
-#   "Kitware").
+#  CPACK_PACKAGE_VENDOR - The name of the package vendor. (e.g.,
+#  "Kitware").
 ##end
 #
 ##variable
-#   CPACK_PACKAGE_VERSION_MAJOR - Package major Version
+#  CPACK_PACKAGE_VERSION_MAJOR - Package major Version
 ##end
 #
 ##variable
-#   CPACK_PACKAGE_VERSION_MINOR - Package minor Version
+#  CPACK_PACKAGE_VERSION_MINOR - Package minor Version
 ##end
 #
 ##variable
-#   CPACK_PACKAGE_VERSION_PATCH - Package patch Version
+#  CPACK_PACKAGE_VERSION_PATCH - Package patch Version
 ##end
 #
 ##variable
-#   CPACK_PACKAGE_DESCRIPTION_FILE - A text file used to describe the
-#   project. Used, for example, the introduction screen of a
-#   CPack-generated Windows installer to describe the project.
+#  CPACK_PACKAGE_DESCRIPTION_FILE - A text file used to describe the
+#  project. Used, for example, the introduction screen of a
+#  CPack-generated Windows installer to describe the project.
 ##end
 #
 ##variable
-#   CPACK_PACKAGE_DESCRIPTION_SUMMARY - Short description of the
-#   project (only a few words).
+#  CPACK_PACKAGE_DESCRIPTION_SUMMARY - Short description of the
+#  project (only a few words).
 ##end
 #
 ##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.
+#  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".
+#  CPACK_PACKAGE_INSTALL_DIRECTORY - Installation directory on the
+#  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 time.
+#  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.
+#  CPACK_MONOLITHIC_INSTALL - Disables the component-based
+#  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.,
-#   CPACK_BINARY_NSIS) allowing the user to enable/disable individual
-#   generators.
+#  CPACK_GENERATOR - List of CPack generators to use. If not
+#  specified, CPack will create a set of options CPACK_BINARY_<GENNAME> (e.g.,
+#  CPACK_BINARY_NSIS) allowing the user to enable/disable individual
+#  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
-#   create a shortcut named "CMake" that will execute the installed
-#   executable ccmake.
+#  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. Not all CPack generators use it (at least NSIS and
+#  OSXX11 do).
 ##end
 #
 ##variable
-#   CPACK_STRIP_FILES - List of files to be stripped. Starting with
-#   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
-#   in CMake, so this change is compatible).
+#  CPACK_STRIP_FILES - List of files to be stripped. Starting with
+#  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
+#  in CMake, so this change is compatible).
 ##end
 #
 # The following CPack variables are specific to source packages, and 
 # 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
-#   CPACK_SOURCE_STRIP_FILES - List of files in the source tree that
-#   will be stripped. Starting with CMake 2.6.0
-#   CPACK_SOURCE_STRIP_FILES will be a boolean variable which enables
-#   stripping of all files (a list of files evaluates to TRUE in CMake,
-#   so this change is compatible).
+#  CPACK_SOURCE_STRIP_FILES - List of files in the source tree that
+#  will be stripped. Starting with CMake 2.6.0
+#  CPACK_SOURCE_STRIP_FILES will be a boolean variable which enables
+#  stripping of all files (a list of files evaluates to TRUE in CMake,
+#  so this change is compatible).
 ##end
 #
 ##variable
-#   CPACK_SOURCE_GENERATOR - List of generators used for the source
-#   packages. As with CPACK_GENERATOR, if this is not specified then
-#   CPack will create a set of options (e.g., CPACK_SOURCE_ZIP)
-#   allowing users to select which packages will be generated.
+#  CPACK_SOURCE_GENERATOR - List of generators used for the source
+#  packages. As with CPACK_GENERATOR, if this is not specified then
+#  CPack will create a set of options (e.g., CPACK_SOURCE_ZIP)
+#  allowing users to select which packages will be generated.
 ##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.*
+#  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 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;
-#   few users will want to change this setting.
+#  CPACK_CMAKE_GENERATOR - What CMake generator should be used if the
+#  project is CMake project. Defaults to the value of CMAKE_GENERATOR
+#  few users will want to change this setting.
 ##end
 #
 ##variable
-#   CPACK_INSTALL_CMAKE_PROJECTS - List of four values that specify
-#   what project to install. The four values are: Build directory,
-#   Project Name, Project Component, Directory. If omitted, CPack will
-#   build an installer that installers everything.
+#  CPACK_INSTALL_CMAKE_PROJECTS - List of four values that specify
+#  what project to install. The four values are: Build directory,
+#  Project Name, Project Component, Directory. If omitted, CPack will
+#  build an installer that installers everything.
 ##end
 #
 ##variable
-#   CPACK_SYSTEM_NAME - System name, defaults to the value of
-#   ${CMAKE_SYSTEM_NAME}.
+#  CPACK_SYSTEM_NAME - System name, defaults to the value of
+#  ${CMAKE_SYSTEM_NAME}.
 ##end
 #
 ##variable
-#   CPACK_PACKAGE_VERSION - Package full version, used internally. By
-#   default, this is built from CPACK_PACKAGE_VERSION_MAJOR,
-#   CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
+#  CPACK_PACKAGE_VERSION - Package full version, used internally. By
+#  default, this is built from CPACK_PACKAGE_VERSION_MAJOR,
+#  CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
 ##end
 #
 ##variable
-#   CPACK_TOPLEVEL_TAG - Directory for the installed files.
+#  CPACK_TOPLEVEL_TAG - Directory for the installed files.
 ##end
 #
 ##variable
-#   CPACK_INSTALL_COMMANDS - Extra commands to install components.
+#  CPACK_INSTALL_COMMANDS - Extra commands to install components.
 ##end
 #
 ##variable
-#   CPACK_INSTALLED_DIRECTORIES - Extra directories to install.
+#  CPACK_INSTALLED_DIRECTORIES - Extra directories to install.
 ##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
diff --git a/Source/CPack/cmCPackDocumentVariables.cxx b/Source/CPack/cmCPackDocumentVariables.cxx
index 68cde78..23e99f8 100644
--- a/Source/CPack/cmCPackDocumentVariables.cxx
+++ b/Source/CPack/cmCPackDocumentVariables.cxx
@@ -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");
 }