kmpkg in CMake projects

kmpkg offers seamless integration with CMake to make installed packages available in your projects automatically. The mechanism in which kmpkg integrates is by providing a CMake toolchain file.

The first time CMake configures a project, it runs internal search routines to locate a viable toolchain (compiler, linker, etc.). This search happens within the project() function in your CMakeLists.txt.

To customize the toolchain selection process, CMake supports using custom CMake-language scripts, known as toolchain files. A toolchain file is specified by setting the CMAKE_TOOLCHAIN_FILE variable. CMake evaluates the contents of the provided toolchain script and sets variable definitions, paths to required build tools, and other build parameters, such as cross-compilation flags, accordingly.

When you set CMAKE_TOOLCHAIN_FILE to use the kmpkg toolchain (<kmpkg-root>/scripts/buildsystems/kmpkg.cmake), kmpkg takes advantage of the toolchain file mechanism to inject code to integrate with built-in CMake functions transparently to you.

You can still use a toolchain file to configure your own toolsets by using the KMPKG_CHAINLOAD_TOOLCHAIN_FILE triplet variable.

The kmpkg integration works differently depending on the operation mode you're using:

In classic mode, kmpkg sets CMake search paths appropriately to make installed packages available via the find_package(), find_library(), and find_path() functions.

In manifest mode, in addition to the above, the toolchain detects manifest files (kmpkg.json files) and runs kmpkg install to automatically acquire the project's dependencies.

Because the toolchain file is evaluated during the project() call, all CMake-level variables that modify a kmpkg setting must be set before the first call to project(). It may also be necessary to reconfigure your CMake project if you modify any kmpkg setting that results in ABI hash changes.

See Installing and Using Packages Example: sqlite for a fully worked example using CMake.

CMAKE_TOOLCHAIN_FILE

info

If you set CMAKE_TOOLCHAIN_FILE in your CMakeList.txt file, make sure that the variable is set before any calls to project().

Projects configured to use the kmpkg toolchain file (via the CMake setting CMAKE_TOOLCHAIN_FILE) can find libraries from kmpkg using the standard CMake functions: find_package(), find_path(), and find_library().

We recommend using CMake Presets to specify your toolchain file. For example, if you have defined the environment variable KMPKG_ROOT, you can use the following CMakePresets.json and pass --preset debug on the configure line:

CMakePresets.json

{
  "version": 3,
  "configurePresets": [
    {
      "name": "debug",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{KMPKG_ROOT}/scripts/buildsystems/kmpkg.cmake"
      }
    }
  ]
}

cmake -B build -S /my/project --preset debug

If you need to use an absolute path for kmpkg specific to your current machine, you can use CMakeUserPresets.json and add it to your .gitignore file.

CMakeUserPresets.json

{
  "version": 2,
  "configurePresets": [
    {
      "name": "default",
      "inherits": "debug",
      "environment": {
        "KMPKG_ROOT": "<path to kmpkg>"
      }
    }
  ]
}

CMake versions older than 3.19 must pass the toolchain file on the configure command line:

cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=<kmpkg-root>/scripts/buildsystems/kmpkg.cmake

Using Libraries

kmpkg supports CMake's native mechanisms for finding libraries: find_package(), find_library(), and find_path(). When installing libraries with specific CMake support, kmpkg will display usage information on how to consume the library:

The package zlib is compatible with built-in CMake targets:

    find_package(ZLIB REQUIRED)
    target_link_libraries(main PRIVATE ZLIB::ZLIB)

kmpkg does not automatically add any include or links paths into your project. To use a header-only library you can use find_path() which will correctly work on all platforms:

# To find and use catch2
find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
target_include_directories(main PRIVATE ${CATCH_INCLUDE_DIR})

IDE Integration

CLion

Open the Toolchains settings (File > Settings on Windows and Linux, CLion > Preferences on macOS), and go to the CMake settings (Build, Execution, Deployment > CMake). In CMake options, add the following line:

-DCMAKE_TOOLCHAIN_FILE=<kmpkg-root>/scripts/buildsystems/kmpkg.cmake

You must add this line to each profile separately.

Using Multiple Toolchain Files

To combine kmpkg's toolchain file with another toolchain file, you can set the CMake cache variable KMPKG_CHAINLOAD_TOOLCHAIN_FILE:

cmake ../my/project \
   -DCMAKE_TOOLCHAIN_FILE=C:/kmpkg/scripts/buildsystems/kmpkg.cmake \
   -DKMPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/toolchain.cmake

Alternatively, you can include the kmpkg toolchain at the end of the primary toolchain file:

# MyToolchain.cmake
set(CMAKE_CXX_COMPILER ...)
set(KMPKG_TARGET_TRIPLET x64-my-custom-windows-triplet)
include(/path/to/kmpkg/scripts/buildsystems/kmpkg.cmake)

info

kmpkg does not automatically apply your toolchain's settings, such as your compiler or compilation flags, while building libraries. To change kmpkg's library settings, you must make a custom triplet file (which can share your toolchain)**

Settings Reference

All kmpkg-affecting variables must be defined before the first project() directive such as in a CMakePresets.json's "cacheVariables" map, via the command line, or set() statements.

KMPKG_TARGET_TRIPLET

This setting controls the triplet kmpkg will install and consume libraries from.

If unset, kmpkg will automatically detect an appropriate default triplet given the current compiler settings. If you change this CMake variable, you must delete your cache and reconfigure.

KMPKG_HOST_TRIPLET

This variable controls which triplet host dependencies will be installed for.

If unset, kmpkg will automatically detect an appropriate native triplet (x64-windows, x64-osx, x64-linux).

See also Host dependencies.

KMPKG_INSTALLED_DIR

This variable sets the location where libraries will be installed and consumed from.

In manifest mode, the default is ${CMAKE_BINARY_DIR}/kmpkg_installed.

In classic mode, the default is ${KMPKG_ROOT}/installed.

KMPKG_MANIFEST_MODE

This variable forces kmpkg to operate in either manifest mode or classic mode.

Defaults to ON when KMPKG_MANIFEST_DIR is non-empty or ${CMAKE_SOURCE_DIR}/kmpkg.json exists.

To disable manifest mode while a kmpkg.json is detected, set this to OFF.

KMPKG_MANIFEST_DIR

This variable specifies an alternate folder containing a kmpkg.json manifest.

Defaults to ${CMAKE_SOURCE_DIR} if ${CMAKE_SOURCE_DIR}/kmpkg.json exists.

KMPKG_MANIFEST_INSTALL

This variable controls whether kmpkg will be automatically run to install your dependencies during your configure step.

Defaults to ON if KMPKG_MANIFEST_MODE is ON.

KMPKG_BOOTSTRAP_OPTIONS

This variable can be set to additional command parameters to pass to ./bootstrap-kmpkg.

In manifest mode, kmpkg will be automatically bootstrapped if the executable does not exist.

KMPKG_OVERLAY_TRIPLETS

This variable can be set to a list of paths to be passed on the command line as --overlay-triplets=...

KMPKG_OVERLAY_PORTS

This variable can be set to a list of paths to be passed on the command line as --overlay-ports=...

KMPKG_MANIFEST_FEATURES

This variable can be set to a list of features to activate when installing from your manifest.

For example, features can be used by projects to control building with additional dependencies to enable tests or samples:

{
  "name": "mylibrary",
  "version": "1.0",
  "dependencies": [ "curl" ],
  "features": {
    "samples": {
      "description": "Build Samples",
      "dependencies": [ "fltk" ]
    },
    "tests": {
      "description": "Build Tests",
      "dependencies": [ "gtest" ]
    }
  }
}

This setting can be controlled directly by CMake Presets with "cacheVariables" or indirectly based on other settings:

# CMakeLists.txt

option(BUILD_TESTING "Build tests" OFF)
if(BUILD_TESTING)
  list(APPEND KMPKG_MANIFEST_FEATURES "tests")
endif()

option(BUILD_SAMPLES "Build samples" OFF)
if(BUILD_SAMPLES)
  list(APPEND KMPKG_MANIFEST_FEATURES "samples")
endif()

project(myapp)

# ...

KMPKG_MANIFEST_NO_DEFAULT_FEATURES

This variable controls activation of default features in addition to those listed in KMPKG_MANIFEST_FEATURES. If set to ON, default features will not be automatically activated.

Defaults to OFF.

KMPKG_INSTALL_OPTIONS

This variable can be set to a list of additional command line parameters to pass to the kmpkg tool during automatic installation.

KMPKG_PREFER_SYSTEM_LIBS

warning

This feature has been deprecated. Use empty overlay ports instead.

This variable controls whether kmpkg will append instead of prepend its paths to CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH and CMAKE_FIND_ROOT_PATH so that kmpkg libraries/packages are found after toolchain/system libraries/packages.

Defaults to OFF.

KMPKG_FEATURE_FLAGS

This variable can be set to a list of feature flags to pass to the kmpkg tool during automatic installation to opt-in to experimental behavior.

See the --feature-flags= command line option for more information.

KMPKG_TRACE_FIND_PACKAGE

When set to ON, Print every call to find_package. Nested calls (e.g. via find_dependency) are indented according to nesting depth.

KMPKG_LOCK_FIND_PACKAGE_<Pkg>

When this option is set, non-nested calls to find_package are either required (KMPKG_LOCK_FIND_PACKAGE_<Pkg>=ON) or disabled (KMPKG_LOCK_FIND_PACKAGE_<Pkg>=OFF).

This variable is a tool to control direct dependencies and related features in kmpkg ports which use the CMake build system. It can be used with kmpkg_check_features and avoids unintended effects on transitive dependencies.