Build a CPack package from a CMake build directory

You will turn an existing CMake build directory into a package, using CPack's generated CPackConfig.cmake file. The examples use the installed CMake 3.28.3 and create a compressed tar archive without changing the source tree. Allow 15 to 30 minutes if the project already configures cleanly.

1. Check the installed tool and project

You need a configured CMake project and its build directory. The project should include the CPack module, normally near the end of CMakeLists.txt:

set(CPACK_GENERATOR "TGZ")
include(CPack)

That module creates CPackConfig.cmake during configuration. It is not the same thing as the CMake generator that produced your build files. Check which executable will run and which version is installed:

$ command -v cpack
/usr/bin/cpack
$ cpack --version
cpack version 3.28.3

CMake suite maintained and supported by Kitware (kitware.com/cmake).

If command -v points into an unexpected virtual environment or project toolchain, resolve that before packaging. Do not use sudo for this check. A normal user should be able to read the build directory and write the package destination.

2. Confirm that CPack has a configuration file

Run this from the build directory, or use an absolute path. The default configuration name is CPackConfig.cmake in the current directory:

$ test -r /path/to/build/CPackConfig.cmake && echo "CPack configuration is readable"
CPack configuration is readable
$ grep -E 'CPACK_(GENERATOR|PACKAGE_NAME|PACKAGE_VERSION|PACKAGE_DIRECTORY)' \
    /path/to/build/CPackConfig.cmake

The exact variables printed depend on the project. If the file does not exist, configure the project again after adding include(CPack). That is a source change, so review the project first and rebuild or reconfigure using the project's normal command. Do not create a hand-written replacement by guessing the install rules.

The generated configuration is executable CMake language. Treat it like code: read it, and do not run a configuration file copied from an untrusted source merely because its name looks familiar.

3. List the available generator names

Generators select the package backend. The installed CPack reports names such as TGZ, ZIP, DEB and RPM; availability is platform-dependent. Ask your executable instead of relying on a list from another host:

$ cpack --help | sed -n '/Generators/,/Options/p'
Generators
  7Z                           = 7-Zip file format
  DEB                          = Debian packages
  ...
  TGZ                          = Tar GZip compression
  ZIP                          = ZIP file format

For a portable first test, TGZ needs only the tools shipped with CPack. A Debian package may need package metadata and a suitable project install layout. A generator that appears in help can still fail later if its external packaging tools or project-specific inputs are missing.

4. Build the package with the project's defaults

Use --config when you are not already in the directory containing the generated file:

$ cpack --config /path/to/build/CPackConfig.cmake
CPack: Create package using TGZ
CPack: Install projects
CPack: - package: /path/to/build/packages/project-1.2.3-Linux.tar.gz generated.

The wording and filename vary with the project and generator. CPack normally uses CPACK_PACKAGE_DIRECTORY for its output area and creates a _CPack_Packages working directory below it. Keep that working area separate from source files and from a directory containing a previous release.

For a multi-configuration build, select a configuration that has already been built:

$ cpack --config /path/to/build/CPackConfig.cmake -C Release

-C accepts a semicolon-separated list, but do not name Release unless that configuration exists and its binaries have been built. With a single-configuration generator, the relevant build type was chosen during configuration instead.

5. Override one run without editing the project

Command-line overrides are useful for a test package or a controlled release job. -G accepts a semicolon-separated generator list, so this produces both archive formats if the project and tools support them:

$ cpack --config /path/to/build/CPackConfig.cmake \
    -G 'TGZ;ZIP' \
    -B /path/to/package-output

-B sets the package directory for this invocation. The directory is used for the resulting packages and for CPack's working area. Choose an empty, disposable destination when testing. The command can replace files with matching names, so check it first:

$ find /path/to/package-output -maxdepth 1 -type f -printf '%f\n'
$ cpack --config /path/to/build/CPackConfig.cmake -B /path/to/package-output \
    -P project-test -R 0.0.0-test -G TGZ
$ find /path/to/package-output -maxdepth 1 -type f -printf '%f\n'

-P overrides CPACK_PACKAGE_NAME, while -R overrides CPACK_PACKAGE_VERSION. These options affect this CPack run; they do not rewrite CPackConfig.cmake. Do not use a fake version for an artefact that will be distributed as a real release.

6. Verify the artefact and diagnose failures

First check the exit status and list the output files. For a TGZ package, inspect its archive contents without extracting it:

$ cpack --config /path/to/build/CPackConfig.cmake -G TGZ -B /path/to/package-output
$ printf 'cpack exit status: %s\n' "$?"
cpack exit status: 0
$ find /path/to/package-output -maxdepth 1 -type f -name '*.tar.gz' -printf '%f\n'
project-1.2.3-Linux.tar.gz
$ tar -tzf /path/to/package-output/project-1.2.3-Linux.tar.gz | sed -n '1,20p'

Check that the archive contains the installed files you intended, not merely that it exists. If CPack reports that a generator cannot be found, use the exact name from cpack --help. If a package is empty or missing files, inspect the project's install() rules and rerun CMake configuration. CPack packages the install result; it does not automatically package every file in the source tree.

Use -V for generator and install details, and reserve --debug for deeper CPack diagnostics. --trace and --trace-expand expose the underlying CMake scripts and can produce a large amount of output, so redirect them to a reviewable log rather than using them in an automated terminal without a limit.

7. Clean up a test run safely

Package generation changes the selected package directory and its CPack working area. It does not modify the input source archive or build outputs as part of the normal workflow. Before deleting a test result, confirm the path is exactly the disposable directory you chose:

$ realpath /path/to/package-output
/path/to/package-output
$ find /path/to/package-output -maxdepth 2 -print

Only then remove that test directory with your normal housekeeping process. Do not remove the build directory to fix a package failure: it contains the generated configuration and may contain the compiled artefacts needed for the next run. If a release package was overwritten, recover it from the project's artefact store or backup rather than trying to reconstruct its exact bytes.