From ec5951e07805f077b7458203ed01b2ee8bb9da24 Mon Sep 17 00:00:00 2001 From: Marc Chevrier Date: Mon, 26 Oct 2020 13:10:37 +0100 Subject: cmake_path: Enhance documentation --- Help/command/cmake_path.rst | 249 ++++++++++++++++++++++---------------------- 1 file changed, 127 insertions(+), 122 deletions(-) diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index 555926b..cb84dd1 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -65,15 +65,15 @@ The following exceptions apply: the target system. So this is not generally applicable to the target system in cross-compiling environment. -For all commands, ```` placeholder expect a variable name. An error will -be raised if the variable does not exist, except for `APPEND`_ and +For all commands, ```` placeholder expect a variable name. An error +will be raised if the variable does not exist, except for `APPEND`_ and `CMAKE_PATH`_ sub-commands. ```` placeholder expect a string literal. -``[...]`` placeholder expect zero or more arguments. ```` +``[...]`` placeholder expect zero or more arguments. ```` placeholder expect a variable name. .. note:: - ``cmake_path`` command does not support list of paths. The ```` + ``cmake_path`` command does not support list of paths. The ```` placeholder must store only one path name. To initialize a path variable, three possibilities can be used: @@ -96,7 +96,7 @@ To initialize a path variable, three possibilities can be used: `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 ```` variable. +except `CMAKE_PATH`_, store the result in the required ```` variable. Sub-commands supporting ``NORMALIZE`` option will :ref:`normalize ` the path. @@ -107,58 +107,58 @@ Synopsis .. parsed-literal:: `Decomposition`_ - cmake_path(`GET`_ :ref:`ROOT_NAME ` ) - cmake_path(`GET`_ :ref:`ROOT_DIRECTORY ` ) - cmake_path(`GET`_ :ref:`ROOT_PATH ` ) - cmake_path(`GET`_ :ref:`FILENAME ` ) - cmake_path(`GET`_ :ref:`EXTENSION ` [LAST_ONLY] ) - cmake_path(`GET`_ :ref:`STEM ` [LAST_ONLY] ) - cmake_path(`GET`_ :ref:`RELATIVE_PATH ` ) - cmake_path(`GET`_ :ref:`PARENT_PATH ` ) + cmake_path(`GET`_ :ref:`ROOT_NAME ` ) + cmake_path(`GET`_ :ref:`ROOT_DIRECTORY ` ) + cmake_path(`GET`_ :ref:`ROOT_PATH ` ) + cmake_path(`GET`_ :ref:`FILENAME ` ) + cmake_path(`GET`_ :ref:`EXTENSION ` [LAST_ONLY] ) + cmake_path(`GET`_ :ref:`STEM ` [LAST_ONLY] ) + cmake_path(`GET`_ :ref:`RELATIVE_PATH ` ) + cmake_path(`GET`_ :ref:`PARENT_PATH ` ) `Modification`_ - cmake_path(`APPEND`_ [...] [OUTPUT_VARIABLE ]) - cmake_path(`CONCAT`_ [...] [OUTPUT_VARIABLE ]) - cmake_path(`REMOVE_FILENAME`_ [OUTPUT_VARIABLE ]) - cmake_path(`REPLACE_FILENAME`_ [OUTPUT_VARIABLE ]) - cmake_path(`REMOVE_EXTENSION`_ [LAST_ONLY] - [OUTPUT_VARIABLE ]) - cmake_path(`REPLACE_EXTENSION`_ [LAST_ONLY] - [OUTPUT_VARIABLE ]) + cmake_path(`APPEND`_ [...] [OUTPUT_VARIABLE ]) + cmake_path(`CONCAT`_ [...] [OUTPUT_VARIABLE ]) + cmake_path(`REMOVE_FILENAME`_ [OUTPUT_VARIABLE ]) + cmake_path(`REPLACE_FILENAME`_ [OUTPUT_VARIABLE ]) + cmake_path(`REMOVE_EXTENSION`_ [LAST_ONLY] + [OUTPUT_VARIABLE ]) + cmake_path(`REPLACE_EXTENSION`_ [LAST_ONLY] + [OUTPUT_VARIABLE ]) `Generation`_ - cmake_path(`NORMAL_PATH`_ [OUTPUT_VARIABLE ]) - cmake_path(`RELATIVE_PATH`_ [BASE_DIRECTORY ] - [OUTPUT_VARIABLE ]) - cmake_path(`PROXIMATE_PATH`_ [BASE_DIRECTORY ] - [OUTPUT_VARIABLE ]) - cmake_path(`ABSOLUTE_PATH`_ [BASE_DIRECTORY ] [NORMALIZE] - [OUTPUT_VARIABLE ]) + cmake_path(`NORMAL_PATH`_ [OUTPUT_VARIABLE ]) + cmake_path(`RELATIVE_PATH`_ [BASE_DIRECTORY ] + [OUTPUT_VARIABLE ]) + cmake_path(`PROXIMATE_PATH`_ [BASE_DIRECTORY ] + [OUTPUT_VARIABLE ]) + cmake_path(`ABSOLUTE_PATH`_ [BASE_DIRECTORY ] [NORMALIZE] + [OUTPUT_VARIABLE ]) `Conversion`_ - cmake_path(`CMAKE_PATH`_ [NORMALIZE] ) - cmake_path(`NATIVE_PATH`_ [NORMALIZE] ) - cmake_path(`CONVERT`_ `TO_CMAKE_PATH_LIST`_ ) - cmake_path(`CONVERT`_ `TO_NATIVE_PATH_LIST`_ ) + cmake_path(`CMAKE_PATH`_ [NORMALIZE] ) + cmake_path(`NATIVE_PATH`_ [NORMALIZE] ) + cmake_path(`CONVERT`_ `TO_CMAKE_PATH_LIST`_ ) + cmake_path(`CONVERT`_ `TO_NATIVE_PATH_LIST`_ ) `Comparison`_ - cmake_path(`COMPARE`_ ) + cmake_path(`COMPARE`_ ) `Query`_ - cmake_path(`HAS_ROOT_NAME`_ ) - cmake_path(`HAS_ROOT_DIRECTORY`_ ) - cmake_path(`HAS_ROOT_PATH`_ ) - cmake_path(`HAS_FILENAME`_ ) - cmake_path(`HAS_EXTENSION`_ ) - cmake_path(`HAS_STEM`_ ) - cmake_path(`HAS_RELATIVE_PATH`_ ) - cmake_path(`HAS_PARENT_PATH`_ ) - cmake_path(`IS_ABSOLUTE`_ ) - cmake_path(`IS_RELATIVE`_ ) - cmake_path(`IS_PREFIX`_ [NORMALIZE] ) + cmake_path(`HAS_ROOT_NAME`_ ) + cmake_path(`HAS_ROOT_DIRECTORY`_ ) + cmake_path(`HAS_ROOT_PATH`_ ) + cmake_path(`HAS_FILENAME`_ ) + cmake_path(`HAS_EXTENSION`_ ) + cmake_path(`HAS_STEM`_ ) + cmake_path(`HAS_RELATIVE_PATH`_ ) + cmake_path(`HAS_PARENT_PATH`_ ) + cmake_path(`IS_ABSOLUTE`_ ) + cmake_path(`IS_RELATIVE`_ ) + cmake_path(`IS_PREFIX`_ [NORMALIZE] ) `Hashing`_ - cmake_path(`HASH`_ [NORMALIZE] ) + cmake_path(`HASH`_ [NORMALIZE] ) Decomposition ^^^^^^^^^^^^^ @@ -168,7 +168,7 @@ Decomposition .. code-block:: cmake - cmake_path(GET ROOT_NAME ) + cmake_path(GET ROOT_NAME ) Returns the root name of the path. If the path does not include a root name, returns an empty path. @@ -194,7 +194,7 @@ For example: .. code-block:: cmake - cmake_path(GET ROOT_DIRECTORY ) + cmake_path(GET ROOT_DIRECTORY ) Returns the root directory of the path. If the path does not include a root directory, returns an empty path. @@ -215,7 +215,7 @@ For example: .. code-block:: cmake - cmake_path(GET ROOT_PATH ) + cmake_path(GET ROOT_PATH ) Returns the root path of the path. If the path does not include a root path, returns an empty path. @@ -238,7 +238,7 @@ For example: .. code-block:: cmake - cmake_path(GET FILENAME ) + cmake_path(GET FILENAME ) Returns the :ref:`filename ` component of the path. If the path ends with a ``directory-separator``, there is no filename, so returns an empty @@ -265,7 +265,7 @@ For example: .. code-block:: cmake - cmake_path(GET EXTENSION [LAST_ONLY] ) + cmake_path(GET EXTENSION [LAST_ONLY] ) Returns the :ref:`extension ` of the filename component. @@ -301,7 +301,7 @@ The following exceptions apply: .. code-block:: cmake - cmake_path(GET STEM [LAST_ONLY] ) + cmake_path(GET STEM [LAST_ONLY] ) Returns the :ref:`filename ` component of the path stripped of its :ref:`extension `. @@ -334,11 +334,11 @@ The following exceptions apply: .. code-block:: cmake - cmake_path(GET RELATIVE_PATH ) + cmake_path(GET RELATIVE_PATH ) Returns path relative to ``root-path``, that is, a pathname composed of -every component of ```` after ``root-path``. If ```` is an empty -path, returns an empty path. +every component of ```` after ``root-path``. If ```` is +an empty path, returns an empty path. For Example: @@ -361,12 +361,12 @@ For Example: .. code-block:: cmake - cmake_path(GET PARENT_PATH ) + cmake_path(GET PARENT_PATH ) Returns the path to the parent directory. If `HAS_RELATIVE_PATH`_ sub-command returns false, the result is a copy of -````. Otherwise, the result is ```` with one fewer element. +````. Otherwise, the result is ```` with one fewer element. For Example: @@ -392,15 +392,17 @@ Modification .. code-block:: cmake - cmake_path(APPEND [...] [OUTPUT_VARIABLE ]) + cmake_path(APPEND [...] [OUTPUT_VARIABLE ]) -Append all the ```` arguments to the ```` using ``/`` as +Append all the ```` arguments to the ```` using ``/`` as ``directory-separator``. For each ```` argument, the following algorithm (pseudo-code) applies: .. code-block:: cmake + # is the contents of + IF (.is_absolute() OR (.has_root_name() AND NOT .root_name() STREQUAL .root_name())) @@ -411,7 +413,7 @@ For each ```` argument, the following algorithm (pseudo-code) applies: IF (.has_root_directory()) remove any root-directory and the entire relative path from ELSEIF (.has_filename() OR - (NOT .has_root_directory() OR .is_absolute())) + (NOT .has_root_directory() OR .is_absolute())) appends directory-separator to ENDIF() @@ -421,22 +423,22 @@ For each ```` argument, the following algorithm (pseudo-code) applies: .. code-block:: cmake - cmake_path(CONCAT [...] [OUTPUT_VARIABLE ]) + cmake_path(CONCAT [...] [OUTPUT_VARIABLE ]) -Concatenates all the ```` arguments to the ```` without +Concatenates all the ```` arguments to the ```` without ``directory-separator``. .. _REMOVE_FILENAME: .. code-block:: cmake - cmake_path(REMOVE_FILENAME [OUTPUT_VARIABLE ]) + cmake_path(REMOVE_FILENAME [OUTPUT_VARIABLE ]) Removes the :ref:`filename ` component (as returned by -:ref:`GET ... FILENAME `) from ````. +:ref:`GET ... FILENAME `) from ````. After this function returns, if change is done in-place, `HAS_FILENAME`_ -returns false for ````. +returns false for ````. For Example: @@ -458,13 +460,13 @@ For Example: .. code-block:: cmake - cmake_path(REPLACE_FILENAME [OUTPUT_VARIABLE ]) + cmake_path(REPLACE_FILENAME [OUTPUT_VARIABLE ]) -Replaces the :ref:`filename ` component from ```` with +Replaces the :ref:`filename ` component from ```` with ````. -If ```` has no filename component (`HAS_FILENAME`_ returns false), the -path is unchanged. +If ```` has no filename component (`HAS_FILENAME`_ returns false), +the path is unchanged. Equivalent to the following: @@ -480,23 +482,24 @@ Equivalent to the following: .. code-block:: cmake - cmake_path(REMOVE_EXTENSION [LAST_ONLY] [OUTPUT_VARIABLE ]) + cmake_path(REMOVE_EXTENSION [LAST_ONLY] + [OUTPUT_VARIABLE ]) -Removes the :ref:`extension `, if any, from ````. +Removes the :ref:`extension `, if any, from ````. .. _REPLACE_EXTENSION: .. code-block:: cmake - cmake_path(REPLACE_EXTENSION [LAST_ONLY] - [OUTPUT_VARIABLE ]) + cmake_path(REPLACE_EXTENSION [LAST_ONLY] + [OUTPUT_VARIABLE ]) Replaces the :ref:`extension ` with ````. - 1. If ```` has an :ref:`extension ` + 1. If ```` has an :ref:`extension ` (`HAS_EXTENSION`_ is true), it is removed. - 2. A ``dot`` character is appended to ````, if ```` is not empty - or does not begin with a ``dot`` character. + 2. A ``dot`` character is appended to ````, if ```` is not + empty or does not begin with a ``dot`` character. 3. ```` is appended as if `CONCAT`_ was used. @@ -517,9 +520,9 @@ Generation .. code-block:: cmake - cmake_path(NORMAL_PATH [OUTPUT_VARIABLE ]) + cmake_path(NORMAL_PATH [OUTPUT_VARIABLE ]) -Normalize ````. +Normalize ````. A path can be normalized by following this algorithm: @@ -544,10 +547,10 @@ A path can be normalized by following this algorithm: .. code-block:: cmake - cmake_path(RELATIVE_PATH [BASE_DIRECTORY ] - [OUTPUT_VARIABLE ]) + cmake_path(RELATIVE_PATH [BASE_DIRECTORY ] + [OUTPUT_VARIABLE ]) -Returns ```` made relative to ``BASE_DIRECTORY`` argument. If +Returns ```` made relative to ``BASE_DIRECTORY`` argument. If ``BASE_DIRECTORY`` is not specified, the default base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. @@ -558,11 +561,11 @@ For reference, the algorithm used to compute the relative path is described .. code-block:: cmake - cmake_path(PROXIMATE_PATH [BASE_DIRECTORY ] - [OUTPUT_VARIABLE ]) + cmake_path(PROXIMATE_PATH [BASE_DIRECTORY ] + [OUTPUT_VARIABLE ]) If the value of `RELATIVE_PATH`_ is not an empty path, return -it. Otherwise return ````. +it. Otherwise return ````. If ``BASE_DIRECTORY`` is not specified, the default base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. @@ -571,10 +574,10 @@ If ``BASE_DIRECTORY`` is not specified, the default base directory will be .. code-block:: cmake - cmake_path(ABSOLUTE_PATH [BASE_DIRECTORY ] [NORMALIZE] - [OUTPUT_VARIABLE ]) + cmake_path(ABSOLUTE_PATH [BASE_DIRECTORY ] [NORMALIZE] + [OUTPUT_VARIABLE ]) -If ```` is a relative path (`IS_RELATIVE`_ is true), it is evaluated +If ```` is a relative path (`IS_RELATIVE`_ is true), it is evaluated relative to the given base directory specified by ``BASE_DIRECTORY`` option. If ``BASE_DIRECTORY`` is not specifired, the default base directory will be @@ -595,7 +598,7 @@ Conversion .. code-block:: cmake - cmake_path(CMAKE_PATH [NORMALIZE] ) + cmake_path(CMAKE_PATH [NORMALIZE] ) Converts a native ```` path into cmake-style path with forward-slashes (``/``). On Windows, the long filename marker is taken into account. @@ -624,9 +627,9 @@ For Example: .. code-block:: cmake - cmake_path(NATIVE_PATH [NORMALIZE] ) + cmake_path(NATIVE_PATH [NORMALIZE] ) -Converts a cmake-style ```` into a native +Converts a cmake-style ```` into a native path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere). When ``NORMALIZE`` option is specified, the path is :ref:`normalized @@ -638,13 +641,13 @@ When ``NORMALIZE`` option is specified, the path is :ref:`normalized .. code-block:: cmake - cmake_path(CONVERT TO_CMAKE_PATH_LIST [NORMALIZE]) + cmake_path(CONVERT TO_CMAKE_PATH_LIST [NORMALIZE]) Converts a native ```` 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 ```` variable. +result of the conversion is stored in the ```` variable. When ``NORMALIZE`` option is specified, the path is :ref:`normalized ` before the conversion. @@ -654,12 +657,12 @@ When ``NORMALIZE`` option is specified, the path is :ref:`normalized .. code-block:: cmake - cmake_path(CONVERT TO_NATIVE_PATH_LIST [NORMALIZE]) + cmake_path(CONVERT TO_NATIVE_PATH_LIST [NORMALIZE]) Converts a cmake-style ```` 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 ```` +search path. The result of the conversion is stored in the ```` variable. When ``NORMALIZE`` option is specified, the path is :ref:`normalized @@ -688,8 +691,8 @@ Comparison .. code-block:: cmake - cmake_path(COMPARE EQUAL ) - cmake_path(COMPARE NOT_EQUAL ) + cmake_path(COMPARE EQUAL ) + cmake_path(COMPARE NOT_EQUAL ) Compares the lexical representations of the path and another path. @@ -697,6 +700,8 @@ For testing equality, the following algorithm (pseudo-code) apply: .. code-block:: cmake + # is the contents of + IF (NOT .root_name() STREQUAL .root_name()) returns FALSE ELSEIF (.has_root_directory() XOR .has_root_directory()) @@ -714,43 +719,43 @@ Query .. code-block:: cmake - cmake_path(HAS_ROOT_NAME ) + cmake_path(HAS_ROOT_NAME ) -Checks if ```` has ``root-name``. +Checks if ```` has ``root-name``. .. _HAS_ROOT_DIRECTORY: .. code-block:: cmake - cmake_path(HAS_ROOT_DIRECTORY ) + cmake_path(HAS_ROOT_DIRECTORY ) -Checks if ```` has ``root-directory``. +Checks if ```` has ``root-directory``. .. _HAS_ROOT_PATH: .. code-block:: cmake - cmake_path(HAS_ROOT_PATH ) + cmake_path(HAS_ROOT_PATH ) -Checks if ```` has root path. +Checks if ```` has root path. -Effectively, checks if ```` has ``root-name`` and ``root-directory``. +Effectively, checks if ```` has ``root-name`` and ``root-directory``. .. _HAS_FILENAME: .. code-block:: cmake - cmake_path(HAS_FILENAME ) + cmake_path(HAS_FILENAME ) -Checks if ```` has a :ref:`filename `. +Checks if ```` has a :ref:`filename `. .. _HAS_EXTENSION: .. code-block:: cmake - cmake_path(HAS_EXTENSION ) + cmake_path(HAS_EXTENSION ) -Checks if ```` has an :ref:`extension `. If the first +Checks if ```` has an :ref:`extension `. If the first character in the filename is a period, it is not treated as an extension (for example ".profile"). @@ -758,36 +763,36 @@ example ".profile"). .. code-block:: cmake - cmake_path(HAS_STEM ) + cmake_path(HAS_STEM ) -Checks if ```` has stem (:ref:`GET ... STEM ` returns a non +Checks if ```` has stem (:ref:`GET ... STEM ` returns a non empty path). .. _HAS_RELATIVE_PATH: .. code-block:: cmake - cmake_path(HAS_RELATIVE_PATH ) + cmake_path(HAS_RELATIVE_PATH ) -Checks if ```` has relative path (`GET_RELATIVE_PATH`_ returns a +Checks if ```` has relative path (`GET_RELATIVE_PATH`_ returns a non-empty path). .. _HAS_PARENT_PATH: .. code-block:: cmake - cmake_path(HAS_PARENT_PATH ) + cmake_path(HAS_PARENT_PATH ) -Checks if ```` has parent path. The result is true except if the path is -only composed of a :ref:`filename `. +Checks if ```` has parent path. The result is true except if the path +is only composed of a :ref:`filename `. .. _IS_ABSOLUTE: .. code-block:: cmake - cmake_path(IS_ABSOLUTE ) + cmake_path(IS_ABSOLUTE ) -Checks if ```` is absolute. +Checks if ```` is absolute. An absolute path is a path that unambiguously identifies the location of a file without reference to an additional starting location. @@ -796,7 +801,7 @@ without reference to an additional starting location. .. code-block:: cmake - cmake_path(IS_RELATIVE ) + cmake_path(IS_RELATIVE ) Checks if path is relative (i.e. not :ref:`absolute `). @@ -804,9 +809,9 @@ Checks if path is relative (i.e. not :ref:`absolute `). .. code-block:: cmake - cmake_path(IS_PREFIX [NORMALIZE] ) + cmake_path(IS_PREFIX [NORMALIZE] ) -Checks if ```` is the prefix of ````. +Checks if ```` is the prefix of ````. When ``NORMALIZE`` option is specified, the paths are :ref:`normalized ` before the check. @@ -818,11 +823,11 @@ Hashing .. code-block:: cmake - cmake_path(HASH [NORMALIZE] ) + cmake_path(HASH [NORMALIZE] ) -Compute hash value of ```` such that if for two paths (``p1`` and ``p2``) -are equal (:ref:`COMPARE ... EQUAL `) then hash value of p1 is equal -to hash value of p2. +Compute hash value of ```` such that if for two paths (``p1`` and +``p2``) are equal (:ref:`COMPARE ... EQUAL `) then hash value of p1 is +equal to hash value of p2. When ``NORMALIZE`` option is specified, the paths are :ref:`normalized ` before the check. -- cgit v0.12