Merge topic 'cpack_docs_cleanup'

9a8687121f Help: Improve accuracy, readability and cross-referencing of cpack docs

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2013

3 files changed, 76 insertions, 82 deletions

diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst
index 105bb67..87aa38d 100644
--- a/Help/manual/cpack.1.rst
+++ b/Help/manual/cpack.1.rst
@@ -8,92 +8,85 @@ Synopsis
 
 .. parsed-literal::
 
- cpack -G <generator> [<options>]
+ cpack [<options>]
 
 Description
 ===========
 
-The "cpack" executable is the CMake packaging program.
-CMake-generated build trees created for projects that use the
-INSTALL_* commands have packaging support.  This program will generate
-the package.
-
-CMake is a cross-platform build system generator.  Projects specify
-their build process with platform-independent CMake listfiles included
-in each directory of a source tree with the name CMakeLists.txt.
-Users build a project by using CMake to generate a build system for a
-native tool on their platform.
+The ``cpack`` executable is the CMake packaging program.
+CMake projects use :command:`install` commands to define the contents of
+packages which can be generated in various formats by this tool.
+The :module:`CPack` module greatly simplifies the creation of the input file
+used by ``cpack``, allowing most aspects of the packaging configuration to be
+controlled directly from the CMake project's own ``CMakeLists.txt`` files.
 
 Options
 =======
 
-``-G <generator>``
- Use the specified generator to generate package.
-
- CPack may support multiple native packaging systems on certain
- platforms.  A generator is responsible for generating input files
- for particular system and invoking that systems.  Possible generator
- names are specified in the Generators section.
+``-G <generators>``
+  ``<generators>`` is a :ref:`semicolon-separated list <CMake Language Lists>`
+  of generator names.  ``cpack`` will iterate through this list and produce
+  package(s) in that generator's format according to the details provided in
+  the ``CPackConfig.cmake`` configuration file.  A generator is responsible for
+  generating the required inputs for a particular package system and invoking
+  that system's package creation tools.  Possible generator names are specified
+  in the :manual:`Generators <cmake-generators(7)>` section of the manual and
+  the ``--help`` option lists the generators supported for the target platform.
+  If this option is not given, the :variable:`CPACK_GENERATOR` variable
+  determines the default set of generators that will be used.
 
 ``-C <Configuration>``
- Specify the project configuration
-
- This option specifies the configuration that the project was build
- with, for example 'Debug', 'Release'.
+  Specify the project configuration to be packaged (e.g. ``Debug``,
+  ``Release``, etc.).  When the CMake project uses a multi-configuration
+  generator such as Xcode or Visual Studio, this option is needed to tell
+  ``cpack`` which built executables to include in the package.
 
 ``-D <var>=<value>``
- Set a CPack variable.
-
- Set a variable that can be used by the generator.
+  Set a CPack variable.  This will override any value set for ``<var>`` in the
+  input file read by ``cpack``.
 
-``--config <config file>``
- Specify the config file.
-
- Specify the config file to use to create the package.  By default
- CPackConfig.cmake in the current directory will be used.
+``--config <configFile>``
+  Specify the configuration file read by ``cpack`` to provide the packaging
+  details.  By default, ``CPackConfig.cmake`` in the current directory will
+  be used.
 
 ``--verbose,-V``
- enable verbose output
-
- Run cpack with verbose output.
+  Run ``cpack`` with verbose output.  This can be used to show more details
+  from the package generation tools and is suitable for project developers.
 
 ``--debug``
- enable debug output (for CPack developers)
-
- Run cpack with debug output (for CPack developers).
+  Run ``cpack`` with debug output.  This option is intended mainly for the
+  developers of ``cpack`` itself and is not normally needed by project
+  developers.
 
 ``--trace``
- Put underlying cmake scripts in trace mode.
+  Put the underlying cmake scripts in trace mode.
 
 ``--trace-expand``
- Put underlying cmake scripts in expanded trace mode.
-
-``-P <package name>``
- override/define CPACK_PACKAGE_NAME
-
- If the package name is not specified on cpack command line
- thenCPack.cmake defines it as CMAKE_PROJECT_NAME
-
-``-R <package version>``
- override/define CPACK_PACKAGE_VERSION
-
- If version is not specified on cpack command line thenCPack.cmake
- defines it from CPACK_PACKAGE_VERSION_[MAJOR|MINOR|PATCH]look into
- CPack.cmake for detail
-
-``-B <package directory>``
- override/define CPACK_PACKAGE_DIRECTORY
-
- The directory where CPack will be doing its packaging work.The
- resulting package will be found there.  Inside this directoryCPack
- creates '_CPack_Packages' sub-directory which is theCPack temporary
- directory.
-
-``--vendor <vendor name>``
- override/define CPACK_PACKAGE_VENDOR
-
- If vendor is not specified on cpack command line (or inside
- CMakeLists.txt) thenCPack.cmake defines it with a default value
+  Put the underlying cmake scripts in expanded trace mode.
+
+``-P <packageName>``
+  Override/define the value of the :variable:`CPACK_PACKAGE_NAME` variable used
+  for packaging.  Any value set for this variable in the ``CPackConfig.cmake``
+  file will then be ignored.
+
+``-R <packageVersion>``
+  Override/define the value of the :variable:`CPACK_PACKAGE_VERSION`
+  variable used for packaging.  It will override a value set in the
+  ``CPackConfig.cmake`` file or one automatically computed from
+  :variable:`CPACK_PACKAGE_VERSION_MAJOR`,
+  :variable:`CPACK_PACKAGE_VERSION_MINOR` and
+  :variable:`CPACK_PACKAGE_VERSION_PATCH`.
+
+``-B <packageDirectory>``
+  Override/define :variable:`CPACK_PACKAGE_DIRECTORY`, which controls the
+  directory where CPack will perform its packaging work.  The resultant
+  package(s) will be created at this location by default and a
+  ``_CPack_Packages`` subdirectory will also be created below this directory to
+  use as a working area during package creation.
+
+``--vendor <vendorName>``
+  Override/define :variable:`CPACK_PACKAGE_VENDOR`.
 
 .. include:: OPTIONS_HELP.txt
 
diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake
index 3ff8be6..a71f84a 100644
--- a/Modules/CPack.cmake
+++ b/Modules/CPack.cmake
@@ -43,9 +43,9 @@
 #
 # * cpack runs
 # * it includes CPackConfig.cmake
-# * it iterates over the generators listed in that file's
-#   CPACK_GENERATOR list variable (unless told to use just a
-#   specific one via -G on the command line...)
+# * it iterates over the generators given by the ``-G`` command line option,
+#   or if no such option was specified, over the list of generators given by
+#   the CPACK_GENERATOR variable set in the CPackConfig.cmake input file.
 # * foreach generator, it then
 #
 #   - sets CPACK_GENERATOR to the one currently being iterated
@@ -182,12 +182,11 @@
 #
 # .. variable:: CPACK_GENERATOR
 #
-#  List of CPack generators to use. If not specified, CPack will create a
+#  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
+#  the user to enable/disable individual generators.  If the ``-G`` option
+#  is given on the :manual:`cpack <cpack(1)>` command line, it will override
+#  this variable and any CPACK_BINARY_<GENNAME> options.
 #
 # .. variable:: CPACK_OUTPUT_CONFIG_FILE
 #
diff --git a/Source/CPack/cpack.cxx b/Source/CPack/cpack.cxx
index b6ff38b..87ef5b6 100644
--- a/Source/CPack/cpack.cxx
+++ b/Source/CPack/cpack.cxx
@@ -33,23 +33,25 @@ static const char* cmDocumentationName[][2] = {
 };
 
 static const char* cmDocumentationUsage[][2] = {
-  { nullptr, "  cpack -G <generator> [options]" },
+  // clang-format off
+  { nullptr, "  cpack [options]" },
   { nullptr, nullptr }
+  // clang-format on
 };
 
 static const char* cmDocumentationOptions[][2] = {
-  { "-G <generator>", "Use the specified generator to generate package." },
+  { "-G <generators>", "Override/define CPACK_GENERATOR" },
   { "-C <Configuration>", "Specify the project configuration" },
   { "-D <var>=<value>", "Set a CPack variable." },
-  { "--config <config file>", "Specify the config file." },
-  { "--verbose,-V", "enable verbose output" },
+  { "--config <configFile>", "Specify the config file." },
+  { "--verbose,-V", "Enable verbose output" },
   { "--trace", "Put underlying cmake scripts in trace mode." },
   { "--trace-expand", "Put underlying cmake scripts in expanded trace mode." },
-  { "--debug", "enable debug output (for CPack developers)" },
-  { "-P <package name>", "override/define CPACK_PACKAGE_NAME" },
-  { "-R <package version>", "override/define CPACK_PACKAGE_VERSION" },
-  { "-B <package directory>", "override/define CPACK_PACKAGE_DIRECTORY" },
-  { "--vendor <vendor name>", "override/define CPACK_PACKAGE_VENDOR" },
+  { "--debug", "Enable debug output (for CPack developers)" },
+  { "-P <packageName>", "Override/define CPACK_PACKAGE_NAME" },
+  { "-R <packageVersion>", "Override/define CPACK_PACKAGE_VERSION" },
+  { "-B <packageDirectory>", "Override/define CPACK_PACKAGE_DIRECTORY" },
+  { "--vendor <vendorName>", "Override/define CPACK_PACKAGE_VENDOR" },
   { nullptr, nullptr }
 };