reactos/CMake
1
0
Fork 0
mirror of https://github.com/reactos/CMake.git synced 2025-02-12 06:51:00 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Help: Clarify add_custom_command DEPENDS conversion to file paths

Browse Source 
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.
This commit is contained in:
Brad King 2020-03-06 08:39:31 -05:00
parent d1cb554c99
commit 785f2b2df1
1 changed files with 30 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
Help/command/add_custom_command.rst
View File

@ -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 <cmake-generator-expressions(7)>`.