Creating Installers with CPack and GitHub Actions

Let's cover a more complex scenario where our executable has runtime dependencies - .dll files on Windows. This means the installer must include not only GreeterApp.exe but also all the .dll files it depends on.

Depending on our preferred configuration, this might include external dependencies like spdlog.dll and fmt.dll, or internal dependencies such as our own GreeterLib being compiled as a .dll.

To test this, we'll switch back to using our release configuration preset on all platforms:

1name: C++ CI
2
3on:
4  pull_request:
5    branches: ["main"]
6
7jobs:
8  build-and-test:
9    strategy:
10      matrix:
11        os: [ubuntu-latest, windows-latest, macos-latest]
12    runs-on: ${{ matrix.os }}
13    steps:
14      - name: Check out code
15        uses: actions/checkout@v4
16
17      - name: Set up vcpkg
18        uses: lukka/run-vcpkg@v11
19
20      - name: Configure CMake
21        run: cmake --preset release
22
23      - name: Build project
24        run: cmake --build --preset release
25
26      - name: Run tests
27        run: ctest --preset release
28
29      - name: Package Development
30        run: cpack --preset dev-zip
31
32      - name: Upload Development Package Artifact
33        uses: actions/upload-artifact@v4
34        with:
35          name: Greeter-Development-${{ matrix.os }}
36          path: build/Greeter-*-Development.zip
37
38      - name: Package Application
39        if: matrix.os == 'windows-latest'
40        run: cpack --preset windows-release-installer
41
42      - name: Upload Application Package Artifact
43        if: matrix.os == 'windows-latest'
44        uses: actions/upload-artifact@v4
45        with:
46          name: Greeter-Installer-${{ matrix.os }}
47          path: build/Greeter-*.msi

By default, vcpkg builds our dependencies as shared libraries (.dll files) so our executable will now have runtime dependencies. For this project, those are the spdlog and fmt libraries.

Installing Runtime Dependencies

The most direct way of installing our runtime dependencies is simple install(FILES ...) commands. We simply provide the path to our dependencies. For dependencies managed by vcpkg, there are some variables that can help us track them down:

1install(FILES
2  "${VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/bin/libfmt.dll"
3  "${VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/bin/libspdlog.dll"
4  DESTINATION ${CMAKE_INSTALL_BINDIR}
5  COMPONENT Application
6)

This would work, but only on Windows, and only for release configurations. We could do more work to make this portable, however, CMake 3.21 introduced the RUNTIME_DEPENDENCIES keyword to the install() command to make this problem slightly easier to solve.

Using RUNTIME_DEPENDENCIES

The following example would install all runtime dependencies of SomeTarget into the binary directory, and assign them to the Application component:

1install(
2  TARGETS SomeTarget
3  RUNTIME_DEPENDENCIES
4  DESTINATION ${CMAKE_INSTALL_BINDIR}
5  COMPONENT Application
6)

However, in most real-world scenarios, this command tries to install too many things. Our programs will typically rely on dependencies provided by the platform itself, such as DLL files that are included with Windows. We don't want those to be included in our package, so we need to filter this list.

Filtering RUNTIME_DEPENDENCIES

To filter the list of dependencies we want to install, the install() command provides a few options. The most useful tend to be PRE_EXCLUDE_REGEXES and PRE_INCLUDE_REGEXES. These allow us to provide regular expressions for files that we want to be excluded or included in our installation command.

In the following example, we exclude everything by default using the .* expression, and then include only dependencies that have fmt or spdlog in their name using .*fmt.* and .*spdlog.*:

1cmake_minimum_required(VERSION 3.23)
2
3add_library(GreeterAppLogic src/run.cpp)
4find_package(spdlog CONFIG REQUIRED)
5
6target_link_libraries(GreeterAppLogic PRIVATE
7  GreeterLib
8  spdlog::spdlog
9)
10
11target_sources(GreeterAppLogic PUBLIC
12  FILE_SET HEADERS
13  BASE_DIRS "include"
14  FILES "include/app/run.h"
15)
16
17add_executable(GreeterApp src/main.cpp)
18target_link_libraries(GreeterApp PRIVATE GreeterAppLogic)
19
20include(GNUInstallDirs)
21install(
22  TARGETS GreeterApp
23  DESTINATION ${CMAKE_INSTALL_BINDIR}
24  COMPONENT Application
25)
26
27install(
28  TARGETS GreeterApp
29  RUNTIME_DEPENDENCIES
30  PRE_INCLUDE_REGEXES ".*fmt.*" ".*spdlog.*"
31  PRE_EXCLUDE_REGEXES ".*"
32  DESTINATION ${CMAKE_INSTALL_BINDIR}
33  COMPONENT Application
34)

We would expand this list as we add more dependencies or, alternatively, change our approach where we include everything by default, and then specify only what we want to exclude.

Installing Internal Libraries

For internal runtime dependencies, such as our GreeterLib, we install those using regular install(TARGETS ...) commands:

1install(
2  TARGETS MyLibrary
3  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
4    COMPONENT Application
5)

Our GreeterLib's RUNTIME files are already being installed to the binary directory and assigned to the Development component. To include them with our installer, we just need to add them to the Application component and then build with BUILD_SHARED_LIBS enabled:

1# ...
2
3install(
4  TARGETS GreeterLib
5  EXPORT GreeterLibTargets
6  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
7    COMPONENT Development
8  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
9    COMPONENT Development
10  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
11    COMPONENT Development
12    COMPONENT Application 
13  FILE_SET HEADERS DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
14    COMPONENT Development
15)
16
17# ...

To build our target as a runtime dependency rather than a static library, we set the BUILD_SHARED_LIBS cache variable to "ON":

1{
2  "version": 6,
3  "configurePresets": [
4     // ...
5  {
6    "name": "shared-internal-libs",
7    "inherits": "release",
8    "cacheVariables": {
9      "BUILD_SHARED_LIBS": "ON"
10    }
11  }],
12  // ...
13}

To create a valid MSI installer, our program needs a Globally Unique Identifier (GUID). This GUID is what Windows uses to track the installed product, manage updates, and handle uninstalls.

Every product must have a GUID but, if we don't provide one, WiX will automatically generate one at build time. However, this GUID will be different on every build. This makes it impossible for Windows to realise that the installers generated from two different builds are actually for the same application.

To address this, we should specify an exact GUID for our program and consistently use it. We can generate a GUID using command-line utilities (uuidgen on Linux/macOS, [guid]::NewGuid() in PowerShell) or an online tool like uuidgenerator.net.

Once you have a GUID, you set it in your root CMakeLists.txt using the CPACK_WIX_UPGRADE_GUID variable. This must be done before the include(CPack) command:

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)
13add_subdirectory(benchmarks)
14
15set(CPACK_ARCHIVE_COMPONENT_INSTALL ON)
16set(CPACK_WIX_UPGRADE_GUID "c8288165-c0b1-4c9a-ba61-877175be0b5a")
17include(CPack)
18
19cpack_add_component(Development
20  DISPLAY_NAME "The Greeter Library"
21  DESCRIPTION "Compiled Library, Header Files, and CMake Configuration Files"
22)
23
24cpack_add_component(Application
25  DISPLAY_NAME "The Greeter Application"
26  DESCRIPTION "An application that says hello to the user"
27)

If we generate two different installers, they will now use this same GUID. If we install our program using one of the installers, and then run the second, Windows will understand that both are for the same underlying program.

Rather than treating the second installer as a separate program, it will now present options for the user to upgrade, repair, or uninstall what they already have:

Our installer now correctly bundles the executable and its required DLLs. However, installers can contain multiple components, and present users with options on which they want to install, uninstall, or upgrade.

Let's replicate this by imagining we have a simple Documentation.pdf file in our project root that explains how to use our program.

We set the install rules and configure the component in the usual way:

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)
13add_subdirectory(benchmarks)
14
15set(CPACK_ARCHIVE_COMPONENT_INSTALL ON)
16set(CPACK_WIX_UPGRADE_GUID "c8288165-c0b1-4c9a-ba61-877175be0b5a")
17include(CPack)
18
19cpack_add_component(Development
20  DISPLAY_NAME "The Greeter Library"
21  DESCRIPTION "Compiled Library, Header Files, and CMake Configuration Files"
22)
23
24cpack_add_component(Application
25  DISPLAY_NAME "The Greeter Application"
26  DESCRIPTION "An application that says hello to the user"
27)
28
29install(FILES
30  ${CMAKE_SOURCE_DIR}/Documentation.pdf
31  DESTINATION "docs"
32  COMPONENT Documentation
33)
34
35cpack_add_component(Documentation
36  DISPLAY_NAME "Greeter Documentation"
37  DESCRIPTION "A PDF file explaining how to use the application"
38)

Finally, we'll update our package preset to include both components:

1{
2  "version": 6,
3  // ...
4  
5  "packagePresets": [
6    // ...
7    {
8      "name": "windows-release-installer",
9      "displayName": "Windows Installer (MSI)",
10      "inherits": "default",
11      "generators": ["WIX"],
12      "variables": {
13        "CPACK_COMPONENTS_ALL": "Application" 
14        "CPACK_COMPONENTS_ALL": "Application;Documentation" 
15      }
16    }
17  ]
18}

Now, when a user runs the installer, they will see a feature tree where they can inspect the different parts of the installation:

This technique is particularly useful when used with components that are downloaded on-demand. This means users don't download a massive installer containing components they may not want. Instead, we ship a lightweight installer which downloads components on demand based on what users select within the UI. We won't cover this here, as it requires fairly advanced setup, as well as setting up a web server to host our downloads.

When using WiX, this can be implemented using Burn bundles, and the CPack module we're using provides a friendlier front end based around the cpack_configure_downloads() command documented here.

The cpack_add_component() command offers further options to control how our components are presented, and how they interact with each other.

We can state that one component depends on another component using the DEPENDS keyword:

1cpack_add_component(Application
2  DISPLAY_NAME "The Greeter Application"
3  DESCRIPTION "An application that says hello to the user"
4  DEPENDS RuntimeDependencies
5)
6
7cpack_add_component(RuntimeDependencies
8  DISPLAY_NAME "The Runtime Dependencies"
9  DESCRIPTION "DLLs and other files that are required for the application"
10)

By default, the installer will assume the user wants to install all of our components. The easiest way to change that is by setting components to DISABLED, meaning they will initially be deselected:

1cpack_add_component(OptionalStuff
2  DISPLAY_NAME "Optional Stuff"
3  DESCRIPTION "You probably dont want this"
4  DISABLED 
5)

We can set a component as REQUIRED, meaning it must be installed and cannot be deselected:

1cpack_add_component(Application
2  DISPLAY_NAME "The Greeter Application"
3  DESCRIPTION "An application that says hello to the user"
4  REQUIRED 
5  DEPENDS RuntimeDependencies
6)

Finally, we can set a component as HIDDEN. This effectively removes the component from the visible options, but still includes it in the installation (assuming it's not also DISABLED):

1# Everyone needs this and they don't need to know it exists
2# So we just mark it as REQUIRED and HIDDEN
3cpack_add_component(RuntimeDependencies
4  DISPLAY_NAME "The Runtime Dependencies"
5  DESCRIPTION "DLLs and other files that are required for the application"
6  REQUIRED HIDDEN 
7)

To further improve the user experience, we can group related components together. Let's create a SupportingFiles group for our docs, and other ancillary components we might need in the future.

We do this using the cpack_add_component_group() command. Groups can also be nested inside other groups by setting the PARENT_GROUP within this command.

We assign components to a group using the GROUP argument of their cpack_add_component() command or, alternatively, setting CPACK_COMPONENT_<Name>_GROUP:

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)
13add_subdirectory(benchmarks)
14
15set(CPACK_ARCHIVE_COMPONENT_INSTALL ON)
16set(CPACK_WIX_UPGRADE_GUID "c8288165-c0b1-4c9a-ba61-877175be0b5a")
17include(CPack)
18
19cpack_add_component(Development
20  DISPLAY_NAME "The Greeter Library"
21  DESCRIPTION "Compiled Library, Header Files, and CMake Configuration Files"
22)
23
24cpack_add_component(Application
25  DISPLAY_NAME "The Greeter Application"
26  DESCRIPTION "An application that says hello to the user"
27)
28
29install(FILES
30  ${CMAKE_SOURCE_DIR}/Documentation.pdf
31  DESTINATION "docs"
32  COMPONENT Documentation
33)
34
35cpack_add_component_group(SupportingFiles 
36  DISPLAY_NAME "Supporting Files" 
37  DESCRIPTION "Additional optional content" 
38  PARENT_GROUP "" # Top-level group 
39  EXPANDED # Expanded by default in the installer UI 
40)
41
42cpack_add_component(Documentation
43  DISPLAY_NAME "Greeter Documentation"
44  DESCRIPTION "A PDF file explaining how to use the application"
45  GROUP SupportingFiles 
46)
47
48# Alternatively:
49set(CPACK_COMPONENT_Documentation_GROUP SupportingFiles)

This change results in a more organized feature selection screen in the installer, which is especially helpful for large applications with many optional components.

Most of what we've configured so far, such as our cpack_add_component() and cpack_add_component_group() comments, have been generic settings that are compatible across a wide range of package types. If we were to switch our generator to NSIS, an alternative to WIX, our component configuration would work there, too.

However, CPack includes further, more specific settings for each individual generator. These generators, and how we can use them, are listed on the official docs.

The .zip packages we were using earlier were created using the Archive generator, and the installer we created in this lesson is using the WiX generator.

Behind the scenes, WiX installers are hugely customizable. The WiX documentation lists all the possibilities. CPack's WiX generator offers a front-end to this, allowing us to customize things by setting CMake variables.

For example, let's modify the license that is shown by default in the installation steps. This licence can be styled and exported in the rich text format (.rtf) supported by most document editors:

1{\rtf1\ansi\deff0
2{\fonttbl{\f0 Arial;}}
3{\colortbl;\red0\green0\blue0;}
4\pard
5\f0\fs28\b Sample License\par
6\fs20 This is a sample license file.\par
7\i You agree to all terms and conditions by installing this software.\i0\par
8}

To have WiX use this file, we set the CPACK_WIX_LICENSE_RTF variable:

1# ...
2set(CPACK_ARCHIVE_COMPONENT_INSTALL ON)
3set(CPACK_WIX_UPGRADE_GUID "c8288165-c0b1-4c9a-ba61-877175be0b5a")
4set(CPACK_WIX_LICENSE_RTF "${CMAKE_SOURCE_DIR}/license.rtf")
5include(CPack)
6# ...

There are many more variables we can set, controlling things like the images shown in the installer (CPACK_WIX_UI_BANNER and CPACK_WIX_UI_DIALOG) as well as the icon we want to use for our program (CPACK_WIX_PRODUCT_ICON).

The generator's official docs list all the possibilities.

In this lesson, we've gone beyond simple archives to create user-friendly installer, and we've automated its creation in our CI pipeline.

• The WiX Toolset: CPack's WIX generator is a front-end for the WiX Toolset, which builds .msi installers.
• Handling Dependencies: We saw how to create a self-contained executable with static linking and, more importantly, how to use install(RUNTIME_DEPENDENCIES) to automatically bundle all required .dll files for a shared library build.
• CI Automation: We used a matrix strategy in GitHub Actions to build our installer exclusively on the Windows runner, demonstrating how to handle platform-specific packaging in a multi-platform workflow.
• Components and Groups: We used CPack components to group installed files, allowing us to create different packages from the same project and to provide a structured feature selection UI for the user.
• Customizing Installers: We introduced how to customize an installer through CPack's generators, which act as a front-end to the underlying tool.