diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index 3094ad6b0f..3fc3b7cc26 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -30,14 +30,14 @@ Synopsis `Normalization`_ `Decomposition`_ - cmake_path(`GET`_ :ref:`ROOT_NAME ` ) - cmake_path(`GET`_ :ref:`ROOT_DIRECTORY ` ) - cmake_path(`GET`_ :ref:`ROOT_PATH ` ) - cmake_path(`GET`_ :ref:`FILENAME ` ) - cmake_path(`GET`_ :ref:`EXTENSION ` [LAST_ONLY] ) - cmake_path(`GET`_ :ref:`STEM ` [LAST_ONLY] ) - cmake_path(`GET`_ :ref:`RELATIVE_PART ` ) - cmake_path(`GET`_ :ref:`PARENT_PATH ` ) + cmake_path(`GET`_ `ROOT_NAME `_ ) + cmake_path(`GET`_ `ROOT_DIRECTORY `_ ) + cmake_path(`GET`_ `ROOT_PATH `_ ) + cmake_path(`GET`_ `FILENAME `_ ) + cmake_path(`GET`_ `EXTENSION `_ [LAST_ONLY] ) + cmake_path(`GET`_ `STEM `_ [LAST_ONLY] ) + cmake_path(`GET`_ `RELATIVE_PART `_ ) + cmake_path(`GET`_ `PARENT_PATH `_ ) `Query`_ cmake_path(`HAS_ROOT_NAME`_ ) @@ -51,10 +51,12 @@ Synopsis cmake_path(`IS_ABSOLUTE`_ ) cmake_path(`IS_RELATIVE`_ ) cmake_path(`IS_PREFIX`_ [NORMALIZE] ) - cmake_path(`COMPARE`_ ) + + `Comparison`_ + cmake_path(`COMPARE`_ ) `Modification`_ - cmake_path(:ref:`SET ` [NORMALIZE] ) + cmake_path(`SET`_ [NORMALIZE] ) cmake_path(`APPEND`_ [...] [OUTPUT_VARIABLE ]) cmake_path(`APPEND_STRING`_ [...] [OUTPUT_VARIABLE ]) cmake_path(`REMOVE_FILENAME`_ [OUTPUT_VARIABLE ]) @@ -69,8 +71,8 @@ Synopsis `Native Conversion`_ cmake_path(`NATIVE_PATH`_ [NORMALIZE] ) - cmake_path(`CONVERT`_ `TO_CMAKE_PATH_LIST`_ [NORMALIZE]) - cmake_path(`CONVERT`_ `TO_NATIVE_PATH_LIST`_ [NORMALIZE]) + cmake_path(`CONVERT`_ `TO_CMAKE_PATH_LIST `_ [NORMALIZE]) + cmake_path(`CONVERT`_ `TO_NATIVE_PATH_LIST `_ [NORMALIZE]) `Hashing`_ cmake_path(`HASH`_ ) @@ -172,12 +174,11 @@ Creating A Path Variable ^^^^^^^^^^^^^^^^^^^^^^^^ While a path can be created with care using an ordinary :command:`set` -command, it is recommended to use :ref:`cmake_path(SET) ` -instead, as it automatically converts the path to the required form where -required. The :ref:`cmake_path(APPEND) ` subcommand may -be another suitable alternative where a path needs to be constructed by -joining fragments. The following example compares the three methods for -constructing the same path: +command, it is recommended to use :command:`cmake_path(SET)` instead, as it +automatically converts the path to the required form where required. The +:command:`cmake_path(APPEND)` subcommand may be another suitable alternative +where a path needs to be constructed by joining fragments. The following +example compares the three methods for constructing the same path: .. code-block:: cmake @@ -224,21 +225,12 @@ Decomposition ^^^^^^^^^^^^^ .. _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 component or group of components from a path. See `Path Structure And Terminology`_ for the meaning of each path component. -.. code-block:: cmake - +.. signature:: cmake_path(GET ROOT_NAME ) cmake_path(GET ROOT_DIRECTORY ) cmake_path(GET ROOT_PATH ) @@ -247,17 +239,26 @@ component or group of components from a path. See cmake_path(GET STEM [LAST_ONLY] ) cmake_path(GET RELATIVE_PART ) cmake_path(GET PARENT_PATH ) + :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 -stored in ````. For example, only Windows systems have the concept -of a ``root-name``, so when the host machine is non-Windows, the ``ROOT_NAME`` -subcommand will always return an empty string. + If a requested component is not present in the path, an empty string will be + stored in ````. For example, only Windows systems have the concept + of a ``root-name``, so when the host machine is non-Windows, the ``ROOT_NAME`` + subcommand will always return an empty string. -For ``PARENT_PATH``, if the `HAS_RELATIVE_PART`_ subcommand returns false, -the result is a copy of ````. Note that this implies that a root -directory is considered to have a parent, with that parent being itself. -Where `HAS_RELATIVE_PART`_ returns true, the result will essentially be -```` with one less element. + For ``PARENT_PATH``, if the :cref:`HAS_RELATIVE_PART` sub-command returns + false, the result is a copy of ````. Note that this implies that a + root directory is considered to have a parent, with that parent being itself. + Where :cref:`HAS_RELATIVE_PART` returns true, the result will essentially be + ```` with one less element. Root examples """"""""""""" @@ -394,22 +395,12 @@ Path traversal examples Query ^^^^^ -Each of the ``GET`` subcommands has a corresponding ``HAS_...`` -subcommand which can be used to discover whether a particular path +Each of the `cmake_path(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. -.. _HAS_ROOT_NAME: -.. _HAS_ROOT_DIRECTORY: -.. _HAS_ROOT_PATH: -.. _HAS_FILENAME: -.. _HAS_EXTENSION: -.. _HAS_STEM: -.. _HAS_RELATIVE_PART: -.. _HAS_PARENT_PATH: - -.. code-block:: cmake - +.. signature:: cmake_path(HAS_ROOT_NAME ) cmake_path(HAS_ROOT_DIRECTORY ) cmake_path(HAS_ROOT_PATH ) @@ -419,88 +410,85 @@ meaning of each path component. cmake_path(HAS_RELATIVE_PART ) cmake_path(HAS_PARENT_PATH ) -Each of the above follows the predictable pattern of setting ```` -to true if the path has the associated component, or false otherwise. -Note the following special cases: + Each of the above follows the predictable pattern of setting ```` + to true if the path has the associated component, or false otherwise. + Note the following special cases: -* For ``HAS_ROOT_PATH``, a true result will only be returned if at least one - of ``root-name`` or ``root-directory`` is non-empty. + * For ``HAS_ROOT_PATH``, a true result will only be returned if at least one + of ``root-name`` or ``root-directory`` is non-empty. -* 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 - consists of just a :ref:`filename `. - -.. _IS_ABSOLUTE: - -.. code-block:: cmake + * 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 + consists of just a :ref:`filename `. +.. signature:: cmake_path(IS_ABSOLUTE ) -Sets ```` to true if ```` is absolute. An absolute path -is a path that unambiguously identifies the location of a file without -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 -considered absolute. On other platforms, just a ``root-directory-separator`` -is sufficient. Note that this means on Windows, ``IS_ABSOLUTE`` can be -false while ``HAS_ROOT_DIRECTORY`` can be true. - -.. _IS_RELATIVE: - -.. code-block:: cmake + Sets ```` to true if ```` is absolute. An absolute path + is a path that unambiguously identifies the location of a file without + 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 + considered absolute. On other platforms, just a ``root-directory-separator`` + is sufficient. Note that this means on Windows, ``IS_ABSOLUTE`` can be + false while :cref:`HAS_ROOT_DIRECTORY` can be true. +.. signature:: cmake_path(IS_RELATIVE ) -This will store the opposite of ``IS_ABSOLUTE`` in ````. - -.. _IS_PREFIX: - -.. code-block:: cmake + This will store the opposite of :cref:`IS_ABSOLUTE` in ````. +.. signature:: cmake_path(IS_PREFIX [NORMALIZE] ) -Checks if ```` is the prefix of ````. + Checks if ```` is the prefix of ````. -When the ``NORMALIZE`` option is specified, ```` and ```` -are :ref:`normalized ` before the check. + When the ``NORMALIZE`` option is specified, ```` and ```` + are :ref:`normalized ` before the check. -.. code-block:: cmake + .. code-block:: cmake - set(path "/a/b/c") - 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 "/x/y/z" result) # result = false + set(path "/a/b/c") + 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 "/x/y/z" result) # result = false - set(path "/a/b") - cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true + set(path "/a/b") + cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true + +.. _Path Comparison: + +Comparison +^^^^^^^^^^ -.. _Path COMPARE: .. _COMPARE: -.. code-block:: cmake - +.. signature:: cmake_path(COMPARE EQUAL ) cmake_path(COMPARE NOT_EQUAL ) + :target: + COMPARE ... EQUAL + COMPARE ... NOT_EQUAL -Compares the lexical representations of two paths provided as string literals. -No normalization is performed on either path, except multiple consecutive -directory separators are effectively collapsed into a single separator. -Equality is determined according to the following pseudo-code logic: + Compares the lexical representations of two paths provided as string literals. + No normalization is performed on either path, except multiple consecutive + directory separators are effectively collapsed into a single separator. + Equality is determined according to the following pseudo-code logic: -:: + :: - if(NOT .root_name() STREQUAL .root_name()) - return FALSE + if(NOT .root_name() STREQUAL .root_name()) + return FALSE - if(.has_root_directory() XOR .has_root_directory()) - return FALSE + if(.has_root_directory() XOR .has_root_directory()) + return FALSE - Return FALSE if a relative portion of is not lexicographically - equal to the relative portion of . This comparison is performed path - component-wise. If all of the components compare equal, then return TRUE. + Return FALSE if a relative portion of is not lexicographically + equal to the relative portion of . This comparison is performed path + component-wise. If all of the components compare equal, then return TRUE. -.. note:: - Unlike most other ``cmake_path()`` subcommands, the ``COMPARE`` subcommand - takes literal strings as input, not the names of variables. + .. note:: + Unlike most other ``cmake_path()`` subcommands, the ``COMPARE`` subcommand + takes literal strings as input, not the names of variables. .. _Path Modification: @@ -508,150 +496,129 @@ Equality is determined according to the following pseudo-code logic: Modification ^^^^^^^^^^^^ -.. _cmake_path-SET: - -.. code-block:: cmake - +.. signature:: cmake_path(SET [NORMALIZE] ) -Assign the ```` path to ````. If ```` is a native -path, it is converted into a cmake-style path with forward-slashes -(``/``). On Windows, the long filename marker is taken into account. + Assigns the ```` path to ````. If ```` is a native + 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 -` after the conversion. + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + ` after the conversion. -For example: + For example: -.. code-block:: cmake + .. code-block:: cmake - set(native_path "c:\\a\\b/..\\c") - cmake_path(SET path "${native_path}") - message("CMake path is \"${path}\"") + set(native_path "c:\\a\\b/..\\c") + cmake_path(SET path "${native_path}") + message("CMake path is \"${path}\"") - cmake_path(SET path NORMALIZE "${native_path}") - message("Normalized CMake path is \"${path}\"") + cmake_path(SET path NORMALIZE "${native_path}") + message("Normalized CMake path is \"${path}\"") -Output:: + Output:: - CMake path is "c:/a/b/../c" - Normalized CMake path is "c:/a/c" - -.. _APPEND: - -.. code-block:: cmake + CMake path is "c:/a/b/../c" + Normalized CMake path is "c:/a/c" +.. signature:: cmake_path(APPEND [...] [OUTPUT_VARIABLE ]) -Append all the ```` arguments to the ```` using ``/`` as -the ``directory-separator``. Depending on the ````, the previous -contents of ```` may be discarded. For each ```` argument, -the following algorithm (pseudo-code) applies: + Appends all the ```` arguments to the ```` using ``/`` as + the ``directory-separator``. Depending on the ````, the previous + contents of ```` may be discarded. For each ```` argument, + the following algorithm (pseudo-code) applies: -:: + :: - # is the contents of + # is the contents of - if(.is_absolute() OR - (.has_root_name() AND - NOT .root_name() STREQUAL .root_name())) - replace with - return() - endif() + if(.is_absolute() OR + (.has_root_name() AND + NOT .root_name() STREQUAL .root_name())) + replace with + return() + endif() - if(.has_root_directory()) - remove any root-directory and the entire relative path from - elseif(.has_filename() OR - (NOT .has_root_directory() OR .is_absolute())) - append directory-separator to - endif() + if(.has_root_directory()) + remove any root-directory and the entire relative path from + elseif(.has_filename() OR + (NOT .has_root_directory() OR .is_absolute())) + append directory-separator to + endif() - append omitting any root-name to - -.. _APPEND_STRING: - -.. code-block:: cmake + append omitting any root-name to +.. signature:: cmake_path(APPEND_STRING [...] [OUTPUT_VARIABLE ]) -Append all the ```` arguments to the ```` without adding any -``directory-separator``. - -.. _REMOVE_FILENAME: - -.. code-block:: cmake + Appends all the ```` arguments to the ```` without adding any + ``directory-separator``. +.. signature:: cmake_path(REMOVE_FILENAME [OUTPUT_VARIABLE ]) -Removes the :ref:`filename ` component (as returned by -:ref:`GET ... FILENAME `) from ````. After removal, -any trailing ``directory-separator`` is left alone, if present. + Removes the :ref:`filename ` component (as returned by + :cref:`GET ... FILENAME`) from ````. After removal, any trailing + ``directory-separator`` is left alone, if present. -If ``OUTPUT_VARIABLE`` is not given, then after this function returns, -`HAS_FILENAME`_ returns false for ````. + If ``OUTPUT_VARIABLE`` is not given, then after this function returns, + :cref:`HAS_FILENAME` returns false for ````. -For example: + For example: -.. code-block:: cmake + .. code-block:: cmake - set(path "/a/b") - cmake_path(REMOVE_FILENAME path) - message("First path is \"${path}\"") + set(path "/a/b") + cmake_path(REMOVE_FILENAME path) + message("First path is \"${path}\"") - # filename is now already empty, the following removes nothing - cmake_path(REMOVE_FILENAME path) - message("Second path is \"${path}\"") + # filename is now already empty, the following removes nothing + cmake_path(REMOVE_FILENAME path) + message("Second path is \"${path}\"") -Output:: + Output:: - First path is "/a/" - Second path is "/a/" - -.. _REPLACE_FILENAME: - -.. code-block:: cmake + First path is "/a/" + Second path is "/a/" +.. signature:: cmake_path(REPLACE_FILENAME [OUTPUT_VARIABLE ]) -Replaces the :ref:`filename ` component from ```` -with ````. If ```` has no filename component (i.e. -`HAS_FILENAME`_ returns false), the path is unchanged. The operation is -equivalent to the following: + Replaces the :ref:`filename ` component from ```` + with ````. If ```` has no filename component (i.e. + :cref:`HAS_FILENAME` returns false), the path is unchanged. The operation is + equivalent to the following: -.. code-block:: cmake + .. code-block:: cmake - cmake_path(HAS_FILENAME path has_filename) - if(has_filename) - cmake_path(REMOVE_FILENAME path) - cmake_path(APPEND path "${input}") - endif() - -.. _REMOVE_EXTENSION: - -.. code-block:: cmake + cmake_path(HAS_FILENAME path has_filename) + if(has_filename) + cmake_path(REMOVE_FILENAME path) + cmake_path(APPEND path "${input}") + endif() +.. signature:: cmake_path(REMOVE_EXTENSION [LAST_ONLY] [OUTPUT_VARIABLE ]) -Removes the :ref:`extension `, if any, from ````. - -.. _REPLACE_EXTENSION: - -.. code-block:: cmake + Removes the :ref:`extension `, if any, from ````. +.. signature:: cmake_path(REPLACE_EXTENSION [LAST_ONLY] [OUTPUT_VARIABLE ]) -Replaces the :ref:`extension ` with ````. Its effect -is equivalent to the following: + Replaces the :ref:`extension ` with ````. Its effect + is equivalent to the following: -.. code-block:: cmake + .. code-block:: cmake - cmake_path(REMOVE_EXTENSION path) - if(NOT input MATCHES "^\\.") - cmake_path(APPEND_STRING path ".") - endif() - cmake_path(APPEND_STRING path "${input}") + cmake_path(REMOVE_EXTENSION path) + if(NOT input MATCHES "^\\.") + cmake_path(APPEND_STRING path ".") + endif() + cmake_path(APPEND_STRING path "${input}") .. _Path Generation: @@ -659,50 +626,41 @@ is equivalent to the following: Generation ^^^^^^^^^^ -.. _NORMAL_PATH: - -.. code-block:: cmake - +.. signature:: cmake_path(NORMAL_PATH [OUTPUT_VARIABLE ]) -Normalize ```` according the steps described in :ref:`Normalization`. - -.. _cmake_path-RELATIVE_PATH: -.. _RELATIVE_PATH: - -.. code-block:: cmake + Normalizes ```` according the steps described in + :ref:`Normalization`. +.. signature:: cmake_path(RELATIVE_PATH [BASE_DIRECTORY ] [OUTPUT_VARIABLE ]) -Modifies ```` to make it relative to the ``BASE_DIRECTORY`` argument. -If ``BASE_DIRECTORY`` is not specified, the default base directory will be -:variable:`CMAKE_CURRENT_SOURCE_DIR`. + Modifies ```` to make it relative to the ``BASE_DIRECTORY`` argument. + If ``BASE_DIRECTORY`` is not specified, the default base directory will be + :variable:`CMAKE_CURRENT_SOURCE_DIR`. -For reference, the algorithm used to compute the relative path is the same -as that used by C++ -`std::filesystem::path::lexically_relative -`_. - -.. _ABSOLUTE_PATH: - -.. code-block:: cmake + For reference, the algorithm used to compute the relative path is the same + as that used by C++ + `std::filesystem::path::lexically_relative + `_. +.. signature:: cmake_path(ABSOLUTE_PATH [BASE_DIRECTORY ] [NORMALIZE] [OUTPUT_VARIABLE ]) -If ```` is a relative path (`IS_RELATIVE`_ is true), it is evaluated -relative to the given base directory specified by ``BASE_DIRECTORY`` option. -If ``BASE_DIRECTORY`` is not specified, the default base directory will be -:variable:`CMAKE_CURRENT_SOURCE_DIR`. + If ```` is a relative path (:cref:`IS_RELATIVE` is true), it is + evaluated relative to the given base directory specified by ``BASE_DIRECTORY`` + option. If ``BASE_DIRECTORY`` is not specified, the default base directory + will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. -When the ``NORMALIZE`` option is specified, the path is :ref:`normalized -` after the path computation. + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + ` after the path computation. -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 -with symbolic links resolved and leading tildes expanded, use the -:command:`file(REAL_PATH)` command instead. + 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 + with symbolic links resolved and leading tildes expanded, use the + :command:`file(REAL_PATH)` command instead. Native Conversion ^^^^^^^^^^^^^^^^^ @@ -710,89 +668,79 @@ Native Conversion For commands in this section, *native* refers to the host platform, not the target platform when cross-compiling. -.. _cmake_path-NATIVE_PATH: -.. _NATIVE_PATH: - -.. code-block:: cmake - +.. signature:: cmake_path(NATIVE_PATH [NORMALIZE] ) -Converts a cmake-style ```` into a native path with -platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere). + Converts a cmake-style ```` into a native path with + platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere). -When the ``NORMALIZE`` option is specified, the path is :ref:`normalized -` before the conversion. + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + ` before the conversion. .. _CONVERT: -.. _cmake_path-TO_CMAKE_PATH_LIST: -.. _TO_CMAKE_PATH_LIST: - -.. code-block:: cmake +.. signature:: cmake_path(CONVERT TO_CMAKE_PATH_LIST [NORMALIZE]) + :target: + CONVERT ... TO_CMAKE_PATH_LIST -Converts a native ```` 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 ```` variable. + Converts a native ```` 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 ```` variable. -When the ``NORMALIZE`` option is specified, the path is :ref:`normalized -` before the conversion. + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + ` before the conversion. -.. note:: - Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand - 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 + .. note:: + Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand + takes a literal string as input, not the name of a variable. +.. signature:: cmake_path(CONVERT TO_NATIVE_PATH_LIST [NORMALIZE]) + :target: + CONVERT ... TO_NATIVE_PATH_LIST -Converts a cmake-style ```` 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 ```` variable. + Converts a cmake-style ```` 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 ```` variable. -When the ``NORMALIZE`` option is specified, the path is :ref:`normalized -` before the conversion. + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + ` before the conversion. -.. note:: - Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand - takes a literal string as input, not the name of a variable. + .. note:: + Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand + 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") - cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths) - message("Native path list is \"${native_paths}\"") + set(paths "/a/b/c" "/x/y/z") + cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST 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 ^^^^^^^ -.. _HASH: +.. signature:: + cmake_path(HASH ) -.. code-block:: cmake - - cmake_path(HASH ) - -Compute a hash value of ```` such that for two paths ``p1`` and -``p2`` that compare equal (:ref:`COMPARE ... EQUAL `), the hash -value of ``p1`` is equal to the hash value of ``p2``. The path is always -:ref:`normalized ` before the hash is computed. + Computes a hash value of ```` such that for two paths ``p1`` and + ``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 ` before the hash is computed. diff --git a/Help/command/file.rst b/Help/command/file.rst index 8a9f6e91f4..389fcc8845 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -6,17 +6,16 @@ File manipulation command. This command is dedicated to file and path manipulation requiring access to the 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. .. note:: - The sub-commands `RELATIVE_PATH`_, `TO_CMAKE_PATH`_ and `TO_NATIVE_PATH`_ has - been superseded, respectively, by sub-commands - :ref:`RELATIVE_PATH `, - :ref:`CONVERT ... TO_CMAKE_PATH_LIST ` and - :ref:`CONVERT ... TO_NATIVE_PATH_LIST ` of - :command:`cmake_path` command. + The sub-commands `RELATIVE_PATH`_, `TO_CMAKE_PATH`_, and `TO_NATIVE_PATH`_ + have been superseded, respectively, by the sub-commands + :command:`cmake_path(RELATIVE_PATH)`, + :command:`cmake_path(CONVERT ... TO_CMAKE_PATH_LIST)`, and + :command:`cmake_path(CONVERT ... TO_NATIVE_PATH_LIST)`. Synopsis ^^^^^^^^ diff --git a/Help/command/if.rst b/Help/command/if.rst index 14b199d9a5..c12ec12ce3 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -415,7 +415,7 @@ Path Comparisons ... endif() - See :ref:`cmake_path(COMPARE) ` for more details. + See :ref:`cmake_path(COMPARE) ` for more details. Variable Expansion ^^^^^^^^^^^^^^^^^^ diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 4514dbcd05..6412c23d88 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -677,7 +677,7 @@ Path Comparisons performed on either path. Returns ``1`` if the paths are equal, ``0`` otherwise. - See :ref:`cmake_path(COMPARE) ` for more details. + See :ref:`cmake_path(COMPARE) ` for more details. .. _GenEx Path Queries: @@ -720,13 +720,15 @@ All paths are expected to be in cmake-style format. .. versionadded:: 3.24 - Returns ``1`` if the path is :ref:`absolute `, ``0`` otherwise. + Returns ``1`` if the path is absolute according to + :command:`cmake_path(IS_ABSOLUTE)`, ``0`` otherwise. .. genex:: $ .. 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:: $ @@ -818,7 +820,7 @@ in cmake-style format. ``directory-separator``. Depending on the ``input``, the value of ``path`` may be discarded. - See :ref:`cmake_path(APPEND) ` for more details. + See :command:`cmake_path(APPEND)` for more details. .. genex:: $ @@ -828,7 +830,7 @@ in cmake-style format. ``$``) removed. After removal, any trailing ``directory-separator`` is left alone, if present. - See :ref:`cmake_path(REMOVE_FILENAME) ` for more details. + See :command:`cmake_path(REMOVE_FILENAME)` for more details. .. genex:: $ @@ -838,7 +840,7 @@ in cmake-style format. ``path`` has no filename component (i.e. ``$`` returns ``0``), ``path`` is unchanged. - See :ref:`cmake_path(REPLACE_FILENAME) ` for more details. + See :command:`cmake_path(REPLACE_FILENAME)` for more details. .. genex:: $ @@ -846,7 +848,7 @@ in cmake-style format. Returns ``path`` with the :ref:`extension ` removed, if any. - See :ref:`cmake_path(REMOVE_EXTENSION) ` for more details. + See :command:`cmake_path(REMOVE_EXTENSION)` for more details. .. genex:: $ @@ -855,7 +857,7 @@ in cmake-style format. Returns ``path`` with the :ref:`extension ` replaced by ``input``, if any. - See :ref:`cmake_path(REPLACE_EXTENSION) ` for more details. + See :command:`cmake_path(REPLACE_EXTENSION)` for more details. .. genex:: $ @@ -871,8 +873,7 @@ in cmake-style format. Returns ``path``, modified to make it relative to the ``base_directory`` argument. - See :ref:`cmake_path(RELATIVE_PATH) ` for more - details. + See :command:`cmake_path(RELATIVE_PATH)` for more details. .. genex:: $ @@ -885,7 +886,7 @@ in cmake-style format. When the ``NORMALIZE`` option is specified, the path is :ref:`normalized ` after the path computation. - See :ref:`cmake_path(ABSOLUTE_PATH) ` for more details. + See :command:`cmake_path(ABSOLUTE_PATH)` for more details. Shell Paths ^^^^^^^^^^^