Merge topic 'cmake_path'

eb583b0a66 cmake_path command: path management
212e953d35 cmCMakePath: Class for path handling

Acked-by: Kitware Robot <[email protected]>
Acked-by: Ben Boeckel <[email protected]>
Acked-by: Raul Tambre <[email protected]>
Merge-request: !5158

Help/command/cmake_path.rst

@@ -0,0 +1,641 @@
+cmake_path
+----------
+
+.. versionadded:: 3.19
+
+Filesystem path manipulation command.
+
+This command is dedicated to the manipulation of objects of type path which
+represent paths on a filesystem. Only syntactic aspects of paths are handled:
+the pathname may represent a non-existing path or even one that is not allowed
+to exist on the current file system or OS.
+
+For operations involving the filesystem, have a look at the :command:`file`
+command.
+
+The path name has the following syntax:
+
+1. ``root-name`` (optional): identifies the root on a filesystem with multiple
+   roots (such as ``"C:"`` or ``"//myserver"``).
+
+2. ``root-directory`` (optional): a directory separator that, if present, marks
+   this path as absolute. If it is missing (and the first element other than
+   the root name is a file name), then the path is relative.
+
+Zero or more of the following:
+
+3. ``file-name``: sequence of characters that aren't directory separators. This
+   name may identify a file, a hard link, a symbolic link, or a directory. Two
+   special file-names are recognized:
+
+     * ``dot``: the file name consisting of a single dot character ``.`` is a
+       directory name that refers to the current directory.
+
+     * ``dot-dot``: the file name consisting of two dot characters ``..`` is a
+       directory name that refers to the parent directory.
+
+4. ``directory-separator``: the forward slash character ``/``. If this
+   character is repeated, it is treated as a single directory separator:
+   ``/usr///////lib`` is the same as ``/usr/lib``.
+
+.. _EXTENSION_DEF:
+
+A ``file-name`` can have an extension. By default, the extension is defined as
+the sub-string beginning at the leftmost period (including the period) and
+until the end of the pathname. When the option ``LAST_ONLY`` is specified, the
+extension is the sub-string beginning at the rightmost period.
+
+.. note::
+
+  ``cmake_path`` command handles paths in the format of the build system, not
+  the target system. So this is not generally applicable to the target system
+  in cross-compiling environment.
+
+For all commands, ``<path>`` placeholder expect a variable name. An error will
+be raised if the variable does not exist, except for `APPEND`_ and
+`CMAKE_PATH`_ sub-commands. ``<input>`` placeholder expect a string literal.
+``[<input>...]`` placeholder expect zero or more arguments. ``<output>``
+placeholder expect a variable name.
+
+.. note::
+
+  ``cmake_path`` command does not support list of paths. The ``<path>``
+  placeholder must store only one path name.
+
+To initialize a path variable, three possibilities can be used:
+
+1. :command:`set` command.
+2. :ref:`cmake_path(APPEND) <APPEND>` command. Can be used to build a path from
+   already available path fragments.
+3. :ref:`cmake_path(CMAKE_PATH) <CMAKE_PATH>` command. Mainly used to build a
+   path variable from a native path.
+
+  .. code-block:: cmake
+
+    # To build the path "${CMAKE_CURRENT_SOURCE_DIR}/data"
+
+    set (path1 "${CMAKE_CURRENT_SOURCE_DIR}/data")
+
+    cmake_path(APPEND path2 "${CMAKE_CURRENT_SOURCE_DIR}" "data")
+
+    cmake_path(CMAKE_PATH path3 "${CMAKE_CURRENT_SOURCE_DIR}/data")
+
+`Modification`_ and `Generation`_ sub-commands store the result in-place or in
+the variable specified by  ``OUTPUT_VARIABLE`` option. All other sub-commands,
+except `CMAKE_PATH`_, store the result in the required ``<output>`` variable.
+
+Sub-commands supporting ``NORMALIZE`` option will :ref:`normalize <NORMAL_PATH>`
+the path.
+
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  `Decomposition`_
+    cmake_path(`GET`_ <path> :ref:`ROOT_NAME <GET_ROOT_NAME>` <output>)
+    cmake_path(`GET`_ <path> :ref:`ROOT_DIRECTORY <GET_ROOT_DIRECTORY>` <output>)
+    cmake_path(`GET`_ <path> :ref:`ROOT_PATH <GET_ROOT_PATH>` <output>)
+    cmake_path(`GET`_ <path> :ref:`FILENAME <GET_FILENAME>` <output>)
+    cmake_path(`GET`_ <path> :ref:`EXTENSION <GET_EXTENSION>` [LAST_ONLY] <output>)
+    cmake_path(`GET`_ <path> :ref:`STEM <GET_STEM>` [LAST_ONLY] <output>)
+    cmake_path(`GET`_ <path> :ref:`RELATIVE_PATH <GET_RELATIVE_PATH>` <output>)
+    cmake_path(`GET`_ <path> :ref:`PARENT_PATH <GET_PARENT_PATH>` <output>)
+
+  `Modification`_
+    cmake_path(`APPEND`_ <path> [<input>...] [OUTPUT_VARIABLE <output>])
+    cmake_path(`CONCAT`_ <path> [<input>...] [OUTPUT_VARIABLE <output>])
+    cmake_path(`REMOVE_FILENAME`_ <path> [OUTPUT_VARIABLE <output>])
+    cmake_path(`REPLACE_FILENAME`_ <path> <input> [OUTPUT_VARIABLE <output>])
+    cmake_path(`REMOVE_EXTENSION`_ <path> [LAST_ONLY]
+                                       [OUTPUT_VARIABLE <output>])
+    cmake_path(`REPLACE_EXTENSION`_ <path> [LAST_ONLY] <input>
+                                        [OUTPUT_VARIABLE <output>])
+
+  `Generation`_
+    cmake_path(`NORMAL_PATH`_ <path> [OUTPUT_VARIABLE <output>])
+    cmake_path(`RELATIVE_PATH`_ <path> [BASE_DIRECTORY <path>]
+                                    [OUTPUT_VARIABLE <output>])
+    cmake_path(`PROXIMATE_PATH`_ <path> [BASE_DIRECTORY <path>]
+                                     [OUTPUT_VARIABLE <output>])
+    cmake_path(`ABSOLUTE_PATH`_ <path> [BASE_DIRECTORY <path>] [NORMALIZE]
+                                    [OUTPUT_VARIABLE <output>])
+
+  `Conversion`_
+    cmake_path(`CMAKE_PATH`_ <path> [NORMALIZE] <input>)
+    cmake_path(`NATIVE_PATH`_ <path> [NORMALIZE] <output>)
+    cmake_path(`CONVERT`_ <input> `TO_CMAKE_PATH_LIST`_ <output>)
+    cmake_path(`CONVERT`_ <input> `TO_NATIVE_PATH_LIST`_ <output>)
+
+  `Comparison`_
+    cmake_path(`COMPARE`_ <path> <OP> <input> <output>)
+
+  `Query`_
+    cmake_path(`HAS_ROOT_NAME`_ <path> <output>)
+    cmake_path(`HAS_ROOT_DIRECTORY`_ <path> <output>)
+    cmake_path(`HAS_ROOT_PATH`_ <path> <output>)
+    cmake_path(`HAS_FILENAME`_ <path> <output>)
+    cmake_path(`HAS_EXTENSION`_ <path> <output>)
+    cmake_path(`HAS_STEM`_ <path> <output>)
+    cmake_path(`HAS_RELATIVE_PATH`_ <path> <output>)
+    cmake_path(`HAS_PARENT_PATH`_ <path> <output>)
+    cmake_path(`IS_ABSOLUTE`_ <path> <output>)
+    cmake_path(`IS_RELATIVE`_ <path> <output>)
+    cmake_path(`IS_PREFIX`_ <path> <input> [NORMALIZE] <output>)
+
+  `Hashing`_
+    cmake_path(`HASH`_ <path> [NORMALIZE] <output>)
+
+Decomposition
+^^^^^^^^^^^^^
+
+.. _GET:
+.. _GET_ROOT_NAME:
+
+.. code-block:: cmake
+
+  cmake_path(GET <path> ROOT_NAME <output>)
+
+Returns the root name of the path. If the path does not include a root name,
+returns an empty path.
+
+.. _GET_ROOT_DIRECTORY:
+
+.. code-block:: cmake
+
+  cmake_path(GET <path> ROOT_DIRECTORY <output>)
+
+Returns the root directory of the path. If the path does not include a root
+directory, returns an empty path.
+
+.. _GET_ROOT_PATH:
+
+.. code-block:: cmake
+
+  cmake_path(GET <path> ROOT_PATH <output>)
+
+Returns the root path of the path. If the path does not include a root path,
+returns an empty path.
+
+Effectively, returns the following: ``root-name / root-directory``.
+
+.. _GET_FILENAME:
+
+.. code-block:: cmake
+
+  cmake_path(GET <path> FILENAME <output>)
+
+Returns the filename component of the path. If the path ends with a
+``directory-separator``, there is no filename, so returns an empty path.
+
+.. _GET_EXTENSION:
+
+.. code-block:: cmake
+
+  cmake_path(GET <path> EXTENSION [LAST_ONLY] <output>)
+
+Returns the :ref:`extension <EXTENSION_DEF>` of the filename component.
+
+If the ``FILENAME`` component of the path contains a period (``.``), and is not
+one of the special filesystem elements ``dot`` or ``dot-dot``, then the
+:ref:`extension <EXTENSION_DEF>` is returned.
+
+  .. code-block:: cmake
+
+    set (path "name.ext1.ext2")
+    cmake_path (GET path EXTENSION result)
+    cmake_path (GET path EXTENSION LAST_ONLY result)
+
+First extension extraction will return ``.ex1.ext2``, while the second one will
+return only ``.ext2``.
+
+The following exceptions apply:
+
+  * If the first character in the filename is a period, that period is ignored
+    (a filename like ``".profile"`` is not treated as an extension).
+
+  * If the pathname is either ``.`` or ``..``, or if ``FILENAME`` component
+    does not contain the ``.`` character, then an empty path is returned.
+
+.. _GET_STEM:
+
+.. code-block:: cmake
+
+  cmake_path(GET <path> STEM [LAST_ONLY] <output>)
+
+Returns the ``FILENAME`` component of the path stripped of its
+:ref:`extension <EXTENSION_DEF>`.
+
+  .. code-block:: cmake
+
+    set (path "name.ext1.ext2")
+    cmake_path (GET path STEM result)
+    cmake_path (GET path STEM LAST_ONLY result)
+
+First stem extraction will return only ``name``, while the second one will
+return ``name.ext1``.
+
+The following exceptions apply:
+
+  * If the first character in the filename is a period, that period is ignored
+    (a filename like ``".profile"`` is not treated as an extension).
+
+  * If the filename is one of the special filesystem components ``dot`` or
+    ``dot-dot``, or if it has no periods, the function returns the entire
+    ``FILENAME`` component.
+
+.. _GET_RELATIVE_PATH:
+
+.. code-block:: cmake
+
+  cmake_path(GET <path> RELATIVE_PATH <output>)
+
+Returns path relative to ``root-path``, that is, a pathname composed of
+every component of ``<path>`` after ``root-path``. If ``<path>`` is an empty
+path, returns an empty path.
+
+.. _GET_PARENT_PATH:
+
+.. code-block:: cmake
+
+  cmake_path(GET <path> PARENT_PATH <output>)
+
+Returns the path to the parent directory.
+
+If `HAS_RELATIVE_PATH`_ sub-command returns false, the result is a copy of
+``<path>``. Otherwise, the result is ``<path>`` with one fewer element.
+
+Modification
+^^^^^^^^^^^^
+
+.. _APPEND:
+
+.. code-block:: cmake
+
+    cmake_path(APPEND <path> [<input>...] [OUTPUT_VARIABLE <output>])
+
+Append all the ``<input>`` arguments to the ``<path>`` using ``/`` as
+``directory-separator``.
+
+For each ``<input>`` argument, the following algorithm (pseudo-code) applies:
+
+  .. code-block:: cmake
+
+    IF (<input>.is_absolute() OR
+         (<input>.has_root_name() AND
+          NOT <input>.root_name() STREQUAL <path>.root_name()))
+      replaces <path> with <input>
+      RETURN()
+    ENDIF()
+
+    IF (<input>.has_root_directory())
+      remove any root-directory and the entire relative path from <path>
+    ELSEIF (<path>.has_filename() OR
+             (NOT <path>.has_root_directory() OR <path>.is_absolute()))
+      appends directory-separator to <path>
+    ENDIF()
+
+    appends <input> omitting any root-name to <path>
+
+.. _CONCAT:
+
+.. code-block:: cmake
+
+    cmake_path(CONCAT <path> [<input>...] [OUTPUT_VARIABLE <output>])
+
+Concatenates all the ``<input>`` arguments to the ``<path>`` without
+``directory-separator``.
+
+.. _REMOVE_FILENAME:
+
+.. code-block:: cmake
+
+    cmake_path(REMOVE_FILENAME <path> [OUTPUT_VARIABLE <output>])
+
+Removes a single filename component (as returned by
+:ref:`GET ... FILENAME <GET_FILENAME>`) from ``<path>``.
+
+After this function returns, if change is done in-place, `HAS_FILENAME`_
+returns false for ``<path>``.
+
+.. _REPLACE_FILENAME:
+
+.. code-block:: cmake
+
+    cmake_path(REPLACE_FILENAME <path> <input> [OUTPUT_VARIABLE <output>])
+
+Replaces a single filename component from ``<path>`` with ``<input>``.
+
+Equivalent to the following:
+
+  .. code-block:: cmake
+
+    cmake_path(REMOVE_FILENAME path)
+    cmake_path(APPEND path "replacement");
+
+If ``<path>`` has no filename component (`HAS_FILENAME`_ returns false), the
+path is unchanged.
+
+.. _REMOVE_EXTENSION:
+
+.. code-block:: cmake
+
+    cmake_path(REMOVE_EXTENSION <path> [LAST_ONLY] [OUTPUT_VARIABLE <output>])
+
+Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path>``.
+
+.. _REPLACE_EXTENSION:
+
+.. code-block:: cmake
+
+    cmake_path(REPLACE_EXTENSION <path> [LAST_ONLY] <input>
+                                 [OUTPUT_VARIABLE <output>])
+
+Replaces the :ref:`extension <EXTENSION_DEF>` with ``<input>``.
+
+First, if ``<path>`` has an :ref:`extension <EXTENSION_DEF>` (`HAS_EXTENSION`_
+is true), it is removed. Then, a ``dot`` character is appended to ``<path>``,
+if ``<input>`` is not empty or does not begin with a ``dot`` character.
+
+Then ``<input>`` is appended as if `CONCAT`_ was used.
+
+Generation
+^^^^^^^^^^
+
+.. _NORMAL_PATH:
+
+.. code-block:: cmake
+
+    cmake_path(NORMAL_PATH <path> [OUTPUT_VARIABLE <output>])
+
+Normalize ``<path>``.
+
+A path can be normalized by following this algorithm:
+
+  1. If the path is empty, stop (normal form of an empty path is an empty
+     path).
+  2. Replace each ``directory-separator`` (which may consist of multiple
+     separators) with a single ``/``.
+  3. Replace each ``directory-separator`` character in the ``root-name`` with
+     ``/``.
+  4. Remove each ``dot`` and any immediately following ``directory-separator``.
+  5. Remove each non-dot-dot filename immediately followed by a
+     ``directory-separator`` and a ``dot-dot``, along with any immediately
+     following ``directory-separator``.
+  6. If there is ``root-directory``, remove all ``dot-dots`` and any
+     ``directory-separators`` immediately following them.
+  7. If the last filename is ``dot-dot``, remove any trailing
+     ``directory-separator``.
+  8. If the path is empty, add a ``dot`` (normal form of ``./`` is ``.``).
+
+.. _cmake_path-RELATIVE_PATH:
+.. _RELATIVE_PATH:
+
+.. code-block:: cmake
+
+    cmake_path(RELATIVE_PATH <path> [BASE_DIRECTORY <path>]
+                             [OUTPUT_VARIABLE <output>])
+
+Returns ``<path>`` made relative to ``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 described
+`here <https://en.cppreference.com/w/cpp/filesystem/path/lexically_normal>`_.
+
+.. _PROXIMATE_PATH:
+
+.. code-block:: cmake
+
+    cmake_path(PROXIMATE_PATH <path> [BASE_DIRECTORY <path>]
+                              [OUTPUT_VARIABLE <output>])
+
+If the value of `RELATIVE_PATH`_ is not an empty path, return
+it. Otherwise return ``<path>``.
+
+If ``BASE_DIRECTORY`` is not specified, the default base directory will be
+:variable:`CMAKE_CURRENT_SOURCE_DIR`.
+
+.. _ABSOLUTE_PATH:
+
+.. code-block:: cmake
+
+    cmake_path(ABSOLUTE_PATH <path> [BASE_DIRECTORY <path>] [NORMALIZE]
+                             [OUTPUT_VARIABLE <output>])
+
+If ``<path>`` is a relative path, it is evaluated relative to the given base
+directory specified by ``BASE_DIRECTORY`` option. If no base directory is
+provided, the default base directory will be
+:variable:`CMAKE_CURRENT_SOURCE_DIR`.
+
+When ``NORMALIZE`` option is specified, the path is :ref:`normalized
+<NORMAL_PATH>` after the path computation.
+
+Because ``cmake_path`` does not access to the filesystem, symbolic links are
+not resolved. To compute a real path, use :command:`get_filename_component`
+command with ``REALPATH`` sub-command.
+
+Conversion
+^^^^^^^^^^
+
+.. _cmake_path-CMAKE_PATH:
+.. _CMAKE_PATH:
+
+.. code-block:: cmake
+
+    cmake_path(CMAKE_PATH <path> [NORMALIZE] <input>])
+
+Converts a native ``<input>`` path into cmake-style path with forward-slashes
+(``/``). On Windows, the long filename marker is taken into account.
+
+When ``NORMALIZE`` option is specified, the path is :ref:`normalized
+<NORMAL_PATH>` before the conversion.
+
+.. _cmake_path-NATIVE_PATH:
+.. _NATIVE_PATH:
+
+.. code-block:: cmake
+
+    cmake_path(NATIVE_PATH <path> [NORMALIZE] <output>)
+
+Converts a cmake-style ``<path>`` into a native
+path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere).
+
+When ``NORMALIZE`` option is specified, the path is :ref:`normalized
+<NORMAL_PATH>` before the conversion.
+
+.. _CONVERT:
+.. _cmake_path-TO_CMAKE_PATH_LIST:
+.. _TO_CMAKE_PATH_LIST:
+
+.. code-block:: cmake
+
+   cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <output> [NORMALIZE])
+
+Converts a native ``<input>`` path into cmake-style path with forward-slashes
+(``/``).  On Windows, 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. The
+result of the conversion is stored in the ``<output>`` variable.
+
+When ``NORMALIZE`` option is specified, the path is :ref:`normalized
+<NORMAL_PATH>` before the conversion.
+
+.. _cmake_path-TO_NATIVE_PATH_LIST:
+.. _TO_NATIVE_PATH_LIST:
+
+.. code-block:: cmake
+
+  cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <output> [NORMALIZE])
+
+Converts a cmake-style ``<input>`` path into a native path with
+platform-specific slashes (``\`` on Windows and ``/`` elsewhere). The input can
+be a single path or a cmake-style list. A list will be converted into a native
+search path. The result of the conversion is stored in the ``<output>``
+variable.
+
+When ``NORMALIZE`` option is specified, the path is :ref:`normalized
+<NORMAL_PATH>` before the conversion.
+
+Comparison
+^^^^^^^^^^
+
+.. _COMPARE:
+
+.. code-block:: cmake
+
+    cmake_path(COMPARE <path> EQUAL <input> <output>)
+    cmake_path(COMPARE <path> NOT_EQUAL <input> <output>)
+
+Compares the lexical representations of the path and another path.
+
+For testing equality, the following algorithm (pseudo-code) apply:
+
+  .. code-block:: cmake
+
+    IF (NOT <path>.root_name() STREQUAL <input>.root_name())
+      returns FALSE
+    ELSEIF (<path>.has_root_directory() XOR <input>.has_root_directory())
+      returns FALSE
+    ENDIF()
+
+    returns TRUE or FALSE if the relative portion of <path> is
+      lexicographically equal or not to the relative portion of <input>.
+      Comparison is performed path component-wise
+
+Query
+^^^^^
+
+.. _HAS_ROOT_NAME:
+
+.. code-block:: cmake
+
+    cmake_path(HAS_ROOT_NAME <path> <output>)
+
+Checks if ``<path>`` has ``root-name``.
+
+.. _HAS_ROOT_DIRECTORY:
+
+.. code-block:: cmake
+
+    cmake_path(HAS_ROOT_DIRECTORY <path> <output>)
+
+Checks if ``<path>`` has ``root-directory``.
+
+.. _HAS_ROOT_PATH:
+
+.. code-block:: cmake
+
+    cmake_path(HAS_ROOT_PATH <path> <output>)
+
+Checks if ``<path>`` has root path.
+
+Effectively, checks the following: ``root-name / root-directory``.
+
+.. _HAS_FILENAME:
+
+.. code-block:: cmake
+
+    cmake_path(HAS_FILENAME <path> <output>)
+
+Checks if ``<path>`` has ``file-name``.
+
+.. _HAS_EXTENSION:
+
+.. code-block:: cmake
+
+    cmake_path(HAS_EXTENSION <path> <output>)
+
+Checks if ``<path>`` has an :ref:`<extension <EXTENSION_DEF>`. If the first
+character in the filename is a period, it is not treated as an extension (for
+example ".profile").
+
+.. _HAS_STEM:
+
+.. code-block:: cmake
+
+    cmake_path(HAS_STEM <path> <output>)
+
+Checks if ``<path>`` has stem.
+
+.. _HAS_RELATIVE_PATH:
+
+.. code-block:: cmake
+
+    cmake_path(HAS_RELATIVE_PATH <path> <output>)
+
+Checks if ``<path>`` has relative path.
+
+.. _HAS_PARENT_PATH:
+
+.. code-block:: cmake
+
+    cmake_path(HAS_PARENT_PATH <path> <output>)
+
+Checks if ``<path>`` has parent path.
+
+.. _IS_ABSOLUTE:
+
+.. code-block:: cmake
+
+    cmake_path(IS_ABSOLUTE <path> <output>)
+
+Checks if ``<path>`` is absolute.
+
+An absolute path is a path that unambiguously identifies the location of a file
+without reference to an additional starting location.
+
+.. _IS_RELATIVE:
+
+.. code-block:: cmake
+
+    cmake_path(IS_RELATIVE <path> <output>)
+
+Checks if path is relative.
+
+.. _IS_PREFIX:
+
+.. code-block:: cmake
+
+    cmake_path(IS_PREFIX <path> <input> [NORMALIZE] <output>)
+
+Checks if ``<path>`` is the prefix of ``<input>``.
+
+When ``NORMALIZE`` option is specified, the paths are :ref:`normalized
+<NORMAL_PATH>` before the check.
+
+Hashing
+^^^^^^^
+
+.. _HASH:
+
+.. code-block:: cmake
+
+    cmake_path(HASH <path> [NORMALIZE] <output>)
+
+Compute hash value of ``<path>`` such that if for two paths (``p1`` and ``p2``)
+are equal (:ref:`COMPARE ... EQUAL <COMPARE>`) then hash value of p1 is equal
+to hash value of p2.
+
+When ``NORMALIZE`` option is specified, the paths are :ref:`normalized
+<NORMAL_PATH>` before the check.

Help/command/file.rst

@@ -3,6 +3,21 @@ file
 
 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
+: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 <cmake_path-RELATIVE_PATH>`,
+  :ref:`CONVERT ... TO_CMAKE_PATH_LIST <cmake_path-TO_CMAKE_PATH_LIST>` and
+  :ref:`CONVERT ... TO_NATIVE_PATH_LIST <cmake_path-TO_NATIVE_PATH_LIST>` of
+  :command:`cmake_path` command.
+
 Synopsis
 ^^^^^^^^
 

Help/command/get_filename_component.rst

@@ -44,6 +44,11 @@ Paths are returned with forward slashes and have no trailing slashes.  If the
 optional ``CACHE`` argument is specified, the result variable is added to the
 cache.
 
+.. note::
+
+  All previous sub-commands, except ``REALPATH``, has been superseded by
+  :command:`cmake_path` command.
+
 .. code-block:: cmake
 
   get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])

Help/manual/cmake-commands.7.rst

@@ -20,6 +20,7 @@ These commands are always available.
    /command/cmake_language
    /command/cmake_minimum_required
    /command/cmake_parse_arguments
+   /command/cmake_path
    /command/cmake_policy
    /command/configure_file
    /command/continue

Help/release/dev/cmake_path-command.rst

@@ -0,0 +1,5 @@
+cmake_path-command
+------------------
+
+* The :command:`cmake_path` command was added for operations on
+  filesystem paths.

Source/CMakeLists.txt

@@ -182,6 +182,8 @@ set(SRCS
   cmCheckCustomOutputs.cxx
   cmCLocaleEnvironmentScope.h
   cmCLocaleEnvironmentScope.cxx
+  cmCMakePath.h
+  cmCMakePath.cxx
   cmCommandArgumentParserHelper.cxx
   cmCommonTargetGenerator.cxx
   cmCommonTargetGenerator.h
@@ -498,6 +500,8 @@ set(SRCS
   cmCMakeLanguageCommand.h
   cmCMakeMinimumRequired.cxx
   cmCMakeMinimumRequired.h
+  cmCMakePathCommand.h
+  cmCMakePathCommand.cxx
   cmCMakePolicyCommand.cxx
   cmCMakePolicyCommand.h
   cmConditionEvaluator.cxx

Source/Checks/cm_cxx_features.cmake

@@ -1,6 +1,7 @@
 include(${CMAKE_CURRENT_LIST_DIR}/cm_message_checks_compat.cmake)
 
 function(cm_check_cxx_feature name)
+  set(TRY_RUN_FEATURE "${ARGN}")
   string(TOUPPER ${name} FEATURE)
   if(NOT DEFINED CMake_HAVE_CXX_${FEATURE})
     cm_message_checks_compat(
@@ -12,12 +13,26 @@ function(cm_check_cxx_feature name)
     else()
       set(maybe_cxx_standard "")
     endif()
-    try_compile(CMake_HAVE_CXX_${FEATURE}
-      ${CMAKE_CURRENT_BINARY_DIR}
-      ${CMAKE_CURRENT_LIST_DIR}/cm_cxx_${name}.cxx
-      CMAKE_FLAGS ${maybe_cxx_standard}
-      OUTPUT_VARIABLE OUTPUT
-      )
+    if (TRY_RUN_FEATURE)
+      try_run(CMake_RUN_CXX_${FEATURE} CMake_COMPILE_CXX_${FEATURE}
+        ${CMAKE_CURRENT_BINARY_DIR}
+        ${CMAKE_CURRENT_LIST_DIR}/cm_cxx_${name}.cxx
+        CMAKE_FLAGS ${maybe_cxx_standard}
+        OUTPUT_VARIABLE OUTPUT
+        )
+      if (CMake_RUN_CXX_${FEATURE} EQUAL "0" AND CMake_COMPILE_CXX_${FEATURE})
+        set(CMake_HAVE_CXX_${FEATURE} ON CACHE INTERNAL "TRY_RUN" FORCE)
+      else()
+        set(CMake_HAVE_CXX_${FEATURE} OFF CACHE INTERNAL "TRY_RUN" FORCE)
+      endif()
+    else()
+      try_compile(CMake_HAVE_CXX_${FEATURE}
+        ${CMAKE_CURRENT_BINARY_DIR}
+        ${CMAKE_CURRENT_LIST_DIR}/cm_cxx_${name}.cxx
+        CMAKE_FLAGS ${maybe_cxx_standard}
+        OUTPUT_VARIABLE OUTPUT
+        )
+    endif()
     set(check_output "${OUTPUT}")
     # Filter out MSBuild output that looks like a warning.
     string(REGEX REPLACE " +0 Warning\\(s\\)" "" check_output "${check_output}")
@@ -64,7 +79,7 @@ if(CMake_HAVE_CXX_MAKE_UNIQUE)
 endif()
 cm_check_cxx_feature(unique_ptr)
 if (NOT CMAKE_CXX_STANDARD LESS "17")
-  cm_check_cxx_feature(filesystem)
+  cm_check_cxx_feature(filesystem TRY_RUN)
 else()
   set(CMake_HAVE_CXX_FILESYSTEM FALSE)
 endif()

Source/Checks/cm_cxx_filesystem.cxx

@@ -3,8 +3,25 @@
 
 int main()
 {
+  std::filesystem::path p0(L"/a/b/c");
+
   std::filesystem::path p1("/a/b/c");
   std::filesystem::path p2("/a/b/c");
+  if (p1 != p2) {
+    return 1;
+  }
+
+#if defined(_WIN32)
+  std::filesystem::path p3("//host/a/b/../c");
+  if (p3.lexically_normal().generic_string() != "//host/a/c") {
+    return 1;
+  }
+
+  std::filesystem::path p4("c://a/.///b/../");
+  if (p4.lexically_normal().generic_string() != "c:/a/") {
+    return 1;
+  }
+#endif
 
-  return p1 == p2 ? 0 : 1;
+  return 0;
 }

Source/cmCMakePath.cxx

@@ -0,0 +1,146 @@
+/* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+   file Copyright.txt or https://cmake.org/licensing for details.  */
+
+#include "cmConfigure.h" // IWYU pragma: keep
+
+#include "cmCMakePath.h"
+
+#include <string>
+
+#if defined(_WIN32)
+#  include <cstdlib>
+#endif
+
+#include <cm/filesystem>
+#include <cm/string_view>
+
+#if defined(_WIN32)
+#  include "cmStringAlgorithms.h"
+#endif
+
+cmCMakePath& cmCMakePath::ReplaceWideExtension(cm::string_view extension)
+{
+  auto file = this->Path.filename().string();
+  if (!file.empty() && file != "." && file != "..") {
+    auto pos = file.find('.', file[0] == '.' ? 1 : 0);
+    if (pos != std::string::npos) {
+      file.erase(pos);
+    }
+  }
+  if (!extension.empty()) {
+    if (extension[0] != '.') {
+      file += '.';
+    }
+    file.append(std::string(extension));
+  }
+  this->Path.replace_filename(file);
+  return *this;
+}
+
+cmCMakePath cmCMakePath::GetWideExtension() const
+{
+  auto file = this->Path.filename().string();
+  if (file.empty() || file == "." || file == "..") {
+    return cmCMakePath{};
+  }
+
+  auto pos = file.find('.', file[0] == '.' ? 1 : 0);
+  if (pos != std::string::npos) {
+    return cm::string_view(file.data() + pos, file.length() - pos);
+  }
+
+  return cmCMakePath{};
+}
+
+cmCMakePath cmCMakePath::GetNarrowStem() const
+{
+  auto stem = this->Path.stem().string();
+  if (!stem.empty()) {
+    auto pos = stem.find('.', stem[0] == '.' ? 1 : 0);
+    if (pos != std::string::npos) {
+      return stem.substr(0, pos);
+    }
+  }
+  return stem;
+}
+
+cmCMakePath cmCMakePath::Absolute(const cm::filesystem::path& base) const
+{
+  if (this->Path.is_relative()) {
+    auto path = base;
+    path /= this->Path;
+    // filesystem::path::operator/= use preferred_separator ('\' on Windows)
+    // so converts back to '/'
+    return path.generic_string();
+  }
+  return *this;
+}
+
+bool cmCMakePath::IsPrefix(const cmCMakePath& path) const
+{
+  auto prefix_it = this->Path.begin();
+  auto prefix_end = this->Path.end();
+  auto path_it = path.Path.begin();
+  auto path_end = path.Path.end();
+
+  while (prefix_it != prefix_end && path_it != path_end &&
+         *prefix_it == *path_it) {
+    ++prefix_it;
+    ++path_it;
+  }
+  return prefix_it == prefix_end;
+}
+
+std::string cmCMakePath::FormatPath(std::string path, format fmt)
+{
+#if defined(_WIN32)
+  if (fmt == auto_format || fmt == native_format) {
+    auto prefix = path.substr(0, 4);
+    for (auto& c : prefix) {
+      if (c == '\\') {
+        c = '/';
+      }
+    }
+    // remove Windows long filename marker
+    if (prefix == "//?/"_s) {
+      path.erase(0, 4);
+    }
+    if (cmHasPrefix(path, "UNC/"_s) || cmHasPrefix(path, "UNC\\"_s)) {
+      path.erase(0, 2);
+      path[0] = '/';
+    }
+  }
+#else
+  static_cast<void>(fmt);
+#endif
+  return path;
+}
+
+void cmCMakePath::GetNativePath(std::string& path) const
+{
+  cm::filesystem::path tmp(this->Path);
+  tmp.make_preferred();
+
+  path = tmp.string();
+}
+void cmCMakePath::GetNativePath(std::wstring& path) const
+{
+  cm::filesystem::path tmp(this->Path);
+  tmp.make_preferred();
+
+  path = tmp.wstring();
+
+#if defined(_WIN32)
+  // Windows long filename
+  static std::wstring UNC(L"\\\\?\\UNC");
+  static std::wstring PREFIX(L"\\\\?\\");
+
+  if (this->IsAbsolute() && path.length() > _MAX_PATH - 12) {
+    if (this->HasRootName() && path[0] == L'\\') {
+      path = UNC + path.substr(1);
+    } else {
+      path = PREFIX + path;
+    }
+  }
+#endif
+}

Source/cmCMakePath.h

@@ -0,0 +1,571 @@
+/* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+   file Copyright.txt or https://cmake.org/licensing for details.  */
+
+#pragma once
+
+#include "cmConfigure.h" // IWYU pragma: keep
+
+#include <cstddef>
+#include <string>
+#include <utility>
+
+#include <cm/filesystem>
+#include <cm/string_view>
+#include <cm/type_traits>
+#include <cmext/string_view>
+
+namespace detail {
+#if defined(__SUNPRO_CC) && defined(__sparc)
+// Oracle DeveloperStudio C++ compiler on Solaris/Sparc fails to compile
+// the full 'is_pathable' and 'is_move_pathable' checks.  We use it only to
+// improve error messages via 'enable_if' when calling methods with incorrect
+// types. Just pretend all types are allowed so we can at least compile valid
+// code.
+template <typename T>
+struct is_pathable : std::true_type
+{
+};
+
+template <typename T>
+struct is_move_pathable : std::true_type
+{
+};
+
+#else
+template <typename T, typename = void>
+struct is_pathable : std::false_type
+{
+};
+
+template <>
+struct is_pathable<cm::filesystem::path> : std::true_type
+{
+};
+template <>
+struct is_pathable<std::string> : std::true_type
+{
+};
+template <>
+struct is_pathable<cm::string_view> : std::true_type
+{
+};
+template <>
+struct is_pathable<cm::static_string_view> : std::true_type
+{
+};
+template <typename T>
+struct is_pathable<
+  T,
+  cm::enable_if_t<std::is_same<char*, typename std::decay<T>::type>::value,
+                  void>>
+  : cm::bool_constant<std::is_same<char*, typename std::decay<T>::type>::value>
+{
+};
+
+template <typename T>
+struct is_move_pathable : std::false_type
+{
+};
+
+template <>
+struct is_move_pathable<cm::filesystem::path> : std::true_type
+{
+};
+template <>
+struct is_move_pathable<std::string> : std::true_type
+{
+};
+#endif
+}
+
+class cmCMakePath
+{
+private:
+  template <typename Source>
+  using enable_if_move_pathable =
+    cm::enable_if_t<detail::is_move_pathable<Source>::value, cmCMakePath&>;
+
+  template <typename Source>
+  using enable_if_pathable =
+    cm::enable_if_t<detail::is_pathable<Source>::value, cmCMakePath&>;
+
+public:
+  using value_type = cm::filesystem::path::value_type;
+  using string_type = cm::filesystem::path::string_type;
+
+  enum format : unsigned char
+  {
+    auto_format =
+      static_cast<unsigned char>(cm::filesystem::path::format::auto_format),
+    native_format =
+      static_cast<unsigned char>(cm::filesystem::path::format::native_format),
+    generic_format =
+      static_cast<unsigned char>(cm::filesystem::path::format::generic_format)
+  };
+
+  class iterator;
+  using const_iterator = iterator;
+
+  cmCMakePath() noexcept = default;
+
+  cmCMakePath(const cmCMakePath&) = default;
+
+  cmCMakePath(cmCMakePath&& path) noexcept
+    : Path(std::forward<cm::filesystem::path>(path.Path))
+  {
+  }
+
+  cmCMakePath(cm::filesystem::path path) noexcept
+    : Path(std::move(path))
+  {
+  }
+  cmCMakePath(cm::string_view source, format fmt = generic_format) noexcept
+    : Path(FormatPath(source, fmt))
+  {
+  }
+  template <typename Source, typename = enable_if_move_pathable<Source>>
+  cmCMakePath(Source source, format fmt = generic_format)
+    : Path(FormatPath(std::move(source), fmt))
+  {
+  }
+
+  template <typename Source, typename = enable_if_move_pathable<Source>>
+  cmCMakePath& Assign(Source&& source)
+  {
+    this->Path = std::forward<Source>(source);
+    return *this;
+  }
+  template <typename Source, typename = enable_if_pathable<Source>>
+  cmCMakePath& Assign(const Source& source)
+  {
+    this->Path = source;
+    return *this;
+  }
+
+  cmCMakePath& operator=(const cmCMakePath& path)
+  {
+    if (this != &path) {
+      this->Path = path.Path;
+    }
+    return *this;
+  }
+  cmCMakePath& operator=(cmCMakePath&& path) noexcept
+  {
+    if (this != &path) {
+      this->Path = std::move(path.Path);
+    }
+    return *this;
+  }
+  template <typename Source, typename = enable_if_move_pathable<Source>>
+  cmCMakePath& operator=(Source&& source)
+  {
+    this->Assign(std::forward<Source>(source));
+    return *this;
+  }
+  template <typename Source, typename = enable_if_pathable<Source>>
+  cmCMakePath& operator=(const Source& source)
+  {
+    this->Assign(source);
+    return *this;
+  }
+
+  // Concatenation
+  cmCMakePath& Append(const cmCMakePath& path)
+  {
+    return this->Append(path.Path);
+  }
+  cmCMakePath& Append(const cm::filesystem::path& path)
+  {
+    this->Path /= path;
+    // filesystem::path::append use preferred_separator ('\' on Windows)
+    // so convert back to '/'
+    this->Path = this->Path.generic_string();
+    return *this;
+  }
+
+  template <typename Source, typename = enable_if_pathable<Source>>
+  cmCMakePath& Append(const Source& source)
+  {
+    return this->Append(cm::filesystem::path(source));
+  }
+
+  cmCMakePath& operator/=(const cmCMakePath& path)
+  {
+    return this->Append(path);
+  }
+  template <typename Source, typename = enable_if_pathable<Source>>
+  cmCMakePath& operator/=(const Source& source)
+  {
+    return this->Append(source);
+  }
+
+  cmCMakePath& Concat(const cmCMakePath& path)
+  {
+    this->Path += path.Path;
+    return *this;
+  }
+  cmCMakePath& Concat(cm::static_string_view source)
+  {
+    this->Path.concat(std::string(source));
+    return *this;
+  }
+  template <typename Source, typename = enable_if_pathable<Source>>
+  cmCMakePath& Concat(const Source& source)
+  {
+    this->Path.concat(source);
+    return *this;
+  }
+
+  cmCMakePath& operator+=(const cmCMakePath& path)
+  {
+    return this->Concat(path);
+  }
+  template <typename Source, typename = enable_if_pathable<Source>>
+  cmCMakePath& operator+=(const Source& source)
+  {
+    return this->Concat(source);
+  }
+
+  // Manipulation
+  void Clear() noexcept { this->Path.clear(); }
+
+  cmCMakePath& RemoveFileName()
+  {
+    this->Path.remove_filename();
+    return *this;
+  }
+
+  cmCMakePath& ReplaceFileName(const cmCMakePath& filename)
+  {
+    if (this->Path.has_filename()) {
+      this->Path.replace_filename(filename.Path);
+    }
+    return *this;
+  }
+  template <typename Source, typename = enable_if_pathable<Source>>
+  cmCMakePath& ReplaceFileName(const Source& filename)
+  {
+    if (this->Path.has_filename()) {
+      this->Path.replace_filename(filename);
+    }
+    return *this;
+  }
+
+  cmCMakePath& ReplaceExtension(const cmCMakePath& extension = cmCMakePath())
+  {
+    this->Path.replace_extension(extension.Path);
+    return *this;
+  }
+  template <typename Source, typename = enable_if_pathable<Source>>
+  cmCMakePath& ReplaceExtension(const Source& extension)
+  {
+    this->Path.replace_extension(extension);
+    return *this;
+  }
+
+  cmCMakePath& ReplaceWideExtension(
+    const cmCMakePath& extension = cmCMakePath())
+  {
+    return this->ReplaceWideExtension(
+      static_cast<cm::string_view>(extension.Path.string()));
+  }
+  template <typename Source, typename = enable_if_pathable<Source>>
+  cmCMakePath& ReplaceWideExtension(const Source& extension)
+  {
+    return this->ReplaceWideExtension(cm::string_view(extension));
+  }
+  cmCMakePath& ReplaceWideExtension(cm::string_view extension);
+
+  cmCMakePath& RemoveExtension()
+  {
+    if (this->Path.has_extension()) {
+      this->ReplaceExtension(cm::string_view(""));
+    }
+    return *this;
+  }
+
+  cmCMakePath& RemoveWideExtension()
+  {
+    if (this->Path.has_extension()) {
+      this->ReplaceWideExtension(cm::string_view(""));
+    }
+    return *this;
+  }
+
+  void swap(cmCMakePath& other) noexcept { this->Path.swap(other.Path); }
+
+  // Observers
+  std::string String() const { return this->Path.string(); }
+  std::wstring WString() const { return this->Path.wstring(); }
+
+  string_type Native() const
+  {
+    string_type path;
+    this->GetNativePath(path);
+
+    return path;
+  }
+  std::string NativeString() const
+  {
+    std::string path;
+    this->GetNativePath(path);
+
+    return path;
+  }
+  std::wstring NativeWString() const
+  {
+    std::wstring path;
+    this->GetNativePath(path);
+
+    return path;
+  }
+  std::string GenericString() const { return this->Path.generic_string(); }
+  std::wstring GenericWString() const { return this->Path.generic_wstring(); }
+
+  // Decomposition
+  cmCMakePath GetRootName() const { return this->Path.root_name(); }
+  cmCMakePath GetRootDirectory() const { return this->Path.root_directory(); }
+  cmCMakePath GetRootPath() const { return this->Path.root_path(); }
+  cmCMakePath GetFileName() const { return this->Path.filename(); }
+  cmCMakePath GetExtension() const { return this->Path.extension(); }
+  cmCMakePath GetWideExtension() const;
+  cmCMakePath GetStem() const { return this->Path.stem(); }
+  cmCMakePath GetNarrowStem() const;
+
+  cmCMakePath GetRelativePath() const { return this->Path.relative_path(); }
+  cmCMakePath GetParentPath() const { return this->Path.parent_path(); }
+
+  // Generation
+  cmCMakePath Normal() const
+  {
+    auto path = this->Path.lexically_normal();
+    // filesystem::path:lexically_normal use preferred_separator ('\') on
+    // Windows) so convert back to '/'
+    return path.generic_string();
+  }
+
+  cmCMakePath Relative(const cmCMakePath& base) const
+  {
+    return this->Relative(base.Path);
+  }
+  cmCMakePath Relative(const cm::filesystem::path& base) const
+  {
+    auto path = this->Path.lexically_relative(base);
+    // filesystem::path:lexically_relative use preferred_separator ('\') on
+    // Windows) so convert back to '/'
+    return path.generic_string();
+  }
+  template <typename Source, typename = enable_if_pathable<Source>>
+  cmCMakePath Relative(const Source& base) const
+  {
+    return this->Relative(cm::filesystem::path(base));
+  }
+
+  cmCMakePath Proximate(const cmCMakePath& base) const
+  {
+    return this->Proximate(base.Path);
+  }
+  cmCMakePath Proximate(const cm::filesystem::path& base) const
+  {
+    auto path = this->Path.lexically_proximate(base);
+    // filesystem::path::lexically_proximate use preferred_separator ('\') on
+    // Windows) so convert back to '/'
+    return path.generic_string();
+  }
+  template <typename Source, typename = enable_if_pathable<Source>>
+  cmCMakePath Proximate(const Source& base) const
+  {
+    return this->Proximate(cm::filesystem::path(base));
+  }
+
+  cmCMakePath Absolute(const cmCMakePath& base) const
+  {
+    return this->Absolute(base.Path);
+  }
+  template <typename Source, typename = enable_if_pathable<Source>>
+  cmCMakePath Absolute(const Source& base) const
+  {
+    return this->Absolute(cm::filesystem::path(base));
+  }
+  cmCMakePath Absolute(const cm::filesystem::path& base) const;
+
+  // Comparison
+  int Compare(const cmCMakePath& path) const noexcept
+  {
+    return this->Path.compare(path.Path);
+  }
+
+  // Query
+  bool IsEmpty() const noexcept { return this->Path.empty(); }
+
+  bool HasRootPath() const { return this->Path.has_root_path(); }
+  bool HasRootName() const { return this->Path.has_root_name(); }
+  bool HasRootDirectory() const { return this->Path.has_root_directory(); }
+  bool HasRelativePath() const { return this->Path.has_relative_path(); }
+  bool HasParentPath() const { return this->Path.has_parent_path(); }
+  bool HasFileName() const { return this->Path.has_filename(); }
+  bool HasStem() const { return this->Path.has_stem(); }
+  bool HasExtension() const { return this->Path.has_extension(); }
+
+  bool IsAbsolute() const { return this->Path.is_absolute(); }
+  bool IsRelative() const { return this->Path.is_relative(); }
+  bool IsPrefix(const cmCMakePath& path) const;
+
+  // Iterators
+  // =========
+  inline iterator begin() const;
+  inline iterator end() const;
+
+  // Non-members
+  // ===========
+  friend inline bool operator==(const cmCMakePath& lhs,
+                                const cmCMakePath& rhs) noexcept
+  {
+    return lhs.Compare(rhs) == 0;
+  }
+  friend inline bool operator!=(const cmCMakePath& lhs,
+                                const cmCMakePath& rhs) noexcept
+  {
+    return lhs.Compare(rhs) != 0;
+  }
+
+  friend inline cmCMakePath operator/(const cmCMakePath& lhs,
+                                      const cmCMakePath& rhs)
+  {
+    cmCMakePath result(lhs);
+    result /= rhs;
+
+    return result;
+  }
+
+private:
+  friend std::size_t hash_value(const cmCMakePath& path) noexcept;
+
+  static std::string FormatPath(std::string path, format fmt = generic_format);
+  static std::string FormatPath(cm::string_view path,
+                                format fmt = generic_format)
+  {
+    return FormatPath(std::string(path), fmt);
+  }
+
+  void GetNativePath(std::string& path) const;
+  void GetNativePath(std::wstring& path) const;
+
+  cm::filesystem::path Path;
+};
+
+class cmCMakePath::iterator
+{
+public:
+  using iterator_category = cm::filesystem::path::iterator::iterator_category;
+
+  using value_type = cmCMakePath;
+  using difference_type = cm::filesystem::path::iterator::difference_type;
+  using pointer = const cmCMakePath*;
+  using reference = const cmCMakePath&;
+
+  iterator() = default;
+
+  iterator(const iterator& other)
+    : Iterator(other.Iterator)
+    , Path(other.Path)
+    , PathElement(*this->Iterator)
+  {
+  }
+
+  ~iterator() = default;
+
+  iterator& operator=(const iterator& other)
+  {
+    if (this != &other) {
+      this->Iterator = other.Iterator;
+      this->Path = other.Path;
+      this->PathElement = *this->Iterator;
+    }
+
+    return *this;
+  }
+
+  reference operator*() const { return this->PathElement; }
+
+  pointer operator->() const { return &this->PathElement; }
+
+  iterator& operator++()
+  {
+    ++this->Iterator;
+    this->PathElement = *this->Iterator;
+
+    return *this;
+  }
+
+  iterator operator++(int)
+  {
+    iterator it(*this);
+    this->operator++();
+    return it;
+  }
+
+  iterator& operator--()
+  {
+    --this->Iterator;
+    this->PathElement = *this->Iterator;
+
+    return *this;
+  }
+
+  iterator operator--(int)
+  {
+    iterator it(*this);
+    this->operator--();
+    return it;
+  }
+
+private:
+  friend class cmCMakePath;
+  friend bool operator==(const iterator&, const iterator&);
+
+  iterator(const cmCMakePath* path, const cm::filesystem::path::iterator& it)
+    : Iterator(it)
+    , Path(path)
+    , PathElement(*this->Iterator)
+  {
+  }
+
+  cm::filesystem::path::iterator Iterator;
+  const cmCMakePath* Path = nullptr;
+  cmCMakePath PathElement;
+};
+
+inline cmCMakePath::iterator cmCMakePath::begin() const
+{
+  return iterator(this, this->Path.begin());
+}
+inline cmCMakePath::iterator cmCMakePath::end() const
+{
+  return iterator(this, this->Path.end());
+}
+
+// Non-member functions
+// ====================
+inline bool operator==(const cmCMakePath::iterator& lhs,
+                       const cmCMakePath::iterator& rhs)
+{
+  return lhs.Path == rhs.Path && lhs.Path != nullptr &&
+    lhs.Iterator == rhs.Iterator;
+}
+
+inline bool operator!=(const cmCMakePath::iterator& lhs,
+                       const cmCMakePath::iterator& rhs)
+{
+  return !(lhs == rhs);
+}
+
+inline void swap(cmCMakePath& lhs, cmCMakePath& rhs) noexcept
+{
+  lhs.swap(rhs);
+}
+
+inline std::size_t hash_value(const cmCMakePath& path) noexcept
+{
+  return cm::filesystem::hash_value(path.Path);
+}

Source/cmCMakePathCommand.cxx

@@ -0,0 +1,1019 @@
+/* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+   file Copyright.txt or https://cmake.org/licensing for details.  */
+#include "cmCMakePathCommand.h"
+
+#include <algorithm>
+#include <functional>
+#include <iomanip>
+#include <map>
+#include <sstream>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include <cm/string_view>
+#include <cmext/string_view>
+
+#include "cmArgumentParser.h"
+#include "cmCMakePath.h"
+#include "cmExecutionStatus.h"
+#include "cmMakefile.h"
+#include "cmRange.h"
+#include "cmStringAlgorithms.h"
+#include "cmSubcommandTable.h"
+#include "cmSystemTools.h"
+
+namespace {
+// Helper classes for argument parsing
+template <typename Result>
+class CMakePathArgumentParser : public cmArgumentParser<Result>
+{
+public:
+  CMakePathArgumentParser()
+    : cmArgumentParser<Result>()
+  {
+  }
+
+  template <typename T>
+  CMakePathArgumentParser& Bind(cm::static_string_view name, T Result::*member)
+  {
+    cmArgumentParser<Result>::Bind(name, member);
+    return *this;
+  }
+
+  template <int Advance = 2>
+  Result Parse(std::vector<std::string> const& args,
+               std::vector<std::string>* keywordsMissingValue = nullptr,
+               std::vector<std::string>* parsedKeywords = nullptr) const
+  {
+    this->Inputs.clear();
+
+    return cmArgumentParser<Result>::Parse(cmMakeRange(args).advance(Advance),
+                                           &this->Inputs, keywordsMissingValue,
+                                           parsedKeywords);
+  }
+
+  const std::vector<std::string>& GetInputs() const { return Inputs; }
+
+protected:
+  mutable std::vector<std::string> Inputs;
+};
+
+// OUTPUT_VARIABLE is expected
+template <typename Result>
+class ArgumentParserWithOutputVariable : public CMakePathArgumentParser<Result>
+{
+public:
+  ArgumentParserWithOutputVariable()
+    : CMakePathArgumentParser<Result>()
+  {
+    this->Bind("OUTPUT_VARIABLE"_s, &Result::Output);
+  }
+
+  template <typename T>
+  ArgumentParserWithOutputVariable& Bind(cm::static_string_view name,
+                                         T Result::*member)
+  {
+    cmArgumentParser<Result>::Bind(name, member);
+    return *this;
+  }
+
+  template <int Advance = 2>
+  Result Parse(std::vector<std::string> const& args) const
+  {
+    this->KeywordsMissingValue.clear();
+    this->ParsedKeywords.clear();
+
+    return CMakePathArgumentParser<Result>::template Parse<Advance>(
+      args, &this->KeywordsMissingValue, &this->ParsedKeywords);
+  }
+
+  const std::vector<std::string>& GetKeywordsMissingValue() const
+  {
+    return this->KeywordsMissingValue;
+  }
+  const std::vector<std::string>& GetParsedKeywords() const
+  {
+    return this->ParsedKeywords;
+  }
+
+  bool checkOutputVariable(const Result& arguments,
+                           cmExecutionStatus& status) const
+  {
+    if (std::find(this->GetKeywordsMissingValue().begin(),
+                  this->GetKeywordsMissingValue().end(),
+                  "OUTPUT_VARIABLE"_s) !=
+        this->GetKeywordsMissingValue().end()) {
+      status.SetError("OUTPUT_VARIABLE requires an argument.");
+      return false;
+    }
+
+    if (std::find(this->GetParsedKeywords().begin(),
+                  this->GetParsedKeywords().end(),
+                  "OUTPUT_VARIABLE"_s) != this->GetParsedKeywords().end() &&
+        arguments.Output.empty()) {
+      status.SetError("Invalid name for output variable.");
+      return false;
+    }
+
+    return true;
+  }
+
+private:
+  mutable std::vector<std::string> KeywordsMissingValue;
+  mutable std::vector<std::string> ParsedKeywords;
+};
+
+struct OutputVariable
+{
+  std::string Output;
+};
+// Usable when OUTPUT_VARIABLE is the only option
+class OutputVariableParser
+  : public ArgumentParserWithOutputVariable<OutputVariable>
+{
+};
+
+struct NormalizeOption
+{
+  bool Normalize = false;
+};
+// Usable when NORMALIZE is the only option
+class NormalizeParser : public CMakePathArgumentParser<NormalizeOption>
+{
+public:
+  NormalizeParser() { this->Bind("NORMALIZE"_s, &NormalizeOption::Normalize); }
+};
+
+// retrieve value of input path from specified variable
+bool getInputPath(const std::string& arg, cmExecutionStatus& status,
+                  std::string& path)
+{
+  auto def = status.GetMakefile().GetDefinition(arg);
+  if (def == nullptr) {
+    status.SetError("undefined variable for input path.");
+    return false;
+  }
+
+  path = *def;
+  return true;
+}
+
+bool HandleGetCommand(std::vector<std::string> const& args,
+                      cmExecutionStatus& status)
+{
+  static std::map<cm::string_view,
+                  std::function<cmCMakePath(const cmCMakePath&, bool)>> const
+    actions{ { "ROOT_NAME"_s,
+               [](const cmCMakePath& path, bool) -> cmCMakePath {
+                 return path.GetRootName();
+               } },
+             { "ROOT_DIRECTORY"_s,
+               [](const cmCMakePath& path, bool) -> cmCMakePath {
+                 return path.GetRootDirectory();
+               } },
+             { "ROOT_PATH"_s,
+               [](const cmCMakePath& path, bool) -> cmCMakePath {
+                 return path.GetRootPath();
+               } },
+             { "FILENAME"_s,
+               [](const cmCMakePath& path, bool) -> cmCMakePath {
+                 return path.GetFileName();
+               } },
+             { "EXTENSION"_s,
+               [](const cmCMakePath& path, bool last_only) -> cmCMakePath {
+                 if (last_only) {
+                   return path.GetExtension();
+                 }
+                 return path.GetWideExtension();
+               } },
+             { "STEM"_s,
+               [](const cmCMakePath& path, bool last_only) -> cmCMakePath {
+                 if (last_only) {
+                   return path.GetStem();
+                 }
+                 return path.GetNarrowStem();
+               } },
+             { "RELATIVE_PATH"_s,
+               [](const cmCMakePath& path, bool) -> cmCMakePath {
+                 return path.GetRelativePath();
+               } },
+             { "PARENT_PATH"_s,
+               [](const cmCMakePath& path, bool) -> cmCMakePath {
+                 return path.GetParentPath();
+               } } };
+
+  if (args.size() < 4) {
+    status.SetError("GET must be called with at least three arguments.");
+    return false;
+  }
+
+  const auto& action = args[2];
+
+  if (actions.find(action) == actions.end()) {
+    status.SetError(
+      cmStrCat("GET called with an unknown action: ", action, "."));
+    return false;
+  }
+
+  struct Arguments
+  {
+    bool LastOnly = false;
+  };
+
+  CMakePathArgumentParser<Arguments> parser;
+  if ((action == "EXTENSION"_s || action == "STEM"_s)) {
+    parser.Bind("LAST_ONLY"_s, &Arguments::LastOnly);
+  }
+
+  Arguments const arguments = parser.Parse<3>(args);
+
+  if (parser.GetInputs().size() != 1) {
+    status.SetError("GET called with unexpected arguments.");
+    return false;
+  }
+  if (parser.GetInputs().front().empty()) {
+    status.SetError("Invalid name for output variable.");
+    return false;
+  }
+
+  std::string path;
+  if (!getInputPath(args[1], status, path)) {
+    return false;
+  }
+
+  auto result = actions.at(action)(path, arguments.LastOnly);
+
+  status.GetMakefile().AddDefinition(parser.GetInputs().front(),
+                                     result.String());
+
+  return true;
+}
+
+bool HandleAppendCommand(std::vector<std::string> const& args,
+                         cmExecutionStatus& status)
+{
+  static OutputVariableParser const parser{};
+
+  const auto arguments = parser.Parse(args);
+
+  if (!parser.checkOutputVariable(arguments, status)) {
+    return false;
+  }
+
+  cmCMakePath path(status.GetMakefile().GetSafeDefinition(args[1]));
+  for (const auto& input : parser.GetInputs()) {
+    path /= input;
+  }
+
+  status.GetMakefile().AddDefinition(
+    arguments.Output.empty() ? args[1] : arguments.Output, path.String());
+
+  return true;
+}
+
+bool HandleConcatCommand(std::vector<std::string> const& args,
+                         cmExecutionStatus& status)
+{
+  static OutputVariableParser const parser{};
+
+  const auto arguments = parser.Parse(args);
+
+  if (!parser.checkOutputVariable(arguments, status)) {
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  cmCMakePath path(inputPath);
+  for (const auto& input : parser.GetInputs()) {
+    path += input;
+  }
+
+  status.GetMakefile().AddDefinition(
+    arguments.Output.empty() ? args[1] : arguments.Output, path.String());
+
+  return true;
+}
+
+bool HandleRemoveFilenameCommand(std::vector<std::string> const& args,
+                                 cmExecutionStatus& status)
+{
+  static OutputVariableParser const parser{};
+
+  const auto arguments = parser.Parse(args);
+
+  if (!parser.checkOutputVariable(arguments, status)) {
+    return false;
+  }
+
+  if (!parser.GetInputs().empty()) {
+    status.SetError("REMOVE_FILENAME called with unexpected arguments.");
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  cmCMakePath path(inputPath);
+  path.RemoveFileName();
+
+  status.GetMakefile().AddDefinition(
+    arguments.Output.empty() ? args[1] : arguments.Output, path.String());
+
+  return true;
+}
+
+bool HandleReplaceFilenameCommand(std::vector<std::string> const& args,
+                                  cmExecutionStatus& status)
+{
+  static OutputVariableParser const parser{};
+
+  const auto arguments = parser.Parse(args);
+
+  if (!parser.checkOutputVariable(arguments, status)) {
+    return false;
+  }
+
+  if (parser.GetInputs().size() > 1) {
+    status.SetError("REPLACE_FILENAME called with unexpected arguments.");
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  cmCMakePath path(inputPath);
+  path.ReplaceFileName(
+    parser.GetInputs().empty() ? "" : parser.GetInputs().front());
+
+  status.GetMakefile().AddDefinition(
+    arguments.Output.empty() ? args[1] : arguments.Output, path.String());
+
+  return true;
+}
+
+bool HandleRemoveExtensionCommand(std::vector<std::string> const& args,
+                                  cmExecutionStatus& status)
+{
+  struct Arguments
+  {
+    std::string Output;
+    bool LastOnly = false;
+  };
+
+  static auto const parser =
+    ArgumentParserWithOutputVariable<Arguments>{}.Bind("LAST_ONLY"_s,
+                                                       &Arguments::LastOnly);
+
+  Arguments const arguments = parser.Parse(args);
+
+  if (!parser.checkOutputVariable(arguments, status)) {
+    return false;
+  }
+
+  if (!parser.GetInputs().empty()) {
+    status.SetError("REMOVE_EXTENSION called with unexpected arguments.");
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  cmCMakePath path(inputPath);
+
+  if (arguments.LastOnly) {
+    path.RemoveExtension();
+  } else {
+    path.RemoveWideExtension();
+  }
+
+  status.GetMakefile().AddDefinition(
+    arguments.Output.empty() ? args[1] : arguments.Output, path.String());
+
+  return true;
+}
+
+bool HandleReplaceExtensionCommand(std::vector<std::string> const& args,
+                                   cmExecutionStatus& status)
+{
+  struct Arguments
+  {
+    std::string Output;
+    bool LastOnly = false;
+  };
+
+  static auto const parser =
+    ArgumentParserWithOutputVariable<Arguments>{}.Bind("LAST_ONLY"_s,
+                                                       &Arguments::LastOnly);
+
+  Arguments const arguments = parser.Parse(args);
+
+  if (!parser.checkOutputVariable(arguments, status)) {
+    return false;
+  }
+
+  if (parser.GetInputs().size() > 1) {
+    status.SetError("REPLACE_EXTENSION called with unexpected arguments.");
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  cmCMakePath path(inputPath);
+  cmCMakePath extension(
+    parser.GetInputs().empty() ? "" : parser.GetInputs().front());
+
+  if (arguments.LastOnly) {
+    path.ReplaceExtension(extension);
+  } else {
+    path.ReplaceWideExtension(extension);
+  }
+
+  status.GetMakefile().AddDefinition(
+    arguments.Output.empty() ? args[1] : arguments.Output, path.String());
+
+  return true;
+}
+
+bool HandleNormalPathCommand(std::vector<std::string> const& args,
+                             cmExecutionStatus& status)
+{
+  static OutputVariableParser const parser{};
+
+  const auto arguments = parser.Parse(args);
+
+  if (!parser.checkOutputVariable(arguments, status)) {
+    return false;
+  }
+
+  if (!parser.GetInputs().empty()) {
+    status.SetError("NORMAL_PATH called with unexpected arguments.");
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  auto path = cmCMakePath(inputPath).Normal();
+
+  status.GetMakefile().AddDefinition(
+    arguments.Output.empty() ? args[1] : arguments.Output, path.String());
+
+  return true;
+}
+
+bool HandleTransformPathCommand(
+  std::vector<std::string> const& args, cmExecutionStatus& status,
+  const std::function<cmCMakePath(const cmCMakePath&,
+                                  const std::string& base)>& transform,
+  bool normalizeOption = false)
+{
+  struct Arguments
+  {
+    std::string Output;
+    std::string BaseDirectory;
+    bool Normalize = false;
+  };
+
+  auto parser = ArgumentParserWithOutputVariable<Arguments>{}.Bind(
+    "BASE_DIRECTORY"_s, &Arguments::BaseDirectory);
+  if (normalizeOption) {
+    parser.Bind("NORMALIZE"_s, &Arguments::Normalize);
+  }
+
+  Arguments arguments = parser.Parse(args);
+
+  if (!parser.checkOutputVariable(arguments, status)) {
+    return false;
+  }
+
+  if (!parser.GetInputs().empty()) {
+    status.SetError(cmStrCat(args[0], " called with unexpected arguments."));
+    return false;
+  }
+
+  if (std::find(parser.GetKeywordsMissingValue().begin(),
+                parser.GetKeywordsMissingValue().end(), "BASE_DIRECTORY"_s) !=
+      parser.GetKeywordsMissingValue().end()) {
+    status.SetError("BASE_DIRECTORY requires an argument.");
+    return false;
+  }
+
+  if (std::find(parser.GetParsedKeywords().begin(),
+                parser.GetParsedKeywords().end(),
+                "BASE_DIRECTORY"_s) == parser.GetParsedKeywords().end()) {
+    arguments.BaseDirectory = status.GetMakefile().GetCurrentSourceDirectory();
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  auto path = transform(cmCMakePath(inputPath), arguments.BaseDirectory);
+  if (arguments.Normalize) {
+    path = path.Normal();
+  }
+
+  status.GetMakefile().AddDefinition(
+    arguments.Output.empty() ? args[1] : arguments.Output, path.String());
+
+  return true;
+}
+
+bool HandleRelativePathCommand(std::vector<std::string> const& args,
+                               cmExecutionStatus& status)
+{
+  return HandleTransformPathCommand(
+    args, status,
+    [](const cmCMakePath& path, const std::string& base) -> cmCMakePath {
+      return path.Relative(base);
+    });
+}
+
+bool HandleProximatePathCommand(std::vector<std::string> const& args,
+                                cmExecutionStatus& status)
+{
+  return HandleTransformPathCommand(
+    args, status,
+    [](const cmCMakePath& path, const std::string& base) -> cmCMakePath {
+      return path.Proximate(base);
+    });
+}
+
+bool HandleAbsolutePathCommand(std::vector<std::string> const& args,
+                               cmExecutionStatus& status)
+{
+  return HandleTransformPathCommand(
+    args, status,
+    [](const cmCMakePath& path, const std::string& base) -> cmCMakePath {
+      return path.Absolute(base);
+    },
+    true);
+}
+
+bool HandleCMakePathCommand(std::vector<std::string> const& args,
+                            cmExecutionStatus& status)
+{
+  if (args.size() < 3 || args.size() > 4) {
+    status.SetError("CMAKE_PATH must be called with two or three arguments.");
+    return false;
+  }
+
+  static NormalizeParser const parser;
+
+  const auto arguments = parser.Parse(args);
+
+  if (parser.GetInputs().size() != 1) {
+    status.SetError("CMAKE_PATH called with unexpected arguments.");
+    return false;
+  }
+
+  if (args[1].empty()) {
+    status.SetError("Invalid name for output variable.");
+    return false;
+  }
+
+  auto path =
+    cmCMakePath(parser.GetInputs().front(), cmCMakePath::native_format);
+
+  if (arguments.Normalize) {
+    path = path.Normal();
+  }
+
+  status.GetMakefile().AddDefinition(args[1], path.GenericString());
+
+  return true;
+}
+
+bool HandleNativePathCommand(std::vector<std::string> const& args,
+                             cmExecutionStatus& status)
+{
+  if (args.size() < 3 || args.size() > 4) {
+    status.SetError("NATIVE_PATH must be called with two or three arguments.");
+    return false;
+  }
+
+  static NormalizeParser const parser;
+
+  const auto arguments = parser.Parse(args);
+
+  if (parser.GetInputs().size() != 1) {
+    status.SetError("NATIVE_PATH called with unexpected arguments.");
+    return false;
+  }
+  if (parser.GetInputs().front().empty()) {
+    status.SetError("Invalid name for output variable.");
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  cmCMakePath path(inputPath);
+  if (arguments.Normalize) {
+    path = path.Normal();
+  }
+
+  status.GetMakefile().AddDefinition(parser.GetInputs().front(),
+                                     path.NativeString());
+
+  return true;
+}
+
+bool HandleConvertCommand(std::vector<std::string> const& args,
+                          cmExecutionStatus& status)
+{
+#if defined(_WIN32) && !defined(__CYGWIN__)
+  const auto pathSep = ";"_s;
+#else
+  const auto pathSep = ":"_s;
+#endif
+  const auto cmakePath = "TO_CMAKE_PATH_LIST"_s;
+  const auto nativePath = "TO_NATIVE_PATH_LIST"_s;
+
+  if (args.size() < 4 || args.size() > 5) {
+    status.SetError("CONVERT must be called with three or four arguments.");
+    return false;
+  }
+
+  const auto& action = args[2];
+
+  if (action != cmakePath && action != nativePath) {
+    status.SetError(
+      cmStrCat("CONVERT called with an unknown action: ", action, "."));
+    return false;
+  }
+
+  if (args[3].empty()) {
+    status.SetError("Invalid name for output variable.");
+    return false;
+  }
+
+  static NormalizeParser const parser;
+
+  const auto arguments = parser.Parse<4>(args);
+
+  if (!parser.GetInputs().empty()) {
+    status.SetError("CONVERT called with unexpected arguments.");
+    return false;
+  }
+
+  std::vector<std::string> paths;
+
+  if (action == cmakePath) {
+    paths = cmSystemTools::SplitString(args[1], pathSep.front());
+  } else {
+    cmExpandList(args[1], paths);
+  }
+
+  for (auto& path : paths) {
+    auto p = cmCMakePath(path,
+                         action == cmakePath ? cmCMakePath::native_format
+                                             : cmCMakePath::generic_format);
+    if (arguments.Normalize) {
+      p = p.Normal();
+    }
+    if (action == cmakePath) {
+      path = p.GenericString();
+    } else {
+      path = p.NativeString();
+    }
+  }
+
+  auto value = cmJoin(paths, action == cmakePath ? ";"_s : pathSep);
+  status.GetMakefile().AddDefinition(args[3], value);
+
+  return true;
+}
+
+bool HandleCompareCommand(std::vector<std::string> const& args,
+                          cmExecutionStatus& status)
+{
+  if (args.size() != 5) {
+    status.SetError("COMPARE must be called with four arguments.");
+    return false;
+  }
+
+  static std::map<cm::string_view,
+                  std::function<bool(const cmCMakePath&,
+                                     const cmCMakePath&)>> const operators{
+    { "EQUAL"_s,
+      [](const cmCMakePath& path1, const cmCMakePath& path2) -> bool {
+        return path1 == path2;
+      } },
+    { "NOT_EQUAL"_s,
+      [](const cmCMakePath& path1, const cmCMakePath& path2) -> bool {
+        return path1 != path2;
+      } }
+  };
+
+  const auto op = operators.find(args[2]);
+  if (op == operators.end()) {
+    status.SetError(cmStrCat(
+      "COMPARE called with an unknown comparison operator: ", args[2], "."));
+    return false;
+  }
+
+  if (args[4].empty()) {
+    status.SetError("Invalid name for output variable.");
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  cmCMakePath path1(inputPath);
+  cmCMakePath path2(args[3]);
+  auto result = op->second(path1, path2);
+
+  status.GetMakefile().AddDefinitionBool(args[4], result);
+
+  return true;
+}
+
+bool HandleHasItemCommand(
+  std::vector<std::string> const& args, cmExecutionStatus& status,
+  const std::function<bool(const cmCMakePath&)>& has_item)
+{
+  if (args.size() != 3) {
+    status.SetError(
+      cmStrCat(args.front(), " must be called with two arguments."));
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  if (args[2].empty()) {
+    status.SetError("Invalid name for output variable.");
+    return false;
+  }
+
+  cmCMakePath path(inputPath);
+  auto result = has_item(path);
+
+  status.GetMakefile().AddDefinitionBool(args[2], result);
+
+  return true;
+}
+
+bool HandleHasRootNameCommand(std::vector<std::string> const& args,
+                              cmExecutionStatus& status)
+{
+  return HandleHasItemCommand(
+    args, status,
+    [](const cmCMakePath& path) -> bool { return path.HasRootName(); });
+}
+
+bool HandleHasRootDirectoryCommand(std::vector<std::string> const& args,
+                                   cmExecutionStatus& status)
+{
+  return HandleHasItemCommand(
+    args, status,
+    [](const cmCMakePath& path) -> bool { return path.HasRootDirectory(); });
+}
+
+bool HandleHasRootPathCommand(std::vector<std::string> const& args,
+                              cmExecutionStatus& status)
+{
+  return HandleHasItemCommand(
+    args, status,
+    [](const cmCMakePath& path) -> bool { return path.HasRootPath(); });
+}
+
+bool HandleHasFilenameCommand(std::vector<std::string> const& args,
+                              cmExecutionStatus& status)
+{
+  return HandleHasItemCommand(
+    args, status,
+    [](const cmCMakePath& path) -> bool { return path.HasFileName(); });
+}
+
+bool HandleHasExtensionCommand(std::vector<std::string> const& args,
+                               cmExecutionStatus& status)
+{
+  return HandleHasItemCommand(
+    args, status,
+    [](const cmCMakePath& path) -> bool { return path.HasExtension(); });
+}
+
+bool HandleHasStemCommand(std::vector<std::string> const& args,
+                          cmExecutionStatus& status)
+{
+  return HandleHasItemCommand(
+    args, status,
+    [](const cmCMakePath& path) -> bool { return path.HasStem(); });
+}
+
+bool HandleHasRelativePathCommand(std::vector<std::string> const& args,
+                                  cmExecutionStatus& status)
+{
+  return HandleHasItemCommand(
+    args, status,
+    [](const cmCMakePath& path) -> bool { return path.HasRelativePath(); });
+}
+
+bool HandleHasParentPathCommand(std::vector<std::string> const& args,
+                                cmExecutionStatus& status)
+{
+  return HandleHasItemCommand(
+    args, status,
+    [](const cmCMakePath& path) -> bool { return path.HasParentPath(); });
+}
+
+bool HandleIsAbsoluteCommand(std::vector<std::string> const& args,
+                             cmExecutionStatus& status)
+{
+  if (args.size() != 3) {
+    status.SetError("IS_ABSOLUTE must be called with two arguments.");
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  if (args[2].empty()) {
+    status.SetError("Invalid name for output variable.");
+    return false;
+  }
+
+  bool isAbsolute = cmCMakePath(inputPath).IsAbsolute();
+
+  status.GetMakefile().AddDefinitionBool(args[2], isAbsolute);
+
+  return true;
+}
+
+bool HandleIsRelativeCommand(std::vector<std::string> const& args,
+                             cmExecutionStatus& status)
+{
+  if (args.size() != 3) {
+    status.SetError("IS_RELATIVE must be called with two arguments.");
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  if (args[2].empty()) {
+    status.SetError("Invalid name for output variable.");
+    return false;
+  }
+
+  bool isRelative = cmCMakePath(inputPath).IsRelative();
+
+  status.GetMakefile().AddDefinitionBool(args[2], isRelative);
+
+  return true;
+}
+
+bool HandleIsPrefixCommand(std::vector<std::string> const& args,
+                           cmExecutionStatus& status)
+{
+  if (args.size() < 4 || args.size() > 5) {
+    status.SetError("IS_PREFIX must be called with three or four arguments.");
+    return false;
+  }
+
+  static NormalizeParser const parser;
+
+  const auto arguments = parser.Parse(args);
+
+  if (parser.GetInputs().size() != 2) {
+    status.SetError("IS_PREFIX called with unexpected arguments.");
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  const auto& input = parser.GetInputs().front();
+  const auto& output = parser.GetInputs().back();
+
+  if (output.empty()) {
+    status.SetError("Invalid name for output variable.");
+    return false;
+  }
+
+  bool isPrefix;
+  if (arguments.Normalize) {
+    isPrefix =
+      cmCMakePath(inputPath).Normal().IsPrefix(cmCMakePath(input).Normal());
+  } else {
+    isPrefix = cmCMakePath(inputPath).IsPrefix(input);
+  }
+
+  status.GetMakefile().AddDefinitionBool(output, isPrefix);
+
+  return true;
+}
+
+bool HandleHashCommand(std::vector<std::string> const& args,
+                       cmExecutionStatus& status)
+{
+  if (args.size() < 3 || args.size() > 4) {
+    status.SetError("HASH must be called with two or three arguments.");
+    return false;
+  }
+
+  static NormalizeParser const parser;
+
+  const auto arguments = parser.Parse(args);
+
+  if (parser.GetInputs().size() != 1) {
+    status.SetError("HASH called with unexpected arguments.");
+    return false;
+  }
+
+  std::string inputPath;
+  if (!getInputPath(args[1], status, inputPath)) {
+    return false;
+  }
+
+  const auto& output = parser.GetInputs().front();
+
+  if (output.empty()) {
+    status.SetError("Invalid name for output variable.");
+    return false;
+  }
+
+  auto hash = hash_value(arguments.Normalize ? cmCMakePath(inputPath).Normal()
+                                             : cmCMakePath(inputPath));
+
+  std::ostringstream out;
+  out << std::setbase(16) << hash;
+
+  status.GetMakefile().AddDefinition(output, out.str());
+
+  return true;
+}
+} // anonymous namespace
+
+bool cmCMakePathCommand(std::vector<std::string> const& args,
+                        cmExecutionStatus& status)
+{
+  if (args.size() < 2) {
+    status.SetError("must be called with at least two arguments.");
+    return false;
+  }
+
+  static cmSubcommandTable const subcommand{
+    { "GET"_s, HandleGetCommand },
+    { "APPEND"_s, HandleAppendCommand },
+    { "CONCAT"_s, HandleConcatCommand },
+    { "REMOVE_FILENAME"_s, HandleRemoveFilenameCommand },
+    { "REPLACE_FILENAME"_s, HandleReplaceFilenameCommand },
+    { "REMOVE_EXTENSION"_s, HandleRemoveExtensionCommand },
+    { "REPLACE_EXTENSION"_s, HandleReplaceExtensionCommand },
+    { "NORMAL_PATH"_s, HandleNormalPathCommand },
+    { "RELATIVE_PATH"_s, HandleRelativePathCommand },
+    { "PROXIMATE_PATH"_s, HandleProximatePathCommand },
+    { "ABSOLUTE_PATH"_s, HandleAbsolutePathCommand },
+    { "CMAKE_PATH"_s, HandleCMakePathCommand },
+    { "NATIVE_PATH"_s, HandleNativePathCommand },
+    { "CONVERT"_s, HandleConvertCommand },
+    { "COMPARE"_s, HandleCompareCommand },
+    { "HAS_ROOT_NAME"_s, HandleHasRootNameCommand },
+    { "HAS_ROOT_DIRECTORY"_s, HandleHasRootDirectoryCommand },
+    { "HAS_ROOT_PATH"_s, HandleHasRootPathCommand },
+    { "HAS_FILENAME"_s, HandleHasFilenameCommand },
+    { "HAS_EXTENSION"_s, HandleHasExtensionCommand },
+    { "HAS_STEM"_s, HandleHasStemCommand },
+    { "HAS_RELATIVE_PATH"_s, HandleHasRelativePathCommand },
+    { "HAS_PARENT_PATH"_s, HandleHasParentPathCommand },
+    { "IS_ABSOLUTE"_s, HandleIsAbsoluteCommand },
+    { "IS_RELATIVE"_s, HandleIsRelativeCommand },
+    { "IS_PREFIX"_s, HandleIsPrefixCommand },
+    { "HASH"_s, HandleHashCommand }
+  };
+
+  return subcommand(args[0], args, status);
+}

Source/cmCMakePathCommand.h

@@ -0,0 +1,14 @@
+/* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+   file Copyright.txt or https://cmake.org/licensing for details.  */
+
+#pragma once
+
+#include "cmConfigure.h" // IWYU pragma: keep
+
+#include <string>
+#include <vector>
+
+class cmExecutionStatus;
+
+bool cmCMakePathCommand(std::vector<std::string> const& args,
+                        cmExecutionStatus& status);

Source/cmCommands.cxx

@@ -17,6 +17,7 @@
 #include "cmBreakCommand.h"
 #include "cmBuildCommand.h"
 #include "cmCMakeMinimumRequired.h"
+#include "cmCMakePathCommand.h"
 #include "cmCMakePolicyCommand.h"
 #include "cmCommand.h"
 #include "cmConfigureFileCommand.h"
@@ -120,6 +121,7 @@ void GetScriptingCommands(cmState* state)
 {
   state->AddBuiltinCommand("break", cmBreakCommand);
   state->AddBuiltinCommand("cmake_minimum_required", cmCMakeMinimumRequired);
+  state->AddBuiltinCommand("cmake_path", cmCMakePathCommand);
   state->AddBuiltinCommand("cmake_policy", cmCMakePolicyCommand);
   state->AddBuiltinCommand("configure_file", cmConfigureFileCommand);
   state->AddBuiltinCommand("continue", cmContinueCommand);

Tests/RunCMake/CMakeLists.txt

@@ -305,6 +305,7 @@ add_RunCMake_test(export)
 add_RunCMake_test(cmake_language)
 add_RunCMake_test(cmake_minimum_required)
 add_RunCMake_test(cmake_parse_arguments)
+add_RunCMake_test(cmake_path)
 add_RunCMake_test(continue)
 add_executable(color_warning color_warning.c)
 add_RunCMake_test(ctest_build -DCOLOR_WARNING=$<TARGET_FILE:color_warning>)

Tests/RunCMake/cmake_path/ABSOLUTE_PATH-OUTPUT_VARIABLE-invalid-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/ABSOLUTE_PATH-OUTPUT_VARIABLE-no-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/ABSOLUTE_PATH-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/ABSOLUTE_PATH-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/ABSOLUTE_PATH.cmake

@@ -0,0 +1,39 @@
+
+include ("${RunCMake_SOURCE_DIR}/check_errors.cmake")
+unset (errors)
+
+set (path "../../a/d")
+cmake_path(ABSOLUTE_PATH path BASE_DIRECTORY "/x/y/a/f")
+if (NOT path STREQUAL "/x/y/a/f/../../a/d")
+  list (APPEND errors "'${path}' instead of '/x/y/a/f/../../a/d'")
+endif()
+
+set (path "../../a/d")
+cmake_path(ABSOLUTE_PATH path BASE_DIRECTORY "/x/y/a/f" NORMALIZE)
+if (NOT path STREQUAL "/x/y/a/d")
+  list (APPEND errors "'${path}' instead of '/x/y/a/d'")
+endif()
+
+set (path "../../a/d")
+cmake_path(ABSOLUTE_PATH path BASE_DIRECTORY "/x/y/a/f" NORMALIZE OUTPUT_VARIABLE output)
+if (NOT path STREQUAL "../../a/d")
+  list (APPEND errors "input changed unexpectedly")
+endif()
+if (NOT output STREQUAL "/x/y/a/d")
+  list (APPEND errors "'${output}' instead of '/x/y/a/d'")
+endif()
+
+set (path "/a/d/../e")
+cmake_path(ABSOLUTE_PATH path BASE_DIRECTORY "/x/y/a/f")
+if (NOT path STREQUAL "/a/d/../e")
+  list (APPEND errors "'${path}' instead of '/a/d/../e'")
+endif()
+
+set (path "/a/d/../e")
+cmake_path(ABSOLUTE_PATH path BASE_DIRECTORY "/x/y/a/f" NORMALIZE)
+if (NOT path STREQUAL "/a/e")
+  list (APPEND errors "'${path}' instead of '/a/e'")
+endif()
+
+
+check_errors (ABSOLUTE_PATH ${errors})

Tests/RunCMake/cmake_path/APPEND-OUTPUT_VARIABLE-invalid-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/APPEND-OUTPUT_VARIABLE-no-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/APPEND-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/APPEND.cmake

@@ -0,0 +1,77 @@
+
+include ("${RunCMake_SOURCE_DIR}/check_errors.cmake")
+unset (errors)
+
+cmake_path (APPEND path "/a/b" "c")
+if (NOT path STREQUAL "/a/b/c")
+  list (APPEND errors "'${path}' instead of '/a/b/c'")
+endif()
+
+set (path "/a/b")
+cmake_path (APPEND path "c")
+if (NOT path STREQUAL "/a/b/c")
+  list (APPEND errors "'${path}' instead of '/a/b/c'")
+endif()
+
+cmake_path (APPEND path "x/y" "z" OUTPUT_VARIABLE output)
+if (NOT path STREQUAL "/a/b/c")
+  list (APPEND errors "input changed unexpectedly")
+endif()
+if (NOT output STREQUAL "/a/b/c/x/y/z")
+  list (APPEND errors "'${output}' instead of '/a/b/c/x/y/z'")
+endif()
+
+set (path "a")
+cmake_path (APPEND path "")
+if (NOT path STREQUAL "a/")
+  list (APPEND errors "'${path}' instead of 'a/'")
+endif()
+
+cmake_path (APPEND path "/b")
+if (NOT path STREQUAL "/b")
+  list (APPEND errors "'${path}' instead of '/b'")
+endif()
+
+if (WIN32)
+  set (path "a")
+  cmake_path (APPEND path "c:/b")
+  if (NOT path STREQUAL "c:/b")
+    list (APPEND errors "'${path}' instead of 'c:/b'")
+  endif()
+
+  set (path "a")
+  cmake_path (APPEND path "c:")
+  if (NOT path STREQUAL "c:")
+    list (APPEND errors "'${path}' instead of 'c:'")
+  endif()
+  cmake_path (APPEND path "")
+  if (NOT path STREQUAL "c:")
+    list (APPEND errors "'${path}' instead of 'c:'")
+  endif()
+
+  set (path "c:a")
+  cmake_path (APPEND path "/b")
+  if (NOT path STREQUAL "c:/b")
+    list (APPEND errors "'${path}' instead of 'c:/b'")
+  endif()
+
+  set (path "c:a")
+  cmake_path (APPEND path "c:b")
+  if (NOT path STREQUAL "c:a/b")
+    list (APPEND errors "'${path}' instead of 'c:a/b'")
+  endif()
+
+  set (path "//host")
+  cmake_path (APPEND path "b")
+  if (NOT path STREQUAL "//host/b")
+    list (APPEND errors "'${path}' instead of '//host/b'")
+  endif()
+
+  set (path "//host/")
+  cmake_path (APPEND path "b")
+  if (NOT path STREQUAL "//host/b")
+    list (APPEND errors "'${path}' instead of '//host/b'")
+  endif()
+endif()
+
+check_errors (APPEND ${errors})

Tests/RunCMake/cmake_path/CMAKE_PATH-OUTPUT_VARIABLE-no-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CMAKE_PATH-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CMAKE_PATH-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CMAKE_PATH-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CMAKE_PATH-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CMAKE_PATH.cmake

@@ -0,0 +1,43 @@
+
+include ("${RunCMake_SOURCE_DIR}/check_errors.cmake")
+unset (errors)
+
+cmake_path(CMAKE_PATH path "/x/y/z/../../a/d")
+if (NOT path STREQUAL "/x/y/z/../../a/d")
+  list (APPEND errors "'${path}' instead of '/x/y/z/../../a/d'")
+endif()
+cmake_path(CMAKE_PATH path NORMALIZE "/x/y/z/../../a/d")
+if (NOT path STREQUAL "/x/a/d")
+  list (APPEND errors "'${path}' instead of '/x/a/d'")
+endif()
+
+if (WIN32)
+  cmake_path(CMAKE_PATH path "/x\\y/z\\..\\../a/d")
+  if (NOT path STREQUAL "/x/y/z/../../a/d")
+    list (APPEND errors "'${path}' instead of '/x/y/z/../../a/d'")
+  endif()
+  cmake_path(CMAKE_PATH path NORMALIZE "/x\\y/z\\..\\../a/d")
+  if (NOT path STREQUAL "/x/a/d")
+    list (APPEND errors "'${path}' instead of '/x/a/d'")
+  endif()
+
+  cmake_path(CMAKE_PATH path "//?/c:/x\\y/z\\..\\../a/d")
+  if (NOT path STREQUAL "c:/x/y/z/../../a/d")
+    list (APPEND errors "'${path}' instead of 'c:/x/y/z/../../a/d'")
+  endif()
+  cmake_path(CMAKE_PATH path NORMALIZE "//?/c:/x\\y/z\\..\\../a/d")
+  if (NOT path STREQUAL "c:/x/a/d")
+    list (APPEND errors "'${path}' instead of 'c:/x/a/d'")
+  endif()
+
+  cmake_path(CMAKE_PATH path "\\\\?\\UNC/host/x\\y/z\\..\\../a/d")
+  if (NOT path STREQUAL "//host/x/y/z/../../a/d")
+    list (APPEND errors "'${path}' instead of '//host/x/y/z/../../a/d'")
+  endif()
+  cmake_path(CMAKE_PATH path NORMALIZE "\\\\?\\UNC\\host/x\\y/z\\..\\../a/d")
+  if (NOT path STREQUAL "//host/x/a/d")
+    list (APPEND errors "'${path}' instead of '//host/x/a/d'")
+  endif()
+endif()
+
+check_errors (CMAKE_PATH ${errors})

Tests/RunCMake/cmake_path/CMakeLists.txt

@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 3.18...3.19)
+project(${RunCMake_TEST} NONE)
+include(${RunCMake_TEST}.cmake)

Tests/RunCMake/cmake_path/COMPARE-EQUAL-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/COMPARE-EQUAL-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/COMPARE-EQUAL-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/COMPARE-NOT_EQUAL-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/COMPARE-NOT_EQUAL-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/COMPARE-NOT_EQUAL-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/COMPARE-wrong-operator-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/COMPARE-wrong-operator-stderr.txt

@@ -0,0 +1,2 @@
+CMake Error at COMPARE-wrong-operator.cmake:[0-9]+ \(cmake_path\):
+  cmake_path COMPARE called with an unknown comparison operator: FOO.

Tests/RunCMake/cmake_path/COMPARE-wrong-operator.cmake

@@ -0,0 +1,3 @@
+
+set (path "/a/b")
+cmake_path(COMPARE path FOO "/other" output)

Tests/RunCMake/cmake_path/COMPARE.cmake

@@ -0,0 +1,22 @@
+
+include ("${RunCMake_SOURCE_DIR}/check_errors.cmake")
+unset (errors)
+
+set (path "a///b/c")
+cmake_path(COMPARE path EQUAL "a/b/c" output)
+if (NOT output)
+  list (APPEND errors "'${path}' not equal to 'a/b/c'")
+endif()
+
+set (path "a/b/d/../c")
+cmake_path(COMPARE path NOT_EQUAL "a/b/c" output)
+if (NOT output)
+  list (APPEND errors "'${path}' equal to 'a/b/c'")
+endif()
+cmake_path(NORMAL_PATH path)
+cmake_path(COMPARE path EQUAL "a/b/c" output)
+if (NOT output)
+  list (APPEND errors "'${path}' not equal to 'a/b/c'")
+endif()
+
+check_errors (COMPARE ${errors})

Tests/RunCMake/cmake_path/CONCAT-OUTPUT_VARIABLE-invalid-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CONCAT-OUTPUT_VARIABLE-no-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CONCAT-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CONCAT.cmake

@@ -0,0 +1,20 @@
+
+include ("${RunCMake_SOURCE_DIR}/check_errors.cmake")
+unset (errors)
+
+set (path "/a/b")
+cmake_path (CONCAT path "cd")
+if (NOT path STREQUAL "/a/bcd")
+  list (APPEND errors "'${path}' instead of 'a/bcd'")
+endif()
+
+set (path "/a/b")
+cmake_path (CONCAT path "cd" "ef" OUTPUT_VARIABLE output)
+if (NOT path STREQUAL "/a/b")
+  list (APPEND errors "input changed unexpectedly")
+endif()
+if (NOT output STREQUAL "/a/bcdef")
+  list (APPEND errors "'${output}' instead of 'a/bcdef'")
+endif()
+
+check_errors (CONCAT ${errors})

Tests/RunCMake/cmake_path/CONVERT-TO_CMAKE_PATH_LIST-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CONVERT-TO_CMAKE_PATH_LIST-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CONVERT-TO_CMAKE_PATH_LIST-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CONVERT-TO_NATIVE_PATH_LIST-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CONVERT-TO_NATIVE_PATH_LIST-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CONVERT-TO_NATIVE_PATH_LIST-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CONVERT-wrong-operator-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/CONVERT-wrong-operator-stderr.txt

@@ -0,0 +1,2 @@
+CMake Error at CONVERT-wrong-operator.cmake:[0-9]+ \(cmake_path\):
+  cmake_path CONVERT called with an unknown action: FOO.

Tests/RunCMake/cmake_path/CONVERT-wrong-operator.cmake

@@ -0,0 +1,2 @@
+
+cmake_path(CONVERT "/a/b" FOO output)

Tests/RunCMake/cmake_path/CONVERT.cmake

@@ -0,0 +1,110 @@
+
+include ("${RunCMake_SOURCE_DIR}/check_errors.cmake")
+unset (errors)
+
+cmake_path(CONVERT "/x/y/z/../../a/d" TO_CMAKE_PATH_LIST output)
+if (NOT output STREQUAL "/x/y/z/../../a/d")
+  list (APPEND errors "TO_CMAKE_PATH_LIST: '${output}' instead of '/x/y/z/../../a/d'")
+endif()
+cmake_path(CONVERT "/x/y/z/../../a/d" TO_CMAKE_PATH_LIST output NORMALIZE)
+if (NOT output STREQUAL "/x/a/d")
+  list (APPEND errors "TO_CMAKE_PATH_LIST: '${output}' instead of '/x/a/d'")
+endif()
+
+if (WIN32)
+  cmake_path(CONVERT "/x\\y/z\\..\\../a/d" TO_CMAKE_PATH_LIST output)
+  if (NOT output STREQUAL "/x/y/z/../../a/d")
+    list (APPEND errors "TO_CMAKE_PATH_LIST: '${output}' instead of '/x/y/z/../../a/d'")
+  endif()
+  cmake_path(CONVERT "/x\\y/z\\..\\../a/d" TO_CMAKE_PATH_LIST output NORMALIZE)
+  if (NOT output STREQUAL "/x/a/d")
+    list (APPEND errors "TO_CMAKE_PATH_LIST: '${output}' instead of '/x/a/d'")
+  endif()
+
+  cmake_path(CONVERT "//?/c:/x\\y/z\\..\\../a/d" TO_CMAKE_PATH_LIST output)
+  if (NOT output STREQUAL "c:/x/y/z/../../a/d")
+    list (APPEND errors "TO_CMAKE_PATH_LIST: '${output}' instead of 'c:/x/y/z/../../a/d'")
+  endif()
+  cmake_path(CONVERT "//?/c:/x\\y/z\\..\\../a/d" TO_CMAKE_PATH_LIST output NORMALIZE)
+  if (NOT output STREQUAL "c:/x/a/d")
+    list (APPEND errors "TO_CMAKE_PATH_LIST: '${output}' instead of 'c:/x/a/d'")
+  endif()
+
+  cmake_path(CONVERT "//?/UNC/host/x\\y/z\\..\\../a/d" TO_CMAKE_PATH_LIST output)
+  if (NOT output STREQUAL "//host/x/y/z/../../a/d")
+    list (APPEND errors "TO_CMAKE_PATH_LIST: '${output}' instead of '//host/x/y/z/../../a/d'")
+  endif()
+  cmake_path(CONVERT "//?/UNC/host/x\\y/z\\..\\../a/d" TO_CMAKE_PATH_LIST output NORMALIZE)
+  if (NOT output STREQUAL "//host/x/a/d")
+    list (APPEND errors "TO_CMAKE_PATH_LIST: '${output}' instead of '//host/x/a/d'")
+  endif()
+endif()
+
+if (WIN32)
+  cmake_path(CONVERT "/x\\y/z/..\\../a\\d;c:\\a/b\\c/..\\d" TO_CMAKE_PATH_LIST output)
+  if (NOT output STREQUAL "/x/y/z/../../a/d;c:/a/b/c/../d")
+    list (APPEND errors "TO_CMAKE_PATH_LIST: '${output}' instead of '/x/y/z/../../a/d;c:/a/b/c/../d'")
+  endif()
+  cmake_path(CONVERT "/x\\y/z/..\\../a\\d;c:\\a/b\\c/..\\d" TO_CMAKE_PATH_LIST output NORMALIZE)
+  if (NOT output STREQUAL "/x/a/d;c:/a/b/d")
+    list (APPEND errors "TO_CMAKE_PATH_LIST: '${output}' instead of '/x/a/d;c:/a/b/d'")
+  endif()
+else()
+  cmake_path(CONVERT "/x/y/z/../../a/d:/a/b/c/../d" TO_CMAKE_PATH_LIST output)
+  if (NOT output STREQUAL "/x/y/z/../../a/d;/a/b/c/../d")
+    list (APPEND errors "TO_CMAKE_PATH_LIST: '${outputh}' instead of '/x/y/z/../../a/d;/a/b/c/../d'")
+  endif()
+  cmake_path(CONVERT "/x/y/z/../../a/d:/a/b/c/../d" TO_CMAKE_PATH_LIST output NORMALIZE)
+  if (NOT output STREQUAL "/x/a/d;/a/b/d")
+    list (APPEND errors "TO_CMAKE_PATH_LIST: '${output}' instead of '/x/a/d;/a/b/d'")
+  endif()
+endif()
+
+
+if (WIN32)
+  cmake_path(CONVERT "c:/a//b\\c/..\\d" TO_NATIVE_PATH_LIST output)
+  if (NOT output STREQUAL "c:\\a\\\\b\\c\\..\\d")
+    list (APPEND errors "TO_NATIVE_PATH_LIST: '${output}' instead of 'c:\\a\\\\b\\c\\..\\d'")
+  endif()
+  cmake_path(CONVERT "c:/a//b\\c/..\\d" TO_NATIVE_PATH_LIST output NORMALIZE)
+  if (NOT output STREQUAL "c:\\a\\b\\d")
+    list (APPEND errors "TO_NATIVE_PATH_LIST: '${output}' instead of 'c:\\a\\b\\d'")
+  endif()
+
+  cmake_path(CONVERT "//host/a//b\\c/..\\d" TO_NATIVE_PATH_LIST output)
+  if (NOT output STREQUAL "\\\\host\\a\\\\b\\c\\..\\d")
+    list (APPEND errors "TO_NATIVE_PATH_LIST: '${output}' instead of '\\\\host\\a\\\\b\\c\\..\\d'")
+  endif()
+  cmake_path(CONVERT "//host/a//b\\c/..\\d" TO_NATIVE_PATH_LIST output NORMALIZE)
+  if (NOT output STREQUAL "\\\\host\\a\\b\\d")
+    list (APPEND errors "TO_NATIVE_PATH_LIST: '${output}' instead of '\\\\host\\a\\b\\d'")
+  endif()
+  cmake_path(CONVERT "//host/a//b\\c/..\\d;c:/a//b\\c/..\\d" TO_NATIVE_PATH_LIST output)
+  if (NOT output STREQUAL "\\\\host\\a\\\\b\\c\\..\\d;c:\\a\\\\b\\c\\..\\d")
+    list (APPEND errors "TO_NATIVE_PATH_LIST: '${output}' instead of '\\\\host\\a\\\\b\\c\\..\\d;c:\\a\\\\b\\c\\..\\d'")
+  endif()
+  cmake_path(CONVERT "//host/a//b\\c/..\\d;c:/a//b\\c/..\\d" TO_NATIVE_PATH_LIST output NORMALIZE)
+  if (NOT output STREQUAL "\\\\host\\a\\b\\d;c:\\a\\b\\d")
+    list (APPEND errors "TO_NATIVE_PATH_LIST: '${output}' instead of '\\\\host\\a\\b\\d;c:\\a\\b\\d'")
+  endif()
+else()
+  cmake_path(CONVERT "/a//b/c/../d" TO_NATIVE_PATH_LIST output)
+  if (NOT output STREQUAL "/a//b/c/../d")
+    list (APPEND errors "TO_NATIVE_PATH_LIST: '${output}' instead of '/a//b/c/../d'")
+  endif()
+  cmake_path(CONVERT "/a//b/c/../d" TO_NATIVE_PATH_LIST output NORMALIZE)
+  if (NOT output STREQUAL "/a/b/d")
+    list (APPEND errors "TO_NATIVE_PATH_LIST: '${output}' instead of '/a/b/d'")
+  endif()
+  cmake_path(CONVERT "/x/y/z/../../a/d;/a/b/c/../d" TO_NATIVE_PATH_LIST output)
+  if (NOT output STREQUAL "/x/y/z/../../a/d:/a/b/c/../d")
+    list (APPEND errors "TO_NATIVE_PATH_LIST: '${output}' instead of '/x/y/z/../../a/d:/a/b/c/../d'")
+  endif()
+  cmake_path(CONVERT "/x/y/z/../../a/d;/a/b/c/../d" TO_NATIVE_PATH_LIST output NORMALIZE)
+  if (NOT output STREQUAL "/x/a/d:/a/b/d")
+    list (APPEND errors "TO_NATIVE_PATH_LIST: '${output}' instead of '/x/a/d:/a/b/d'")
+  endif()
+endif()
+
+
+check_errors (CONVERT ${errors})

Tests/RunCMake/cmake_path/GET-EXTENSION-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-EXTENSION-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-EXTENSION-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-EXTENSION-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-FILENAME-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-FILENAME-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-FILENAME-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-FILENAME-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-PARENT_PATH-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-PARENT_PATH-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-PARENT_PATH-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-PARENT_PATH-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-RELATIVE_PATH-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-RELATIVE_PATH-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-RELATIVE_PATH-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-RELATIVE_PATH-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-ROOT_DIRECTORY-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-ROOT_DIRECTORY-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-ROOT_DIRECTORY-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-ROOT_DIRECTORY-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-ROOT_NAME-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-ROOT_NAME-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-ROOT_NAME-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-ROOT_NAME-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-ROOT_PATH-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-ROOT_PATH-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-ROOT_PATH-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-ROOT_PATH-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-STEM-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-STEM-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-STEM-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-STEM-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-wrong-operator-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/GET-wrong-operator-stderr.txt

@@ -0,0 +1,2 @@
+CMake Error at GET-wrong-operator.cmake:[0-9]+ \(cmake_path\):
+  cmake_path GET called with an unknown action: FOO.

Tests/RunCMake/cmake_path/GET-wrong-operator.cmake

@@ -0,0 +1,3 @@
+
+set (path "/a/b")
+cmake_path(GET path FOO output)

Tests/RunCMake/cmake_path/GET.cmake

@@ -0,0 +1,248 @@
+
+include ("${RunCMake_SOURCE_DIR}/check_errors.cmake")
+unset (errors)
+
+###############################################
+## First test with a path defining all elements
+###############################################
+if (WIN32)
+  set (path "C:/aa/bb/cc.ext1.ext2")
+else()
+  set (path "/aa/bb/cc.ext1.ext2")
+endif()
+
+cmake_path(GET path ROOT_NAME output)
+if (WIN32)
+  if (NOT output STREQUAL "C:")
+    list (APPEND errors "ROOT_NAME returns bad data: ${output}")
+  endif()
+else()
+  if (NOT output STREQUAL "")
+    list (APPEND errors "ROOT_NAME returns bad data: ${output}")
+  endif()
+endif()
+
+cmake_path(GET path ROOT_DIRECTORY output)
+if (NOT output STREQUAL "/")
+  list (APPEND errors "ROOT_DIRECTORY returns bad data: ${output}")
+endif()
+
+cmake_path(GET path ROOT_PATH output)
+if (WIN32)
+  if (NOT output STREQUAL "C:/")
+    list (APPEND errors "ROOT_PATH returns bad data: ${output}")
+  endif()
+else()
+  if (NOT output STREQUAL "/")
+    list (APPEND errors "ROOT_PATH returns bad data: ${output}")
+  endif()
+endif()
+
+cmake_path(GET path FILENAME output)
+if (NOT output STREQUAL "cc.ext1.ext2")
+  list (APPEND errors "FILENAME returns bad data: ${output}")
+endif()
+
+cmake_path(GET path EXTENSION output)
+if (NOT output STREQUAL ".ext1.ext2")
+  list (APPEND errors "EXTENSION returns bad data: ${output}")
+endif()
+cmake_path(GET path EXTENSION LAST_ONLY output)
+if (NOT output STREQUAL ".ext2")
+  list (APPEND errors "EXTENSION LAST_ONLY returns bad data: ${output}")
+endif()
+
+cmake_path(GET path STEM output)
+if (NOT output STREQUAL "cc")
+  list (APPEND errors "STEM returns bad data: ${output}")
+endif()
+cmake_path(GET path STEM LAST_ONLY output)
+if (NOT output STREQUAL "cc.ext1")
+  list (APPEND errors "STEM LAST_ONLY returns bad data: ${output}")
+endif()
+
+cmake_path(GET path RELATIVE_PATH output)
+if (NOT output STREQUAL "aa/bb/cc.ext1.ext2")
+  list (APPEND errors "RELATIVE_PATH returns bad data: ${output}")
+endif()
+
+cmake_path(GET path PARENT_PATH output)
+if (WIN32)
+  if (NOT output STREQUAL "C:/aa/bb")
+    list (APPEND errors "PARENT_PATH returns bad data: ${output}")
+  endif()
+else()
+  if (NOT output STREQUAL "/aa/bb")
+    list (APPEND errors "PARENT_PATH returns bad data: ${output}")
+  endif()
+endif()
+
+######################################
+## second, tests with missing elements
+######################################
+set (path "aa/bb/")
+
+cmake_path(GET path ROOT_NAME output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "ROOT_NAME returns bad data: ${output}")
+endif()
+
+cmake_path(GET path ROOT_DIRECTORY output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "ROOT_DIRECTORY returns bad data: ${output}")
+endif()
+
+cmake_path(GET path ROOT_PATH output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "ROOT_PATH returns bad data: ${output}")
+endif()
+
+cmake_path(GET path FILENAME output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "FILENAME returns bad data: ${output}")
+endif()
+
+cmake_path(GET path EXTENSION output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "EXTENSION returns bad data: ${output}")
+endif()
+
+cmake_path(GET path STEM output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "STEM returns bad data: ${output}")
+endif()
+
+cmake_path(GET path RELATIVE_PATH output)
+if (NOT output STREQUAL path)
+  list (APPEND errors "RELATIVE_PATH returns bad data: ${output}")
+endif()
+
+cmake_path(GET path PARENT_PATH output)
+if (NOT output STREQUAL "aa/bb")
+  list (APPEND errors "PARENT_PATH returns bad data: ${output}")
+endif()
+
+##################################
+set (path "/aa/bb/")
+
+cmake_path(GET path ROOT_NAME output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "ROOT_NAME returns bad data: ${output}")
+endif()
+
+cmake_path(GET path ROOT_DIRECTORY output)
+if (NOT output STREQUAL "/")
+  list (APPEND errors "ROOT_DIRECTORY returns bad data: ${output}")
+endif()
+
+cmake_path(GET path ROOT_PATH output)
+if (NOT output STREQUAL "/")
+  list (APPEND errors "ROOT_PATH returns bad data: ${output}")
+endif()
+
+###################################
+set (path "/")
+
+cmake_path(GET path ROOT_NAME output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "ROOT_NAME returns bad data: ${output}")
+endif()
+
+cmake_path(GET path ROOT_DIRECTORY output)
+if (NOT output STREQUAL "/")
+  list (APPEND errors "ROOT_DIRECTORY returns bad data: ${output}")
+endif()
+
+cmake_path(GET path ROOT_PATH output)
+if (NOT output STREQUAL "/")
+  list (APPEND errors "ROOT_PATH returns bad data: ${output}")
+endif()
+
+cmake_path(GET path FILENAME output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "FILENAME returns bad data: ${output}")
+endif()
+
+cmake_path(GET path EXTENSION output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "EXTENSION returns bad data: ${output}")
+endif()
+
+cmake_path(GET path STEM output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "STEM returns bad data: ${output}")
+endif()
+
+cmake_path(GET path RELATIVE_PATH output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "RELATIVE_PATH returns bad data: ${output}")
+endif()
+
+cmake_path(GET path PARENT_PATH output)
+if (NOT output STREQUAL "/")
+  list (APPEND errors "PARENT_PATH returns bad data: ${output}")
+endif()
+
+###################################
+set (path ".file")
+
+cmake_path(GET path FILENAME output)
+if (NOT output STREQUAL ".file")
+  list (APPEND errors "FILENAME returns bad data: ${output}")
+endif()
+
+cmake_path(GET path EXTENSION output)
+if (NOT output STREQUAL "")
+  list (APPEND errors "EXTENSION returns bad data: ${output}")
+endif()
+
+cmake_path(GET path STEM output)
+if (NOT output STREQUAL ".file")
+  list (APPEND errors "STEM returns bad data: ${output}")
+endif()
+
+###################################
+set (path ".file.ext")
+
+cmake_path(GET path FILENAME output)
+if (NOT output STREQUAL ".file.ext")
+  list (APPEND errors "FILENAME returns bad data: ${output}")
+endif()
+
+cmake_path(GET path EXTENSION output)
+if (NOT output STREQUAL ".ext")
+  list (APPEND errors "EXTENSION returns bad data: ${output}")
+endif()
+cmake_path(GET path EXTENSION LAST_ONLY output)
+if (NOT output STREQUAL ".ext")
+  list (APPEND errors "EXTENSION returns bad data: ${output}")
+endif()
+
+cmake_path(GET path STEM output)
+if (NOT output STREQUAL ".file")
+  list (APPEND errors "STEM returns bad data: ${output}")
+endif()
+
+###################################
+set (path ".file.ext1.ext2")
+
+cmake_path(GET path FILENAME output)
+if (NOT output STREQUAL ".file.ext1.ext2")
+  list (APPEND errors "FILENAME returns bad data: ${output}")
+endif()
+
+cmake_path(GET path EXTENSION output)
+if (NOT output STREQUAL ".ext1.ext2")
+  list (APPEND errors "EXTENSION returns bad data: ${output}")
+endif()
+cmake_path(GET path EXTENSION LAST_ONLY output)
+if (NOT output STREQUAL ".ext2")
+  list (APPEND errors "EXTENSION returns bad data: ${output}")
+endif()
+
+cmake_path(GET path STEM output)
+if (NOT output STREQUAL ".file")
+  list (APPEND errors "STEM returns bad data: ${output}")
+endif()
+
+check_errors (GET ${errors})

Tests/RunCMake/cmake_path/HASH-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/HASH-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/HASH-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/HASH-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/HASH.cmake

@@ -0,0 +1,27 @@
+
+include ("${RunCMake_SOURCE_DIR}/check_errors.cmake")
+unset (errors)
+
+set (path1 "a///b/c")
+cmake_path(HASH path1 hash1)
+set (path2 "a/b////c")
+cmake_path(HASH path2 hash2)
+if (NOT hash1 STREQUAL hash2)
+  list (APPEND errors "'hash values not equal for '${path1}' and '${path2}'")
+endif()
+
+set (path1 "a///b/c/../d")
+cmake_path(HASH path1 hash1)
+set (path2 "a/b////d")
+cmake_path(HASH path2 hash2)
+if (hash1 STREQUAL hash2)
+  list (APPEND errors "'hash values equal for '${path1}' and '${path2}'")
+endif()
+cmake_path(HASH path1 hash1 NORMALIZE)
+cmake_path(HASH path2 NORMALIZE hash2)
+if (NOT hash1 STREQUAL hash2)
+  list (APPEND errors "'hash values not equal for '${path1}' and '${path2}'")
+endif()
+
+
+check_errors (HASH ${errors})

Tests/RunCMake/cmake_path/HAS_EXTENSION-invalid-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/HAS_EXTENSION-missing-output-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/HAS_EXTENSION-unexpected-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/HAS_EXTENSION-wrong-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_path/HAS_FILENAME-invalid-output-result.txt

@@ -0,0 +1 @@
+1