From 785f2b2df1991e8baec39f73afe09acfb88be44f Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 6 Mar 2020 08:39:31 -0500 Subject: Help: Clarify add_custom_command DEPENDS conversion to file paths In commit f5126badd8 (add_custom_command: convert DEPENDS path arguments to absolute paths, 2019-12-18, v3.17.0-rc1~263^2) we updated the documentation to describe the behavior introduced by that commit. However, the behavior was removed again by commit fd0ba705ce (add_custom_command: check if a relative path should be an in-source path, 2020-01-09, v3.17.0-rc1~141^2~4) without updating the documentation. Update the documentation again to describe the behavior as of the latter commit. Spell out the steps that `cmLocalGenerator::GetRealDependency` and `cmTargetTraceDependencies::IsUtility` use to add file-level and target-level dependencies. --- Help/command/add_custom_command.rst | 44 +++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 14 deletions(-) diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 576ed5b..69d6e9a 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -112,26 +112,42 @@ The options are: build time. ``DEPENDS`` - Specify files on which the command depends. Entries in the ``DEPENDS`` - argument list which may also be target names are assumed to be target names, - so only entries which contain a path separator are detected as file paths. + Specify files on which the command depends. Each argument is converted + to a dependency as follows: + + 1. If the argument is the name of a 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. + + 2. If the argument is an absolute path, a file-level dependency + is created on that path. + + 3. If the argument is the name of a source file that has been + added to a target or on which a source file property has been set, + a file-level dependency is created on that source file. + + 4. If the argument is a relative path and it exists in the current + source directory, a file-level dependency is created on that + file in the current source directory. + + 5. Otherwise, a file-level dependency is created on that path relative + to the current binary directory. + If any dependency is an ``OUTPUT`` of another custom command in the same - directory (``CMakeLists.txt`` file) CMake automatically brings the other + directory (``CMakeLists.txt`` file), CMake automatically brings the other custom command into the target in which this command is built. A target-level dependency is added if any dependency is listed as ``BYPRODUCTS`` of a target or any of its build events in the same directory to ensure the byproducts will be available. - If ``DEPENDS`` is not specified the command will run whenever + + 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. + create the ``OUTPUT``, the rule will always run. Arguments to ``DEPENDS`` may use :manual:`generator expressions `. -- cgit v0.12