From 37e01773e40c76fbf34d08349e15bff1be2d971e Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sun, 24 Jul 2022 16:02:13 +1000 Subject: Help: Clarify behavior of path-based equality conditions 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 --- Help/command/cmake_path.rst | 5 +++-- Help/command/if.rst | 19 ++++++++++++------- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index 6fd3cf6..eb7da07 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -482,8 +482,9 @@ are :ref:`normalized ` before the check. cmake_path(COMPARE NOT_EQUAL ) 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: :: diff --git a/Help/command/if.rst b/Help/command/if.rst index c096725..301cdce 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -320,13 +320,18 @@ Path Comparisons .. _PATH_EQUAL: ``if( PATH_EQUAL )`` - .. versionadded:: 3.24 - Compares the lexical representations of two paths provided as string - literals or variables. No normalization is performed on either path. - - 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``: + .. versionadded:: 3.24 + + 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 ` 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 -- cgit v0.12