summaryrefslogtreecommitdiff
path: root/Help/command/add_custom_target.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Help/command/add_custom_target.rst')
-rw-r--r--Help/command/add_custom_target.rst36
1 files changed, 24 insertions, 12 deletions
diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst
index 08b95168b..2d5f5f081 100644
--- a/Help/command/add_custom_target.rst
+++ b/Help/command/add_custom_target.rst
@@ -49,9 +49,6 @@ The options are:
order-only dependencies to ensure the byproducts will be
available before their dependents build.
- The ``BYPRODUCTS`` option is ignored on non-Ninja generators
- except to mark byproducts ``GENERATED``.
-
``COMMAND``
Specify the command-line(s) to execute at build time.
If more than one ``COMMAND`` is specified they will be executed in order,
@@ -61,18 +58,30 @@ The options are:
a ``COMMAND`` to launch it.)
If ``COMMAND`` specifies an executable target name (created by the
- :command:`add_executable` command) it will automatically be replaced
- by the location of the executable created at build time. If set, the
- :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will
- also be prepended to the command to allow the executable to run on
- the host.
- Additionally a target-level dependency will be added so that the
- executable target will be built before this custom target.
+ :command:`add_executable` command), it will automatically be replaced
+ by the location of the executable created at build time if either of
+ the following is true:
+
+ * The target is not being cross-compiled (i.e. the
+ :variable:`CMAKE_CROSSCOMPILING` variable is not set to true).
+ * The target is being cross-compiled and an emulator is provided (i.e.
+ its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
+ In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
+ prepended to the command before the location of the target executable.
+
+ If neither of the above conditions are met, it is assumed that the
+ command name is a program to be found on the ``PATH`` at build time.
Arguments to ``COMMAND`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
- References to target names in generator expressions imply target-level
- dependencies.
+ Use the ``TARGET_FILE`` generator expression to refer to the location of
+ a target later in the command line (i.e. as a command argument rather
+ than as the command to execute).
+
+ Whenever a target is used as a command to execute or is mentioned in a
+ generator expression as a command argument, a target-level dependency
+ will be added automatically so that the mentioned target will be built
+ before this custom target.
The command and arguments are optional and if not specified an empty
target will be created.
@@ -86,6 +95,9 @@ The options are:
: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.
+ A target-level dependency is added if any dependency is a byproduct
+ of a target or any of its build events in the same directory to ensure
+ the byproducts will be available before this target is built.
Use the :command:`add_dependencies` command to add dependencies
on other targets.