Commit a26ac919 authored by Joachim Wuttke's avatar Joachim Wuttke Committed by Joachim Wuttke

Help: Explain interaction of cpack(1) and CPack.

In particular, make clear that package/installer generators
are not the makefile generators of the cmake command.

Also insert sections in CPack doc, and capitalize section titles.
parent a786062d
......@@ -13,12 +13,29 @@ Synopsis
Description
===========
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.
The ``cpack`` executable is the CMake packaging program. It generates
installers and source packages in a variety of formats.
For each installer or package format, ``cpack`` has a specific backend,
called "generator". A generator is responsible for generating the required
inputs and invoking the specific package creation tools. These installer
or package generators are not to be confused with the makefile generators
of the :manual:`cmake <cmake(1)>` command.
All supported generators are specified in the :manual:`cpack-generators
<cpack-generators(7)>` manual. The command ``cpack --help`` prints a
list of generators supported for the target platform. Which of them are
to be used can be selected through the :variable:`CPACK_GENERATOR` variable
or through the command-line option ``-G``.
The ``cpack`` program is steered by a configuration file written in the
:manual:`CMake language <cmake-language(7)>`. Unless chosen differently
through the command-line option ``--config``, the file ``CPackConfig.cmake``
in the current directory is used.
In the standard CMake workflow, the file ``CPackConfig.cmake`` is generated
by the :manual:`cmake <cmake(1)>` executable, provided the :module:`CPack`
module is included by the project's ``CMakeLists.txt`` file.
Options
=======
......@@ -27,14 +44,9 @@ Options
``<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. All supported generators are specified
in the :manual:`Generators <cpack-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.
the ``CPackConfig.cmake`` configuration file. 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 to be packaged (e.g. ``Debug``,
......
......@@ -10,20 +10,23 @@ Build binary and source package installers.
Introduction
^^^^^^^^^^^^
The CPack module generates binary and source installers in a variety of
formats using the cpack program. Inclusion of the CPack module adds
two new build targets, ``package`` and ``package_source``, which build
the binary and source installers respectively. The generated binary
installers contain everything installed via CMake's :command:`install`
command (and the deprecated :command:`install_files`,
:command:`install_programs` and :command:`install_targets` commands).
The CPack module generates a file ``CPackConfig.cmake`` intended for
use in a subsequent run of the :manual:`cpack <cpack(1)>` program
where it steers the generation of installers or/and source packages.
Inclusion of the CPack module adds two new build targets, ``package``
and ``package_source``, which build the binary and source installers
respectively. 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.
CPack generators
CPack Generators
^^^^^^^^^^^^^^^^
The :variable:`CPACK_GENERATOR` variable has different meanings in different
......@@ -60,7 +63,7 @@ This is the key: For each generator listed in :variable:`CPACK_GENERATOR` in
internally to *the one currently being used* and then include the
:variable:`CPACK_PROJECT_CONFIG_FILE`.
Variables common to all CPack generators
Variables common to all CPack Generators
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Before including this CPack module in your ``CMakeLists.txt`` file, there
......@@ -250,6 +253,9 @@ installers. The most commonly-used variables are:
received by the cpack program. Defaults to ``FALSE`` for backwards
compatibility.
Variables for Source Package Generators
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following CPack variables are specific to source packages, and
will not affect binary packages:
......@@ -284,6 +290,9 @@ will not affect binary packages:
must be properly escaped), e.g.,
``/CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*``
Variables for Advanced Use
^^^^^^^^^^^^^^^^^^^^^^^^^^
The following variables are for advanced uses of CPack:
.. variable:: CPACK_CMAKE_GENERATOR
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment