echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge topic 'patch-load-cache'

Browse Source 
6fc8d20250 load_cache: Improve explanation of command signatures

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !10216
This commit is contained in:
Brad King 2025-01-24 15:20:00 +00:00 committed by Kitware Robot
commit 5f6114f8b8
1 changed files with 85 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
Help/command/load_cache.rst
View File

@ -1,26 +1,96 @@
load_cache
----------
Load in the values from another project's CMake 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:
.. signature::
load_cache(<build-dir> READ_WITH_PREFIX <prefix> <entry>...)
:target: READ_WITH_PREFIX
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.
The following signature of this command is strongly discouraged, but it is
provided for backward compatibility:
.. signature::
load_cache(<build-dir> [EXCLUDE <entry>...] [INCLUDE_INTERNALS <entry>...])
:target: raw
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.
Examples
^^^^^^^^
Reading specific cache variables from another project and storing them as local
variables:
.. code-block:: cmake
load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)
load_cache(
path/to/other-project/build-dir
READ_WITH_PREFIX prefix_
OTHER_PROJECT_CACHE_VAR_1
OTHER_PROJECT_CACHE_VAR_2
)
Reads the cache and store the requested entries in variables with their
name prefixed with the given prefix. This only reads the values, and
does not create entries in the local project's cache.
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:
.. code-block:: cmake
load_cache(pathToBuildDirectory [EXCLUDE entry1...]
[INCLUDE_INTERNALS entry1...])
load_cache(path/to/other-project/build-dir)
Loads in the values from another cache and store them in the local
project's cache as internal entries. This is useful for a project
that depends on another project built in a different tree. ``EXCLUDE``
option can be used to provide a list of entries to be excluded.
``INCLUDE_INTERNALS`` can be used to provide a list of internal entries to
be included. Normally, no internal entries are brought in. Use of
this form of the command is strongly discouraged, but it is provided
for backward compatibility.
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:
.. code-block:: cmake
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...