Kitware/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-10-15 20:46:37 +08:00
Code Issues Projects Releases Wiki Activity

Help: Use signature directive for cmake_path command

Browse Source 
Using `signature` renders the anchor links for each sub-command, and is
consistent with the other `Help/command` pages which contain multiple
sub-commands.
This commit is contained in:
Tyler Yankee
2025-10-08 10:39:39 -04:00
parent 051b0efd7d
commit c575d84555
4 changed files with 262 additions and 314 deletions
Download Patch File Download Diff File Expand all files Collapse all files

538
Help/command/cmake_path.rst
View File

@@ -30,14 +30,14 @@ Synopsis
`Normalization`_ `Normalization`_
`Decomposition`_ `Decomposition`_
cmake_path(`GET`_ <path-var> :ref:`ROOT_NAME <GET_ROOT_NAME>` <out-var>) cmake_path(`GET`_ <path-var> `ROOT_NAME <GET ... ROOT_NAME_>`_ <out-var>)
cmake_path(`GET`_ <path-var> :ref:`ROOT_DIRECTORY <GET_ROOT_DIRECTORY>` <out-var>) cmake_path(`GET`_ <path-var> `ROOT_DIRECTORY <GET ... ROOT_DIRECTORY_>`_ <out-var>)
cmake_path(`GET`_ <path-var> :ref:`ROOT_PATH <GET_ROOT_PATH>` <out-var>) cmake_path(`GET`_ <path-var> `ROOT_PATH <GET ... ROOT_PATH_>`_ <out-var>)
cmake_path(`GET`_ <path-var> :ref:`FILENAME <GET_FILENAME>` <out-var>) cmake_path(`GET`_ <path-var> `FILENAME <GET ... FILENAME_>`_ <out-var>)
cmake_path(`GET`_ <path-var> :ref:`EXTENSION <GET_EXTENSION>` [LAST_ONLY] <out-var>) cmake_path(`GET`_ <path-var> `EXTENSION <GET ... EXTENSION_>`_ [LAST_ONLY] <out-var>)
cmake_path(`GET`_ <path-var> :ref:`STEM <GET_STEM>` [LAST_ONLY] <out-var>) cmake_path(`GET`_ <path-var> `STEM <GET ... STEM_>`_ [LAST_ONLY] <out-var>)
cmake_path(`GET`_ <path-var> :ref:`RELATIVE_PART <GET_RELATIVE_PART>` <out-var>) cmake_path(`GET`_ <path-var> `RELATIVE_PART <GET ... RELATIVE_PART_>`_ <out-var>)
cmake_path(`GET`_ <path-var> :ref:`PARENT_PATH <GET_PARENT_PATH>` <out-var>) cmake_path(`GET`_ <path-var> `PARENT_PATH <GET ... PARENT_PATH_>`_ <out-var>)
`Query`_ `Query`_
cmake_path(`HAS_ROOT_NAME`_ <path-var> <out-var>) cmake_path(`HAS_ROOT_NAME`_ <path-var> <out-var>)
@@ -51,10 +51,12 @@ Synopsis
cmake_path(`IS_ABSOLUTE`_ <path-var> <out-var>) cmake_path(`IS_ABSOLUTE`_ <path-var> <out-var>)
cmake_path(`IS_RELATIVE`_ <path-var> <out-var>) cmake_path(`IS_RELATIVE`_ <path-var> <out-var>)
cmake_path(`IS_PREFIX`_ <path-var> <input> [NORMALIZE] <out-var>) cmake_path(`IS_PREFIX`_ <path-var> <input> [NORMALIZE] <out-var>)
cmake_path(`COMPARE`_ <input1> <OP> <input2> <out-var>)
`Comparison`_
cmake_path(`COMPARE`_ <input1> <op> <input2> <out-var>)
`Modification`_ `Modification`_
cmake_path(:ref:`SET <cmake_path-SET>` <path-var> [NORMALIZE] <input>) cmake_path(`SET`_ <path-var> [NORMALIZE] <input>)
cmake_path(`APPEND`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) cmake_path(`APPEND`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
cmake_path(`APPEND_STRING`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) cmake_path(`APPEND_STRING`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
cmake_path(`REMOVE_FILENAME`_ <path-var> [OUTPUT_VARIABLE <out-var>]) cmake_path(`REMOVE_FILENAME`_ <path-var> [OUTPUT_VARIABLE <out-var>])
@@ -69,8 +71,8 @@ Synopsis
`Native Conversion`_ `Native Conversion`_
cmake_path(`NATIVE_PATH`_ <path-var> [NORMALIZE] <out-var>) cmake_path(`NATIVE_PATH`_ <path-var> [NORMALIZE] <out-var>)
cmake_path(`CONVERT`_ <input> `TO_CMAKE_PATH_LIST`_ <out-var> [NORMALIZE]) cmake_path(`CONVERT`_ <input> `TO_CMAKE_PATH_LIST <CONVERT ... TO_CMAKE_PATH_LIST_>`_ <out-var> [NORMALIZE])
cmake_path(`CONVERT`_ <input> `TO_NATIVE_PATH_LIST`_ <out-var> [NORMALIZE]) cmake_path(`CONVERT`_ <input> `TO_NATIVE_PATH_LIST <CONVERT ... TO_NATIVE_PATH_LIST_>`_ <out-var> [NORMALIZE])
`Hashing`_ `Hashing`_
cmake_path(`HASH`_ <path-var> <out-var>) cmake_path(`HASH`_ <path-var> <out-var>)
@@ -172,12 +174,11 @@ Creating A Path Variable
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
While a path can be created with care using an ordinary :command:`set` While a path can be created with care using an ordinary :command:`set`
command, it is recommended to use :ref:`cmake_path(SET) <cmake_path-SET>` command, it is recommended to use :command:`cmake_path(SET)` instead, as it
instead, as it automatically converts the path to the required form where automatically converts the path to the required form where required. The
required. The :ref:`cmake_path(APPEND) <APPEND>` subcommand may :command:`cmake_path(APPEND)` subcommand may be another suitable alternative
be another suitable alternative where a path needs to be constructed by where a path needs to be constructed by joining fragments. The following
joining fragments. The following example compares the three methods for example compares the three methods for constructing the same path:
constructing the same path:
.. code-block:: cmake .. code-block:: cmake
@@ -224,21 +225,12 @@ Decomposition
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
.. _GET: .. _GET:
.. _GET_ROOT_NAME:
.. _GET_ROOT_DIRECTORY:
.. _GET_ROOT_PATH:
.. _GET_FILENAME:
.. _GET_EXTENSION:
.. _GET_STEM:
.. _GET_RELATIVE_PART:
.. _GET_PARENT_PATH:
The following forms of the ``GET`` subcommand each retrieve a different The following forms of the ``GET`` subcommand each retrieve a different
component or group of components from a path. See component or group of components from a path. See
`Path Structure And Terminology`_ for the meaning of each path component. `Path Structure And Terminology`_ for the meaning of each path component.
.. code-block:: cmake .. signature::
cmake_path(GET <path-var> ROOT_NAME <out-var>) cmake_path(GET <path-var> ROOT_NAME <out-var>)
cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>) cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
cmake_path(GET <path-var> ROOT_PATH <out-var>) cmake_path(GET <path-var> ROOT_PATH <out-var>)
@@ -247,17 +239,26 @@ component or group of components from a path. See
cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>) cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
cmake_path(GET <path-var> RELATIVE_PART <out-var>) cmake_path(GET <path-var> RELATIVE_PART <out-var>)
cmake_path(GET <path-var> PARENT_PATH <out-var>) cmake_path(GET <path-var> PARENT_PATH <out-var>)
:target:
GET ... ROOT_NAME
GET ... ROOT_DIRECTORY
GET ... ROOT_PATH
GET ... FILENAME
GET ... EXTENSION
GET ... STEM
GET ... RELATIVE_PART
GET ... PARENT_PATH
If a requested component is not present in the path, an empty string will be If a requested component is not present in the path, an empty string will be
stored in ``<out-var>``. For example, only Windows systems have the concept stored in ``<out-var>``. For example, only Windows systems have the concept
of a ``root-name``, so when the host machine is non-Windows, the ``ROOT_NAME`` of a ``root-name``, so when the host machine is non-Windows, the ``ROOT_NAME``
subcommand will always return an empty string. subcommand will always return an empty string.
For ``PARENT_PATH``, if the `HAS_RELATIVE_PART`_ subcommand returns false, For ``PARENT_PATH``, if the :cref:`HAS_RELATIVE_PART` sub-command returns
the result is a copy of ``<path-var>``. Note that this implies that a root false, the result is a copy of ``<path-var>``. Note that this implies that a
directory is considered to have a parent, with that parent being itself. root directory is considered to have a parent, with that parent being itself.
Where `HAS_RELATIVE_PART`_ returns true, the result will essentially be Where :cref:`HAS_RELATIVE_PART` returns true, the result will essentially be
``<path-var>`` with one less element. ``<path-var>`` with one less element.
Root examples Root examples
""""""""""""" """""""""""""
@@ -394,22 +395,12 @@ Path traversal examples
Query Query
^^^^^ ^^^^^
Each of the ``GET`` subcommands has a corresponding ``HAS_...`` Each of the `cmake_path(GET) <GET_>`_ subcommands has a corresponding
subcommand which can be used to discover whether a particular path ``HAS_...`` subcommand which can be used to discover whether a particular path
component is present. See `Path Structure And Terminology`_ for the component is present. See `Path Structure And Terminology`_ for the
meaning of each path component. meaning of each path component.
.. _HAS_ROOT_NAME: .. signature::
.. _HAS_ROOT_DIRECTORY:
.. _HAS_ROOT_PATH:
.. _HAS_FILENAME:
.. _HAS_EXTENSION:
.. _HAS_STEM:
.. _HAS_RELATIVE_PART:
.. _HAS_PARENT_PATH:
.. code-block:: cmake
cmake_path(HAS_ROOT_NAME <path-var> <out-var>) cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>) cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
cmake_path(HAS_ROOT_PATH <path-var> <out-var>) cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
@@ -419,88 +410,85 @@ meaning of each path component.
cmake_path(HAS_RELATIVE_PART <path-var> <out-var>) cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
cmake_path(HAS_PARENT_PATH <path-var> <out-var>) cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
Each of the above follows the predictable pattern of setting ``<out-var>`` Each of the above follows the predictable pattern of setting ``<out-var>``
to true if the path has the associated component, or false otherwise. to true if the path has the associated component, or false otherwise.
Note the following special cases: Note the following special cases:
* For ``HAS_ROOT_PATH``, a true result will only be returned if at least one * For ``HAS_ROOT_PATH``, a true result will only be returned if at least one
of ``root-name`` or ``root-directory`` is non-empty. of ``root-name`` or ``root-directory`` is non-empty.
* For ``HAS_PARENT_PATH``, the root directory is also considered to have a * For ``HAS_PARENT_PATH``, the root directory is also considered to have a
parent, which will be itself. The result is true except if the path parent, which will be itself. The result is true except if the path
consists of just a :ref:`filename <FILENAME_DEF>`. consists of just a :ref:`filename <FILENAME_DEF>`.
.. _IS_ABSOLUTE:
.. code-block:: cmake
.. signature::
cmake_path(IS_ABSOLUTE <path-var> <out-var>) cmake_path(IS_ABSOLUTE <path-var> <out-var>)
Sets ``<out-var>`` to true if ``<path-var>`` is absolute. An absolute path Sets ``<out-var>`` to true if ``<path-var>`` is absolute. An absolute path
is a path that unambiguously identifies the location of a file without is a path that unambiguously identifies the location of a file without
reference to an additional starting location. On Windows, this means the reference to an additional starting location. On Windows, this means the
path must have both a ``root-name`` and a ``root-directory-separator`` to be path must have both a ``root-name`` and a ``root-directory-separator`` to be
considered absolute. On other platforms, just a ``root-directory-separator`` considered absolute. On other platforms, just a ``root-directory-separator``
is sufficient. Note that this means on Windows, ``IS_ABSOLUTE`` can be is sufficient. Note that this means on Windows, ``IS_ABSOLUTE`` can be
false while ``HAS_ROOT_DIRECTORY`` can be true. false while :cref:`HAS_ROOT_DIRECTORY` can be true.
.. _IS_RELATIVE:
.. code-block:: cmake
.. signature::
cmake_path(IS_RELATIVE <path-var> <out-var>) cmake_path(IS_RELATIVE <path-var> <out-var>)
This will store the opposite of ``IS_ABSOLUTE`` in ``<out-var>``. This will store the opposite of :cref:`IS_ABSOLUTE` in ``<out-var>``.
.. _IS_PREFIX:
.. code-block:: cmake
.. signature::
cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>) cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
Checks if ``<path-var>`` is the prefix of ``<input>``. Checks if ``<path-var>`` is the prefix of ``<input>``.
When the ``NORMALIZE`` option is specified, ``<path-var>`` and ``<input>`` When the ``NORMALIZE`` option is specified, ``<path-var>`` and ``<input>``
are :ref:`normalized <Normalization>` before the check. are :ref:`normalized <Normalization>` before the check.
.. code-block:: cmake .. code-block:: cmake
set(path "/a/b/c") set(path "/a/b/c")
cmake_path(IS_PREFIX path "/a/b/c/d" result) # result = true cmake_path(IS_PREFIX path "/a/b/c/d" result) # result = true
cmake_path(IS_PREFIX path "/a/b" result) # result = false cmake_path(IS_PREFIX path "/a/b" result) # result = false
cmake_path(IS_PREFIX path "/x/y/z" result) # result = false cmake_path(IS_PREFIX path "/x/y/z" result) # result = false
set(path "/a/b") set(path "/a/b")
cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true
.. _Path Comparison:
Comparison
^^^^^^^^^^
.. _Path COMPARE:
.. _COMPARE: .. _COMPARE:
.. code-block:: cmake .. signature::
cmake_path(COMPARE <input1> EQUAL <input2> <out-var>) cmake_path(COMPARE <input1> EQUAL <input2> <out-var>)
cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>) cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
:target:
COMPARE ... EQUAL
COMPARE ... NOT_EQUAL
Compares the lexical representations of two paths provided as string literals. Compares the lexical representations of two paths provided as string literals.
No normalization is performed on either path, except multiple consecutive No normalization is performed on either path, except multiple consecutive
directory separators are effectively collapsed into a single separator. directory separators are effectively collapsed into a single separator.
Equality is determined according to the following pseudo-code logic: Equality is determined according to the following pseudo-code logic:
:: ::
if(NOT <input1>.root_name() STREQUAL <input2>.root_name()) if(NOT <input1>.root_name() STREQUAL <input2>.root_name())
return FALSE return FALSE
if(<input1>.has_root_directory() XOR <input2>.has_root_directory()) if(<input1>.has_root_directory() XOR <input2>.has_root_directory())
return FALSE return FALSE
Return FALSE if a relative portion of <input1> is not lexicographically Return FALSE if a relative portion of <input1> is not lexicographically
equal to the relative portion of <input2>. This comparison is performed path equal to the relative portion of <input2>. This comparison is performed path
component-wise. If all of the components compare equal, then return TRUE. component-wise. If all of the components compare equal, then return TRUE.
.. note:: .. note::
Unlike most other ``cmake_path()`` subcommands, the ``COMPARE`` subcommand Unlike most other ``cmake_path()`` subcommands, the ``COMPARE`` subcommand
takes literal strings as input, not the names of variables. takes literal strings as input, not the names of variables.
.. _Path Modification: .. _Path Modification:
@@ -508,150 +496,129 @@ Equality is determined according to the following pseudo-code logic:
Modification Modification
^^^^^^^^^^^^ ^^^^^^^^^^^^
.. _cmake_path-SET: .. signature::
.. code-block:: cmake
cmake_path(SET <path-var> [NORMALIZE] <input>) cmake_path(SET <path-var> [NORMALIZE] <input>)
Assign the ``<input>`` path to ``<path-var>``. If ``<input>`` is a native 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. (``/``). On Windows, the long filename marker is taken into account.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` after the conversion. <Normalization>` after the conversion.
For example: For example:
.. code-block:: cmake .. code-block:: cmake
set(native_path "c:\\a\\b/..\\c") set(native_path "c:\\a\\b/..\\c")
cmake_path(SET path "${native_path}") cmake_path(SET path "${native_path}")
message("CMake path is \"${path}\"") message("CMake path is \"${path}\"")
cmake_path(SET path NORMALIZE "${native_path}") cmake_path(SET path NORMALIZE "${native_path}")
message("Normalized CMake path is \"${path}\"") message("Normalized CMake path is \"${path}\"")
Output:: Output::
CMake path is "c:/a/b/../c" CMake path is "c:/a/b/../c"
Normalized CMake path is "c:/a/c" Normalized CMake path is "c:/a/c"
.. _APPEND:
.. code-block:: cmake
.. signature::
cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
Append all the ``<input>`` arguments to the ``<path-var>`` using ``/`` as Appends all the ``<input>`` arguments to the ``<path-var>`` using ``/`` as
the ``directory-separator``. Depending on the ``<input>``, the previous the ``directory-separator``. Depending on the ``<input>``, the previous
contents of ``<path-var>`` may be discarded. For each ``<input>`` argument, contents of ``<path-var>`` may be discarded. For each ``<input>`` argument,
the following algorithm (pseudo-code) applies: the following algorithm (pseudo-code) applies:
:: ::
# <path> is the contents of <path-var> # <path> is the contents of <path-var>
if(<input>.is_absolute() OR if(<input>.is_absolute() OR
(<input>.has_root_name() AND (<input>.has_root_name() AND
NOT <input>.root_name() STREQUAL <path>.root_name())) NOT <input>.root_name() STREQUAL <path>.root_name()))
replace <path> with <input> replace <path> with <input>
return() return()
endif() endif()
if(<input>.has_root_directory()) if(<input>.has_root_directory())
remove any root-directory and the entire relative path from <path> remove any root-directory and the entire relative path from <path>
elseif(<path>.has_filename() OR elseif(<path>.has_filename() OR
(NOT <path-var>.has_root_directory() OR <path>.is_absolute())) (NOT <path-var>.has_root_directory() OR <path>.is_absolute()))
append directory-separator to <path> append directory-separator to <path>
endif() endif()
append <input> omitting any root-name to <path> append <input> omitting any root-name to <path>
.. _APPEND_STRING:
.. code-block:: cmake
.. signature::
cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
Append all the ``<input>`` arguments to the ``<path-var>`` without adding any Appends all the ``<input>`` arguments to the ``<path-var>`` without adding any
``directory-separator``. ``directory-separator``.
.. _REMOVE_FILENAME:
.. code-block:: cmake
.. signature::
cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>]) cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
Removes the :ref:`filename <FILENAME_DEF>` component (as returned by Removes the :ref:`filename <FILENAME_DEF>` component (as returned by
:ref:`GET ... FILENAME <GET_FILENAME>`) from ``<path-var>``. After removal, :cref:`GET ... FILENAME`) from ``<path-var>``. After removal, any trailing
any trailing ``directory-separator`` is left alone, if present. ``directory-separator`` is left alone, if present.
If ``OUTPUT_VARIABLE`` is not given, then after this function returns, If ``OUTPUT_VARIABLE`` is not given, then after this function returns,
`HAS_FILENAME`_ returns false for ``<path-var>``. :cref:`HAS_FILENAME` returns false for ``<path-var>``.
For example: For example:
.. code-block:: cmake .. code-block:: cmake
set(path "/a/b") set(path "/a/b")
cmake_path(REMOVE_FILENAME path) cmake_path(REMOVE_FILENAME path)
message("First path is \"${path}\"") message("First path is \"${path}\"")
# filename is now already empty, the following removes nothing # filename is now already empty, the following removes nothing
cmake_path(REMOVE_FILENAME path) cmake_path(REMOVE_FILENAME path)
message("Second path is \"${path}\"") message("Second path is \"${path}\"")
Output:: Output::
First path is "/a/" First path is "/a/"
Second path is "/a/" Second path is "/a/"
.. _REPLACE_FILENAME:
.. code-block:: cmake
.. signature::
cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>]) cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
Replaces the :ref:`filename <FILENAME_DEF>` component from ``<path-var>`` Replaces the :ref:`filename <FILENAME_DEF>` component from ``<path-var>``
with ``<input>``. If ``<path-var>`` has no filename component (i.e. with ``<input>``. If ``<path-var>`` has no filename component (i.e.
`HAS_FILENAME`_ returns false), the path is unchanged. The operation is :cref:`HAS_FILENAME` returns false), the path is unchanged. The operation is
equivalent to the following: equivalent to the following:
.. code-block:: cmake .. code-block:: cmake
cmake_path(HAS_FILENAME path has_filename) cmake_path(HAS_FILENAME path has_filename)
if(has_filename) if(has_filename)
cmake_path(REMOVE_FILENAME path) cmake_path(REMOVE_FILENAME path)
cmake_path(APPEND path "${input}") cmake_path(APPEND path "${input}")
endif() endif()
.. _REMOVE_EXTENSION:
.. code-block:: cmake
.. signature::
cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY] cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY]
[OUTPUT_VARIABLE <out-var>]) [OUTPUT_VARIABLE <out-var>])
Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path-var>``. Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path-var>``.
.. _REPLACE_EXTENSION:
.. code-block:: cmake
.. signature::
cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input> cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input>
[OUTPUT_VARIABLE <out-var>]) [OUTPUT_VARIABLE <out-var>])
Replaces the :ref:`extension <EXTENSION_DEF>` with ``<input>``. Its effect Replaces the :ref:`extension <EXTENSION_DEF>` with ``<input>``. Its effect
is equivalent to the following: is equivalent to the following:
.. code-block:: cmake .. code-block:: cmake
cmake_path(REMOVE_EXTENSION path) cmake_path(REMOVE_EXTENSION path)
if(NOT input MATCHES "^\\.") if(NOT input MATCHES "^\\.")
cmake_path(APPEND_STRING path ".") cmake_path(APPEND_STRING path ".")
endif() endif()
cmake_path(APPEND_STRING path "${input}") cmake_path(APPEND_STRING path "${input}")
.. _Path Generation: .. _Path Generation:
@@ -659,50 +626,41 @@ is equivalent to the following:
Generation Generation
^^^^^^^^^^ ^^^^^^^^^^
.. _NORMAL_PATH: .. signature::
.. code-block:: cmake
cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>]) cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
Normalize ``<path-var>`` according the steps described in :ref:`Normalization`. Normalizes ``<path-var>`` according the steps described in
:ref:`Normalization`.
.. _cmake_path-RELATIVE_PATH:
.. _RELATIVE_PATH:
.. code-block:: cmake
.. signature::
cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>] cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>]
[OUTPUT_VARIABLE <out-var>]) [OUTPUT_VARIABLE <out-var>])
Modifies ``<path-var>`` to make it relative to the ``BASE_DIRECTORY`` argument. Modifies ``<path-var>`` to make it relative to the ``BASE_DIRECTORY`` argument.
If ``BASE_DIRECTORY`` is not specified, the default base directory will be If ``BASE_DIRECTORY`` is not specified, the default base directory will be
:variable:`CMAKE_CURRENT_SOURCE_DIR`. :variable:`CMAKE_CURRENT_SOURCE_DIR`.
For reference, the algorithm used to compute the relative path is the same For reference, the algorithm used to compute the relative path is the same
as that used by C++ as that used by C++
`std::filesystem::path::lexically_relative `std::filesystem::path::lexically_relative
<https://en.cppreference.com/w/cpp/filesystem/path/lexically_normal>`_. <https://en.cppreference.com/w/cpp/filesystem/path/lexically_normal>`_.
.. _ABSOLUTE_PATH:
.. code-block:: cmake
.. signature::
cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE]
[OUTPUT_VARIABLE <out-var>]) [OUTPUT_VARIABLE <out-var>])
If ``<path-var>`` is a relative path (`IS_RELATIVE`_ is true), it is evaluated If ``<path-var>`` is a relative path (:cref:`IS_RELATIVE` is true), it is
relative to the given base directory specified by ``BASE_DIRECTORY`` option. evaluated relative to the given base directory specified by ``BASE_DIRECTORY``
If ``BASE_DIRECTORY`` is not specified, the default base directory will be option. If ``BASE_DIRECTORY`` is not specified, the default base directory
:variable:`CMAKE_CURRENT_SOURCE_DIR`. will be :variable:`CMAKE_CURRENT_SOURCE_DIR`.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` after the path computation. <Normalization>` after the path computation.
Because ``cmake_path()`` does not access the filesystem, symbolic links are Because ``cmake_path()`` does not access the filesystem, symbolic links are
not resolved and any leading tilde is not expanded. To compute a real path not resolved and any leading tilde is not expanded. To compute a real path
with symbolic links resolved and leading tildes expanded, use the with symbolic links resolved and leading tildes expanded, use the
:command:`file(REAL_PATH)` command instead. :command:`file(REAL_PATH)` command instead.
Native Conversion Native Conversion
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
@@ -710,89 +668,79 @@ Native Conversion
For commands in this section, *native* refers to the host platform, not the For commands in this section, *native* refers to the host platform, not the
target platform when cross-compiling. target platform when cross-compiling.
.. _cmake_path-NATIVE_PATH: .. signature::
.. _NATIVE_PATH:
.. code-block:: cmake
cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>) 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). platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere).
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion. <Normalization>` before the conversion.
.. _CONVERT: .. _CONVERT:
.. _cmake_path-TO_CMAKE_PATH_LIST:
.. _TO_CMAKE_PATH_LIST:
.. code-block:: cmake
.. signature::
cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE]) cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
:target:
CONVERT ... TO_CMAKE_PATH_LIST
Converts a native ``<input>`` path into a cmake-style path with forward Converts a native ``<input>`` path into a cmake-style path with forward
slashes (``/``). On Windows hosts, the long filename marker is taken into 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 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 ``$ENV{PATH}``. A search path will be converted to a cmake-style list
separated by ``;`` characters (on non-Windows platforms, this essentially separated by ``;`` characters (on non-Windows platforms, this essentially
means ``:`` separators are replaced with ``;``). The result of the means ``:`` separators are replaced with ``;``). The result of the
conversion is stored in the ``<out-var>`` variable. conversion is stored in the ``<out-var>`` variable.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion. <Normalization>` before the conversion.
.. note:: .. note::
Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand
takes a literal string as input, not the name of a variable. takes a literal string as input, not the name of a variable.
.. _cmake_path-TO_NATIVE_PATH_LIST:
.. _TO_NATIVE_PATH_LIST:
.. code-block:: cmake
.. signature::
cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE]) cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])
: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). platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere).
The input can be a single path or a cmake-style list. A list will be 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, converted into a native search path (``;``-separated on Windows,
``:``-separated on other platforms). The result of the conversion is ``:``-separated on other platforms). The result of the conversion is
stored in the ``<out-var>`` variable. stored in the ``<out-var>`` variable.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion. <Normalization>` before the conversion.
.. note:: .. note::
Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand
takes a literal string as input, not the name of a variable. takes a literal string as input, not the name of a variable.
For example: For example:
.. code-block:: cmake .. code-block:: cmake
set(paths "/a/b/c" "/x/y/z") set(paths "/a/b/c" "/x/y/z")
cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths) cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths)
message("Native path list is \"${native_paths}\"") message("Native path list is \"${native_paths}\"")
Output on Windows:: Output on Windows::
Native path list is "\a\b\c;\x\y\z" Native path list is "\a\b\c;\x\y\z"
Output on all other platforms:: Output on all other platforms::
Native path list is "/a/b/c:/x/y/z" Native path list is "/a/b/c:/x/y/z"
Hashing Hashing
^^^^^^^ ^^^^^^^
.. _HASH: .. signature::
cmake_path(HASH <path-var> <out-var>)
.. code-block:: cmake Computes a hash value of ``<path-var>`` such that for two paths ``p1`` and
``p2`` that compare equal (:cref:`COMPARE ... EQUAL`), the hash value of
cmake_path(HASH <path-var> <out-var>) ``p1`` is equal to the hash value of ``p2``. The path is always
:ref:`normalized <Normalization>` before the hash is computed.
Compute a hash value of ``<path-var>`` such that for two paths ``p1`` and
``p2`` that compare equal (:ref:`COMPARE ... EQUAL <COMPARE>`), 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.

13
Help/command/file.rst
View File

@@ -6,17 +6,16 @@ File manipulation command.
This command is dedicated to file and path manipulation requiring access to the This command is dedicated to file and path manipulation requiring access to the
filesystem. filesystem.
For other path manipulation, handling only syntactic aspects, have a look at For other path manipulation, handling only syntactic aspects, see the
:command:`cmake_path` command. :command:`cmake_path` command.
.. note:: .. note::
The sub-commands `RELATIVE_PATH`_, `TO_CMAKE_PATH`_ and `TO_NATIVE_PATH`_ has The sub-commands `RELATIVE_PATH`_, `TO_CMAKE_PATH`_, and `TO_NATIVE_PATH`_
been superseded, respectively, by sub-commands have been superseded, respectively, by the sub-commands
:ref:`RELATIVE_PATH <cmake_path-RELATIVE_PATH>`, :command:`cmake_path(RELATIVE_PATH)`,
:ref:`CONVERT ... TO_CMAKE_PATH_LIST <cmake_path-TO_CMAKE_PATH_LIST>` and :command:`cmake_path(CONVERT ... TO_CMAKE_PATH_LIST)`, and
:ref:`CONVERT ... TO_NATIVE_PATH_LIST <cmake_path-TO_NATIVE_PATH_LIST>` of :command:`cmake_path(CONVERT ... TO_NATIVE_PATH_LIST)`.
:command:`cmake_path` command.
Synopsis Synopsis
^^^^^^^^ ^^^^^^^^

2
Help/command/if.rst
View File

@@ -415,7 +415,7 @@ Path Comparisons
... ...
endif() endif()
See :ref:`cmake_path(COMPARE) <Path COMPARE>` for more details. See :ref:`cmake_path(COMPARE) <Path Comparison>` for more details.
Variable Expansion Variable Expansion
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^

23
Help/manual/cmake-generator-expressions.7.rst
View File

@@ -677,7 +677,7 @@ Path Comparisons
performed on either path. Returns ``1`` if the paths are equal, ``0`` performed on either path. Returns ``1`` if the paths are equal, ``0``
otherwise. otherwise.
See :ref:`cmake_path(COMPARE) <Path COMPARE>` for more details. See :ref:`cmake_path(COMPARE) <Path Comparison>` for more details.
.. _GenEx Path Queries: .. _GenEx Path Queries:
@@ -720,13 +720,15 @@ All paths are expected to be in cmake-style format.
.. versionadded:: 3.24 .. versionadded:: 3.24
Returns ``1`` if the path is :ref:`absolute <IS_ABSOLUTE>`, ``0`` otherwise. Returns ``1`` if the path is absolute according to
:command:`cmake_path(IS_ABSOLUTE)`, ``0`` otherwise.
.. genex:: $<PATH:IS_RELATIVE,path> .. genex:: $<PATH:IS_RELATIVE,path>
.. versionadded:: 3.24 .. versionadded:: 3.24
This will return the opposite of ``IS_ABSOLUTE``. Returns ``1`` if the path is relative according to
:command:`cmake_path(IS_RELATIVE)`, ``0`` otherwise.
.. genex:: $<PATH:IS_PREFIX[,NORMALIZE],path,input> .. genex:: $<PATH:IS_PREFIX[,NORMALIZE],path,input>
@@ -818,7 +820,7 @@ in cmake-style format.
``directory-separator``. Depending on the ``input``, the value of ``path`` ``directory-separator``. Depending on the ``input``, the value of ``path``
may be discarded. may be discarded.
See :ref:`cmake_path(APPEND) <APPEND>` for more details. See :command:`cmake_path(APPEND)` for more details.
.. genex:: $<PATH:REMOVE_FILENAME,path...> .. genex:: $<PATH:REMOVE_FILENAME,path...>
@@ -828,7 +830,7 @@ in cmake-style format.
``$<PATH:GET_FILENAME>``) removed. After removal, any trailing ``$<PATH:GET_FILENAME>``) removed. After removal, any trailing
``directory-separator`` is left alone, if present. ``directory-separator`` is left alone, if present.
See :ref:`cmake_path(REMOVE_FILENAME) <REMOVE_FILENAME>` for more details. See :command:`cmake_path(REMOVE_FILENAME)` for more details.
.. genex:: $<PATH:REPLACE_FILENAME,path...,input> .. genex:: $<PATH:REPLACE_FILENAME,path...,input>
@@ -838,7 +840,7 @@ in cmake-style format.
``path`` has no filename component (i.e. ``$<PATH:HAS_FILENAME>`` returns ``path`` has no filename component (i.e. ``$<PATH:HAS_FILENAME>`` returns
``0``), ``path`` is unchanged. ``0``), ``path`` is unchanged.
See :ref:`cmake_path(REPLACE_FILENAME) <REPLACE_FILENAME>` for more details. See :command:`cmake_path(REPLACE_FILENAME)` for more details.
.. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path...> .. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path...>
@@ -846,7 +848,7 @@ in cmake-style format.
Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` removed, if any. Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` removed, if any.
See :ref:`cmake_path(REMOVE_EXTENSION) <REMOVE_EXTENSION>` for more details. See :command:`cmake_path(REMOVE_EXTENSION)` for more details.
.. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path...,input> .. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path...,input>
@@ -855,7 +857,7 @@ in cmake-style format.
Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` replaced by Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` replaced by
``input``, if any. ``input``, if any.
See :ref:`cmake_path(REPLACE_EXTENSION) <REPLACE_EXTENSION>` for more details. See :command:`cmake_path(REPLACE_EXTENSION)` for more details.
.. genex:: $<PATH:NORMAL_PATH,path...> .. genex:: $<PATH:NORMAL_PATH,path...>
@@ -871,8 +873,7 @@ in cmake-style format.
Returns ``path``, modified to make it relative to the ``base_directory`` Returns ``path``, modified to make it relative to the ``base_directory``
argument. argument.
See :ref:`cmake_path(RELATIVE_PATH) <cmake_path-RELATIVE_PATH>` for more See :command:`cmake_path(RELATIVE_PATH)` for more details.
details.
.. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path...,base_directory> .. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path...,base_directory>
@@ -885,7 +886,7 @@ in cmake-style format.
When the ``NORMALIZE`` option is specified, the path is When the ``NORMALIZE`` option is specified, the path is
:ref:`normalized <Normalization>` after the path computation. :ref:`normalized <Normalization>` after the path computation.
See :ref:`cmake_path(ABSOLUTE_PATH) <ABSOLUTE_PATH>` for more details. See :command:`cmake_path(ABSOLUTE_PATH)` for more details.
Shell Paths Shell Paths
^^^^^^^^^^^ ^^^^^^^^^^^