From 621ba5e1f217aabb401d1401117ee2a3652fcc5d Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 15 Jan 2021 21:55:51 -0500 Subject: cmRST: Add support for 'envvar' directive This was accidentally left out of commit 8acf46caf1 (Utilities/Sphinx: Add role and directive for 'envvar' in CMake domain, 2018-04-19, v3.12.0-rc1~200^2~1). --- Source/cmRST.cxx | 2 +- Tests/CMakeLib/testRST.expect | 8 ++++++++ Tests/CMakeLib/testRST.rst | 8 ++++++++ 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx index 26e93bb..686455e 100644 --- a/Source/cmRST.cxx +++ b/Source/cmRST.cxx @@ -25,7 +25,7 @@ cmRST::cmRST(std::ostream& os, std::string docroot) , Markup(MarkupNone) , Directive(DirectiveNone) , CMakeDirective("^.. (cmake:)?(" - "command|variable" + "command|envvar|variable" ")::[ \t]+([^ \t\n]+)$") , CMakeModuleDirective("^.. cmake-module::[ \t]+([^ \t\n]+)$") , ParsedLiteralDirective("^.. parsed-literal::[ \t]*(.*)$") diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect index 970adaa..64f0896 100644 --- a/Tests/CMakeLib/testRST.expect +++ b/Tests/CMakeLib/testRST.expect @@ -48,6 +48,14 @@ Bracket Comment Content Command other_cmd description. +.. cmake:envvar:: some_var + + Environment variable some_var description. + +.. envvar:: other_var + + Environment variable other_var description. + .. cmake:variable:: some_var Variable some_var description. diff --git a/Tests/CMakeLib/testRST.rst b/Tests/CMakeLib/testRST.rst index 6462f1b..4c77595 100644 --- a/Tests/CMakeLib/testRST.rst +++ b/Tests/CMakeLib/testRST.rst @@ -51,6 +51,14 @@ Inline literal ``__`` followed by inline link `Link Text `_. Command other_cmd description. +.. cmake:envvar:: some_var + + Environment variable some_var description. + +.. envvar:: other_var + + Environment variable other_var description. + .. cmake:variable:: some_var Variable some_var description. -- cgit v0.12 From 954a9e9893221c4ffe56b5534c4919329d511b74 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 15 Jan 2021 13:58:42 -0500 Subject: Help/dev: Mention 'envvar' domain object in CMake Documentation Guide This was accidentally left out of commit 8acf46caf1 (Utilities/Sphinx: Add role and directive for 'envvar' in CMake domain, 2018-04-19, v3.12.0-rc1~200^2~1). --- Help/dev/documentation.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index c302790..07f04d2 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -123,6 +123,11 @@ documentation: ``command`` A CMake language command. +``envvar`` + An environment variable. + See the `cmake-env-variables(7)`_ manual + and the `set()`_ command. + ``generator`` A CMake native build system generator. See the `cmake(1)`_ command-line tool's ``-G`` option. @@ -174,6 +179,10 @@ other documents: This indented block documents . + .. envvar:: + + This indented block documents . + .. variable:: This indented block documents . @@ -183,6 +192,7 @@ the first approach above. .. _`Sphinx Domain`: http://sphinx-doc.org/domains.html .. _`cmake(1)`: https://cmake.org/cmake/help/latest/manual/cmake.1.html +.. _`cmake-env-variables(7)`: https://cmake.org/cmake/help/latest/manual/cmake-env-variables.7.html .. _`cmake-modules(7)`: https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html .. _`cmake-policies(7)`: https://cmake.org/cmake/help/latest/manual/cmake-policies.7.html .. _`cmake-properties(7)`: https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html -- cgit v0.12 From cc1f53351c52d03aecc47f8074ab1290cf7fb1a5 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 15 Jan 2021 14:00:47 -0500 Subject: Help/dev: Mention 'cpack_gen' domain object in CMake Documentation Guide This was accidentally left out of commit 2a2829cc75 (Help: Add new section for CPack generators, 2018-06-15, v3.13.0-rc1~394^2~3). --- Help/dev/documentation.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index 07f04d2..e34c754 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -123,6 +123,10 @@ documentation: ``command`` A CMake language command. +``cpack_gen`` + A CPack package generator. + See the `cpack(1)`_ command-line tool's ``-G`` option. + ``envvar`` An environment variable. See the `cmake-env-variables(7)`_ manual @@ -198,6 +202,7 @@ the first approach above. .. _`cmake-properties(7)`: https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html .. _`cmake-variables(7)`: https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html .. _`cmake_policy()`: https://cmake.org/cmake/help/latest/command/cmake_policy.html +.. _`cpack(1)`: https://cmake.org/cmake/help/latest/manual/cpack.1.html .. _`include()`: https://cmake.org/cmake/help/latest/command/include.html .. _`set()`: https://cmake.org/cmake/help/latest/command/set.html .. _`set_property()`: https://cmake.org/cmake/help/latest/command/set_property.html -- cgit v0.12 From 7d498d6b436638f5d85a0e97d43d51603d79205c Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 15 Jan 2021 14:01:53 -0500 Subject: Utilities/Sphinx: Add role and directive for 'genex' in CMake domain This enables cross-reference syntax for CMake generator expressions: :genex:`SOME_GENEX` :genex:`$` :genex:`$` and definition of CMake generator expressions via a directive: .. genex:: SOME_GENEX .. genex:: $ .. genex:: $ It also adds generator expressions defined by the directive and by `Help/genex/SOME_GENEX.rst` documents to the index. --- Help/dev/documentation.rst | 15 +++++++++++++-- Source/cmRST.cxx | 5 +++-- Tests/CMakeLib/testRST.expect | 14 ++++++++++++++ Tests/CMakeLib/testRST.rst | 14 ++++++++++++++ Utilities/Sphinx/cmake.py | 21 +++++++++++++++++++-- Utilities/Sphinx/create_identifiers.py | 1 + 6 files changed, 64 insertions(+), 6 deletions(-) diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index e34c754..29fc880 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -136,6 +136,10 @@ documentation: A CMake native build system generator. See the `cmake(1)`_ command-line tool's ``-G`` option. +``genex`` + A CMake generator expression. + See the `cmake-generator-expressions(7)`_ manual. + ``manual`` A CMake manual page, like the `cmake(1)`_ manual. @@ -169,10 +173,12 @@ which is expected to be of the form:: ------------- and to appear at or near the top of the ``.rst`` file before any other -lines starting in a letter, digit, or ``<``. If no such title appears +lines starting in a letter, digit, ``<``, or ``$``. If no such title appears literally in the ``.rst`` file, the object name is the ````. If a title does appear, it is expected that ```` is equal -to ```` with any ``<`` and ``>`` characters removed. +to ```` with any ``<`` and ``>`` characters removed, +or in the case of a ``$`` or ``$``, the +``genex-name``. Second, the CMake Domain provides directives to define objects inside other documents: @@ -187,6 +193,10 @@ other documents: This indented block documents . + .. genex:: + + This indented block documents . + .. variable:: This indented block documents . @@ -197,6 +207,7 @@ the first approach above. .. _`Sphinx Domain`: http://sphinx-doc.org/domains.html .. _`cmake(1)`: https://cmake.org/cmake/help/latest/manual/cmake.1.html .. _`cmake-env-variables(7)`: https://cmake.org/cmake/help/latest/manual/cmake-env-variables.7.html +.. _`cmake-generator-expressions(7)`: https://cmake.org/cmake/help/latest/manual/cmake-generator-expressions.7.html .. _`cmake-modules(7)`: https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html .. _`cmake-policies(7)`: https://cmake.org/cmake/help/latest/manual/cmake-policies.7.html .. _`cmake-properties(7)`: https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx index 686455e..fce6e80 100644 --- a/Source/cmRST.cxx +++ b/Source/cmRST.cxx @@ -25,7 +25,7 @@ cmRST::cmRST(std::ostream& os, std::string docroot) , Markup(MarkupNone) , Directive(DirectiveNone) , CMakeDirective("^.. (cmake:)?(" - "command|envvar|variable" + "command|envvar|genex|variable" ")::[ \t]+([^ \t\n]+)$") , CMakeModuleDirective("^.. cmake-module::[ \t]+([^ \t\n]+)$") , ParsedLiteralDirective("^.. parsed-literal::[ \t]*(.*)$") @@ -37,7 +37,8 @@ cmRST::cmRST(std::ostream& os, std::string docroot) , NoteDirective("^.. note::[ \t]*(.*)$") , ModuleRST(R"(^#\[(=*)\[\.rst:$)") , CMakeRole("(:cmake)?:(" - "command|cpack_gen|generator|variable|envvar|module|policy|" + "command|cpack_gen|generator|genex|" + "variable|envvar|module|policy|" "prop_cache|prop_dir|prop_gbl|prop_inst|prop_sf|" "prop_test|prop_tgt|" "manual" diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect index 64f0896..4870f65 100644 --- a/Tests/CMakeLib/testRST.expect +++ b/Tests/CMakeLib/testRST.expect @@ -20,6 +20,12 @@ Environment variable ``SOME_ENV_VAR``. Environment variable ``some env var`` with space and target. Generator ``Some Generator`` with space. Generator ``Some Generator`` with space. +Generator expression ``SOME_GENEX``. +Generator expression ``$`` with brackets. +Generator expression ``$`` with brackets and parameter. +Generator expression ``some genex`` with space and target. +Generator expression ``$`` with brackets, space, and target. +Generator expression ``$`` with brackets, parameter, space, and target. Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``. Inline link Link Text. Inline link Link Text . @@ -56,6 +62,14 @@ Bracket Comment Content Environment variable other_var description. +.. cmake:genex:: SOME_GENEX + + Generator expression SOME_GENEX description. + +.. genex:: $ + + Generator expression $ description. + .. cmake:variable:: some_var Variable some_var description. diff --git a/Tests/CMakeLib/testRST.rst b/Tests/CMakeLib/testRST.rst index 4c77595..44931a7 100644 --- a/Tests/CMakeLib/testRST.rst +++ b/Tests/CMakeLib/testRST.rst @@ -27,6 +27,12 @@ Environment variable :envvar:`SOME_ENV_VAR`. Environment variable :envvar:`some env var ` with space and target. Generator :generator:`Some Generator` with space. Generator :cpack_gen:`Some Generator` with space. +Generator expression :genex:`SOME_GENEX`. +Generator expression :genex:`$` with brackets. +Generator expression :genex:`$` with brackets and parameter. +Generator expression :genex:`some genex ` with space and target. +Generator expression :genex:`$ ` with brackets, space, and target. +Generator expression :genex:`$ ` with brackets, parameter, space, and target. Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``. Inline link `Link Text `_. Inline link `Link Text \ `_. @@ -59,6 +65,14 @@ Inline literal ``__`` followed by inline link `Link Text `_. Environment variable other_var description. +.. cmake:genex:: SOME_GENEX + + Generator expression SOME_GENEX description. + +.. genex:: $ + + Generator expression $ description. + .. cmake:variable:: some_var Variable some_var description. diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py index e175d0d..ece4bf5 100644 --- a/Utilities/Sphinx/cmake.py +++ b/Utilities/Sphinx/cmake.py @@ -191,6 +191,7 @@ _cmake_index_objs = { 'cpack_gen': _cmake_index_entry('cpack generator'), 'envvar': _cmake_index_entry('envvar'), 'generator': _cmake_index_entry('generator'), + 'genex': _cmake_index_entry('genex'), 'guide': _cmake_index_entry('guide'), 'manual': _cmake_index_entry('manual'), 'module': _cmake_index_entry('module'), @@ -224,7 +225,7 @@ class CMakeTransform(Transform): self.titles = {} def parse_title(self, docname): - """Parse a document title as the first line starting in [A-Za-z0-9<] + """Parse a document title as the first line starting in [A-Za-z0-9<$] or fall back to the document basename if no such line exists. The cmake --help-*-list commands also depend on this convention. Return the title or False if the document file does not exist. @@ -239,7 +240,7 @@ class CMakeTransform(Transform): title = False else: for line in f: - if len(line) > 0 and (line[0].isalnum() or line[0] == '<'): + if len(line) > 0 and (line[0].isalnum() or line[0] == '<' or line[0] == '$'): title = line.rstrip() break f.close() @@ -260,6 +261,10 @@ class CMakeTransform(Transform): if objtype == 'command': targetname = title.lower() else: + if objtype == 'genex': + m = CMakeXRefRole._re_genex.match(title) + if m: + title = m.group(1) targetname = title targetid = '%s:%s' % (objtype, targetname) targetnode = nodes.target('', '', ids=[targetid]) @@ -277,6 +282,10 @@ class CMakeObject(ObjectDescription): def handle_signature(self, sig, signode): # called from sphinx.directives.ObjectDescription.run() signode += addnodes.desc_name(sig, sig) + if self.objtype == 'genex': + m = CMakeXRefRole._re_genex.match(sig) + if m: + sig = m.group(1) return sig def add_target_and_index(self, name, sig, signode): @@ -302,6 +311,7 @@ class CMakeXRefRole(XRefRole): # See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'. _re = re.compile(r'^(.+?)(\s*)(?$', re.DOTALL) _re_sub = re.compile(r'^([^()\s]+)\s*\(([^()]*)\)$', re.DOTALL) + _re_genex = re.compile(r'^\$<([^<>:]+)(:[^<>]+)?>$', re.DOTALL) def __call__(self, typ, rawtext, text, *args, **keys): # Translate CMake command cross-references of the form: @@ -312,6 +322,10 @@ class CMakeXRefRole(XRefRole): m = CMakeXRefRole._re_sub.match(text) if m: text = '%s <%s>' % (text, m.group(1)) + elif typ == 'cmake:genex': + m = CMakeXRefRole._re_genex.match(text) + if m: + text = '%s <%s>' % (text, m.group(1)) # CMake cross-reference targets frequently contain '<' so escape # any explicit `` with '<' not preceded by whitespace. while True: @@ -374,6 +388,7 @@ class CMakeDomain(Domain): 'cpack_gen': ObjType('cpack_gen', 'cpack_gen'), 'envvar': ObjType('envvar', 'envvar'), 'generator': ObjType('generator', 'generator'), + 'genex': ObjType('genex', 'genex'), 'guide': ObjType('guide', 'guide'), 'variable': ObjType('variable', 'variable'), 'module': ObjType('module', 'module'), @@ -390,6 +405,7 @@ class CMakeDomain(Domain): directives = { 'command': CMakeObject, 'envvar': CMakeObject, + 'genex': CMakeObject, 'variable': CMakeObject, # Other object types cannot be created except by the CMakeTransform # 'generator': CMakeObject, @@ -409,6 +425,7 @@ class CMakeDomain(Domain): 'cpack_gen': CMakeXRefRole(), 'envvar': CMakeXRefRole(), 'generator': CMakeXRefRole(), + 'genex': CMakeXRefRole(), 'guide': CMakeXRefRole(), 'variable': CMakeXRefRole(), 'module': CMakeXRefRole(), diff --git a/Utilities/Sphinx/create_identifiers.py b/Utilities/Sphinx/create_identifiers.py index e35f127..0ff39a0 100755 --- a/Utilities/Sphinx/create_identifiers.py +++ b/Utilities/Sphinx/create_identifiers.py @@ -25,6 +25,7 @@ for line in lines: ("envvar", "envvar"), ("variable", "variable"), ("generator", "generator"), + ("genex", "genex"), ("guide", "guide"), ("target property", "prop_tgt"), ("test property", "prop_test"), -- cgit v0.12 From 778321beb46dace10fced95c44383df6dfaae798 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 15 Jan 2021 22:09:24 -0500 Subject: Help: Remove extra blank line from cmake-generator-expressions(7) --- Help/manual/cmake-generator-expressions.7.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index c949ce1..50c816c 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -99,7 +99,6 @@ String Comparisons ``$`` ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. - Variable Queries ---------------- -- cgit v0.12 From c2dc7e0f53d577e34ba692a13bda6ae0cb9792c6 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 15 Jan 2021 22:15:32 -0500 Subject: Help: Convert genex documentation to sphinx domain objects This makes them linkable, indexed, and enables cross-references. --- Help/manual/cmake-generator-expressions.7.rst | 384 +++++++++++++++++++------- 1 file changed, 282 insertions(+), 102 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 50c816c..ca4ea3e 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -46,7 +46,8 @@ Available boolean expressions are: Logical Operators ----------------- -``$`` +.. genex:: $ + Converts ``string`` to ``0`` or ``1``. Evaluates to ``0`` if any of the following is true: @@ -57,23 +58,27 @@ Logical Operators Otherwise evaluates to ``1``. -``$`` +.. genex:: $ + where ``conditions`` is a comma-separated list of boolean expressions. Evaluates to ``1`` if all conditions are ``1``. Otherwise evaluates to ``0``. -``$`` +.. genex:: $ + where ``conditions`` is a comma-separated list of boolean expressions. Evaluates to ``1`` if at least one of the conditions is ``1``. Otherwise evaluates to ``0``. -``$`` +.. genex:: $ + ``0`` if ``condition`` is ``1``, else ``1``. String Comparisons ------------------ -``$`` +.. genex:: $ + ``1`` if ``string1`` and ``string2`` are equal, else ``0``. The comparison is case-sensitive. For a case-insensitive comparison, combine with a :ref:`string transforming generator expression @@ -83,100 +88,150 @@ String Comparisons $,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ... -``$`` +.. genex:: $ + ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. -``$`` + +.. genex:: $ + ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. Uses case-sensitive comparisons. -``$`` + +.. genex:: $ + ``1`` if ``v1`` is a version less than ``v2``, else ``0``. -``$`` + +.. genex:: $ + ``1`` if ``v1`` is a version greater than ``v2``, else ``0``. -``$`` + +.. genex:: $ + ``1`` if ``v1`` is the same version as ``v2``, else ``0``. -``$`` + +.. genex:: $ + ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. -``$`` + +.. genex:: $ + ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. Variable Queries ---------------- -``$`` +.. genex:: $ + ``1`` if ``target`` exists, else ``0``. -``$`` + +.. genex:: $ + ``1`` if config is any one of the entries in ``cfgs``, else ``0``. This is a case-insensitive comparison. The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_` is also considered by this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` target. -``$`` + +.. genex:: $ + where ``platform_ids`` is a comma-separated list. ``1`` if the CMake's platform id matches any one of the entries in ``platform_ids``, otherwise ``0``. See also the :variable:`CMAKE_SYSTEM_NAME` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the C compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the CXX compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the CUDA compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Objective-C compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Objective-C++ compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Fortran compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the ISPC compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the ``policy`` was NEW when the 'head' target was created, else ``0``. If the ``policy`` was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies. -``$`` + +.. genex:: $ + where ``features`` is a comma-spearated list. Evaluates to ``1`` if all of the ``features`` are available for the 'head' target, and ``0`` otherwise. If this expression is used while evaluating @@ -188,7 +243,8 @@ Variable Queries .. _`Boolean COMPILE_LANGUAGE Generator Expression`: -``$`` +.. genex:: $ + ``1`` when the language used for compilation unit matches ``language`` and the CMake's compiler id of the language compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. This expression is a short form @@ -224,7 +280,8 @@ Variable Queries $<$,$>:COMPILING_C_WITH_CLANG> ) -``$`` +.. genex:: $ + ``1`` when the language used for compilation unit matches any of the entries in ``languages``, otherwise ``0``. This expression may be used to specify compile options, compile definitions, and include directories for source files of a @@ -269,7 +326,8 @@ Variable Queries .. _`Boolean LINK_LANGUAGE Generator Expression`: -``$`` +.. genex:: $ + ``1`` when the language used for link step matches ``language`` and the CMake's compiler id of the language linker matches any one of the entries in ``compiler_ids``, otherwise ``0``. This expression is a short form for the @@ -308,7 +366,8 @@ Variable Queries ``$`` for constraints about the usage of this generator expression. -``$`` +.. genex:: $ + ``1`` when the language used for link step matches any of the entries in ``languages``, otherwise ``0``. This expression may be used to specify link libraries, link options, link directories and link dependencies of a @@ -370,14 +429,16 @@ Variable Queries evaluation will give ``C`` as link language, so the second pass will correctly add target ``libother`` as link dependency. -``$`` +.. genex:: $ + Returns the list if it is the device link step, an empty list otherwise. The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION` and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`. This expression can only be used to specify link options. -``$`` +.. genex:: $ + Returns the list if it is the normal link step, an empty list otherwise. This expression is mainly useful when a device link step is also involved (see ``$`` generator expression). This expression can only @@ -433,11 +494,16 @@ Escaped Characters String literals to escape the special meaning a character would otherwise have: -``$`` +.. genex:: $ + A literal ``>``. Used for example to compare strings that contain a ``>``. -``$`` + +.. genex:: $ + A literal ``,``. Used for example to compare strings which contain a ``,``. -``$`` + +.. genex:: $ + A literal ``;``. Used to prevent list expansion on an argument with ``;``. .. _`Conditional Generator Expressions`: @@ -448,11 +514,13 @@ Conditional Expressions Conditional generator expressions depend on a boolean condition that must be ``0`` or ``1``. -``$`` +.. genex:: $ + Evaluates to ``true_string`` if ``condition`` is ``1``. Otherwise evaluates to the empty string. -``$`` +.. genex:: $ + Evaluates to ``true_string`` if ``condition`` is ``1``. Otherwise evaluates to ``false_string``. @@ -471,22 +539,34 @@ otherwise expands to the empty string. String Transformations ---------------------- -``$`` +.. genex:: $ + Joins the list with the content of ``string``. -``$`` + +.. genex:: $ + Removes duplicated items in the given ``list``. -``$`` + +.. genex:: $ + Includes or removes items from ``list`` that match the regular expression ``regex``. -``$`` + +.. genex:: $ + Content of ``string`` converted to lower case. -``$`` + +.. genex:: $ + Content of ``string`` converted to upper case. -``$`` +.. genex:: $ + Content of ``expr`` evaluated as a generator expression in the current context. This enables consumption of generator expressions whose evaluation results itself in generator expressions. -``$`` + +.. genex:: $ + Content of ``expr`` evaluated as a generator expression in the context of ``tgt`` target. This enables consumption of custom target properties that themselves contain generator expressions. @@ -525,62 +605,99 @@ String Transformations Variable Queries ---------------- -``$`` +.. genex:: $ + Configuration name. -``$`` + +.. genex:: $ + Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. -``$`` + +.. genex:: $ + The current system's CMake platform id. See also the :variable:`CMAKE_SYSTEM_NAME` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the C compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the CXX compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the CUDA compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the OBJC compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the OBJCXX compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the ISPC compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The version of the C compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The version of the CXX compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The version of the CUDA compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The version of the OBJC compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The version of the OBJCXX compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The version of the Fortran compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The version of the ISPC compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The compile language of source files when evaluating compile options. See :ref:`the related boolean expression ` ``$`` for notes about the portability of this generator expression. -``$`` + +.. genex:: $ + The link language of target when evaluating link options. See :ref:`the related boolean expression ` ``$`` @@ -607,14 +724,19 @@ In the following, "the ``tgt`` filename" means the name of the ``tgt`` binary file. This has to be distinguished from "the target name", which is just the string ``tgt``. -``$`` +.. genex:: $ + The target name ``tgt`` if the target exists, an empty string otherwise. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Full path to the ``tgt`` binary file. -``$`` + +.. genex:: $ + Base name of ``tgt``, i.e. ``$`` without prefix and suffix. For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. @@ -631,36 +753,48 @@ which is just the string ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Prefix of the ``tgt`` filename (such as ``lib``). See also the :prop_tgt:`PREFIX` target property. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``). See also the :prop_tgt:`SUFFIX` target property. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + The ``tgt`` filename. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Directory of the ``tgt`` binary file. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + File used when linking to the ``tgt`` target. This will usually be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``), but for a shared library on DLL platforms, it would be the ``.lib`` import library associated with the DLL. -``$`` + +.. genex:: $ + Base name of file used to link the target ``tgt``, i.e. ``$`` without prefix and suffix. For example, if target file name is ``libbase.a``, the base name is ``base``. @@ -676,7 +810,9 @@ which is just the string ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Prefix of file used to link target ``tgt``. See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target @@ -684,7 +820,9 @@ which is just the string ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Suffix of file used to link where ``tgt`` is the name of a target. The suffix corresponds to the file extension (such as ".so" or ".lib"). @@ -694,36 +832,49 @@ which is just the string ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Name of file used to link target ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Directory of file used to link target ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + File with soname (``.so.3``) where ``tgt`` is the name of a target. -``$`` +.. genex:: $ + Name of file with soname (``.so.3``). Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Directory of with soname (``.so.3``). Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` target properties and their configuration specific variants :prop_tgt:`PDB_NAME_` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_`. -``$`` + +.. genex:: $ + Base name of the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -739,23 +890,31 @@ which is just the string ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Name of the linker generated program database file (.pdb). Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Directory of the linker generated program database file (.pdb). Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Full path to the bundle directory (``my.app``, ``my.framework``, or ``my.bundle``) where ``tgt`` is the name of a target. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Full path to the bundle content directory where ``tgt`` is the name of a target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to @@ -764,17 +923,23 @@ which is just the string ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Value of the property ``prop`` on the target ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Value of the property ``prop`` on the target for which the expression is being evaluated. Note that for generator expressions in :ref:`Target Usage Requirements` this is the consuming target rather than the target specifying the requirement. -``$`` + +.. genex:: $ + Content of the install prefix when the target is exported via :command:`install(EXPORT)`, or when evaluated in :prop_tgt:`INSTALL_NAME_DIR`, and empty otherwise. @@ -782,30 +947,43 @@ which is just the string ``tgt``. Output-Related Expressions -------------------------- -``$`` +.. genex:: $ + Marks ``...`` as being the name of a target. This is required if exporting targets to multiple dependent export sets. The ``...`` must be a literal name of a target- it may not contain generator expressions. -``$`` + +.. genex:: $ + Content of ``...`` except when evaluated in a link interface while propagating :ref:`Target Usage Requirements`, in which case it is the empty string. Intended for use only in an :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, perhaps via the :command:`target_link_libraries` command, to specify private link dependencies without other usage requirements. -``$`` + +.. genex:: $ + Content of ``...`` when the property is exported using :command:`install(EXPORT)`, and empty otherwise. -``$`` + +.. genex:: $ + Content of ``...`` when the property is exported using :command:`export`, or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise. -``$`` + +.. genex:: $ + Content of ``...`` converted to a C identifier. The conversion follows the same behavior as :command:`string(MAKE_C_IDENTIFIER)`. -``$`` + +.. genex:: $ + List of objects resulting from build of ``objLib``. -``$`` + +.. genex:: $ + Content of ``...`` converted to shell path style. For example, slashes are converted to backslashes in Windows shells and drive letters are converted to posix paths in MSYS shells. The ``...`` must be an absolute path. @@ -815,7 +993,8 @@ Output-Related Expressions ``;`` on Windows). Be sure to enclose the argument containing this genex in double quotes in CMake source code so that ``;`` does not split arguments. -``$`` +.. genex:: $ + .. versionadded:: 3.20 Only valid in :command:`add_custom_command` and :command:`add_custom_target` @@ -824,7 +1003,8 @@ Output-Related Expressions in ``...`` are evaluated using the custom command's "output config". With other generators, the content of ``...`` is evaluated normally. -``$`` +.. genex:: $ + .. versionadded:: 3.20 Only valid in :command:`add_custom_command` and :command:`add_custom_target` -- cgit v0.12