mirrors/cmake
2
0
Fork 0
mirror of https://gitlab.kitware.com/cmake/cmake.git synced 2026-09-25 04:09:36 +03:00
Code Activity

Merge topic 'custom-rule-support'

Browse Source 
386d1d874c Add support of custom rules

Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Merge-request: !12361
This commit is contained in:
Brad King
2026-09-21 11:40:22 -04:00
committed by Kitware Robot
parent da84a029d3 386d1d874c
commit c512ae97ce
254 changed files with 4454 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Help/command/add_custom_command.rst
+1
View File
@@ -723,3 +723,4 @@ See Also
^^^^^^^^
* :command:`add_custom_target`
* :command:`add_custom_rule`
Help/command/add_custom_rule.rst
+402
View File
@@ -0,0 +1,402 @@
add_custom_rule
---------------
.. versionadded:: 4.5
Add a custom template rule to the generated build system.
Synopsis
^^^^^^^^
.. parsed-literal::
`Generating Files`_
add_custom_rule(<name> `OUTPUT`_ <output1> [<output2> ...]
COMMAND <command1> [<args1>...]
[...])
`Derived Rule`_
add_custom_rule(<name> `FROM_RULE`_ <rule>
[...])
Generating Files
^^^^^^^^^^^^^^^^
.. signature::
add_custom_rule(<name> OUTPUT <output1> [<output2> ...]
COMMAND <command1> [<args1>...]
[...])
:target:
OUTPUT
Add a custom template rule to produce an output:
.. code-block:: cmake
add_custom_rule(<name> OUTPUT <output1> [<output2> ...]
COMMAND <command1> [<args1>...]
[COMMAND <command2> [<args2>...]] ...
[DEPENDS <depends>...]
[BYPRODUCTS <files>...]
[DEPFILE <depfile>]
[CONFIGURATOR [FOR_FILE_SET <configurator>]
[FOR_SOURCE <configurator>]]
[GLOBAL])
This defines a template rule ``<name>`` to generate specified ``OUTPUT``
file(s). Rule names defined in all uppercase are reserved for CMake's own
built-in rules.
The association of source files with the template rule is done by creating
:ref:`file sets <File Sets>` of type ``<name>``. For each file of the file
set, a :command:`custom command <add_custom_command>` will be created in the
same directory as the target owning the file set and the output files of this
custom command will be declared as part of a file set attached to
the same target. The type of this file set, as well as its name, are
controlled by the :prop_rule:`OUTPUT_FILE_SET` rule property. This output
file set will have the same scope (``PRIVATE``, ``PUBLIC``, or ``INTERFACE``)
as the input file set.
To parameterize the template, some patterns are defined which can be used as
part of the ``add_custom_rule`` arguments as well as the :ref:`rule's
properties <Rule Properties>`. These patterns will be
instantiated for each source file. The supported patterns are:
.. note::
The instantiation of the patterns are done in the context of the directory
where the file set was created.
These patterns cannot be changed by the functions specified by the
``CONFIGURATOR`` option.
``<RULE>``
Name of the rule used as template.
``<TARGET>``
Name of the target to which the file set of sources is attached.
``<FILE_SET>``
Name of the file set used for the rule instantiation.
``<SOURCE_DIR>``
The value of the :variable:`CMAKE_SOURCE_DIR` variable.
``<BINARY_DIR>``
The value of the :variable:`CMAKE_BINARY_DIR` variable.
``<CURRENT_SOURCE_DIR>``
The path to the source directory of the file set creation.
``<CURRENT_BINARY_DIR>``
The path to the binary directory of the file set creation.
``<SOURCE>``
The full path of the current source file being processed.
``<INPUT_DIR>``
The directory of the current source file being processed.
``<FILE_NAME>``
The file name of the current source file being processed.
``<BASE_NAME>``
The stem name (i.e. without directory and extension) of the source file
being processed.
``<INCLUDE_DIRECTORIES>``
Content, in this order, of the :prop_fs:`INCLUDE_DIRECTORIES` file set
property, :prop_sf:`INCLUDE_DIRECTORIES` source property, and
:prop_rule:`INCLUDE_DIRECTORIES` rule property.
Because CMake is not aware of the tool involved by the rule, there is
no specific processing regarding this pattern. This is the user's
responsibility to format, using :manual:`generator expressions
<cmake-generator-expressions(7)>`, the content of pattern to be compatible
with the tool.
For example, if the tool requires the flag ``-inc:`` to identify an include
directory, the following can be specified as part of the ``COMMAND``
option:
.. code-block:: cmake
$<LIST:TRANSFORM,<INCLUDE_DIRECTORIES>,PREPEND,-inc:>
``<COMPILE_DEFINITIONS>``
Content, in this order, of the :prop_rule:`COMPILE_DEFINITIONS` rule
property, :prop_sf:`COMPILE_DEFINITIONS` source property, and
:prop_fs:`COMPILE_DEFINITIONS` file set property.
Because CMake is not aware of the tool involved by the rule, there is
no specific processing regarding this pattern. This is the user's
responsibility to format, using :manual:`generator expressions
<cmake-generator-expressions(7)>`, the content of pattern to be compatible
with the tool.
For example, if the tool requires the flag ``-def:`` to identify a compile
definition, the following can be specified as part of the ``COMMAND``
option:
.. code-block:: cmake
$<LIST:TRANSFORM,<COMPILE_DEFINITIONS>,PREPEND,-def:>
``<COMPILE_OPTIONS>``
Content, in this order, of the :prop_rule:`COMPILE_OPTIONS` rule property,
:prop_sf:`COMPILE_OPTIONS` source property, and:prop_fs:`COMPILE_OPTIONS`
file set property.
The options, which have the same semantics as those of the
:command:`add_custom_command` command, are:
``OUTPUT``
Specify the output files the command is expected to produce.
Each output file will be marked with the :prop_sf:`GENERATED`
source file property automatically. At least one ``OUTPUT`` must be given.
``COMMAND``
Specify the command-line(s) to execute at build time.
At least one ``COMMAND`` must be given.
``DEPENDS``
Specify files on which the command depends.
``BYPRODUCTS``
Specify the files the command is expected to produce but whose
modification time may or may not be newer than the dependencies.
``DEPFILE``
Specify a depfile which holds dependencies for the custom command. It is
usually emitted by the custom command itself.
``CONFIGURATOR``
Specify one or two CMake functions which will be called at the generation
step, in the context of the file set directory, before the effective
instantiation and custom commands definition.
.. note::
The rule properties are all read-only during the execution of the
configurators. Moreover, it is strongly discouraged to change the
target properties.
``FOR_FILE_SET``
The specified function will be called once per file set.
The expected signature is the following:
.. signature::
configurator(rule target fileset outputFileset patterns)
The arguments provide the names of the effective artifacts involved in
the current rule instantiation.
The ``patterns`` argument holds the name of the variable which can be
used to enrich the list of patterns. The expected value is a
:ref:`semicolon-separated list <CMake Language Lists>` of items having
the syntax ``PATTERN=VALUE`` or ``PATTERN=``. More precisely, each item
must match the regular expression ``(^[A-Z][A-Z0-9_]+)=(.*)$``. Items
which does not this regular expression will be ignored.
``FOR_SOURCE``
The specified function will be called for each file of the file set.
The expected signature is the following:
.. signature::
configurator(rule target fileset outputFileset source patterns)
The arguments provide the names of the effective artifacts involved in
the current rule instantiation.
The ``patterns`` argument holds the name of the variable which can be
used to enrich the list of patterns. The expected value is a
:ref:`semicolon-separated list <CMake Language Lists>` of items having
the syntax ``PATTERN=VALUE`` or ``PATTERN=``. More precisely, each item
must match the regular expression ``(^[A-Z][A-Z0-9_]+)=(.*)$``. Items
which does not this regular expression will be ignored.
.. note::
The source configurator is evaluated after the file set one. So, the
changes done by it will overwrite any changes done by the file set
configurator.
.. note::
Any patterns specified through The :prop_fs:`RULE_PATTERNS` file set
and :prop_sf:`<RULE>_PATTERNS` source file properties will take
precedence over, respectively, the file set and the source configurators.
``GLOBAL``
Make the rule name globally visible. Without this keyword, the rule will
only be visible in the directory where it was created as well as the
sub-directories.
Example
=======
Define a rule to compile swig files:
.. code-block:: cmake
function(fileset_configurator rule target fileset patterns)
# define <OUTFILE_DIR> pattern
set(${patterns} "OUTFILE_DIR=<CURRENT_BINARY_DIR>" PARENT_SCOPE)
endfunction()
function(source_configurator rule target fileset source patterns)
# define flag to handle C++
get_property(cxx SOURCE "${source}" TARGET_DIRECTORY "${target}" PROPERTY CPLUSPLUS)
if (cxx)
set_property(SOURCE "${source}" TARGET_DIRECTORY "${target}"
APPEND PROPERTY COMPILE_OPTIONS -c++)
endif()
endfunction()
set(OUTFILE_EXT "$<IF:$<BOOL:$<SOURCE_PROPERTY:<SOURCE>,TARGET_DIRECTORY:<TARGET>,CPLUSPLUS>>,.cxx,.c>")
set(SWIG_LANGUAGE "-$<STRING:TOLOWER,$<FILE_SET_PROPERTY:<FILE_SET>,TARGET:<TARGET>,LANGUAGE>>")
add_custom_rule(swig
OUTPUT "<OUTFILE_DIR>/<BASE_NAME>${OUTFILE_EXT}"
COMMAND ${SWIG_EXECUTABLE} "<SOURCE>"
"<OUTFILE_DIR>/<BASE_NAME>${OUTFILE_EXT}"
${SWIG_LANGUAGE}
<COMPILE_OPTIONS>
CONFIGURATOR FOR_FILE_SET fileset_configurator FOR_SOURCE source_configurator)
And, by defining a file set of type ``swig``, we can compile swig sources:
.. code-block:: cmake
add_library(swig_example)
target_sources(swig_example PRIVATE FILE_SET swig_srcs TYPE swig
FILES file1.i file2.i)
# define the target language
set_property(FILE_SET swig_srcs TARGET swig_example PROPERTY LANGUAGE python)
# define swig c++ mode
set_property(SOURCE file1.i file2.i PROPERTY CPLUSPLUS ON)
Derived Rule
^^^^^^^^^^^^
.. signature::
add_custom_rule(<name> FROM_RULE <rule>
[...])
:target:
FROM_RULE
Create a new template rule ``<name>`` inheriting a snapshot of all the
characteristics of the ``<rule>``, including the properties except the
``GLOBAL`` one. Rule names defined in all uppercase are reserved for CMake's
own built-in rules.
.. code-block:: cmake
add_custom_rule(<name> FROM_RULE <rule>
[CONFIGURATOR [FOR_FILE_SET <configurator> [CHAIN|OVERRIDE]]
[FOR_SOURCE <configurator> [CHAIN|OVERRIDE]]]
[GLOBAL])
Properties attached to this new rule can be freely customized, independently
of the rule we inherited from.
The options are:
``FROM_RULE``
Specify the rule from which this new rule will inherit.
``CONFIGURATOR``
Specify one or two CMake functions which will be called at the generation
step before the effective instantiation and custom commands definition.
.. note::
The rule properties are all read-only during the execution of the
configurators. Moreover, it is strongly discouraged to change the
target properties.
``FOR_FILE_SET``
The specified function will be called once per file set.
The expected signature is the following:
.. signature::
configurator(rule target fileset outputFileset patterns)
The arguments provide the names of the effective artifacts involved in
the current rule instantiation.
The ``patterns`` argument holds the name of the variable which can be
used to enrich the list of patterns.
``FOR_SOURCE``
The specified function will be called for each file of the file set.
The expected signature is the following:
.. signature::
configurator(rule target fileset outputFileset source patterns)
The arguments provide the names of the effective artifacts involved in
the current rule instantiation.
The ``patterns`` argument holds the name of the variable which can be
used to enrich the list of patterns.
For these two sub-options, there are two possible configurations:
``CHAIN``
This ``<configurator>`` will be added to the already specified
configurators of inherited rules. Configurators will be called in order
of their rules' definition.
``OVERRIDE``
The specified ``<configurator>`` will override any other already defined
configurators. This is the default.
``GLOBAL``
Make the rule name globally visible. Without this keyword, the rule will
only be visible in the directory where it was created as well as the
sub-directories.
Example
=======
By reusing the previous defined rule ``swig``, we can provide a more simple way
to compile swig sources by creating a more specialized rule:
.. code-block:: cmake
function(python_configurator rule target fileset outputFileset patterns)
# define target language
set_property(FILE_SET ${fileset} TARGET ${target} PROPERTY LANGUAGE python)
endfunction()
function(cxx_configurator rule target fileset outputFileset source patterns)
# define swig c++ mode
set_property(SOURCE "${source}" TARGET_DIRECTORY ${target} PROPERTY CPLUSPLUS ON)
set_property(SOURCE "${source}" TARGET_DIRECTORY ${target}
APPEND PROPERTY COMPILE_OPTIONS -c++)
endfunction()
add_custom_rule(swig_python FROM_RULE swig
CONFIGURATOR FOR_FILE_SET python_configurator CHAIN
FOR_SOURCE cxx_configurator OVERRIDE)
Now, we can define a file set which does not need any specific settings. And
because the ``CHAIN`` option was specified for the file set configurator, the
pattern ``<OUTFILE_DIR>`` will be defined as well.
.. code-block:: cmake
add_library(swig_example)
target_sources(swig_example PRIVATE FILE_SET swig_srcs TYPE swig_python
FILES file1.i file2.i)
See Also
^^^^^^^^
* :command:`set_property(RULE)`
* :command:`get_property(RULE)`
* :command:`target_sources`
* :command:`add_custom_command`
Help/command/get_property.rst
+7
View File
@@ -8,6 +8,7 @@ Get a property.
get_property(<variable>
<GLOBAL |
DIRECTORY [<dir>] |
RULE <rule> |
TARGET <target> |
FILE_SET <file_set> TARGET <target> |
SOURCE <source>
@@ -39,6 +40,12 @@ It must be one of the following:
.. versionadded:: 3.19
``<dir>`` may reference a binary directory.
``RULE``
.. versionadded:: 4.5
Scope must name one existing rule in the current directory, created
by the :command:`add_custom_rule` command.
``TARGET``
Scope must name one existing target.
See also the :command:`get_target_property` command.
Help/command/set_property.rst
+7
View File
@@ -7,6 +7,7 @@ Set a named property in a given scope.
set_property({GLOBAL |
DIRECTORY [<dir>] |
RULE <rule>... |
TARGET <target>... |
FILE_SET <file_set>... TARGET <target> |
SOURCE <source>...
@@ -36,6 +37,12 @@ It must be one of the following:
.. versionadded:: 3.19
``<dir>`` may reference a binary directory.
``RULE``
.. versionadded:: 4.5
Scope may name zero or more existing rules in the current directory, created
by the :command:`add_custom_rule` command.
``TARGET``
Scope may name zero or more existing targets.
See also the :command:`set_target_properties` command.
Help/manual/cmake-buildsystem.7.rst
+12 -2
View File
@@ -426,8 +426,18 @@ Acceptable file set types are:
using the ``export`` keyword). This file set type may not have an
``INTERFACE`` scope except on ``IMPORTED`` targets.
The optional default file sets are named after their type. The target may not
be a custom target or, for ``HEADERS`` and ``CXX_MODULES`` types, a
``<rule>``
.. versionadded:: 4.5
Specifies sources which will be processed by the custom rule defined by the
:command:`add_custom_rule` command.
For ``HEADERS``, ``SOURCES``, and ``CXX_MODULES`` types, the optional default
file sets are named after their type.
For ``<rule>`` types, the target may be a custom target.
For ``HEADERS`` and ``CXX_MODULES`` types, the target may not be a
:prop_tgt:`FRAMEWORK` target.
Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for
Help/manual/cmake-commands.7.rst
+1
View File
@@ -80,6 +80,7 @@ These commands are available only in CMake projects.
/command/add_compile_definitions
/command/add_compile_options
/command/add_custom_command
/command/add_custom_rule
/command/add_custom_target
/command/add_definitions
/command/add_dependencies
Help/manual/cmake-generator-expressions.7.rst
+20
View File
@@ -1449,6 +1449,26 @@ Configuration Expressions
in ``...`` are evaluated using the custom command's "command config".
With other generators, the content of ``...`` is evaluated normally.
Rule-Dependent Expressions
--------------------------
Rule Properties
^^^^^^^^^^^^^^^
These expressions look up the values of rule properties.
.. genex:: $<RULE_PROPERTY:rule,prop>
.. versionadded:: 4.5
Value of the property ``prop`` on the rule ``rule``, or empty if
the property is not set. An error will be raised if the rule is not
known by CMake.
This generator expression can only be used in the definition of a custom rule
(see :command:`add_custom_rule`). Moreover, ``rule`` parameter must be the
pattern ``<RULE>``. Any other value will raise an error.
Toolchain And Language Expressions
----------------------------------
Help/manual/cmake-properties.7.rst
+36
View File
@@ -88,6 +88,7 @@ Properties on Directories
/prop_dir/RULE_LAUNCH_COMPILE
/prop_dir/RULE_LAUNCH_CUSTOM
/prop_dir/RULE_LAUNCH_LINK
/prop_dir/RULES
/prop_dir/SOURCE_DIR
/prop_dir/SUBDIRECTORIES
/prop_dir/SYSTEM
@@ -99,6 +100,39 @@ Properties on Directories
/prop_dir/VS_SOLUTION_ITEMS
/prop_dir/VS_STARTUP_PROJECT
.. _`Rule Properties`:
Properties on Rules
===================
.. toctree::
:maxdepth: 1
/prop_rule/BYPRODUCTS
/prop_rule/COMMAND
/prop_rule/COMMAND_INDEX
/prop_rule/COMMAND_COUNT
/prop_rule/COMMAND_EXPAND_LISTS
/prop_rule/COMMENT
/prop_rule/COMPILE_DEFINITIONS
/prop_rule/COMPILE_OPTIONS
/prop_rule/DEPENDS_EXPLICIT_ONLY
/prop_rule/DEPENDS
/prop_rule/DEPFILE
/prop_rule/FILE_SET_CONFIGURATORS
/prop_rule/GLOBAL
/prop_rule/INCLUDE_DIRECTORIES
/prop_rule/JOB_POOL_COMPILE
/prop_rule/JOB_SERVER_AWARE
/prop_rule/NAME
/prop_rule/OUTPUT
/prop_rule/OUTPUT_FILE_SET
/prop_rule/PARENT_RULE
/prop_rule/SOURCE_CONFIGURATORS
/prop_rule/USES_TERMINAL
/prop_rule/VERBATIM
/prop_rule/WORKING_DIRECTORY
.. _`Target Properties`:
Properties on Targets
@@ -555,6 +589,7 @@ Properties on File Sets
/prop_fs/INTERFACE_COMPILE_OPTIONS
/prop_fs/INTERFACE_INCLUDE_DIRECTORIES
/prop_fs/INTERFACE_SOURCES
/prop_fs/RULE_PATTERNS
/prop_fs/SCOPE
/prop_fs/SKIP_LINTING
/prop_fs/SKIP_PRECOMPILE_HEADERS
@@ -632,6 +667,7 @@ Properties on Source Files
/prop_sf/OBJECT_DEPENDS
/prop_sf/OBJECT_NAME
/prop_sf/OBJECT_OUTPUTS
/prop_sf/RULE_PATTERNS
/prop_sf/Rust_EMIT
/prop_sf/SKIP_AUTOGEN
/prop_sf/SKIP_AUTOMOC
Help/prop_dir/RULES.rst
+12
View File
@@ -0,0 +1,12 @@
RULES
-----
.. versionadded:: 4.5
This read-only directory property contains a
:ref:`semicolon-separated list <CMake Language Lists>` of
rules added in the directory by calls to the :command:`add_custom_rule`
command.
Each entry in the list is the logical name of a rule, suitable
to pass to the :command:`get_property` command ``RULE`` option
when called in the same directory.
Help/prop_fs/COMPILE_DEFINITIONS.rst
+5 -6
View File
@@ -5,12 +5,11 @@ COMPILE_DEFINITIONS
Preprocessor definitions for compiling a source file.
The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated
list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``.
Function-style definitions are not supported. CMake will
automatically escape the value correctly for the native build system
(note that CMake language syntax may require escapes to specify some
values).
The ``COMPILE_DEFINITIONS`` property may be set to a :ref:`semicolon-separated
list <CMake Language Lists>` of preprocessor definitions using the syntax
``VAR`` or ``VAR=value``. Function-style definitions are not supported. CMake
will automatically escape the value correctly for the native build system (note
that CMake language syntax may require escapes to specify some values).
CMake will automatically drop some definitions that are not supported
by the native build tool. :generator:`Xcode` does not support
Help/prop_fs/INCLUDE_DIRECTORIES.rst
+5 -5
View File
@@ -5,11 +5,11 @@ INCLUDE_DIRECTORIES
List of preprocessor include file search directories.
This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of paths
and will be added to the list of include directories when the sources of this
file set are built. These directories will take precedence over directories
defined at target level and source level except for :generator:`Xcode`
generator due to technical limitations.
This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of
paths and will be added to the list of include directories when the sources of
this file set are built. These directories will take precedence over
directories defined at target level and source level except for
:generator:`Xcode` generator due to technical limitations.
Relative paths should not be added to this property directly.
Help/prop_fs/JOB_POOL_COMPILE.rst
+1
View File
@@ -24,5 +24,6 @@ This property is undefined by default.
See Also
^^^^^^^^
* :prop_rule:`JOB_POOL_COMPILE` rule property
* :prop_sf:`JOB_POOL_COMPILE` source file property
* :prop_tgt:`JOB_POOL_COMPILE` target property
Help/prop_fs/RULE_PATTERNS.rst
+27
View File
@@ -0,0 +1,27 @@
RULE_PATTERNS
-------------
.. versionadded:: 4.5
Patterns specification for instantiating a rule.
The ``RULE_PATTERNS`` property may be set to a
:ref:`semicolon-separated list <CMake Language Lists>` of patterns using the
syntax ``PATTERN=VALUE`` or ``PATTERN=``. More precisely, each item must match
the regular expression ``(^[A-Z][A-Z0-9_]+)=(.*)$``.
CMake will automatically drop any patterns which do not match against this
regular expression.
The list is ordered, so a pattern can use in its definition a previously
defined pattern. In the following example,
``OUTPUT_DIR=/some/path;OUTPUT_FILE=<OUTPUT_DIR>/my_file``, when the pattern
``<OUTPUT_FILE>`` is expanded, the pattern ``<OUTPUT_DIR>`` is already known.
Related properties:
* :prop_sf:`<RULE>_PATTERNS` to specify patterns for a specific file.
Related commands:
* :command:`add_custom_rule` for custom rule specification.
Help/prop_rule/BYPRODUCTS.rst
+9
View File
@@ -0,0 +1,9 @@
BYPRODUCTS
----------
.. versionadded:: 4.5
Read-only property giving a
:ref:`semicolon-separated list <CMake Language Lists>` of the produced
artifacts, if any, by the rule as specified by the ``BYPRODUCTS`` option of the
:command:`add_custom_rule` command.
Help/prop_rule/COMMAND.rst
+12
View File
@@ -0,0 +1,12 @@
COMMAND
-------
.. versionadded:: 4.5
Read-only property giving a
:ref:`semicolon-separated list <CMake Language Lists>` of the arguments of the
rule as specified by the first ``COMMAND`` option of the
:command:`add_custom_rule` command.
This is equivalent to the :prop_rule:`COMMAND_<INDEX>` rule property with the
index ``0``.
Help/prop_rule/COMMAND_COUNT.rst
+10
View File
@@ -0,0 +1,10 @@
COMMAND_COUNT
-------------
.. versionadded:: 4.5
Read-only property giving the count of ``COMMAND`` options of the
:command:`add_custom_rule` command.
To retrieve the ``<INDEX>``th ``COMMAND``, use the :prop_rule:`COMMAND_<INDEX>`
rule property.
Help/prop_rule/COMMAND_EXPAND_LISTS.rst
+11
View File
@@ -0,0 +1,11 @@
COMMAND_EXPAND_LISTS
--------------------
.. versionadded:: 4.5
``COMMAND_EXPAND_LISTS`` is a boolean specifying that the lists in the
``COMMAND`` arguments of the :command:`add_custom_rule` command will be
expanded, including those created with
:manual:`generator expressions <cmake-generator-expressions(7)>`.
By default, ``COMMAND_EXPAND_LISTS`` is true.
Help/prop_rule/COMMAND_INDEX.rst
+16
View File
@@ -0,0 +1,16 @@
COMMAND_<INDEX>
---------------
.. versionadded:: 4.5
Read-only property giving a
:ref:`semicolon-separated list <CMake Language Lists>` of the arguments of the
rule as specified by the ``<INDEX>``th ``COMMAND`` option of the
:command:`add_custom_rule` command. The index range is starting at ``0``. If
the index specified is out of the range of commands, ``NOTFOUND`` is returned.
The :prop_rule:`COMMAND` rule property can be used as a shorthand to the
``COMMAND_0`` rule property.
The number of commands can be retrieve using the :prop_rule:`COMMAND_COUNT`
rule property.
Help/prop_rule/COMMENT.rst
+8
View File
@@ -0,0 +1,8 @@
COMMENT
-------
.. versionadded:: 4.5
Display the given message before the commands are executed at build time.
Arguments to ``COMMENT`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
Help/prop_rule/COMPILE_DEFINITIONS.rst
+24
View File
@@ -0,0 +1,24 @@
COMPILE_DEFINITIONS
-------------------
.. versionadded:: 4.5
Preprocessor definitions for compiling the file set's sources associated with
this rule.
The ``COMPILE_DEFINITIONS`` property may be set to a
:ref:`semicolon-separated list <CMake Language Lists>` of preprocessor
definitions using the syntax ``VAR`` or ``VAR=value``. Function-style
definitions are not supported. CMake will automatically escape the value
correctly for the native build system (note that CMake language syntax may
require escapes to specify some values).
CMake will automatically drop definitions that are not supported
by the native build tool.
.. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.rst
Contents of ``COMPILE_DEFINITIONS`` may use :manual:`generator expressions
<cmake-generator-expressions(7)>` with the syntax ``$<...>``. See the
:manual:`cmake-buildsystem(7)` manual for more on defining buildsystem
properties.
Help/prop_rule/COMPILE_OPTIONS.rst
+15
View File
@@ -0,0 +1,15 @@
COMPILE_OPTIONS
---------------
List of options to pass to the compiler.
This property holds a :ref:`semicolon-separated list <CMake Language Lists>`
of options specified so far for its rule. Use the
:command:`set_property(RULE)` command to append more options.
Contents of ``COMPILE_OPTIONS`` may use :manual:`generator expressions
<cmake-generator-expressions(7)>` with the syntax ``$<...>``. See the
:manual:`cmake-buildsystem(7)` manual for more on defining buildsystem
properties.
.. include:: ../command/include/OPTIONS_SHELL.rst
Help/prop_rule/DEPENDS.rst
+9
View File
@@ -0,0 +1,9 @@
DEPENDS
-------
.. versionadded:: 4.5
Read-only property giving a
:ref:`semicolon-separated list <CMake Language Lists>` of the dependencies, if
any, of the rule as specified by the ``DEPENDS`` option of the
:command:`add_custom_rule` command.
Help/prop_rule/DEPENDS_EXPLICIT_ONLY.rst
+11
View File
@@ -0,0 +1,11 @@
DEPENDS_EXPLICIT_ONLY
---------------------
.. versionadded:: 4.5
``DEPENDS_EXPLICIT_ONLY`` is a boolean indicating that the rule's ``DEPENDS``
argument represents all files required by the command and implicit dependencies
are not required.
If not defined, the :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY`
will be used during the instantiations of the rule.
Help/prop_rule/DEPFILE.rst
+7
View File
@@ -0,0 +1,7 @@
DEPFILE
-------
.. versionadded:: 4.5
Read-only property giving the dependency file, if any, of the rule as specified
by the ``DEPFILE`` option of the :command:`add_custom_rule` command.
Help/prop_rule/FILE_SET_CONFIGURATORS.rst
+9
View File
@@ -0,0 +1,9 @@
FILE_SET_CONFIGURATORS
----------------------
.. versionadded:: 4.5
Read-only property giving a
:ref:`semicolon-separated list <CMake Language Lists>` of the file set
configurators, as specified by ``CONFIGURATOR FOR_FILE_SET`` option, given in
the order of their evaluation.
Help/prop_rule/GLOBAL.rst
+20
View File
@@ -0,0 +1,20 @@
GLOBAL
------
.. versionadded:: 4.5
Indication of whether a rule is globally visible.
The boolean value of this property is true for rules created with the
``GLOBAL`` options to :command:`add_custom_rule()`.
For rules created without the additional option ``GLOBAL`` this is false.
However, setting this property to true promotes that rule to global scope. This
promotion can only be done in the same directory where the rule was created.
.. note::
Once an rule has been made global, it cannot be changed back to
non-global. Therefore, if a project sets this property, it may only
provide a value of true. CMake will issue an error if the project tries to
set the property to a non-true value, even if the value was already false.
Help/prop_rule/INCLUDE_DIRECTORIES.rst
+20
View File
@@ -0,0 +1,20 @@
INCLUDE_DIRECTORIES
-------------------
.. versionadded:: 4.5
List of preprocessor include file search directories.
The ``INCLUDE_DIRECTORIES`` property may be set to a
:ref:`semicolon-separated list <CMake Language Lists>` of directories given so
far to the :command:`set_property(RULE)` command.
The value of this property is used by the rule definitions to set the include
paths for the compiler.
Relative paths should not be added to this property.
Contents of ``INCLUDE_DIRECTORIES`` may use :manual:`generator expressions
<cmake-generator-expressions(7)>` with the syntax ``$<...>``. See the
:manual:`cmake-buildsystem(7)` manual for more on defining buildsystem
properties.
Help/prop_rule/JOB_POOL_COMPILE.rst
+17
View File
@@ -0,0 +1,17 @@
JOB_POOL_COMPILE
----------------
.. versionadded:: 4.5
:ref:`Ninja only <Ninja Generators>`: Pool used for compiling.
The number of parallel compile processes for a rule may be limited by defining
pools with the global :prop_gbl:`JOB_POOLS` property and then specifying the
pool to use.
See Also
^^^^^^^^
* :prop_tgt:`JOB_POOL_COMPILE` target property
* :prop_fs:`JOB_POOL_COMPILE` file set property
* :prop_sf:`JOB_POOL_COMPILE` source file property
Help/prop_rule/JOB_SERVER_AWARE.rst
+15
View File
@@ -0,0 +1,15 @@
JOB_SERVER_AWARE
----------------
.. versionadded:: 4.5
``JOB_SERVER_AWARE`` is a boolean specifying that the commands produced by the
instantiation of the rule are GNU Make job server aware.
For the :generator:`Unix Makefiles`, :generator:`MSYS Makefiles`, and
:generator:`MinGW Makefiles` generators this will add the ``+`` prefix to the
recipe line. See the `GNU Make Documentation`_ for more information.
This option is ignored by other generators.
.. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html
Help/prop_rule/NAME.rst
+6
View File
@@ -0,0 +1,6 @@
NAME
----
.. versionadded:: 4.5
Read-only property giving the name of the rule.
Help/prop_rule/OUTPUT.rst
+9
View File
@@ -0,0 +1,9 @@
OUTPUT
------
.. versionadded:: 4.5
Read-only property giving a
:ref:`semicolon-separated list <CMake Language Lists>` of outputs of the rule
as specified by the ``OUTPUT`` option of the :command:`add_custom_rule`
command.
Help/prop_rule/OUTPUT_FILE_SET.rst
+23
View File
@@ -0,0 +1,23 @@
OUTPUT_FILE_SET
---------------
.. versionadded:: 4.5
Specify the name and the type of the file set storing the files produced by the
instantiation of a rule.
The ``OUTPUT_FILE_SET`` property must hold a
:ref:`semicolon-separated list <CMake Language Lists>` of two elements
specifying the name of the file set and the type.
The name can use the following patterns to enable the production of unique
names for the output file set:
* ``<RULE>``: name of the rule
* ``<TARGET>``: name of the target
* ``<FILE_SET>``: name of the file set
The type must be one of the :ref:`predefined types <File Sets>`.
This property gets the following default value:
``__cmake_rule_<RULE>_<TARGET>_<FILE_SET>_outputs;SOURCES``.
Help/prop_rule/PARENT_RULE.rst
+8
View File
@@ -0,0 +1,8 @@
PARENT_RULE
-----------
.. versionadded:: 4.5
Read-only property giving the name of the parent rule for rules created by
:command:`add_custom_rule(FROM_RULE)` command. This is an empty string for
other rules.
Help/prop_rule/SOURCE_CONFIGURATORS.rst
+9
View File
@@ -0,0 +1,9 @@
SOURCE_CONFIGURATORS
--------------------
.. versionadded:: 4.5
Read-only property giving a
:ref:`semicolon-separated list <CMake Language Lists>` of the source
configurators, as specified by ``CONFIGURATOR FOR_SOURCE`` option, given in
the order of their evaluation.
Help/prop_rule/USES_TERMINAL.rst
+9
View File
@@ -0,0 +1,9 @@
USES_TERMINAL
-------------
.. versionadded:: 4.5
``USES_TERMINAL`` is a boolean which request that the commands produced by the
instantiation of the rule will be given direct access to the terminal if
possible. With the :ref:`Ninja Generators`, this places the command in the
``console`` :prop_gbl:`pool <JOB_POOLS>`.
Help/prop_rule/VERBATIM.rst
+15
View File
@@ -0,0 +1,15 @@
VERBATIM
--------
.. versionadded:: 4.5
``VERBATIM`` is a boolean indicating that all arguments to the commands
produced by the instantiation of the rule will be escaped properly for the
build tool so that the invoked command receives each argument unchanged. Note
that one level of escapes is still used by the CMake language processor before
:command:`add_custom_command` command even sees the arguments.
By default, ``VERBATIM`` has a true value because it is recommended as it
enables correct behavior. When ``VERBATIM`` is not given the behavior is
platform specific because there is no protection of tool-specific special
characters.
Help/prop_rule/WORKING_DIRECTORY.rst
+13
View File
@@ -0,0 +1,13 @@
WORKING_DIRECTORY
-----------------
.. versionadded:: 4.5
Execute the commands produced by the instantiation of the rule with the given
current working directory. If it is a relative path, it will be interpreted
relative to the build tree directory corresponding to the current source
directory of the target. If not specified, the default value is the build
directory corresponding to the current source directory of the target.
Arguments to ``WORKING_DIRECTORY`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
Help/prop_sf/JOB_POOL_COMPILE.rst
+1
View File
@@ -23,5 +23,6 @@ This property is undefined by default.
See Also
^^^^^^^^
* :prop_rule:`JOB_POOL_COMPILE` rule property
* :prop_fs:`JOB_POOL_COMPILE` file set property
* :prop_tgt:`JOB_POOL_COMPILE` target property
Help/prop_sf/RULE_PATTERNS.rst
+27
View File
@@ -0,0 +1,27 @@
<RULE>_PATTERNS
---------------
.. versionadded:: 4.5
Patterns specification for instantiating the rule ``<RULE>``.
The ``<RULE>_PATTERNS`` property may be set to a
:ref:`semicolon-separated list <CMake Language Lists>` of patterns using the
syntax ``PATTERN=VALUE`` or ``PATTERN=``. More precisely, each item must match
the regular expression ``(^[A-Z][A-Z0-9_]+)=(.*)$``.
CMake will automatically drop any patterns which do not match against this
regular expression.
The list is ordered, so a pattern can use in its definition a previously
defined pattern. In the following example,
``OUTPUT_DIR=/some/path;OUTPUT_FILE=<OUTPUT_DIR>/my_file``, when the pattern
``<OUTPUT_FILE>`` is expanded, the pattern ``<OUTPUT_DIR>`` is already known.
Related properties:
* :prop_fs:`RULE_PATTERNS` to specify patterns for a file set.
Related commands:
* :command:`add_custom_rule` for custom rule specification.
Help/prop_tgt/JOB_POOL_COMPILE.rst
+1
View File
@@ -19,5 +19,6 @@ This property is initialized by the value of
See Also
^^^^^^^^
* :prop_rule:`JOB_POOL_COMPILE` rule property
* :prop_fs:`JOB_POOL_COMPILE` file set property
* :prop_sf:`JOB_POOL_COMPILE` source file property
Help/release/dev/add_custom_rule.rst
+5
View File
@@ -0,0 +1,5 @@
add_custom_rule
---------------
* The :command:`add_custom_rule` command was added to allow the definition of
pattern rules.
Help/release/dev/genex-rule_property.rst
+5
View File
@@ -0,0 +1,5 @@
genex-rule_property
-------------------
* CMake gains the :genex:`RULE_PROPERTY` generator expression to query
properties of rules created by :command:`add_custom_rule` command.