mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-02-15 03:30:39 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'doc-cmake_path-out-var'

Browse Source 
6592b8ac14 Help/cmake_path: Clarify output variable behavior

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !11681
This commit is contained in:
Brad King
2026-02-13 14:56:33 +00:00
committed by Kitware Robot
parent 32bd370b6b 6592b8ac14
commit 3990abf9fb
2 changed files with 57 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
Help/command/cmake_path.rst
View File

@@ -169,6 +169,7 @@ Some commands refer to a ``root-path``. This is the concatenation of
be empty. A ``relative-part`` refers to the full path with any ``root-path``
removed.
.. _Creating a Path Variable:
Creating A Path Variable
^^^^^^^^^^^^^^^^^^^^^^^^
@@ -193,6 +194,16 @@ in-place, or in a separate variable named after an ``OUTPUT_VARIABLE``
keyword. All other sub-commands store the result in a mandatory ``<out-var>``
variable.
.. note::
The ``cmake_path`` command can be used directly with variables provided by
CMake representing paths (e.g., :variable:`CMAKE_SOURCE_DIR`). However, since
the command can modify these variables, and many of them have undefined
behavior when modified, they should never be specified as an ``<out-var>``,
and only as the ``<path-var>`` when a separate ``<out-var>`` is specified.
See :manual:`cmake-variables(7)` for the list of CMake variables and
identifiers reserved by CMake.
.. _Normalization:
Normalization
@@ -395,7 +406,7 @@ Path traversal examples
Query
^^^^^
Each of the `cmake_path(GET) <GET_>`_ subcommands has a corresponding
Each of the :cref:`GET` subcommands has a corresponding
``HAS_...`` subcommand which can be used to discover whether a particular path
component is present. See `Path Structure And Terminology`_ for the
meaning of each path component.
@@ -500,7 +511,7 @@ Modification
cmake_path(SET <path-var> [NORMALIZE] <input>)
Assigns the ``<input>`` path to ``<path-var>``. If ``<input>`` is a native
path, it is converted into a cmake-style path with forward-slashes
path, it is converted into a CMake-style path with forward-slashes
(``/``). On Windows, the long filename marker is taken into account.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
@@ -550,12 +561,16 @@ Modification
append <input> omitting any root-name to <path>
See :ref:`Creating a Path Variable` for details on the output variable.
.. signature::
cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
Appends all the ``<input>`` arguments to the ``<path-var>`` without adding any
``directory-separator``.
See :ref:`Creating a Path Variable` for details on the output variable.
.. signature::
cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
@@ -563,8 +578,8 @@ Modification
:cref:`GET ... FILENAME`) from ``<path-var>``. After removal, any trailing
``directory-separator`` is left alone, if present.
If ``OUTPUT_VARIABLE`` is not given, then after this function returns,
:cref:`HAS_FILENAME` returns false for ``<path-var>``.
:cref:`HAS_FILENAME` will return false for the result, whether stored in
``<out-var>`` or ``<path-var>``.
For example:
@@ -583,6 +598,8 @@ Modification
First path is "/a/"
Second path is "/a/"
See :ref:`Creating a Path Variable` for details on the output variable.
.. signature::
cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
@@ -599,12 +616,16 @@ Modification
cmake_path(APPEND path "${input}")
endif()
See :ref:`Creating a Path Variable` for details on the output variable.
.. signature::
cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY]
[OUTPUT_VARIABLE <out-var>])
Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path-var>``.
See :ref:`Creating a Path Variable` for details on the output variable.
.. signature::
cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input>
[OUTPUT_VARIABLE <out-var>])
@@ -620,6 +641,8 @@ Modification
endif()
cmake_path(APPEND_STRING path "${input}")
See :ref:`Creating a Path Variable` for details on the output variable.
.. _Path Generation:
@@ -632,6 +655,8 @@ Generation
Normalizes ``<path-var>`` according the steps described in
:ref:`Normalization`.
See :ref:`Creating a Path Variable` for details on the output variable.
.. signature::
cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>]
[OUTPUT_VARIABLE <out-var>])
@@ -645,6 +670,8 @@ Generation
`std::filesystem::path::lexically_relative
<https://en.cppreference.com/w/cpp/filesystem/path/lexically_normal>`_.
See :ref:`Creating a Path Variable` for details on the output variable.
.. signature::
cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE]
[OUTPUT_VARIABLE <out-var>])
@@ -662,6 +689,8 @@ Generation
with symbolic links resolved and leading tildes expanded, use the
:command:`file(REAL_PATH)` command instead.
See :ref:`Creating a Path Variable` for details on the output variable.
Native Conversion
^^^^^^^^^^^^^^^^^
@@ -671,12 +700,14 @@ target platform when cross-compiling.
.. signature::
cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
Converts a cmake-style ``<path-var>`` into a native path with
Converts a CMake-style ``<path-var>`` into a native path with
platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere).
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion.
See :ref:`Creating a Path Variable` for details on the output variable.
.. _CONVERT:
.. signature::
@@ -684,17 +715,20 @@ target platform when cross-compiling.
:target:
CONVERT ... TO_CMAKE_PATH_LIST
Converts a native ``<input>`` path into a cmake-style path with forward
slashes (``/``). On Windows hosts, the long filename marker is taken into
Converts a native ``<input>`` path into a CMake-style path with forward
slashes (``/``).
On Windows hosts, the long filename marker is taken into
account. The input can be a single path or a system search path like
``$ENV{PATH}``. A search path will be converted to a cmake-style list
separated by ``;`` characters (on non-Windows platforms, this essentially
means ``:`` separators are replaced with ``;``). The result of the
conversion is stored in the ``<out-var>`` variable.
``$ENV{PATH}``. A search path will be converted to a
:ref:`semicolon-separated list <CMake Language Lists>` (on non-Windows
platforms, this essentially means ``:`` separators are replaced with ``;``).
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion.
See :ref:`Creating a Path Variable` for details on the output variable.
.. note::
Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand
takes a literal string as input, not the name of a variable.
@@ -704,16 +738,18 @@ target platform when cross-compiling.
:target:
CONVERT ... TO_NATIVE_PATH_LIST
Converts a cmake-style ``<input>`` path into a native path with
Converts a CMake-style ``<input>`` path into a native path with
platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere).
The input can be a single path or a cmake-style list. A list will be
converted into a native search path (``;``-separated on Windows,
``:``-separated on other platforms). The result of the conversion is
stored in the ``<out-var>`` variable.
The input can be a single path or a :ref:`semicolon-separated list
<CMake Language Lists>`. A list will be converted into a native search path
(``;``-separated on Windows, ``:``-separated on other platforms).
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion.
See :ref:`Creating a Path Variable` for details on the output variable.
.. note::
Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand
takes a literal string as input, not the name of a variable.
@@ -744,3 +780,5 @@ Hashing
``p2`` that compare equal (:cref:`COMPARE ... EQUAL`), the hash value of
``p1`` is equal to the hash value of ``p2``. The path is always
:ref:`normalized <Normalization>` before the hash is computed.
See :ref:`Creating a Path Variable` for details on the output variable.

6
Help/command/file.rst
View File

@@ -710,12 +710,12 @@ Path Conversion
file(TO_CMAKE_PATH "<path>" <variable>)
file(TO_NATIVE_PATH "<path>" <variable>)
The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style
The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a CMake-style
path with forward-slashes (``/``). The input can be a single path or a
system search path like ``$ENV{PATH}``. A search path will be converted
to a cmake-style list separated by ``;`` characters.
to a :ref:`semicolon-separated list <CMake Language Lists>`.
The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native
The ``TO_NATIVE_PATH`` mode converts a CMake-style ``<path>`` into a native
path with platform-specific slashes (``\`` on Windows hosts and ``/``
elsewhere).