Packaging with CPack

With this configuration in place, generating the package is a simple command-line step that you run after a successful build. Remember, for this to work, we need appropriate install() rules in place. Our library's CMakeLists.txt file, with all the install rules we completed in our file sets lesson , is provided below:

1cmake_minimum_required(VERSION 3.23)
2project(GreeterLib VERSION 1.0.0)
3include(GNUInstallDirs)
4
5add_library(GreeterLib src/Greeter.cpp)
6add_library(Greeter::Lib ALIAS GreeterLib)
7
8set_target_properties(GreeterLib PROPERTIES
9  OUTPUT_NAME Greeter
10  EXPORT_NAME Lib
11)
12
13target_sources(GreeterLib
14  PUBLIC
15  FILE_SET HEADERS
16  BASE_DIRS "${PROJECT_SOURCE_DIR}/include"
17  FILES
18    "${PROJECT_SOURCE_DIR}/include/greeter/Greeter.h"
19)
20
21install(
22  TARGETS GreeterLib
23  EXPORT GreeterLibTargets
24  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
25  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
26  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
27  FILE_SET HEADERS DESTINATION
28    ${CMAKE_INSTALL_INCLUDEDIR}
29)
30
31install(EXPORT GreeterLibTargets
32  FILE GreeterLibTargets.cmake
33  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/GreeterLib
34  NAMESPACE Greeter::
35)
36
37include(CMakePackageConfigHelpers)
38
39configure_package_config_file(
40  "cmake/GreeterLibConfig.cmake.in"
41  "GreeterLibConfig.cmake"
42  INSTALL_DESTINATION
43  "${CMAKE_INSTALL_LIBDIR}/cmake/GreeterLib"
44)
45
46write_basic_package_version_file(
47  "GreeterLibConfigVersion.cmake"
48  VERSION ${PROJECT_VERSION}
49  COMPATIBILITY AnyNewerVersion
50)
51
52install(FILES
53  "${CMAKE_CURRENT_BINARY_DIR}/GreeterLibConfig.cmake"
54  "${CMAKE_CURRENT_BINARY_DIR}/GreeterLibConfigVersion.cmake"
55  DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/GreeterLib"
56)

First, let's configure and build our project as usual from the build directory. We'll build in Release mode, as that's what we would most commonly distribute.

If we don't already have presets for this, we should add them:

1{
2  "version": 3,
3  "configurePresets": [
4    // ...
5    {
6      "name": "release",
7      "inherits": "default",
8      "cacheVariables": {
9        "CMAKE_BUILD_TYPE": "Release"
10      }
11    }
12  ],
13  "buildPresets": [
14    // ...
15    {
16      "name": "release",
17      "configurePreset": "release",
18      "configuration": "Release"
19    }
20  ],
21  "testPresets": [
22    // ...
23    {
24      "name": "release",
25      "inherits": "default",
26      "configurePreset": "release"
27    }
28  ],
29  // ...
30}

Then, we configure and build our project in the usual way:

1cmake --preset release

1cmake --build --preset release

Now, from our build directory, we run the cpack command:

1cd ./build

1cpack

CPack will now:

1. Internally run the install step to stage all the necessary files into a temporary directory.
2. Use the specified generator (ZIP) to bundle the contents of that directory into an archive.
3. Place the final archive in the build directory.

1CPack: Create package using ZIP
2CPack: Install projects
3CPack: - Install project: Greeter []
4CPack: Create package
5CPack: - package: D:/projects/cmake/build/Greeter-1.0-win64.zip generated.

If you look in your build directory, you'll find a new file named something like Greeter-1.0-win64.zip. The exact nature of the package, such the architecture our library was compiled for, depends on our environment. We can control this in all the ways we covered previously, such as introducing a toolchain file.

Eventually, these packages will be created by our build server, not our local machine. In many cases, this can eliminate the need for cross-compilation. For example, if we want to build a Windows version of our library or program, we can just use a Windows build server.

In GitHub actions, that's as simple as creating a workflow that sets runs-on: windows-latest in our YAML file. We'll walk through an example of this later in the chapter.

For now, if we take a look inside the generated .zip file, we should see see it contains the complete install-tree we defined in our install() commands, cleanly organized and ready for another developer to use:

1Greeter-1.0-win64/
2├─ include/
3│  └─ greeter/
4│     └─ Greeter.h
5└─ lib/
6  ├─ libGreeter.a (or Greeter.lib)
7  └─ cmake/
8     └─ GreeterLib/
9        ├─ GreeterLibConfig.cmake
10        ├─ GreeterLibConfigVersion.cmake
11        ├─ GreeterLibTargets.cmake
12        └─ GreeterLibTargets-release.cmake

Just as we did for configuring, building, and testing, we can add presets for packaging to our CMakePresets.json to make this process friendlier and more repeatable.

Version Requirements for Package Presets

The packagePresets feature is a newer addition to CMake. To use it, we must meet two version requirements:

1. We must use at least CMake 3.25.
2. Our CMakePresets.json file must use schema version 6 or higher.

Let's update our root CMakeLists.txt and CMakePresets.json to reflect these new requirements.

1cmake_minimum_required(VERSION 3.25) 
2project(Greeter VERSION "1.0")
3
4# ... rest of file is unchanged

1{
2  "version": 6,
3  ...
4}

Creating a Package Preset

Now, we can add a packagePresets section to our file. A package preset links to a configurePreset to know which build directory it should operate on.

It can also contain a variables map, where we can set the various CMake configuration properties we're currently defining in our CMakeLists.txt. Some of the most imporant variables, such as generators, packageName, packageVersion, description, and vendor have dedicated keys that can be set at the top level of the preset.

Let's create a default preset that moves our configuration out of our CMakeLists.txt and into CMakePresets.json:

We can inherit from this preset in the usual way. Let's add a dev-zip preset for generating .zip archives of our developer utilities (ie, the GreeterLib target we set install() rules for):

1{
2  "version": 6,
3  // ...
4  "packagePresets": [{
5    "name": "default",
6    "configurePreset": "release",
7    "description": "The Greeter Library",
8    "vendorName": "StudyPlan.dev",
9    "variables": {
10      "CPACK_PACKAGE_CONTACT": "support@studyplan.dev"
11    }
12  }, {
13    "name": "dev-zip",
14    "displayName": "Developer Archive (ZIP)",
15    "inherits": "default",
16    "generators": ["ZIP"]
17  }]
18}

With this preset defined, our packaging command becomes much simpler and can be run from the project root, just like our other preset commands.

1cpack --preset dev-zip

This command will find the zip preset and it's base default preset, identify the associated build directory, run the install step if necessary, and execute the ZIP generator, producing the exact same distributable archive as before.

1CPack: Create package using ZIP
2CPack: Install projects
3CPack: - Install project: Greeter []
4CPack: Create package
5CPack: - package: D:/projects/cmake/build/Greeter-1.0-win64.zip generated.

Our current package is a monolith; it includes everything we've told install() about. That's fine for now, as we have only defined installation rules for our library.

But what if we want to package different parts of our project for different audiences? For example, a developer using our library needs the headers and CMake files, but someone who just wants to install and run our program may only need the executable. We may want to create a third packages that just includes our documentation.

We need a way to group our installed files into different categories, letting us specify exactly what we want to package on each invocation of cpack. This is the job of CPack Components.

A component is simply a named group of installed files. In this lesson, we'll take the first step by grouping all the files related to GreeterLib into a single Development component. In the next lesson, we'll add a separate Applications component for our executable and create a user-friendly installer.

Step 1: Assigning the Development Component

We'll edit greeter/CMakeLists.txt and add the COMPONENT keyword to everything we're installing, by tracking down our install() commands. This logically tags every file installed by this script as belonging to the same group.

We can call our component whatever we want, but we'll go with Development in this example given our library, header files and CMake files are developer tools:

1cmake_minimum_required(VERSION 3.23)
2project(GreeterLib VERSION 1.0.0)
3include(GNUInstallDirs)
4
5add_library(GreeterLib src/Greeter.cpp)
6add_library(Greeter::Lib ALIAS GreeterLib)
7
8set_target_properties(GreeterLib PROPERTIES
9  OUTPUT_NAME Greeter
10  EXPORT_NAME Lib
11)
12
13target_sources(GreeterLib
14  PUBLIC
15  FILE_SET HEADERS
16  BASE_DIRS "${PROJECT_SOURCE_DIR}/include"
17  FILES
18    "${PROJECT_SOURCE_DIR}/include/greeter/Greeter.h"
19)
20
21install(
22  TARGETS GreeterLib
23  EXPORT GreeterLibTargets
24  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
25    COMPONENT Development
26  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
27    COMPONENT Development
28  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
29    COMPONENT Development
30  FILE_SET HEADERS DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
31    COMPONENT Development
32)
33
34install(EXPORT GreeterLibTargets
35  FILE GreeterLibTargets.cmake
36  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/GreeterLib
37  NAMESPACE Greeter::
38  COMPONENT Development
39)
40
41include(CMakePackageConfigHelpers)
42
43configure_package_config_file(
44  "cmake/GreeterLibConfig.cmake.in"
45  "GreeterLibConfig.cmake"
46  INSTALL_DESTINATION
47  "${CMAKE_INSTALL_LIBDIR}/cmake/GreeterLib"
48)
49
50write_basic_package_version_file(
51  "GreeterLibConfigVersion.cmake"
52  VERSION ${PROJECT_VERSION}
53  COMPATIBILITY AnyNewerVersion
54)
55
56install(FILES
57  "${CMAKE_CURRENT_BINARY_DIR}/GreeterLibConfig.cmake"
58  "${CMAKE_CURRENT_BINARY_DIR}/GreeterLibConfigVersion.cmake"
59  DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/GreeterLib"
60  COMPONENT Development
61)

Step 2: Configuring CPack

Next, we need to tell CPack about our components. To make CPack's archive generators (such as ZIP) that we want them to support components, we need to enable the CPACK_ARCHIVE_COMPONENT_INSTALL flag before we include CPack.

1set(CPACK_ARCHIVE_COMPONENT_INSTALL ON)

After the include(CPack) command, we have access to the cpack_add_component() command, which we can use to tell CMake about our component:

1cpack_add_component(Development)

This command allows us to provide more information about our component, which can be helpful for more complex packaging requirements, or simply as a form of documentation.

We've added a display name and description to our Development component in our complete CMakeLists.txt file below:

1cmake_minimum_required(VERSION 3.23)
2project(Greeter VERSION 1.0)
3
4include(cmake/Coverage.cmake)
5include(cmake/Sanitize.cmake)
6include(cmake/Tidy.cmake)
7
8add_subdirectory(app)
9add_subdirectory(greeter)
10
11enable_testing()
12add_subdirectory(tests)
13
14add_subdirectory(benchmarks)
15
16set(CPACK_ARCHIVE_COMPONENT_INSTALL ON)
17
18include(CPack)
19
20cpack_add_component(Development
21  DISPLAY_NAME "The Greeter Library"
22  DESCRIPTION "Compiled Library, Header, and CMake Files"
23)

Step 3: Configuring CPack

Now, we have an easy way to tell CPack exactly what it should include in each package it generates.

Which components should be included in a package is controlled by the CPACK_COMPONENTS_ALL variable, which we can provide in our packagePreset:

1{
2  "version": 6,
3  // ... 
4  "packagePresets": [
5    // ...
6    {
7      "name": "dev-zip",
8      "displayName": "Developer Archive (ZIP)",
9      "configurePreset": "default",
10      "generators": ["ZIP"],
11      "variables": {
12        "CPACK_COMPONENTS_ALL": "Development"
13      }
14    }
15  ]
16}

Step 4: Verifying the Result

Let's run our preset to confirm our packaging still works, and that our developer package remains unchanged. From the project root:

1cmake --preset release

1cpack --build --preset release

1cpack --preset dev-zip

The resulting .zip archive will should contain the exact same install-tree for our library as before:

1Greeter-1.2.3-win64/
2├─ include/
3│  └─ greeter/
4│     └─ Greeter.h
5└─ lib/
6  ├─ Greeter.lib
7  └─ cmake/
8     └─ ...

Even though our output is currently the same, this has improved the structure and flexibility of our build. Later in the chapter, we'll take advantage of this when we create a separate package from the same project.

CPack is CMake's integrated solution for turning our build artifacts into distributable packages. It uses the install() rules we've already defined to create everything from simple archives to complex graphical installers.

• CPack Configuration: Add include(CPack) to your CMakeLists.txt and set CPACK_* variables to control package metadata and generator choice.
• Developer Packages: Use the ZIP or TGZ generator to create simple archives, perfect for sharing libraries with other developers.
• Package Presets: Use packagePresets in your CMakePresets.json to create simple, named workflows for running cpack with specific configurations.
• Components: Use the COMPONENT argument in your install() commands to group files. This allows you to generate different packages from the same project by selecting components in your package preset.