diff options
| -rw-r--r-- | Help/manual/cpack.1.rst | 123 | ||||
| -rw-r--r-- | Modules/CPack.cmake | 15 | ||||
| -rw-r--r-- | Source/CPack/cpack.cxx | 20 |
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 } }; |