mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-06 05:40:54 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Clarify how target names are handled in custom commands/targets

Browse Source 
Fixes: #19771
This commit is contained in:
Craig Scott
2019-10-05 23:11:14 +10:00
parent 3da9733142
commit c6f08a2125
2 changed files with 45 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
Help/command/add_custom_command.rst
View File

@@ -79,25 +79,33 @@ The options are:
will be ignored.
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.
(Use the ``TARGET_FILE``
:manual:`generator expression <cmake-generator-expressions(7)>` to
reference an executable later in the command line.)
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.
: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, but NOT file-level dependencies. List target names with
the ``DEPENDS`` option to add file-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 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. List target names with
the ``DEPENDS`` option to add such file-level dependencies.
``COMMENT``
Display the given message before the commands are executed at

30
Help/command/add_custom_target.rst
View File

@@ -58,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.