diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/add_custom_command.rst | 23 | ||||
| -rw-r--r-- | Help/command/add_custom_target.rst | 13 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 30 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -rw-r--r-- | Help/policy/CMP0112.rst | 39 | ||||
| -rw-r--r-- | Help/release/dev/relax-target-generator-expression-dependency-addition.rst | 17 | ||||
| -rw-r--r-- | Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst | 2 |
7 files changed, 114 insertions, 11 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 9279748..231f9da 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -102,13 +102,22 @@ The options are: 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. + Whenever one of the following target based generator expressions are used as + a command to execute or is mentioned in 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 + (see policy :policy:`CMP0112`). + + * ``TARGET_FILE`` + * ``TARGET_LINKER_FILE`` + * ``TARGET_SONAME_FILE`` + * ``TARGET_PDB_FILE`` + + This target-level dependency 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 56ab414..2eb0c88 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -81,10 +81,15 @@ The options are: 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. + Whenever one of the following target based generator expressions are used as + a command to execute or is mentioned in a command argument, a target-level + dependency will be added automatically so that the mentioned target will be + built before this custom target (see policy :policy:`CMP0112`). + + * ``TARGET_FILE`` + * ``TARGET_LINKER_FILE`` + * ``TARGET_SONAME_FILE`` + * ``TARGET_PDB_FILE`` The command and arguments are optional and if not specified an empty target will be created. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index c7f6b27..5b55cac 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -596,6 +596,9 @@ which is just the string ``tgt``. ``$<TARGET_NAME_IF_EXISTS:tgt>`` The target name ``tgt`` if the target exists, an empty string otherwise. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_FILE:tgt>`` Full path to the ``tgt`` binary file. ``$<TARGET_FILE_BASE_NAME:tgt>`` @@ -633,6 +636,9 @@ which is just the string ``tgt``. The ``tgt`` filename. ``$<TARGET_FILE_DIR:tgt>`` Directory of the ``tgt`` binary file. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_LINKER_FILE:tgt>`` File used when linking to the ``tgt`` target. This will usually be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``), @@ -674,14 +680,26 @@ which is just the string ``tgt``. expression is evaluated on. ``$<TARGET_LINKER_FILE_NAME:tgt>`` Name of file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_LINKER_FILE_DIR:tgt>`` Directory of file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_SONAME_FILE:tgt>`` File with soname (``.so.3``) where ``tgt`` is the name of a target. ``$<TARGET_SONAME_FILE_NAME:tgt>`` Name of file with soname (``.so.3``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_SONAME_FILE_DIR:tgt>`` Directory of with soname (``.so.3``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_PDB_FILE:tgt>`` Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -707,17 +725,29 @@ which is just the string ``tgt``. expression is evaluated on. ``$<TARGET_PDB_FILE_NAME:tgt>`` Name of the linker generated program database file (.pdb). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_PDB_FILE_DIR:tgt>`` Directory of the linker generated program database file (.pdb). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_BUNDLE_DIR:tgt>`` Full path to the bundle directory (``my.app``, ``my.framework``, or ``my.bundle``) where ``tgt`` is the name of a target. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` Full path to the bundle content directory where ``tgt`` is the name of a target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to ``my.app``, ``my.framework``, or ``my.bundle`` due to the flat bundle structure. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_PROPERTY:tgt,prop>`` Value of the property ``prop`` on the target ``tgt``. diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index ce8969b..cd1d4d3 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -57,6 +57,7 @@ Policies Introduced by CMake 3.19 .. toctree:: :maxdepth: 1 + CMP0112: Target file component generator expressions do not add target dependencies. </policy/CMP0112> CMP0111: An imported target with a missing location fails during generation. </policy/CMP0111> CMP0110: add_test() supports arbitrary characters in test names. </policy/CMP0110> CMP0109: find_program() requires permission to execute but not to read. </policy/CMP0109> diff --git a/Help/policy/CMP0112.rst b/Help/policy/CMP0112.rst new file mode 100644 index 0000000..3eab6d2 --- /dev/null +++ b/Help/policy/CMP0112.rst @@ -0,0 +1,39 @@ +CMP0112 +------- + +.. versionadded:: 3.19 + +Target file component generator expressions do not add target dependencies. + +The following target-based generator expressions that query for directory or +file name components no longer add a dependency on the evaluated target. + + - ``TARGET_FILE_DIR`` + - ``TARGET_LINKER_FILE_BASE_NAME`` + - ``TARGET_LINKER_FILE_NAME`` + - ``TARGET_LINKER_FILE_DIR`` + - ``TARGET_SONAME_FILE_NAME`` + - ``TARGET_SONAME_FILE_DIR`` + - ``TARGET_PDB_FILE_NAME`` + - ``TARGET_PDB_FILE_DIR`` + - ``TARGET_BUNDLE_DIR`` + - ``TARGET_BUNDLE_CONTENT_DIR`` + + +In CMake 3.18 and lower a dependency on the evaluated target of the above +generator expressions would be always added. CMake 3.19 and above prefer +to not add this dependency. This policy provides compatibility for projects +that have not been updated to expect the new behavior. + +The ``OLD`` behavior for this policy is to add a dependency on the evaluated +target for the the above generator expressions. The ``NEW`` behavior of +this policy is to not add a dependency on the evaluated target for the the +above generator expressions. + +This policy was introduced in CMake version 3.19. Unlike many policies, +CMake version |release| does *not* warn by default when this policy +is not set and simply uses ``OLD`` behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0112 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/release/dev/relax-target-generator-expression-dependency-addition.rst b/Help/release/dev/relax-target-generator-expression-dependency-addition.rst new file mode 100644 index 0000000..6d30596 --- /dev/null +++ b/Help/release/dev/relax-target-generator-expression-dependency-addition.rst @@ -0,0 +1,17 @@ +relax-target-generator-expression-dependency-addition +----------------------------------------------------- + +* The following target-based generator expressions that query for directory or + file name components no longer add a dependency on the evaluated target. + See policy :policy:`CMP0112`. + + - ``TARGET_FILE_DIR`` + - ``TARGET_LINKER_FILE_BASE_NAME`` + - ``TARGET_LINKER_FILE_NAME`` + - ``TARGET_LINKER_FILE_DIR`` + - ``TARGET_SONAME_FILE_NAME`` + - ``TARGET_SONAME_FILE_DIR`` + - ``TARGET_PDB_FILE_NAME`` + - ``TARGET_PDB_FILE_DIR`` + - ``TARGET_BUNDLE_DIR`` + - ``TARGET_BUNDLE_CONTENT_DIR`` diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index de71d0e..d35595a 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -25,6 +25,8 @@ warn by default: policy :policy:`CMP0089`. * ``CMAKE_POLICY_WARNING_CMP0102`` controls the warning for policy :policy:`CMP0102`. +* ``CMAKE_POLICY_WARNING_CMP0112`` controls the warning for + policy :policy:`CMP0112`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to |