Help: Revise and format 'add_custom_command' docs
Format the reStructuredText markup manually. Organize the command options into a definition list. Use inline markup to cross-reference related documents.
This commit is contained in:
Brad King
parent
cb88742da4
commit
2a58c872d7
|
|
@ -3,10 +3,12 @@ add_custom_command
|
||||||
|
|
||||||
Add a custom build rule to the generated build system.
|
Add a custom build rule to the generated build system.
|
||||||
|
|
||||||
There are two main signatures for add_custom_command The first
|
There are two main signatures for ``add_custom_command``.
|
||||||
signature is for adding a custom command to produce an output.
|
|
||||||
|
|
||||||
::
|
Generating Files
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The first signature is for adding a custom command to produce an output::
|
||||||
|
|
||||||
add_custom_command(OUTPUT output1 [output2 ...]
|
add_custom_command(OUTPUT output1 [output2 ...]
|
||||||
COMMAND command1 [ARGS] [args1...]
|
COMMAND command1 [ARGS] [args1...]
|
||||||
|
|
@ -18,28 +20,117 @@ signature is for adding a custom command to produce an output.
|
||||||
[WORKING_DIRECTORY dir]
|
[WORKING_DIRECTORY dir]
|
||||||
[COMMENT comment] [VERBATIM] [APPEND])
|
[COMMENT comment] [VERBATIM] [APPEND])
|
||||||
|
|
||||||
This defines a command to generate specified OUTPUT file(s). A target
|
This defines a command to generate specified ``OUTPUT`` file(s).
|
||||||
created in the same directory (CMakeLists.txt file) that specifies any
|
A target created in the same directory (``CMakeLists.txt`` file)
|
||||||
output of the custom command as a source file is given a rule to
|
that specifies any output of the custom command as a source file
|
||||||
generate the file using the command at build time. Do not list the
|
is given a rule to generate the file using the command at build time.
|
||||||
output in more than one independent target that may build in parallel
|
Do not list the output in more than one independent target that
|
||||||
or the two instances of the rule may conflict (instead use
|
may build in parallel or the two instances of the rule may conflict
|
||||||
add_custom_target to drive the command and make the other targets
|
(instead use the :command:`add_custom_target` command to drive the
|
||||||
depend on that one). If an output name is a relative path it will be
|
command and make the other targets depend on that one).
|
||||||
interpreted relative to the build tree directory corresponding to the
|
In makefile terms this creates a new target in the following form::
|
||||||
current source directory. Note that MAIN_DEPENDENCY is completely
|
|
||||||
optional and is used as a suggestion to visual studio about where to
|
|
||||||
hang the custom command. In makefile terms this creates a new target
|
|
||||||
in the following form:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
OUTPUT: MAIN_DEPENDENCY DEPENDS
|
OUTPUT: MAIN_DEPENDENCY DEPENDS
|
||||||
COMMAND
|
COMMAND
|
||||||
|
|
||||||
If more than one command is specified they will be executed in order.
|
The options are:
|
||||||
The optional ARGS argument is for backward compatibility and will be
|
|
||||||
ignored.
|
``APPEND``
|
||||||
|
Append the ``COMMAND`` and ``DEPENDS`` option values to the custom
|
||||||
|
command for the first output specified. There must have already
|
||||||
|
been a previous call to this command with the same output.
|
||||||
|
The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY``
|
||||||
|
options are currently ignored when APPEND is given, but may be
|
||||||
|
used in the future.
|
||||||
|
|
||||||
|
``COMMAND``
|
||||||
|
Specify the command-line(s) to execute at build time.
|
||||||
|
If more than one command is specified they will be executed in order.
|
||||||
|
The optional ``ARGS`` argument is for backward compatibility and
|
||||||
|
will be ignored.
|
||||||
|
|
||||||
|
If ``COMMAND`` specifies an executable target (created by the
|
||||||
|
:command:`add_executable` command) it will automatically be replaced
|
||||||
|
by the location of the executable created at build time.
|
||||||
|
Additionally a target-level dependency will be added so that the
|
||||||
|
executable target will be built before any target using this custom
|
||||||
|
command. However this does NOT add a file-level dependency that
|
||||||
|
would cause the custom command to re-run whenever the executable is
|
||||||
|
recompiled.
|
||||||
|
|
||||||
|
Arguments to ``COMMAND`` may use
|
||||||
|
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||||
|
References to target names in generator expressions imply target-level
|
||||||
|
dependencies, but NOT file-level dependencies. List target names with
|
||||||
|
the ``DEPENDS`` option to add file-level dependencies.
|
||||||
|
|
||||||
|
``COMMENT``
|
||||||
|
Display the given message before the commands are executed at
|
||||||
|
build time.
|
||||||
|
|
||||||
|
``DEPENDS``
|
||||||
|
Specify files on which the command depends. If any dependency is
|
||||||
|
an ``OUTPUT`` of another custom command in the same directory
|
||||||
|
(``CMakeLists.txt`` file) CMake automatically brings the other
|
||||||
|
custom command into the target in which this command is built.
|
||||||
|
If ``DEPENDS`` is not specified the command will run whenever
|
||||||
|
the ``OUTPUT`` is missing; if the command does not actually
|
||||||
|
create the ``OUTPUT`` then the rule will always run.
|
||||||
|
If ``DEPENDS`` specifies any target (created by the
|
||||||
|
:command:`add_custom_target`, :command:`add_executable`, or
|
||||||
|
:command:`add_library` command) a target-level dependency is
|
||||||
|
created to make sure the target is built before any target
|
||||||
|
using this custom command. Additionally, if the target is an
|
||||||
|
executable or library a file-level dependency is created to
|
||||||
|
cause the custom command to re-run whenever the target is
|
||||||
|
recompiled.
|
||||||
|
|
||||||
|
Arguments to ``DEPENDS`` may use
|
||||||
|
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||||
|
|
||||||
|
``IMPLICIT_DEPENDS``
|
||||||
|
Request scanning of implicit dependencies of an input file.
|
||||||
|
The language given specifies the programming language whose
|
||||||
|
corresponding dependency scanner should be used.
|
||||||
|
Currently only ``C`` and ``CXX`` language scanners are supported.
|
||||||
|
The language has to be specified for every file in the
|
||||||
|
``IMPLICIT_DEPENDS`` list. Dependencies discovered from the
|
||||||
|
scanning are added to those of the custom command at build time.
|
||||||
|
Note that the ``IMPLICIT_DEPENDS`` option is currently supported
|
||||||
|
only for Makefile generators and will be ignored by other generators.
|
||||||
|
|
||||||
|
``MAIN_DEPENDENCY``
|
||||||
|
Specify the primary input source file to the command. This is
|
||||||
|
treated just like any value given to the ``DEPENDS`` option
|
||||||
|
but also suggests to Visual Studio generators where to hang
|
||||||
|
the custom command.
|
||||||
|
|
||||||
|
``OUTPUT``
|
||||||
|
Specify the output files the command is expected to produce.
|
||||||
|
If an output name is a relative path it will be interpreted
|
||||||
|
relative to the build tree directory corresponding to the
|
||||||
|
current source directory.
|
||||||
|
If the output of the custom command is not actually created
|
||||||
|
as a file on disk it should be marked with the :prop_sf:`SYMBOLIC`
|
||||||
|
source file property.
|
||||||
|
|
||||||
|
``VERBATIM``
|
||||||
|
All arguments to the commands 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 add_custom_command even sees the
|
||||||
|
arguments. Use of ``VERBATIM`` 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.
|
||||||
|
|
||||||
|
``WORKING_DIRECTORY``
|
||||||
|
Execute the command 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.
|
||||||
|
|
||||||
|
Build Events
|
||||||
|
^^^^^^^^^^^^
|
||||||
|
|
||||||
The second signature adds a custom command to a target such as a
|
The second signature adds a custom command to a target such as a
|
||||||
library or executable. This is useful for performing an operation
|
library or executable. This is useful for performing an operation
|
||||||
|
|
@ -60,79 +151,13 @@ This defines a new command that will be associated with building the
|
||||||
specified target. When the command will happen is determined by which
|
specified target. When the command will happen is determined by which
|
||||||
of the following is specified:
|
of the following is specified:
|
||||||
|
|
||||||
::
|
``PRE_BUILD``
|
||||||
|
Run before any other rules are executed within the target.
|
||||||
PRE_BUILD - run before all other dependencies
|
This is supported only on Visual Studio 7 or later.
|
||||||
PRE_LINK - run after other dependencies
|
For all other generators ``PRE_BUILD`` will be treated as
|
||||||
POST_BUILD - run after the target has been built
|
``PRE_LINK``.
|
||||||
|
``PRE_LINK``
|
||||||
Note that the PRE_BUILD option is only supported on Visual Studio 7 or
|
Run after sources have been compiled but before linking the binary
|
||||||
later. For all other generators PRE_BUILD will be treated as
|
or running the librarian or archiver tool of a static library.
|
||||||
PRE_LINK.
|
``POST_BUILD``
|
||||||
|
Run after all other rules within the target have been executed.
|
||||||
If WORKING_DIRECTORY is specified the command will be executed in the
|
|
||||||
directory given. If it is a relative path it will be interpreted
|
|
||||||
relative to the build tree directory corresponding to the current
|
|
||||||
source directory. If COMMENT is set, the value will be displayed as a
|
|
||||||
message before the commands are executed at build time. If APPEND is
|
|
||||||
specified the COMMAND and DEPENDS option values are appended to the
|
|
||||||
custom command for the first output specified. There must have
|
|
||||||
already been a previous call to this command with the same output.
|
|
||||||
The COMMENT, WORKING_DIRECTORY, and MAIN_DEPENDENCY options are
|
|
||||||
currently ignored when APPEND is given, but may be used in the future.
|
|
||||||
|
|
||||||
If VERBATIM is given then all arguments to the commands 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 add_custom_command
|
|
||||||
even sees the arguments. Use of VERBATIM 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.
|
|
||||||
|
|
||||||
If the output of the custom command is not actually created as a file
|
|
||||||
on disk it should be marked as SYMBOLIC with
|
|
||||||
SET_SOURCE_FILES_PROPERTIES.
|
|
||||||
|
|
||||||
The IMPLICIT_DEPENDS option requests scanning of implicit dependencies
|
|
||||||
of an input file. The language given specifies the programming
|
|
||||||
language whose corresponding dependency scanner should be used.
|
|
||||||
Currently only C and CXX language scanners are supported. The
|
|
||||||
language has to be specified for every file in the IMPLICIT_DEPENDS
|
|
||||||
list. Dependencies discovered from the scanning are added to those of
|
|
||||||
the custom command at build time. Note that the IMPLICIT_DEPENDS
|
|
||||||
option is currently supported only for Makefile generators and will be
|
|
||||||
ignored by other generators.
|
|
||||||
|
|
||||||
If COMMAND specifies an executable target (created by ADD_EXECUTABLE)
|
|
||||||
it will automatically be replaced by the location of the executable
|
|
||||||
created at build time. Additionally a target-level dependency will be
|
|
||||||
added so that the executable target will be built before any target
|
|
||||||
using this custom command. However this does NOT add a file-level
|
|
||||||
dependency that would cause the custom command to re-run whenever the
|
|
||||||
executable is recompiled.
|
|
||||||
|
|
||||||
Arguments to COMMAND may use "generator expressions" with the syntax
|
|
||||||
``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for
|
|
||||||
available expressions.
|
|
||||||
|
|
||||||
References to target names in generator expressions imply target-level
|
|
||||||
dependencies, but NOT file-level dependencies. List target names with
|
|
||||||
the DEPENDS option to add file dependencies.
|
|
||||||
|
|
||||||
The DEPENDS option specifies files on which the command depends. If
|
|
||||||
any dependency is an OUTPUT of another custom command in the same
|
|
||||||
directory (CMakeLists.txt file) CMake automatically brings the other
|
|
||||||
custom command into the target in which this command is built. If
|
|
||||||
DEPENDS is not specified the command will run whenever the OUTPUT is
|
|
||||||
missing; if the command does not actually create the OUTPUT then the
|
|
||||||
rule will always run. If DEPENDS specifies any target (created by an
|
|
||||||
ADD_* command) a target-level dependency is created to make sure the
|
|
||||||
target is built before any target using this custom command.
|
|
||||||
Additionally, if the target is an executable or library a file-level
|
|
||||||
dependency is created to cause the custom command to re-run whenever
|
|
||||||
the target is recompiled.
|
|
||||||
|
|
||||||
Arguments to ``DEPENDS`` may use "generator expressions" with the syntax
|
|
||||||
``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for
|
|
||||||
available expressions.
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue