From 40da958d235a7efc15607436d8ce6fdaee274342 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (o)" Date: Thu, 13 Feb 2020 10:06:55 +0100 Subject: Help: CPack Archive Generator: Clarify source vs binary package - Simplify summary - Revise introduction: - Explain how to package source files, provide configuration sample - Clarify source vs binary package - Clarify meaning of variables (Mandatory=ON makes no sense if a default is defined) --- Help/cpack_gen/archive.rst | 47 +++++++++++++++++++++++++++++++--------------- 1 file changed, 32 insertions(+), 15 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__FILE_NAME - Package file name without extension which is added automatically depending - on the archive format. - - * Mandatory : YES - * Default : ``[-].`` 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 ``[-]``, 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. -- cgit v0.12 From 5c4d730dd4a4ebfc4d4fd549c28e08821e1bc573 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (o)" Date: Wed, 12 Feb 2020 16:52:23 +0100 Subject: Help: CPackComponent: improve summary and introduction Also: * provide some hyperlinks * update parenthesis on graphical installers (no longer restricted to Win and macOS) --- Modules/CPackComponent.cmake | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) 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 -- cgit v0.12 From 0ea52ece71d3e952ec5158caa87ecf84582ea4ca Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (o)" Date: Wed, 12 Feb 2020 16:15:26 +0100 Subject: Help: module CPack: improve summary and Introduction * In summary: * we configure generators, not the generated installers * we generate installers or source packages, not source package installers * In Introduction: * Make paragraph on binary installers more concise * Remove example that refered to CMake source tree * Add paragraph on source packages * omit the parenthesis on graphical installers --- Modules/CPack.cmake | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) 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. -- cgit v0.12