CMakeTargetsFile

Provide operations to configure binary targets using a JSON configuration file. It requires CMake 4.0.1 or newer.

Introduction

In a CMake build project, there is no native and straightforward way to separate the declaration of a binary target from its definition. Both are typically performed together when writing commands in a CMakeLists.txt file. However, in many use cases, the sequence of commands used to define targets is identical across projects, with only the data changing. The definition logic for the binary target remains the same, while only its declarations (i.e., its configuration) change.

One option could be to declare the configuration with variables in the JSON of cmake-presets, but it is not possible to have structured properties and they would be difficult to read.

The purpose of this module is to simplify the automated creation of binary targets and depdencies by allowing their settings to be declared in a standardized JSON configuration file. Thus, the build specification of a target and its usage requirements can be easily defined. The structure of this file is defined using a JSON schema. Various commands are provided to read and interpret this configuration file.

The configuration file must be named CMakeTargets.json and can reside anywhere in the project's directory.

Note

CMake is currently developing the Common Package Specification to standardize the way packages are declared and to improve their integration via the System Package Registry. It is therefore possible that this module may become obsolete in the future. In the meantime, it will continue to evolve to reflect updates introduced in upcoming versions.

Format

The CMake targets declaration file is a JSON document with an object as the root (click to download):

{
  "$schema": "schema.json",
  "$id": "schema.json",
  "externalDeps": {
    "remotes": {
      "AppleLib": {
        "rulesFile": "generic",
        "optional": false,
        "minVersion": "1.15.0",
        "integrationMethod": "FIND_THEN_FETCH",
        "packageLocation": {
          "windows": "C:/Program Files/libs/apple/1.15.0",
          "unix": "/opt/apple/1.15.0",
          "macos": "/opt/apple/1.15.0"
        },
        "downloadInfo": {
          "kind": "git",
          "repository": "https://github.com/lib/apple.git",
          "tag": "1234567"
        },
        "build": {
          "compileFeatures": ["cxx_std_20"],
          "compileDefinitions": ["DEFINE_ONE=1"],
          "compileOptions": ["-Wall"],
          "linkOptions": ["-s"]
        }
      },
      "BananaLib": {
        "rulesFile": "cmake/rules/RulesBananaLib.cmake",
        "optional": true,
        "minVersion": "4",
        "downloadInfo": {}
      },
      "CarrotLib": {
        "rulesFile": "cmake/rules/RulesCarrotLib.cmake",
        "downloadInfo": {
          "kind": "svn",
          "repository": "svn://svn.carrot.lib.org/links/trunk",
          "revision": "1234567"
        }
      },
      "OrangeLib": {
        "rulesFile": "cmake/rules/RulesOrangeLib.cmake",
        "downloadInfo": {
          "kind": "mercurial",
          "repository": "https://hg.example.com/RulesOrangeLib",
          "tag": "1234567"
        }
      },
      "PineappleLib": {
        "rulesFile": "cmake/rules/RulesPineappleLib.cmake",
        "downloadInfo": {
          "kind": "url",
          "repository": "https://example.com/PineappleLib.zip",
          "hash": "1234567"
        }
      }
    },
    "vendoredBinaries": {},
    "vendoredSources": {}
  },
  "targets": {
    "src": {
      "name": "fruit-salad",
      "type": "executable",
      "build": {
        "compileFeatures": ["cxx_std_20", "cxx_thread_local", "cxx_trailing_return_types"],
        "compileDefinitions": ["DEFINE_ONE=1", "DEFINE_TWO=2", "OPTION_1"],
        "compileOptions": ["-Wall", "-Wextra"],
        "linkOptions": ["-s", "-z"]
      },
      "mainFile": "src/main.cpp",
      "pchFile": "include/fruit_salad_pch.h",
      "headerPolicy": {
        "mode": "split",
        "includeDir": "include"
      },
      "dependencies": ["grape", "lemon", "AppleLib", "BananaLib", "CarrotLib", "OrangeLib", "PineappleLib"]
    },
    "src/grape": {
      "name": "grape",
      "type": "staticLib",
      "build": {
        "compileFeatures": [],
        "compileDefinitions": [],
        "compileOptions": [],
        "linkOptions": []
      },
      "mainFile": "src/grape/main.cpp",
      "headerPolicy": {
        "mode": "merged"
      },
      "dependencies": []
    },
    "src/lemon": {
      "name": "lemon",
      "type": "staticLib",
      "build": {
        "compileFeatures": [],
        "compileDefinitions": [],
        "compileOptions": [],
        "linkOptions": []
      },
      "mainFile": "src/lemon/main.cpp",
      "headerPolicy": {
        "mode": "merged"
      },
      "dependencies": []
    }
  }
}

The JSON document must be conformed to the CMakeTargets.json schema described below. All properties are required by default, unless explicitly marked as optional under certain conditions.

The root object recognizes the following fields:

$schema

An optional string that provides a URI to the JSON schema that describes the structure of this JSON document. This field is used for validation and autocompletion in editors that support JSON schema. It doesn't affect the behavior of the document itself. If this field is not specified, the JSON document will still be valid, but tools that use JSON schema for validation and autocompletion may not function correctly. The module does not perform schema validation automatically. Use $schema to document the schema version or to enable external validation and tooling workflows.

$id

An optional string that provides a unique identifier for the JSON document or the schema resource. The value must be a valid URI or a relative URI reference. When present, $id can be used by external tooling to disambiguate or resolve the schema/resource and to avoid collisions between different schema documents. The module stores this property but does not interpret or enforce any semantics associated with $id.

externalDeps

A required root property that defines the set of third-party dependencies whose targets are neither maintained by the project nor included in its lifecycle. It is defined by three properties whose keys correspond to the three types of dependencies: remotes, vendored sources and vendored binaries.

remotes

A required root property that defines the dependencies whose sources or binaries are not stored in the project directories. The property value is an object whose keys are the names of the dependencies. A name is intended to be used as PackageName argument to find the file 'Find<PackageName>.cmake' with find_package(). It must therefore be compatible with CMake's PackageName requirements. Each name must be unique within the CMakeTargets.json file and cannot contain a space.

Each entry of a externalDeps object is a JSON object that may contain the following properties:

rulesFile

A required property that specifies how to integrate the dependency into the build system. It can be either:

  • generic - use the predefined generic rules for integration.

  • a relative path to a .cmake file - the file must exist and contain the logic for handling the dependency.

optional

A required boolean when rulesFile is generic, otherwise optional, indicating whether the dependency is optional (true) or required (false).

minVersion

A required string when rulesFile is generic, otherwise optional, specifying the minimum acceptable version of the dependency. This value is intended to be used as the VERSION argument to find_package() calls for that dependency.

integrationMethod

A required string when rulesFile is generic, otherwise optional. It specifies the integration method to use for bringing the external dependency files. Valid values are:

packageLocation

A required object when rulesFile is generic and integrationMethod is FIND_PACKAGE or FIND_THEN_FETCH, otherwise optional. It defines the location where the dependency package can be found. These values are intended to be used to set the <PackageName>_DIR variable for find_package(). It may contain the following properties:

windows

An optional string representing an additional search path to the directory containing the package for Windows.

unix

An optional string representing an additional search path to the directory containing the package for Unix. Whitespace is not allowed.

macos

An optional string representing an additional search path to the directory containing the package for macOS. Whitespace is not allowed.

downloadInfo

A required object when rulesFile is generic and integrationMethod is FETCH_CONTENT or FIND_THEN_FETCH or EXTERNAL_PROJECT, otherwise optional. It provides the information needed to download the dependency package if it is not available locally. Theses informations are intended to be used as argument to FetchContent_Declare() or ExternalProject_Add(). It has the following properties:

kind

An required string defining the download method to use when rulesFile is generic` (otherwise optional). Valid values are url, git, svn, and mercurial. It support all download methods supported by External Project.

repository

A required URL to the repository to use when rulesFile is generic (otherwise optional).

tag

A required string defining a branch name, tag, or commit identifier to checkout when kind is git or mercurial (otherwise optional).

hash

A required string defining a hash of the file to be downloaded when kind is url (otherwise optional).

revision

A required string defining a revision to checkout when kind is svn (otherwise optional).

build

A required object when rulesFile is generic, otherwise optional, defining some additional settings applied to the dependency during building. It contains the following array properties:

compileFeatures

A list of compile features that must be enabled or disabled when compiling code that consumes the dependency. Example: ["cxx_std_20", "cxx_thread_local", "cxx_trailing_return_types"]. It is intended to be used as a parameter for the target_compile_features() command. The property is required when rulesFile is generic, otherwise optional, but the array can be empty.

compileDefinitions

A list of compile definitions that must be defined when compiling code that consumes the dependency. Example: ["DEFINE_ONE=1", "DEFINE_TWO=2", "OPTION_1"]. It is intended to be used as a parameter for the target_compile_definitions() command. The property is required when rulesFile is generic, otherwise optional, but the array can be empty.

compileOptions

A list of compiler options that must be supplied to the compiler when compiling code that consumes the dependency. Example: ["-Wall", "-Wextra", "/W4"]. It is intended to be used as a parameter for the target_compile_options() command. The property is required when rulesFile is generic, otherwise optional, but the array can be empty.

linkOptions

A list of linker options that must be enabled or disabled when linking code that consumes the dependency. Example: ["-s", "-z", "/INCREMENTAL:NO"]. It is intended to be used as a parameter for the target_link_options() command. The property is required when rulesFile is generic, otherwise optional, but the array can be empty.

vendoredBinaries

A required root property that defines the dependencies whose precompiled binaries are stored within the project directories and integrated into the project as imported targets. The property value is an object whose keys are the names of the dependencies. Each name must be unique within the CMakeTargets.json file and cannot contain a space.

vendoredSources

A required root property that defines the dependencies whose source files are stored within the project directories and must be built as part of the project. The property value is an object whose keys are the names of the dependencies. Each name must be unique within the CMakeTargets.json file and cannot contain a space.

targets

A required root property containing the set targets specific to the project and which are therefore not third-party dependencies. Its value is an object whose keys are unique directory paths that identify the parent folder containing the source files for each target. For example: src, src/grape.

Each path must be relative to the project root and must not include a trailing slash. The directory path serves as the unique identifier for the target within the file because it is assumed that there can be no more than one target defined per folder.

The value for each key is a target definition object as described in the following subsections. The key name (directory path) can be used internally to organize and retrieve target configurations during the CMake building process.

Each entry of a targets is a JSON object that may contain the following properties:

name

A required string defining the human-meaningful name of the target. This name must be unique across all targets listed in the same targets object. Two targets within the same file must not share the same name, even if their directory paths differ. The name is used to create a CMake target.

type

A required string defining the kind of binary to generate for this target. Valid values are:

  • staticLib - a static library.

  • sharedLib - a shared (dynamic) library.

  • interfaceLib - a header-only library.

  • executable - an executable program.

The type influences how the target is built and linked by the consuming CMake logic.

build

A required object describing build settings. It contains the following array properties:

compileFeatures

A list of compile features to pass to the target. Example: ["cxx_std_20", "cxx_thread_local", "cxx_trailing_return_types"]. It is intended to be used as a parameter for the target_compile_features() command. The property is required, but the array can be empty.

compileDefinitions

A list of preprocessor definitions applied when compiling this target. Example: ["DEFINE_ONE=1", "DEFINE_TWO=2", "OPTION_1"]. It is intended to be used as a parameter for the target_compile_definitions() command. The property is required, but the array can be empty.

compileOptions

A list of compiler options to pass when building this target. Example: ["-Wall", "-Wextra", "/W4"]. It is intended to be used as a parameter for the target_compile_options() command. The property is required, but the array can be empty.

linkOptions

A list of linker options to pass when building this target. Example: ["-s", "-z", "/INCREMENTAL:NO"]. It is intended to be used as a parameter for the target_link_options() command. The property is required, but the array can be empty.

All four properties must be present. Lists may be empty to indicate no entries.

mainFile

A required string defining the path to the main source file for this target. The path must be relative to the project root. The file must exist and have a .cpp, .cc, or .cxx extension.

pchFile

An optional string defining the path to the precompiled header file (PCH) for this target. The path must be relative to the project root. If present, it must have one of the following extensions: .h, .hpp, .hxx, .inl, .tpp. If not specified, the target is considered to have no PCH.

headerPolicy

A required object describing how header files are organized within the project. It has the following properties:

mode

A required string specifying whether all header files are grouped in a single common folder or whether public headers are separated from private headers. Valid values are:

  • split - public headers are stored in a different folder (e.g., include/) than private headers (e.g., src/).

  • merged - public and private headers are in the same folder (e.g., src/).

includeDir

Required only if mode is split. A path relative to the project root defining the folder in include/ where the public headers are located. The path must start with include (e.g., include, include/mylib) and must not include a trailing slash.

dependencies

An required array of third-party dependency names that this target depends on. These names must come from the externalDeps objects and other targets in targets. The array may be empty to indicate no dependencies.

Schema

This file provides a machine- readable JSON schema for the CMakeTargets.json format.

Synopsis

Loading
  cmake_targets_file(LOAD <json-file-path>)
  cmake_targets_file(IS_LOADED <output-var>)
  cmake_targets_file(GET_LOADED_FILE <output-var>)

Querying
  cmake_targets_file(HAS_CONFIG <output-var> DEP <dep-name>|TARGET <target-dir-path>)
  cmake_targets_file(GET_CONFIG_LIST <output-list-var> ALL_DEPS|REMOTE_DEPS|TARGETS)
  cmake_targets_file(GET_SETTINGS <output-map-var> DEP <dep-name>|TARGET <target-dir-path>)
  cmake_targets_file(HAS_SETTING <output-var> DEP <dep-name>|TARGET <target-dir-path> KEY <setting-name>)
  cmake_targets_file(GET_KEYS <output-list-var> DEP <dep-name>|TARGET <target-dir-path>)
  cmake_targets_file(GET_VALUE <output-var> DEP <dep-name>|TARGET <target-dir-path> KEY <setting-name>)
  cmake_targets_file(TRY_GET_VALUE <output-var> DEP <dep-name>|TARGET <target-dir-path> KEY <setting-name>)

Debugging
  cmake_targets_file(PRINT_CONFIGS [])
  cmake_targets_file(PRINT_DEP_CONFIG <dep-name>)
  cmake_targets_file(PRINT_TARGET_CONFIG <target-dir-path>)

Loading

cmake_targets_file(LOAD <json-file-path>)

Load and parses a targets configuration file in JSON schema.

The <json-file-path> specifies the location of the configuration file to load. It must refer to an existing file on disk and must have a .json extension. The file must conform to the CMakeTargets.json schema. During loading, the command verifies that the JSON file if conform to the JSON schema.

When this command is invoked, the JSON content is read into memory and stored in global properties for later retrieval. Each dependency or target entry described in the JSON file is parsed into an independent configuration Map, keyed by its directory path. Both the original raw JSON and the list of target directory paths are preserved.

The following global properties are initialized:

TARGETS_CONFIG_RAW_JSON

Contains the loaded JSON file as text.

TARGETS_CONFIG_LOADED

Set to true once the configuration is successfully loaded, otherwise to false.

TARGETS_CONFIG_REMOTE_DEPS

Holds the list of all external remote dependencies defined in the object externalDeps/remotes of the configuration file. They serve as value for <dep-name> to get the dependency configurations stored in TARGETS_CONFIG_DEP_<dep-name>.

TARGETS_CONFIG_DEP_<dep-name>

For each external dependency name in the object externalDeps of the configuration file, stores the serialized key-value Map of its parsed properties.

TARGETS_CONFIG_TARGETS

Holds the list of all target directory paths defined in the object targets of the configuration file. They serve as value for <target-dir-path> to get the target configurations stored in TARGETS_CONFIG_<target-dir-path>.

TARGETS_CONFIG_<target-dir-path>

For each target directory path in the object targets of the configuration file, stores the serialized key-value Map of its parsed properties.

This command must be called exactly once before using any other module operation. If the configuration is already loaded, calling cmake_targets_file(LOAD) again will replace the current configuration in memory.

Each dependency's and target's configurations are stored separately in a global property named TARGETS_CONFIG_DEP_<dep-name> and TARGETS_CONFIG_<target-dir-path> as a Map, where each target JSON block is represented as a flat tree list. Keys in the map are derived from the JSON property names. Nested properties are flattened by concatenating their successive parent keys, separated by a dot (.). For example, the JSON key kind of the AppleLib dependency from the sample JSON file is stored in the map as downloadInfo.kind. The list of all keys for a target's or dependency's map can be retrieved using the cmake_targets_file(GET_KEYS) command.

In this context, a setting is a key/value pair, and the set of settings for a dependency or a target represents the configuration for that dependency or target. The key of a setting is named "setting name" and its value is named "setting value".

Since CMake does not support two-dimensional arrays, and because a Map is itself a particular type of list, JSON arrays are serialized before being stored. Elements in a serialized array are separated by a pipe (|) character. For example, the JSON array ["DEFINE_ONE=1", "DEFINE_TWO=2", "OPTION_1"] become DEFINE_ONE=1|DEFINE_TWO=2|OPTION_1. And to avoid conflicts, pipe characters (|) are first escaped with a slash (\|).

Example usage:

cmake_targets_file(LOAD "${CMAKE_SOURCE_DIR}/CMakeTargets.json")
get_property(raw_json GLOBAL PROPERTY "TARGETS_CONFIG_RAW_JSON")
get_property(is_loaded GLOBAL PROPERTY "TARGETS_CONFIG_LOADED")
get_property(dep_names GLOBAL PROPERTY "TARGETS_CONFIG_REMOTE_DEPS")
get_property(apple_dep_config GLOBAL PROPERTY "TARGETS_CONFIG_DEP_AppleLib")
get_property(banana_dep_config GLOBAL PROPERTY "TARGETS_CONFIG_DEP_BananaLib")
get_property(carrot_dep_config GLOBAL PROPERTY "TARGETS_CONFIG_DEP_CarrotLib")
get_property(orange_dep_config GLOBAL PROPERTY "TARGETS_CONFIG_DEP_OrangeLib")
get_property(pineapple_dep_config GLOBAL PROPERTY "TARGETS_CONFIG_DEP_PineappleLib")
get_property(target_path_list GLOBAL PROPERTY "TARGETS_CONFIG_TARGETS")
get_property(grape_config GLOBAL PROPERTY "TARGETS_CONFIG_src/grape")
get_property(lemon_config GLOBAL PROPERTY "TARGETS_CONFIG_src/lemon")
get_property(src_config GLOBAL PROPERTY "TARGETS_CONFIG_src")
message("'src' array is: ${src_config}")
# Output:
#   'src' array is: name:fruit-salad;type:executable;mainFile:src/main.cpp;
#   dependencies:grape|lemon|AppleLib|BananaLib|CarrotLib|OrangeLib|PineappleLib;
#   pchFile:include/fruit_salad_pch.h;build.compileFeatures:cxx_std_20|
#   cxx_thread_local|cxx_trailing_return_types;build.compileDefinitions:
#   DEFINE_ONE=1|DEFINE_TWO=2|OPTION_1;build.compileOptions:-Wall|-Wextra;
#   build.linkOptions:-s|-z;headerPolicy.mode:split;...
cmake_targets_file(IS_LOADED <output-var>)

Set <output-var> to true if a targets configuration file has been loaded with success, or false otherwise. This checks the global property TARGETS_CONFIG_LOADED set by a successful invocation of the cmake_targets_file(LOAD) command.

Example usage:

cmake_targets_file(LOAD "${CMAKE_SOURCE_DIR}/CMakeTargets.json")
cmake_targets_file(IS_LOADED is_file_loaded)
message("file_loaded: ${is_file_loaded}")
# Output:
#   file_loaded: true
cmake_targets_file(GET_LOADED_FILE <output-var>)

Set <output-var> to the full JSON content of the currently loaded targets configuration file. The content is retrieved from the global property TARGETS_CONFIG_RAW_JSON, which is set by a successful invocation of the cmake_targets_file(LOAD) command.

An error is raised if no configuration file is loaded.

Example usage:

cmake_targets_file(GET_LOADED_FILE json_file_content)
message("json_file_content: ${json_file_content}")
# Output:
#   json_file_content: {
#     "$schema": "schema.json",
#     "$id": "schema.json",
#     "targets": {
#       ...
#     }
#   }

Querying

cmake_targets_file(HAS_CONFIG <output-var> DEP <dep-name>|TARGET <target-dir-path>)

Set <output-var> to true if a requested configuration exists for the given target directory path <target-dir-path> or dependency <dep-name> , or false otherwise.

Example usage :

cmake_targets_file(HAS_CONFIG is_target_configured TARGET "src")
message("is_target_configured (src): ${is_target_configured}")
# output is:
#   is_target_configured (src): true
cmake_targets_file(GET_CONFIG_LIST <output-list-var> ALL_DEPS|REMOTE_DEPS|TARGETS)

Retrieves a list of configuration entries stored in global properties and store the result in <output-list-var>.

The content of the list depends on the keyword used:

  • When ALL_DEPS or REMOTE_DEPS is specified, the command retrieves the list stored in the global property TARGETS_CONFIG_REMOTE_DEPS. The list contains dependency names that can later be used as arguments for DEP <dep-name> in commands that require it.

  • When ARGETS is specified, the command retrieves the list stored in the global property TARGETS_CONFIG_TARGETS. The list contains target directory paths that can later be used as arguments for TARGET <target-dir-path> in commands that require it.

The result is stored in <output-list-var> as a semicolon-separated list.

Example usage :

cmake_targets_file(GET_CONFIG_LIST config_indexes TARGETS)
message("config_indexes (target): ${config_indexes}")
# output is:
#   config_indexes (target): src;src/grape;src/lemon
cmake_targets_file(GET_SETTINGS <output-map-var> DEP <dep-name>|TARGET <target-dir-path>)

Retrieves the list of all settings defined for a given dependency or target configuration in the global property, respectively, TARGETS_CONFIG_DEP_<dep-name> or TARGETS_CONFIG_<target-dir-path>.

The <dep-name> specifies the name of the dependency whose configuration settings should be retrieved. This must correspond to a name returned by cmake_targets_file(GET_CONFIG_LIST), and must match one of the keys in the externalDeps/remotes JSON object of the loaded configuration file.

The <target-dir-path> specifies the directory path of the target whose configuration settings should be retrieved. This must correspond to a directory path returned by cmake_targets_file(GET_CONFIG_LIST), and must match one of the keys in the targets JSON object of the loaded configuration file.

The result is stored in <output-var> as a Map. The values are serialized, so to access a specific value, it is recommended to use the cmake_targets_file(GET_VALUE) command, which deserializes the values.

An error is raised if no configuration file has been previously loaded with the cmake_targets_file(LOAD) command or if the DEP or the TARGET does not exist in the loaded configuration file.

Example usage:

cmake_targets_file(GET_SETTINGS target_config_map TARGET "src")
message("target_config (src): ${target_config_map}")
# Output:
#   target_config (src): name:fruit-salad;type:executable;mainFile:
#   src/main.cpp;pchFile:include/fruit_salad_pch.h;...
cmake_targets_file(HAS_SETTING <output-var> DEP <dep-name>|TARGET <target-dir-path> KEY <setting-name>)

Set <output-var> to true if the configuration of the given dependency or target contains the specified setting key <setting-name>, or false otherwise.

Example usage:

cmake_targets_file(HAS_SETTING has_setting_key TARGET "src" KEY "type")
message("has_setting_key (type): ${has_setting_key}")
# Output:
#   has_setting_key (type): true
cmake_targets_file(GET_KEYS <output-list-var> DEP <dep-name>|TARGET <target-dir-path>)

Retrieves the list of all setting keys defined for a given dependency or target configuration in the global property, respectively, TARGETS_CONFIG_DEP_<dep-name> or TARGETS_CONFIG_<target-dir-path>.

The <dep-name> specifies the name of the dependency whose configuration settings should be retrieved. This must correspond to a name returned by cmake_targets_file(GET_CONFIG_LIST), and must match one of the keys in the externalDeps/remotes JSON object of the loaded configuration file.

The <target-dir-path> specifies the directory path of the target whose configuration settings should be retrieved. This must correspond to a directory path returned by cmake_targets_file(GET_CONFIG_LIST), and must match one of the keys in the targets JSON object of the loaded configuration file.

The result is stored in output-list-var> as a semicolon-separated list.

An error is raised if no configuration file has been previously loaded with the cmake_targets_file(LOAD) command or if the DEP or the TARGET does not exist in the loaded configuration file.

Example usage:

cmake_targets_file(GET_KEYS setting_keys TARGET "src")
message("setting_keys: ${setting_keys}")
# With the JSON example above, output is:
#   setting_keys: name;type;mainFile;pchFile;build.compileFeatures;build.
#   compileDefinitions;build.compileOptions;build.linkOptions;headerPolicy.
#   mode;headerPolicy.includeDir...
cmake_targets_file(GET_VALUE <output-var> DEP <dep-name>|TARGET <target-dir-path> KEY <setting-name>)

Retrieves the value associated to a specific setting key <setting-name> defined for a given dependency or target configuration in the global property , respectively, TARGETS_CONFIG_DEP_<dep-name> or TARGETS_CONFIG_<target-dir-path>.

The <dep-name> specifies the name of the dependency whose configuration settings should be retrieved. This must correspond to a name returned by cmake_targets_file(GET_CONFIG_LIST), and must match one of the keys in the externalDeps/remotes JSON object of the loaded configuration file.

The <target-dir-path> specifies the directory path of the target whose configuration settings should be retrieved. This must correspond to a directory path returned by cmake_targets_file(GET_CONFIG_LIST), and must match one of the keys in the targets JSON object of the loaded configuration file.

The <setting-name> specifies the flattened key name as stored in the Map TARGETS_CONFIG_DEP_<dep-name> or TARGETS_CONFIG_<target-dir-path>. Nested JSON properties are concatenated using a dot (.) separator (e.g., build.compileDefinitions).

The result is stored in <output-var> as a value or a deserialized list.

An error is raised if no configuration file has been previously loaded with the cmake_targets_file(LOAD) command or if the DEP or the TARGET does not exist in the loaded configuration file or if the KEY does not exist in the target configuration.

Example usage:

cmake_targets_file(GET_VALUE setting_value TARGET "src" KEY "type")
message("setting_value (type): ${setting_value}")
# Output:
#   setting_value (type): executable
cmake_targets_file(GET_VALUE setting_value TARGET "src" KEY "build.compileDefinitions")
message("setting_value (build.compileDefinitions): ${setting_value}")
# Output:
#   setting_value (build.compileDefinitions): DEFINE_ONE=1;DEFINE_TWO=2;
#   OPTION_1
cmake_targets_file(GET_VALUE setting_value TARGET "src" KEY "dependencies")
message("setting_value (dependencies): ${setting_value}")
# Output:
#   setting_value (dependencies): grape;lemon;AppleLib;BananaLib;CarrotLib;
#   OrangeLib;PineappleLib
cmake_targets_file(TRY_GET_VALUE <output-var> DEP <dep-name>|TARGET <target-dir-path> KEY <setting-name>)

Try to retrieve the value associated to a specific setting key <setting-name> defined for a given target configuration in the global property, respectively, TARGETS_CONFIG_DEP_<dep-name> or TARGETS_CONFIG_<target-dir-path>. Contrary to cmake_targets_file(GET_VALUE), no error is raised if the KEY does not exist in the configuration.

The <dep-name> specifies the name of the dependency whose configuration settings should be retrieved. This must correspond to a name returned by cmake_targets_file(GET_CONFIG_LIST), and must match one of the keys in the externalDeps/remotes JSON object of the loaded configuration file.

The <target-dir-path> specifies the directory path of the target whose configuration settings should be retrieved. This must correspond to a directory path returned by cmake_targets_file(GET_CONFIG_LIST), and must match one of the keys in the targets JSON object of the loaded configuration file.

The <setting-name> specifies the flattened key name as stored in the Map TARGETS_CONFIG_DEP_<dep-name> or TARGETS_CONFIG_<target-dir-path>. Nested JSON properties are concatenated using a dot (.) separator (e.g., build.compileDefinitions).

The result is stored in <output-var> as a value or a deserialized list. If the KEY does not exist in the target configuration, <output-var> is set to <setting-name>-NOTFOUND.

An error is raised if no configuration file has been previously loaded with the cmake_targets_file(LOAD) command or if the DEP or the TARGET does not exist in the loaded configuration file.

Example usage:

cmake_targets_file(TRY_GET_VALUE setting_value TARGET "src" KEY "type")
message("setting_value (type): ${setting_value}")
# Output:
#   setting_value (type): executable
cmake_targets_file(TRY_GET_VALUE setting_value TARGET "src" KEY "build.compileDefinitions")
message("setting_value (build.compileDefinitions): ${setting_value}")
# Output:
#   setting_value (build.compileDefinitions): DEFINE_ONE=1;DEFINE_TWO=2;
#   OPTION_1
cmake_targets_file(TRY_GET_VALUE setting_value TARGET "src" KEY "dependencies")
message("setting_value (dependencies): ${setting_value}")
# Output:
#   setting_value (dependencies): grape;lemon;AppleLib;BananaLib;CarrotLib;
#   OrangeLib;PineappleLib
cmake_targets_file(TRY_GET_VALUE setting_value TARGET "src" KEY "nonexistent.setting")
message("setting_value (nonexistent.setting): ${setting_value}")
# Output:
#   setting_value (nonexistent.setting): nonexistent.setting-NOTFOUND

Debugging

Prints the configuration of all targets defined in the currently loaded configuration file. It is primarily intended for debugging or inspecting the parsed target settings after loading a configuration file.

An error is raised if no configuration file has been previously loaded with the cmake_targets_file(LOAD) command

Example usage:

cmake_targets_file(PRINT_CONFIGS)
# Output:
#   -- Target: fruit-salad
#   --   type: executable
#   --   build.compileFeatures: cxx_std_20|cxx_thread_local|cxx_trailing_return_types
#   --   build.compileDefinitions: DEFINE_ONE=1|DEFINE_TWO=2|OPTION_1
#   --   build.compileOptions: -Wall|-Wextra
#   --   build.linkOptions: -s|-z
#   --   mainFile: src/main.cpp
#   --   pchFile: include/fruit_salad_pch.h
#   ...

Prints the configuration of a given dependency configuration in the global property TARGETS_CONFIG_DEP_<dep-name>. It is primarily intended for debugging or inspecting a parsed target settings after loading a configuration file.

The <dep-name> specifies the name of the dependency whose configuration settings should be retrieved. This must correspond to a name returned by cmake_targets_file(GET_CONFIG_LIST), and must match one of the keys in the externalDeps/remotes JSON object of the loaded configuration file.

An error is raised if no configuration file has been previously loaded with the cmake_targets_file(LOAD) command or if the DEP does not exist in the loaded configuration file.

Example usage:

cmake_targets_file(PRINT_DEP_CONFIG "AppleLib")
# Output:
#   -- Dependency: AppleLib
#   --   rulesFile: generic
#   --   optional: OFF
#   --   minVersion: 1.15.0
#   --   integrationMethod: FIND_THEN_FETCH
#   --   packageLocation.windows: C:/Program Files/libs/apple/1.15.0
#   --   packageLocation.unix: /opt/apple/1.15.0
#   --   packageLocation.macos: /opt/apple/1.15.0
#   --   downloadInfo.kind: git
#   --   downloadInfo.repository: https://github.com/lib/apple.git
#   --   downloadInfo.tag: 1234567
#   --   build.compileFeatures: cxx_std_20
#   --   build.compileDefinitions: DEFINE_ONE=1
#   --   build.compileOptions: -Wall
#   --   build.linkOptions: -s

Prints the configuration of a given target configuration in the global property TARGETS_CONFIG_<target-dir-path>. It is primarily intended for debugging or inspecting a parsed target settings after loading a configuration file.

The <target-dir-path> specifies the directory path of the target whose configuration settings should be retrieved. This must correspond to a directory path returned by cmake_targets_file(GET_CONFIG_LIST), and must match one of the keys in the targets JSON object of the loaded configuration file.

An error is raised if no configuration file has been previously loaded with the cmake_targets_file(LOAD) command.

Example usage:

cmake_targets_file(PRINT_TARGET_CONFIG "src")
# Output:
#   -- Target: fruit-salad
#   --   type: executable
#   --   build.compileFeatures: cxx_std_20|cxx_thread_local|cxx_trailing_return_types
#   --   build.compileDefinitions: DEFINE_ONE=1|DEFINE_TWO=2|OPTION_1
#   --   build.compileOptions: -Wall|-Wextra
#   --   build.linkOptions: -s|-z
#   --   mainFile: src/main.cpp
#   --   pchFile: include/fruit_salad_pch.h
#   ...