Help/cpack_gen/archive.rst

   1 CPack Archive Generator
   2 -----------------------
   3
   4 CPack generator for packaging files into an archive, which can have
   5 any of the following formats:
   6
   7   - 7Z - 7zip - (.7z)
   8   - TBZ2 (.tar.bz2)
   9   - TGZ (.tar.gz)
  10   - TXZ (.tar.xz)
  11   - TZ (.tar.Z)
  12   - TZST (.tar.zst)
  13   - ZIP (.zip)
  14
  15 .. versionadded:: 3.1
  16   ``7Z`` and ``TXZ`` formats support.
  17
  18 .. versionadded:: 3.16
  19   ``TZST`` format support.
  20
  21 When this generator is called from ``CPackSourceConfig.cmake`` (or through
  22 the ``package_source`` target), then the generated archive will contain all
  23 files in the project directory, except those specified in
  24 :variable:`CPACK_SOURCE_IGNORE_FILES`.  The following is one example of
  25 packaging all source files of a project:
  26
  27 .. code-block:: cmake
  28
  29   set(CPACK_SOURCE_GENERATOR "TGZ")
  30   set(CPACK_SOURCE_IGNORE_FILES
  31     \\.git/
  32     build/
  33     ".*~$"
  34   )
  35   set(CPACK_VERBATIM_VARIABLES YES)
  36   include(CPack)
  37
  38 When this generator is called from ``CPackConfig.cmake`` (or through the
  39 ``package`` target), then the generated archive will contain all files
  40 that have been installed via CMake's :command:`install` command (and the
  41 deprecated commands :command:`install_files`, :command:`install_programs`,
  42 and :command:`install_targets`).
  43
  44 Variables specific to CPack Archive generator
  45 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  46
  47 .. variable:: CPACK_ARCHIVE_FILE_NAME
  48               CPACK_ARCHIVE_<component>_FILE_NAME
  49
  50   Package file name without extension. The extension is determined from the
  51   archive format (see list above) and automatically appended to the file name.
  52   Note that ``<component>`` is all uppercase in the variable name.
  53
  54   The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces
  55   replaced by '-'.
  56
  57   .. versionadded:: 3.9
  58     Per-component ``CPACK_ARCHIVE_<component>_FILE_NAME`` variables.
  59
  60 .. variable:: CPACK_ARCHIVE_FILE_EXTENSION
  61
  62   .. versionadded:: 3.25
  63
  64   Package file extension. Default values are given in the list above.
  65
  66 .. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL
  67
  68   Enable component packaging. If enabled (ON), then the archive generator
  69   creates  multiple packages. The default is OFF, which means that a single
  70   package containing files of all components is generated.
  71
  72 Variables used by CPack Archive generator
  73 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  74
  75 These variables are used by the Archive generator, but are also available to
  76 CPack generators which are essentially archives at their core. These include:
  77
  78   - :cpack_gen:`CPack Cygwin Generator`
  79   - :cpack_gen:`CPack FreeBSD Generator`
  80
  81 .. variable:: CPACK_ARCHIVE_THREADS
  82
  83   .. versionadded:: 3.18
  84
  85   The number of threads to use when performing the compression. If set to
  86   ``0``, the number of available cores on the machine will be used instead.
  87   The default is ``1`` which limits compression to a single thread. Note that
  88   not all compression modes support threading in all environments. Currently,
  89   only the XZ compression may support it.
  90
  91   See also the :variable:`CPACK_THREADS` variable.
  92
  93   .. versionadded:: 3.21
  94
  95     Official CMake binaries available on ``cmake.org`` now ship
  96     with a ``liblzma`` that supports parallel compression.
  97     Older versions did not.