From 6592b8ac1467b3fd5e63f6b7092e056275d91a97 Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Thu, 12 Feb 2026 12:50:51 -0500 Subject: [PATCH] Help/cmake_path: Clarify output variable behavior Add explicit cross-references for commands which optionally take an output variable (otherwise modifying their input in-place) for clarity. Note that `cmake_path` should not be used to modify variables reserved by CMake. Improve references to the "CMake-style" semicolon-separated lists, and apply those corresponding changes to the `file` command page. --- Help/command/cmake_path.rst | 70 ++++++++++++++++++++++++++++--------- Help/command/file.rst | 6 ++-- 2 files changed, 57 insertions(+), 19 deletions(-) diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index 3fc3b7cc26..5fb0ef1f51 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -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 ```` 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 ````, + and only as the ```` when a separate ```` 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) `_ 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 [NORMALIZE] ) Assigns the ```` path to ````. If ```` 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 omitting any root-name to + See :ref:`Creating a Path Variable` for details on the output variable. + .. signature:: cmake_path(APPEND_STRING [...] [OUTPUT_VARIABLE ]) Appends all the ```` arguments to the ```` without adding any ``directory-separator``. + See :ref:`Creating a Path Variable` for details on the output variable. + .. signature:: cmake_path(REMOVE_FILENAME [OUTPUT_VARIABLE ]) @@ -563,8 +578,8 @@ Modification :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, - :cref:`HAS_FILENAME` returns false for ````. + :cref:`HAS_FILENAME` will return false for the result, whether stored in + ```` or ````. 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 [OUTPUT_VARIABLE ]) @@ -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 [LAST_ONLY] [OUTPUT_VARIABLE ]) Removes the :ref:`extension `, if any, from ````. + See :ref:`Creating a Path Variable` for details on the output variable. + .. signature:: cmake_path(REPLACE_EXTENSION [LAST_ONLY] [OUTPUT_VARIABLE ]) @@ -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 ```` according the steps described in :ref:`Normalization`. + See :ref:`Creating a Path Variable` for details on the output variable. + .. signature:: cmake_path(RELATIVE_PATH [BASE_DIRECTORY ] [OUTPUT_VARIABLE ]) @@ -645,6 +670,8 @@ Generation `std::filesystem::path::lexically_relative `_. + See :ref:`Creating a Path Variable` for details on the output variable. + .. signature:: cmake_path(ABSOLUTE_PATH [BASE_DIRECTORY ] [NORMALIZE] [OUTPUT_VARIABLE ]) @@ -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 [NORMALIZE] ) - Converts a cmake-style ```` into a native path with + 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. + 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 ```` path into a cmake-style path with forward - slashes (``/``). On Windows hosts, the long filename marker is taken into + 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. + ``$ENV{PATH}``. A search path will be converted to a + :ref:`semicolon-separated list ` (on non-Windows + platforms, this essentially means ``:`` separators are replaced with ``;``). When the ``NORMALIZE`` option is specified, the path is :ref:`normalized ` 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 ```` path into a native path with + 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. + + The input can be a single path or a :ref:`semicolon-separated list + `. 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 ` 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 ` before the hash is computed. + + See :ref:`Creating a Path Variable` for details on the output variable. diff --git a/Help/command/file.rst b/Help/command/file.rst index 75335dce98..9334fa0a57 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -710,12 +710,12 @@ Path Conversion file(TO_CMAKE_PATH "" ) file(TO_NATIVE_PATH "" ) - The ``TO_CMAKE_PATH`` mode converts a native ```` into a cmake-style + The ``TO_CMAKE_PATH`` mode converts a native ```` 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 `. - The ``TO_NATIVE_PATH`` mode converts a cmake-style ```` into a native + The ``TO_NATIVE_PATH`` mode converts a CMake-style ```` into a native path with platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere).