kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Help: Revise and format 'add_custom_target' 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 2014-11-13 11:52:54 -05:00
parent e7bd9e9b08
commit 66ea634b4c
1 changed files with 62 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
Help/command/add_custom_target.rst
View File

@ -13,33 +13,68 @@ Add a target with no output so it will always be built.
[SOURCES src1 [src2...]])
Adds a target with the given name that executes the given commands.
The target has no output file and is ALWAYS CONSIDERED OUT OF DATE
The target has no output file and is *always considered out of date*
even if the commands try to create a file with the name of the target.
Use ADD_CUSTOM_COMMAND to generate a file with dependencies. By
default nothing depends on the custom target. Use ADD_DEPENDENCIES to
add dependencies to or from other targets. If the ALL option is
specified it indicates that this target should be added to the default
build target so that it will be run every time (the command cannot be
called ALL). The command and arguments are optional and if not
specified an empty target will be created. If WORKING_DIRECTORY is
set, then the command will be run in that directory. 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. Dependencies listed with the DEPENDS
argument may reference files and outputs of custom commands created
with add_custom_command() in the same directory (CMakeLists.txt file).
Use the :command:`add_custom_command` command to generate a file with
dependencies. By default nothing depends on the custom target. Use
the :command:`add_dependencies` command to add dependencies to or
from other targets.
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_target
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.
The options are:
The SOURCES option specifies additional source files to be included in
the custom target. Specified source files will be added to IDE
project files for convenience in editing even if they have not build
rules.
``ALL``
Indicate that this target should be added to the default build
target so that it will be run every time (the command cannot be
called ``ALL``).
``COMMAND``
Specify the command-line(s) to execute at build time.
If more than one ``COMMAND`` is specified they will be executed in order,
but *not* necessarily composed into a stateful shell or batch script.
(To run a full script, use the :command:`configure_file` command or the
:command:`file(GENERATE)` command to create it, and then specify
a ``COMMAND`` to launch it.)
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 this custom target.
Arguments to ``COMMAND`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
References to target names in generator expressions imply target-level
dependencies.
The command and arguments are optional and if not specified an empty
target will be created.
``COMMENT``
Display the given message before the commands are executed at
build time.
``DEPENDS``
Reference files and outputs of custom commands created with
:command:`add_custom_command` command calls in the same directory
(``CMakeLists.txt`` file). They will be brought up to date when
the target is built.
``SOURCES``
Specify additional source files to be included in the custom target.
Specified source files will be added to IDE project files for
convenience in editing even if they have no build rules.
``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_target`` 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.