Build a CPack Package from a CMake Build Directory

CPack turns a CMake build directory you already have into a distributable package, reading the CPackConfig.cmake file that CMake generated for you. These examples use the installed CMake 3.28.3 to build a compressed tar archive, and they never touch your source tree. Budget 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, with the project including the CPack module, usually near the end of CMakeLists.txt:

set(CPACK_GENERATOR "TGZ")
include(CPack)

That module produces CPackConfig.cmake during configuration, which is a different thing from the CMake generator that built your project files. Check which executable actually runs, and its version:

$ 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 resolves to an unexpected virtual environment or project toolchain, sort that out before packaging anything. Skip sudo here: an ordinary user should be able to read the build directory and write to the package destination.

2. Confirm that CPack has a configuration file

Run this from inside the build directory, or supply an absolute path instead. CPack expects CPackConfig.cmake in the current directory by default:

$ 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

Which variables get printed depends entirely on the project. A missing file means configuring again after adding include(CPack), which is a source change: review it, then rebuild or reconfigure through the project's usual command rather than hand-writing a replacement by guessing the install rules.

Remember that generated configuration is executable CMake language, not passive data. Read it like code, and never run a configuration file from an untrusted source just because the filename looks familiar.

3. List the available generator names

Generators pick the packaging backend. Your installed CPack reports names such as TGZ, ZIP, DEB and RPM, though availability depends on the platform. Ask your own executable rather than trusting a list copied 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

TGZ is the easiest first test since it needs only the tools CPack ships with. A Debian package additionally needs package metadata and a suitable install layout. Even a generator that shows up in the help text can still fail later if its external packaging tools or project-specific inputs are missing.

4. Build the package with the project's defaults

Add --config whenever you are working from outside the directory holding 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.

Exact wording and filename shift with the project and generator. CPack normally writes to CPACK_PACKAGE_DIRECTORY and builds a _CPack_Packages working directory underneath it, so keep that working area apart from your source files and from any directory holding a previous release.

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

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

-C takes a semicolon-separated list, but only name Release when that configuration exists and its binaries are built. A single-configuration generator already decided its build type back at configuration time.

5. Override one run without editing the project

Command-line overrides suit a test package or a controlled release job. -G accepts a semicolon-separated generator list, so the following produces both archive formats at once, assuming 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 one invocation, used both for the resulting packages and CPack's working area. Pick an empty, disposable destination for testing, since the command can overwrite files with matching names; check what is there 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 and -R overrides CPACK_PACKAGE_VERSION, both only for this run; neither rewrites CPackConfig.cmake itself. Never fake a version number for an artefact that will ship as a real release.

6. Verify the artefact and diagnose failures

Check the exit status first, then list the output files. For a TGZ package, look inside the archive 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'

Confirm the archive actually contains the files you intended, not merely that it exists. A generator CPack cannot find should be named exactly as cpack --help shows it. An empty or incomplete package usually points back to the project's install() rules, so rerun CMake configuration and check them: CPack packages the install result, it does not sweep up every file in the source tree.

Use -V for generator and install detail, and save --debug for deeper CPack diagnostics. --trace and --trace-expand expose the underlying CMake scripts and can produce a wall of output, so send them to a log you can actually review rather than an unbounded terminal.

7. Clean up a test run safely

Package generation only changes the package directory you selected and its CPack working area; it leaves the source archive and build outputs alone under normal operation. Before deleting a test result, confirm the path really is 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 usual housekeeping. Do not remove the build directory to work around a packaging failure: it holds the generated configuration and may hold the compiled artefacts the next run needs. If a real release package got overwritten, pull it back from the project's artefact store or backup rather than trying to reconstruct its exact bytes.