Merge topic 'doc-cpack'

0ea52ece71 Help: module CPack: improve summary and Introduction
5c4d730dd4 Help: CPackComponent: improve summary and introduction
40da958d23 Help: CPack Archive Generator: Clarify source vs binary package

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

3 files changed, 53 insertions, 38 deletions

diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst
index d455f4b..052f9cf 100644
--- a/Help/cpack_gen/archive.rst
+++ b/Help/cpack_gen/archive.rst
@@ -1,8 +1,8 @@
 CPack Archive Generator
 -----------------------
 
-Archive CPack generator that supports packaging of sources and binaries in
-different formats:
+CPack generator for packaging files into an archive, which can have
+any of the following formats:
 
   - 7Z - 7zip - (.7z)
   - TBZ2 (.tar.bz2)
@@ -12,25 +12,42 @@ different formats:
   - TZST (.tar.zst)
   - ZIP (.zip)
 
+When this generator is called from ``CPackSourceConfig.cmake`` (or through
+the ``package_source`` target), then the generated archive will contain all
+files in the project directory, except those specified in
+:variable:`CPACK_SOURCE_IGNORE_FILES`.  The following is one example of
+packaging all source files of a project:
+
+.. code-block:: cmake
+
+  set(CPACK_SOURCE_GENERATOR "TGZ")
+  set(CPACK_SOURCE_IGNORE_FILES
+    \\.git/
+    build/
+    ".*~$"
+  )
+  set(CPACK_VERBATIM_VARIABLES YES)
+  include(CPack)
+
+When this is generator is called from ``CPackConfig.cmake`` (or through the
+``package`` target), then the generated archive will contain all files
+that have been installed via CMake's :command:`install` command (and the
+deprecated commands :command:`install_files`, :command:`install_programs`,
+and :command:`install_targets`).
+
 Variables specific to CPack Archive generator
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. variable:: CPACK_ARCHIVE_FILE_NAME
               CPACK_ARCHIVE_<component>_FILE_NAME
 
- Package file name without extension which is added automatically depending
- on the archive format.
-
- * Mandatory : YES
- * Default   : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].<extension>`` with
-               spaces replaced by '-'
+  Package file name without extension. The extension is determined from the
+  archive format (see list above) and automatically appended to the file name.
+  The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces
+  replaced by '-'.
 
 .. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL
 
- Enable component packaging for CPackArchive
-
- * Mandatory : NO
- * Default   : OFF
-
- If enabled (ON) multiple packages are generated. By default a single package
- containing files of all components is generated.
+  Enable component packaging. If enabled (ON), then the archive generator
+  creates  multiple packages. The default is OFF, which means that a single
+  package containing files of all components is generated.
diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake
index baf7e47..6234b9d 100644
--- a/Modules/CPack.cmake
+++ b/Modules/CPack.cmake
@@ -5,7 +5,7 @@
 CPack
 -----
 
-Configure the binary and source package installers.
+Configure generators for binary installers and source packages.
 
 Introduction
 ^^^^^^^^^^^^
@@ -19,13 +19,17 @@ Depending on the CMake generator, the CPack module may also add two new build
 targets, ``package`` and ``package_source``. See the `packaging targets`_
 section below for details.
 
-The generated binary installers contain everything installed via CMake's
-:command:`install` command (and the deprecated commands :command:`install_files`,
-:command:`install_programs`, and :command:`install_targets`).
-For certain kinds of binary installers (including the graphical
-installers on macOS and Windows), CPack generates installers that
-allow users to select individual application components to install.
-See :module:`CPackComponent` module for further details.
+The generated binary installers will contain all files that have been installed
+via CMake's :command:`install` command (and the deprecated commands
+:command:`install_files`, :command:`install_programs`, and
+:command:`install_targets`).  Certain kinds of binary installers can be
+configured such that users can select individual application components to
+install.  See the :module:`CPackComponent` module for further details.
+
+Source packages (configured through ``CPackSourceConfig.cmake`` and generated
+by the :cpack_gen:`CPack Archive Generator`) will contain all source files in
+the project directory except those specified in
+:variable:`CPACK_SOURCE_IGNORE_FILES`.
 
 CPack Generators
 ^^^^^^^^^^^^^^^^
@@ -38,10 +42,6 @@ generator.  In a :variable:`CPACK_PROJECT_CONFIG_FILE`,
 :variable:`CPACK_GENERATOR` is a *string naming a single generator*.  If you
 need per-cpack-generator logic to control *other* cpack settings, then you
 need a :variable:`CPACK_PROJECT_CONFIG_FILE`.
-
-The CMake source tree itself contains a :variable:`CPACK_PROJECT_CONFIG_FILE`.
-See the top level file ``CMakeCPackOptions.cmake.in`` for an example.
-
 If set, the :variable:`CPACK_PROJECT_CONFIG_FILE` is included automatically
 on a per-generator basis.  It only need contain overrides.
 
diff --git a/Modules/CPackComponent.cmake b/Modules/CPackComponent.cmake
index 211d767..22fa6bb 100644
--- a/Modules/CPackComponent.cmake
+++ b/Modules/CPackComponent.cmake
@@ -5,19 +5,18 @@
 CPackComponent
 --------------
 
-Build binary and source package installers
+Configure components for binary installers and source packages.
 
 Variables concerning CPack Components
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The CPackComponent module is the module which handles the component
-part of CPack.  See CPack module for general information about CPack.
+This module handles the component part of :module:`CPack`.
 
-For certain kinds of binary installers (including the graphical
-installers on macOS and Windows), CPack generates installers that
-allow users to select individual application components to install.
-The contents of each of the components are identified by the COMPONENT
-argument of CMake's INSTALL command.  These components can be
+For certain kinds of binary installers (especially the graphical installers),
+CPack generates installers that allow users to select individual application
+components to install.
+The contents of each of the components are identified by the ``COMPONENT``
+argument of CMake's :command:`install` command.  These components can be
 annotated with user-friendly names and descriptions, inter-component
 dependencies, etc., and grouped in various ways to customize the
 resulting installer.  See the cpack_add_* commands, described below,
@@ -25,9 +24,8 @@ for more information about component-specific installations.
 
 Component-specific installation allows users to select specific sets
 of components to install during the install process.  Installation
-components are identified by the COMPONENT argument of CMake's INSTALL
-commands, and should be further described by the following CPack
-commands:
+components are identified by the ``COMPONENT`` argument of :command:`install`,
+and should be further described by the following CPack commands:
 
 .. variable:: CPACK_COMPONENTS_ALL