diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/cmake_path.rst | 12 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 212 | ||||
| -rw-r--r-- | Help/release/dev/Genex-PATH.rst | 4 |
3 files changed, 227 insertions, 1 deletions
diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index 454c860..77525ed 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -96,6 +96,8 @@ The following conventions are used in this command's documentation: The name of a variable into which the result of a command will be written. +.. _Path Structure And Terminology: + Path Structure And Terminology ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -216,6 +218,8 @@ normalize a path is as follows: is ``.``). +.. _Path Decomposition: + Decomposition ^^^^^^^^^^^^^ @@ -385,6 +389,8 @@ Path traversal examples Parent path is "c:/" +.. _Path Query: + Query ^^^^^ @@ -495,6 +501,8 @@ according to the following pseudo-code logic: takes literal strings as input, not the names of variables. +.. _Path Modification: + Modification ^^^^^^^^^^^^ @@ -509,7 +517,7 @@ path, it is converted into a cmake-style path with forward-slashes (``/``). On Windows, the long filename marker is taken into account. When the ``NORMALIZE`` option is specified, the path is :ref:`normalized -<Normalization>` before the conversion. +<Normalization>` after the conversion. For example: @@ -644,6 +652,8 @@ is equivalent to the following: cmake_path(APPEND_STRING path "input") +.. _Path Generation: + Generation ^^^^^^^^^^ diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 848a133..1f0dd59 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -123,6 +123,71 @@ String Comparisons ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. +.. _GenEx Path Queries: + +Path Queries +------------ + +The ``$<PATH>`` generator expression offers the same capabilities as the +:command:`cmake_path` command, for the :ref:`Query <Path Query>` options. + +For all ``$<PATH>`` generator expressions, paths are expected in cmake-style +format. The :ref:`$\<PATH:CMAKE_PATH\> <GenEx PATH-CMAKE_PATH>` generator +expression can be used to convert a native path to a cmake-style one. + +The ``$<PATH>`` generator expression can also be used for path +:ref:`Decomposition <GenEx Path Decomposition>` and +:ref:`Transformations <GenEx Path Transformations>`. + +.. genex:: $<PATH:HAS_*,path> + + .. versionadded:: 3.24 + + The following operations return ``1`` if the particular path component is + present, ``0`` otherwise. See :ref:`Path Structure And Terminology` for the + meaning of each path component. + + :: + + $<PATH:HAS_ROOT_NAME,path> + $<PATH:HAS_ROOT_DIRECTORY,path> + $<PATH:HAS_ROOT_PATH,path> + $<PATH:HAS_FILENAME,path> + $<PATH:HAS_EXTENSION,path> + $<PATH:HAS_STEM,path> + $<PATH:HAS_RELATIVE_PART,path> + $<PATH:HAS_PARENT_PATH,path> + + Note the following special cases: + + * For ``HAS_ROOT_PATH``, a true result will only be returned if at least one + of ``root-name`` or ``root-directory`` is non-empty. + + * For ``HAS_PARENT_PATH``, the root directory is also considered to have a + parent, which will be itself. The result is true except if the path + consists of just a :ref:`filename <FILENAME_DEF>`. + +.. genex:: $<PATH:IS_ABSOLUTE,path> + + .. versionadded:: 3.24 + + Returns ``1`` if the path is :ref:`absolute <IS_ABSOLUTE>`, ``0`` otherwise. + +.. genex:: $<PATH:IS_RELATIVE,path> + + .. versionadded:: 3.24 + + This will return the opposite of ``IS_ABSOLUTE``. + +.. genex:: $<PATH:IS_PREFIX[,NORMALIZE],path,input> + + .. versionadded:: 3.24 + + Returns ``1`` if ``path`` is the prefix of ``input``,``0`` otherwise. + + When the ``NORMALIZE`` option is specified, ``path`` and ``input`` are + :ref:`normalized <Normalization>` before the check. + Variable Queries ---------------- @@ -668,6 +733,153 @@ String Transformations echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> ) +.. _GenEx Path Decomposition: + +Path Decomposition +------------------ + +The ``$<PATH>`` generator expression offers the same capabilities as the +:command:`cmake_path` command, for the +:ref:`Decomposition <Path Decomposition>` options. + +For all ``$<PATH>`` generator expressions, paths are expected in cmake-style +format. The :ref:`$\<PATH:CMAKE_PATH\> <GenEx PATH-CMAKE_PATH>` generator +expression can be used to convert a native path to a cmake-style one. + +The ``$<PATH>`` generator expression can also be used for path +:ref:`Queries <GenEx Path Queries>` and +:ref:`Transformations <GenEx Path Transformations>`. + +.. genex:: $<PATH:GET_*,...> + + .. versionadded:: 3.24 + + The following operations retrieve a different component or group of + components from a path. See :ref:`Path Structure And Terminology` for the + meaning of each path component. + + :: + + $<PATH:GET_ROOT_NAME,path> + $<PATH:GET_ROOT_DIRECTORY,path> + $<PATH:GET_ROOT_PATH,path> + $<PATH:GET_FILENAME,path> + $<PATH:GET_EXTENSION[,LAST_ONLY],path> + $<PATH:GET_STEM[,LAST_ONLY],path> + $<PATH:GET_RELATIVE_PART,path> + $<PATH:GET_PARENT_PATH,path> + + If a requested component is not present in the path, an empty string is + returned. + +.. _GenEx Path Transformations: + +Path Transformations +-------------------- + +The ``$<PATH>`` generator expression offers the same capabilities as the +:command:`cmake_path` command, for the +:ref:`Modification <Path Modification>` and +:ref:`Generation <Path Generation>` options. + +For all ``$<PATH>`` generator expressions, paths are expected in cmake-style +format. The :ref:`$\<PATH:CMAKE_PATH\> <GenEx PATH-CMAKE_PATH>` generator +expression can be used to convert a native path to a cmake-style one. + +The ``$<PATH>`` generator expression can also be used for path +:ref:`Queries <GenEx Path Queries>` and +:ref:`Decomposition <GenEx Path Decomposition>`. + +.. _GenEx PATH-CMAKE_PATH: + +.. genex:: $<PATH:CMAKE_PATH[,NORMALIZE],path> + + .. versionadded:: 3.24 + + Returns ``path``. If ``path`` is a native path, it is converted into a + cmake-style path with forward-slashes (``/``). On Windows, the long filename + marker is taken into account. + + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + <Normalization>` after the conversion. + +.. genex:: $<PATH:APPEND,path,input,...> + + .. versionadded:: 3.24 + + Returns all the ``input`` arguments appended to ``path`` using ``/`` as the + ``directory-separator``. Depending on the ``input``, the value of ``path`` + may be discarded. + + See :ref:`cmake_path(APPEND) <APPEND>` for more details. + +.. genex:: $<PATH:REMOVE_FILENAME,path> + + .. versionadded:: 3.24 + + Returns ``path`` with filename component (as returned by + ``$<PATH:GET_FILENAME>``) removed. After removal, any trailing + ``directory-separator`` is left alone, if present. + + See :ref:`cmake_path(REMOVE_FILENAME) <REMOVE_FILENAME>` for more details. + +.. genex:: $<PATH:REPLACE_FILENAME,path,input> + + .. versionadded:: 3.24 + + Returns ``path`` with the filename component replaced by ``input``. If + ``path`` has no filename component (i.e. ``$<PATH:HAS_FILENAME>`` returns + ``0``), ``path`` is unchanged. + + See :ref:`cmake_path(REPLACE_FILENAME) <REPLACE_FILENAME>` for more details. + +.. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path> + + .. versionadded:: 3.24 + + Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` removed, if any. + + See :ref:`cmake_path(REMOVE_EXTENSION) <REMOVE_EXTENSION>` for more details. + +.. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path> + + .. versionadded:: 3.24 + + Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` replaced by + ``input``, if any. + + See :ref:`cmake_path(REPLACE_EXTENSION) <REPLACE_EXTENSION>` for more details. + +.. genex:: $<PATH:NORMAL_PATH,path> + + .. versionadded:: 3.24 + + Returns ``path`` normalized according to the steps described in + :ref:`Normalization`. + +.. genex:: $<PATH:RELATIVE_PATH,path,base_directory> + + .. versionadded:: 3.24 + + Returns ``path``, modified to make it relative to the ``base_directory`` + argument. + + See :ref:`cmake_path(RELATIVE_PATH) <cmake_path-RELATIVE_PATH>` for more + details. + +.. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path,base_directory> + + .. versionadded:: 3.24 + + Returns ``path`` as absolute. If ``path`` is a relative path + (``$<PATH:IS_RELATIVE>`` returns ``1``), it is evaluated relative to the + given base directory specified by ``base_directory`` argument. + + When the ``NORMALIZE`` option is specified, the path is + :ref:`normalized <Normalization>` after the path computation. + + See :ref:`cmake_path(ABSOLUTE_PATH) <ABSOLUTE_PATH>` for more details. + Variable Queries ---------------- diff --git a/Help/release/dev/Genex-PATH.rst b/Help/release/dev/Genex-PATH.rst new file mode 100644 index 0000000..870ee23 --- /dev/null +++ b/Help/release/dev/Genex-PATH.rst @@ -0,0 +1,4 @@ +Genex-PATH +---------- + +* The :genex:`PATH` generator expression was added to manage paths. |