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.
|
||||
|
||||
There are two main signatures for add_custom_command The first
|
||||
signature is for adding a custom command to produce an output.
|
||||
There are two main signatures for ``add_custom_command``.
|
||||
|
||||
::
|
||||
Generating Files
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
The first signature is for adding a custom command to produce an output::
|
||||
|
||||
add_custom_command(OUTPUT output1 [output2 ...]
|
||||
COMMAND command1 [ARGS] [args1...]
|
||||
|
|
@ -18,28 +20,117 @@ signature is for adding a custom command to produce an output.
|
|||
[WORKING_DIRECTORY dir]
|
||||
[COMMENT comment] [VERBATIM] [APPEND])
|
||||
|
||||
This defines a command to generate specified OUTPUT file(s). A target
|
||||
created in the same directory (CMakeLists.txt file) that specifies any
|
||||
output of the custom command as a source file is given a rule to
|
||||
generate the file using the command at build time. Do not list the
|
||||
output in more than one independent target that may build in parallel
|
||||
or the two instances of the rule may conflict (instead use
|
||||
add_custom_target to drive the command and make the other targets
|
||||
depend on that one). If an output name is a relative path it will be
|
||||
interpreted relative to the build tree directory corresponding to the
|
||||
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:
|
||||
|
||||
::
|
||||
This defines a command to generate specified ``OUTPUT`` file(s).
|
||||
A target created in the same directory (``CMakeLists.txt`` file)
|
||||
that specifies any output of the custom command as a source file
|
||||
is given a rule to generate the file using the command at build time.
|
||||
Do not list the output in more than one independent target that
|
||||
may build in parallel or the two instances of the rule may conflict
|
||||
(instead use the :command:`add_custom_target` command to drive the
|
||||
command and make the other targets depend on that one).
|
||||
In makefile terms this creates a new target in the following form::
|
||||
|
||||
OUTPUT: MAIN_DEPENDENCY DEPENDS
|
||||
COMMAND
|
||||
|
||||
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.
|
||||
The options are:
|
||||
|
||||
``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
|
||||
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
|
||||
of the following is specified:
|
||||
|
||||
::
|
||||
|
||||
PRE_BUILD - run before all other dependencies
|
||||
PRE_LINK - run after other dependencies
|
||||
POST_BUILD - run after the target has been built
|
||||
|
||||
Note that the PRE_BUILD option is only supported on Visual Studio 7 or
|
||||
later. For all other generators PRE_BUILD will be treated as
|
||||
PRE_LINK.
|
||||
|
||||
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.
|
||||
``PRE_BUILD``
|
||||
Run before any other rules are executed within the target.
|
||||
This is supported only on Visual Studio 7 or later.
|
||||
For all other generators ``PRE_BUILD`` will be treated as
|
||||
``PRE_LINK``.
|
||||
``PRE_LINK``
|
||||
Run after sources have been compiled but before linking the binary
|
||||
or running the librarian or archiver tool of a static library.
|
||||
``POST_BUILD``
|
||||
Run after all other rules within the target have been executed.
|
||||
|
|
|
|||
Loading…
Reference in New Issue