From c6f08a2125d98a22ae08f6ac8f39095bda09b490 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sat, 5 Oct 2019 23:11:14 +1000 Subject: Help: Clarify how target names are handled in custom commands/targets Fixes: #19771 --- Help/command/add_custom_command.rst | 40 ++++++++++++++++++++++--------------- Help/command/add_custom_target.rst | 30 +++++++++++++++++++--------- 2 files changed, 45 insertions(+), 25 deletions(-) diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index ab2a023..df7cc4e 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -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 ` 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 `. - 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 diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index e74960c..2d5f5f0 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -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 `. - 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. -- cgit v0.12