mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-01 03:11:08 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Clarify behavior of path-based equality conditions

Browse Source 
The docs for if(PATH_EQUAL) did not mention the component-wise
nature of the checks. It also claimed no normalization was
performed, but multiple separators are effectively collapsed
(part of normalization). Improve the wording to clarify both of
these points.

Also update the corresponding description of cmake_path(COMPARE),
which had the same inaccuracy.

Fixes: #23758
This commit is contained in:
Craig Scott
2022-07-24 16:02:13 +10:00
parent 66077528f9
commit 37e01773e4
2 changed files with 14 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
Help/command/cmake_path.rst
View File

@@ -482,8 +482,9 @@ are :ref:`normalized <Normalization>` before the check.
cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
Compares the lexical representations of two paths provided as string literals.
No normalization is performed on either path. Equality is determined
according to the following pseudo-code logic:
No normalization is performed on either path, except multiple consecutive
directory separators are effectively collapsed into a single separator.
Equality is determined according to the following pseudo-code logic:
::

17
Help/command/if.rst
View File

@@ -320,13 +320,18 @@ Path Comparisons
.. _PATH_EQUAL:
``if(<variable|string> PATH_EQUAL <variable|string>)``
.. versionadded:: 3.24
Compares the lexical representations of two paths provided as string
literals or variables. No normalization is performed on either path.
.. versionadded:: 3.24
Lexical comparison has the advantage over string comparison to have a
knowledge of the structure of the path. So, the following comparison is
``TRUE`` using ``PATH_EQUAL`` operator, but ``FALSE`` with ``STREQUAL``:
Compares the two paths component-by-component. Only if every component of
both paths match will the two paths compare equal. Multiple path separators
are effectively collapsed into a single separator, but note that backslashes
are not converted to forward slashes. No other
:ref:`path normalization <Normalization>` is performed.
Component-wise comparison is superior to string-based comparison due to the
handling of multiple path separators. In the following example, the
expression evaluates to true using ``PATH_EQUAL``, but false with
``STREQUAL``:
.. code-block:: cmake