cmTarget: Deprecate COMPILE_DEFINITIONS_ properties with a policy.

1 files changed, 39 insertions, 0 deletions

diff --git a/Help/policy/CMP0043.rst b/Help/policy/CMP0043.rst
new file mode 100644
index 0000000000..89a6cde34e
--- /dev/null
+++ b/Help/policy/CMP0043.rst
@@ -0,0 +1,39 @@
+CMP0043
+-------
+
+Ignore COMPILE_DEFINITIONS_<Config> properties
+
+CMake 2.8.12 and lower allowed setting the
+:prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property and
+:prop_dir:`COMPILE_DEFINITIONS_<CONFIG>` directory property to apply
+configuration-specific compile definitions.
+
+Since CMake 2.8.10, the :prop_tgt:`COMPILE_DEFINITIONS` property has supported
+:manual:`generator expressions <cmake-generator-expressions(7)>` for setting
+configuration-dependent content.  The continued existence of the suffixed
+variables is redundant, and causes a maintenance burden.  Population of the
+:prop_tgt:`COMPILE_DEFINITIONS_DEBUG <COMPILE_DEFINITIONS_<CONFIG>>` property
+may be replaced with a population of :prop_tgt:`COMPILE_DEFINITIONS` directly
+or via :command:`target_compile_definitions`:
+
+.. code-block:: cmake
+
+  # Old Interface:
+  set_property(TARGET tgt APPEND PROPERTY
+    COMPILE_DEFINITIONS_DEBUG DEBUG_MODE
+  )
+
+  # New Interfaces:
+  set_property(TARGET tgt APPEND PROPERTY
+    COMPILE_DEFINITIONS $<$<CONFIG:Debug>:DEBUG_MODE>
+  )
+  target_compile_definitions(tgt PRIVATE $<$<CONFIG:Debug>:DEBUG_MODE>)
+
+The OLD behavior for this policy is to consume the content of the suffixed
+:prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property when generating the
+compilation command. The NEW behavior for this policy is to ignore the content
+of the :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property .
+
+This policy was introduced in CMake version 3.0.0.  CMake version
+|release| warns when the policy is not set and uses OLD behavior.  Use
+the cmake_policy command to set it to OLD or NEW explicitly.