Skip to content

GitLab

Commit 52536344 authored by Craig Scott's avatar Craig Scott Committed by Kitware Robot
Browse files
Options

Merge topic 'cmake_path-stabilization' 

76cea3df cmake_path: rename 'GET ... RELATIVE_PATH' to 'GET ... RELATIVE_PART'
Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Merge-request: !5743
parents 36bb0e32 76cea3df
Hide whitespace changes
Inline Side-by-side
Showing with 76 additions and 97 deletions
Help/command/cmake_path.rst
View file @ 52536344
......@@ -36,7 +36,7 @@ Synopsis
cmake_path(`GET`_ <path-var> :ref:`FILENAME <GET_FILENAME>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`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> :ref:`RELATIVE_PATH <GET_RELATIVE_PATH>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`RELATIVE_PART <GET_RELATIVE_PART>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`PARENT_PATH <GET_PARENT_PATH>` <out-var>)
`Query`_
......@@ -46,7 +46,7 @@ Synopsis
cmake_path(`HAS_FILENAME`_ <path-var> <out-var>)
cmake_path(`HAS_EXTENSION`_ <path-var> <out-var>)
cmake_path(`HAS_STEM`_ <path-var> <out-var>)
cmake_path(`HAS_RELATIVE_PATH`_ <path-var> <out-var>)
cmake_path(`HAS_RELATIVE_PART`_ <path-var> <out-var>)
cmake_path(`HAS_PARENT_PATH`_ <path-var> <out-var>)
cmake_path(`IS_ABSOLUTE`_ <path-var> <out-var>)
cmake_path(`IS_RELATIVE`_ <path-var> <out-var>)
......@@ -161,7 +161,9 @@ constraints):
The *stem* is the part of the ``filename`` before the extension.
Some commands refer to a ``root-path``. This is the concatenation of
``root-name`` and ``root-directory``, either or both of which can be empty.
``root-name`` and ``root-directory-separator``, either or both of which can
be empty. A ``relative-part`` refers to the full path with any ``root-path``
removed.
Creating A Path Variable
......@@ -224,10 +226,12 @@ Decomposition
.. _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.
`Path Structure And Terminology`_ defines the meaning of each path component.
component or group of components from a path. See
`Path Structure And Terminology`_ for the meaning of each path component.
::
......@@ -237,12 +241,19 @@ component or group of components from a path.
cmake_path(GET <path-var> FILENAME <out-var>)
cmake_path(GET <path-var> EXTENSION [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> PARENT_PATH <out-var>)
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
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 ``<path-var>``. 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
``<path-var>`` with one less element.
Root examples
"""""""""""""
......@@ -332,53 +343,31 @@ Extension and stem examples
.some.more extension is ".more"
.some.more stem is ".some"
Relative paths
""""""""""""""
Two other forms of the ``GET`` subcommand interpret a path and return
another path derived from it.
.. _GET_RELATIVE_PATH:
::
cmake_path(GET <path-var> RELATIVE_PATH <out-var>)
Returns the path with any ``root-name`` and ``root-directory-separator``
removed. This leaves just the part of the path relative to the root
directory (or put another way, every component of ``<path-var>`` after
``root-path``). If ``<path-var>`` is an empty path, it returns an empty
path.
For example:
Relative part examples
""""""""""""""""""""""
.. code-block:: cmake
set(path "/a/b")
cmake_path(GET path RELATIVE_PATH result)
message("Relative path is \"${result}\"")
set(path "/")
cmake_path(GET path RELATIVE_PATH result)
message("Relative path is \"${result}\"")
Output::
Relative path is "a/b"
Relative path is ""
set(path "c:/a/b")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")
.. _GET_PARENT_PATH:
set(path "c/d")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")
The other form returns the parent of the path::
set(path "/")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")
cmake_path(GET <path-var> PARENT_PATH <out-var>)
::
If the `HAS_RELATIVE_PATH`_ sub-command returns false, the result is a
copy of ``<path-var>``. Otherwise, the result is ``<path-var>`` with
one fewer element.
Relative part is "a/b"
Relative part is "c/d"
Relative part is ""
For example:
Path traversal examples
"""""""""""""""""""""""
.. code-block:: cmake
......@@ -390,17 +379,18 @@ For example:
cmake_path(GET path PARENT_PATH result)
message("Parent path is \"${result}\"")
Output::
::
Parent path is "c:/a"
Relative path is "c:/"
Parent path is "c:/"
Query
^^^^^
Most of the ``GET`` subcommands also have corresponding ``HAS_...``
subcommands which can be used to discover whether a particular path
component is present. `Path Structure And Terminology`_ defines the
Each of the ``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:
......@@ -409,6 +399,8 @@ meaning of each path component.
.. _HAS_FILENAME:
.. _HAS_EXTENSION:
.. _HAS_STEM:
.. _HAS_RELATIVE_PART:
.. _HAS_PARENT_PATH:
::
......@@ -418,32 +410,19 @@ meaning of each path component.
cmake_path(HAS_FILENAME <path-var> <out-var>)
cmake_path(HAS_EXTENSION <path-var> <out-var>)
cmake_path(HAS_STEM <path-var> <out-var>)
cmake_path(HAS_RELATIVE_PART <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>``
to true if the path has the associated component, or false otherwise.
In the case of ``HAS_ROOT_PATH``, a true result will only be returned if
at least one of ``root-name`` or ``root-directory`` is non-empty.
.. _HAS_RELATIVE_PATH:
Note the following special cases:
::
cmake_path(HAS_RELATIVE_PATH <path-var> <out-var>)
A relative path in this context means everything after the ``root-path``,
if present. This command sets ``<out-var>`` to true if there is at least
one ``item-name`` or ``filename`` in the path.
.. _HAS_PARENT_PATH:
::
cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
* For ``HAS_ROOT_PATH``, a true result will only be returned if at least one
of ``root-name`` or ``root-directory`` is non-empty.
This command sets ``<out-var>`` to true if ``<path-var>`` has parent path.
Note that 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 <FILENAME_DEF>`.
* 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 <FILENAME_DEF>`.
.. _IS_ABSOLUTE:
......
Source/cmCMakePathCommand.cxx
View file @ 52536344
......@@ -194,7 +194,7 @@ bool HandleGetCommand(std::vector<std::string> const& args,
}
return path.GetNarrowStem();
} },
{ "RELATIVE_PATH"_s,
{ "RELATIVE_PART"_s,
[](const cmCMakePath& path, bool) -> cmCMakePath {
return path.GetRelativePath();
} },
......@@ -817,7 +817,7 @@ bool HandleHasStemCommand(std::vector<std::string> const& args,
[](const cmCMakePath& path) -> bool { return path.HasStem(); });
}
bool HandleHasRelativePathCommand(std::vector<std::string> const& args,
bool HandleHasRelativePartCommand(std::vector<std::string> const& args,
cmExecutionStatus& status)
{
return HandleHasItemCommand(
......@@ -986,7 +986,7 @@ bool cmCMakePathCommand(std::vector<std::string> const& args,
{ "HAS_FILENAME"_s, HandleHasFilenameCommand },
{ "HAS_EXTENSION"_s, HandleHasExtensionCommand },
{ "HAS_STEM"_s, HandleHasStemCommand },
{ "HAS_RELATIVE_PATH"_s, HandleHasRelativePathCommand },
{ "HAS_RELATIVE_PART"_s, HandleHasRelativePartCommand },
{ "HAS_PARENT_PATH"_s, HandleHasParentPathCommand },
{ "IS_ABSOLUTE"_s, HandleIsAbsoluteCommand },
{ "IS_RELATIVE"_s, HandleIsRelativeCommand },
......
Tests/RunCMake/cmake_path/GET.cmake
View file @ 52536344
......@@ -61,9 +61,9 @@ if (NOT output STREQUAL "cc.ext1")
list (APPEND errors "STEM LAST_ONLY returns bad data: ${output}")
endif()
cmake_path(GET path RELATIVE_PATH output)
cmake_path(GET path RELATIVE_PART output)
if (NOT output STREQUAL "aa/bb/cc.ext1.ext2")
list (APPEND errors "RELATIVE_PATH returns bad data: ${output}")
list (APPEND errors "RELATIVE_PART returns bad data: ${output}")
endif()
cmake_path(GET path PARENT_PATH output)
......@@ -112,9 +112,9 @@ if (NOT output STREQUAL "")
list (APPEND errors "STEM returns bad data: ${output}")
endif()
cmake_path(GET path RELATIVE_PATH output)
cmake_path(GET path RELATIVE_PART output)
if (NOT output STREQUAL path)
list (APPEND errors "RELATIVE_PATH returns bad data: ${output}")
list (APPEND errors "RELATIVE_PART returns bad data: ${output}")
endif()
cmake_path(GET path PARENT_PATH output)
......@@ -173,9 +173,9 @@ if (NOT output STREQUAL "")
list (APPEND errors "STEM returns bad data: ${output}")
endif()
cmake_path(GET path RELATIVE_PATH output)
cmake_path(GET path RELATIVE_PART output)
if (NOT output STREQUAL "")
list (APPEND errors "RELATIVE_PATH returns bad data: ${output}")
list (APPEND errors "RELATIVE_PART returns bad data: ${output}")
endif()
cmake_path(GET path PARENT_PATH output)
......
Tests/RunCMake/cmake_path/HAS_ITEM.cmake
View file @ 52536344
......@@ -96,14 +96,14 @@ if (output)
endif()
set (path "/a/b")
cmake_path(HAS_RELATIVE_PATH path output)
cmake_path(HAS_RELATIVE_PART path output)
if (NOT output)
list (APPEND errors "RELATIVE_PATH: ${path} does not have relative path")
list (APPEND errors "RELATIVE_PART: ${path} does not have relative part")
endif()
set (path "/")
cmake_path(HAS_RELATIVE_PATH path output)
cmake_path(HAS_RELATIVE_PART path output)
if (output)
list (APPEND errors "RELATIVE_PATH: ${path} has relative path")
list (APPEND errors "RELATIVE_PART: ${path} has relative part")
endif()
set (path "/a/b")
......@@ -180,21 +180,21 @@ if (WIN32)
endif()
set (path "c:/a/b")
cmake_path(HAS_RELATIVE_PATH path output)
cmake_path(HAS_RELATIVE_PART path output)
if (NOT output)
list (APPEND errors "RELATIVE_PATH: ${path} does not have relative path")
list (APPEND errors "RELATIVE_PART: ${path} does not have relative part")
endif()
set (path "c:a/b")
cmake_path(HAS_RELATIVE_PATH path output)
cmake_path(HAS_RELATIVE_PART path output)
if (NOT output)
list (APPEND errors "RELATIVE_PATH: ${path} does not have relative path")
list (APPEND errors "RELATIVE_PART: ${path} does not have relative part")
endif()
set (path "//host/b")
cmake_path(HAS_RELATIVE_PATH path output)
cmake_path(HAS_RELATIVE_PART path output)
if (NOT output)
list (APPEND errors "RELATIVE_PATH: ${path} does not have relative path")
list (APPEND errors "RELATIVE_PART: ${path} does not have relative part")
endif()
set (path "c:/a/b")
......
Tests/RunCMake/cmake_path/RunCMakeTest.cmake
View file @ 52536344
......@@ -7,7 +7,7 @@ set (RunCMake-stderr-file "wrong-path-stderr.txt")
### GET sub-command
foreach (subcommand IN ITEMS ROOT_NAME ROOT_DIRECTORY ROOT_PATH FILENAME EXTENSION
STEM RELATIVE_PATH PARENT_PATH)
STEM RELATIVE_PART PARENT_PATH)
run_cmake_command (GET-${subcommand}-wrong-path "${CMAKE_COMMAND}" "-DCMAKE_PATH_ARGUMENTS=GET wrong_path ${subcommand} output" -P "${RunCMake_SOURCE_DIR}/call-cmake_path.cmake")
endforeach()
......@@ -20,7 +20,7 @@ endforeach()
foreach (command IN ITEMS NATIVE_PATH
HAS_ROOT_NAME HAS_ROOT_DIRECTORY HAS_ROOT_PATH
HAS_FILENAME HAS_EXTENSION HAS_STEM
HAS_RELATIVE_PATH HAS_PARENT_PATH
HAS_RELATIVE_PART HAS_PARENT_PATH
IS_ABSOLUTE IS_RELATIVE IS_PREFIX HASH)
if (command STREQUAL "IS_PREFIX")
set (extra_args path2)
......@@ -36,7 +36,7 @@ set (RunCMake-stderr-file "missing-output-stderr.txt")
### GET sub-command
foreach (subcommand IN ITEMS ROOT_NAME ROOT_DIRECTORY ROOT_PATH FILENAME EXTENSION
STEM RELATIVE_PATH PARENT_PATH)
STEM RELATIVE_PART PARENT_PATH)
run_cmake_command (GET-${subcommand}-missing-output "${CMAKE_COMMAND}" "-DCMAKE_PATH_ARGUMENTS=GET path ${subcommand}" -P "${RunCMake_SOURCE_DIR}/call-cmake_path.cmake")
endforeach()
......@@ -53,7 +53,7 @@ endforeach()
foreach (command IN ITEMS SET NATIVE_PATH
HAS_ROOT_NAME HAS_ROOT_DIRECTORY HAS_ROOT_PATH
HAS_FILENAME HAS_EXTENSION HAS_STEM
HAS_RELATIVE_PATH HAS_PARENT_PATH
HAS_RELATIVE_PART HAS_PARENT_PATH
IS_ABSOLUTE IS_RELATIVE IS_PREFIX HASH)
if (command STREQUAL "IS_PREFIX")
set (extra_args path2)
......@@ -79,7 +79,7 @@ set (RunCMake-stderr-file "invalid-output-var-stderr.txt")
### GET sub-command
foreach (subcommand IN ITEMS ROOT_NAME ROOT_DIRECTORY ROOT_PATH FILENAME EXTENSION
STEM RELATIVE_PATH PARENT_PATH)
STEM RELATIVE_PART PARENT_PATH)
run_cmake_command (GET-${subcommand}-invalid-output "${CMAKE_COMMAND}" "-DCMAKE_PATH_ARGUMENTS=GET path ${subcommand}" -DCHECK_INVALID_OUTPUT=ON -P "${RunCMake_SOURCE_DIR}/call-cmake_path.cmake")
endforeach()
......@@ -96,7 +96,7 @@ endforeach()
foreach (command IN ITEMS NATIVE_PATH
HAS_ROOT_NAME HAS_ROOT_DIRECTORY HAS_ROOT_PATH
HAS_FILENAME HAS_EXTENSION HAS_STEM
HAS_RELATIVE_PATH HAS_PARENT_PATH
HAS_RELATIVE_PART HAS_PARENT_PATH
IS_ABSOLUTE IS_RELATIVE IS_PREFIX HASH)
if (command STREQUAL "IS_PREFIX")
set (extra_args path2)
......@@ -118,7 +118,7 @@ set (RunCMake-stderr-file "unexpected-arg-stderr.txt")
### GET sub-command
foreach (subcommand IN ITEMS ROOT_NAME ROOT_DIRECTORY ROOT_PATH FILENAME EXTENSION
STEM RELATIVE_PATH PARENT_PATH)
STEM RELATIVE_PART PARENT_PATH)
if (subcommand STREQUAL "EXTENSION" OR subcommand STREQUAL "STEM")
set (extra_args LAST_ONLY)
else()
......@@ -146,7 +146,7 @@ endforeach()
foreach (command IN ITEMS SET NATIVE_PATH
HAS_ROOT_NAME HAS_ROOT_DIRECTORY HAS_ROOT_PATH
HAS_FILENAME HAS_EXTENSION HAS_STEM
HAS_RELATIVE_PATH HAS_PARENT_PATH
HAS_RELATIVE_PART HAS_PARENT_PATH
IS_ABSOLUTE IS_RELATIVE IS_PREFIX
HASH)
if (command STREQUAL "IS_PREFIX")
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment