# load_cache

Load in the values from another project's `CMakeCache.txt` cache file. This is useful for projects that depend on another project built in a separate directory tree.

This command has two signatures. The recommended signature is:

load_cache(<build-dir> READ_WITH_PREFIX <prefix> <entry>...)

  Loads the cache file from the specified `<build-dir>` build directory and retrieves the listed cache entries. The retrieved values are stored in local variables, with their names prefixed by the provided `<prefix>`. This only reads the cache values; it does not create or modify entries in the local project's cache.

  `READ_WITH_PREFIX <prefix>`

    For each cache `<entry>`, a local variable is created using the specified `<prefix>` followed by the entry name.

  This signature can be also used in `cmake -P` script mode.

The following signature of this command is strongly discouraged, but it is provided for backward compatibility:

load_cache(<build-dir> [EXCLUDE <entry>...] [INCLUDE_INTERNALS <entry>...])

  This form loads the cache file from the specified `<build-dir>` build directory and imports all its non-internal cache entries into the local project's cache as internal cache variables. By default, only non-internal entries are imported, unless the `INCLUDE_INTERNALS` option is used.

  The options are:

  `EXCLUDE <entry>...`

    This option can be used to exclude a given list of non-internal cache entries when importing values.

  `INCLUDE_INTERNALS <entry>...`

    This option can be used to provide a list of internal cache entries to include in addition to the non-internal cache entries.

  This signature can be used only in CMake projects. Script mode is not supported.

Note

Instead of loading the outside project's cache file and manually accessing variables, a more robust and convenient approach is to use the `export()` command in the outside project, when available. This allows the project to provide its targets, configuration, or features in a structured and maintainable way, making integration simpler and less error-prone.

## Examples

Reading specific cache variables from another project and storing them as local variables:

    load_cache(
      path/to/other-project/build-dir
      READ_WITH_PREFIX prefix_
      OTHER_PROJECT_CACHE_VAR_1
      OTHER_PROJECT_CACHE_VAR_2
    )

    message(STATUS "${prefix_OTHER_PROJECT_CACHE_VAR_1")
    message(STATUS "${prefix_OTHER_PROJECT_CACHE_VAR_2")
    # Outputs:
    # -- some-value...
    # -- another-value...

Reading all non-internal cache entries from another project and storing them as internal cache variables using the obsolete signature:

    load_cache(path/to/other-project/build-dir)

    message(STATUS "${OTHER_PROJECT_CACHE_VAR_1")
    message(STATUS "${OTHER_PROJECT_CACHE_VAR_2")
    # Outputs:
    # -- some-value...
    # -- another-value...

Excluding specific non-internal cache entries and including internal ones using the obsolete signature:

    load_cache(
      path/to/other-project/build-dir
      EXCLUDE OTHER_PROJECT_CACHE_VAR_2
      INCLUDE_INTERNALS OTHER_PROJECT_INTERNAL_CACHE_VAR
    )

    message(STATUS "${OTHER_PROJECT_CACHE_VAR_1")
    message(STATUS "${OTHER_PROJECT_CACHE_VAR_2")
    message(STATUS "${OTHER_PROJECT_INTERNAL_CACHE_VAR}")
    # Outputs:
    # -- some-value...
    # --
    # -- some-internal-value...