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.

1 files changed, 56 insertions, 8 deletions

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");
 }