add_compile_definitions: add new command

This command manages preprocessor definitions at directory level and
supports generator expressions.

Fixes: #15374

8 files changed, 44 insertions, 7 deletions

diff --git a/Help/command/add_compile_definitions.rst b/Help/command/add_compile_definitions.rst
new file mode 100644
index 0000000..37f6650
--- /dev/null
+++ b/Help/command/add_compile_definitions.rst
@@ -0,0 +1,23 @@
+add_compile_definitions
+-----------------------
+
+Adds preprocessor definitions to the compilation of source files.
+
+::
+
+  add_compile_definitions(<definition> ...)
+
+Adds preprocessor definitions to the compiler command line for targets in the
+current directory and below that are added after this command is invoked.
+See documentation of the :prop_dir:`directory <COMPILE_DEFINITIONS>` and
+:prop_tgt:`target <COMPILE_DEFINITIONS>` ``COMPILE_DEFINITIONS`` properties.
+
+Definitions are specified using the syntax ``VAR`` or ``VAR=value``.
+Function-style definitions are not supported. CMake will automatically
+escape the value correctly for the native build system (note that CMake
+language syntax may require escapes to specify some values).
+
+Arguments to ``add_compile_definitions`` may use "generator expressions" with
+the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
+manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
+manual for more on defining buildsystem properties.
diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst
index 44924e6..c445608 100644
--- a/Help/command/add_compile_options.rst
+++ b/Help/command/add_compile_options.rst
@@ -14,7 +14,7 @@ See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and
 
 This command can be used to add any options, but alternative commands
 exist to add preprocessor definitions (:command:`target_compile_definitions`
-and :command:`add_definitions`) or include directories
+and :command:`add_compile_definitions`) or include directories
 (:command:`target_include_directories` and :command:`include_directories`).
 
 Arguments to ``add_compile_options`` may use "generator expressions" with
diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst
index a04faf5..1da15a6 100644
--- a/Help/command/add_definitions.rst
+++ b/Help/command/add_definitions.rst
@@ -10,8 +10,16 @@ Adds -D define flags to the compilation of source files.
 Adds definitions to the compiler command line for targets in the current
 directory and below (whether added before or after this command is invoked).
 This command can be used to add any flags, but it is intended to add
-preprocessor definitions (see the :command:`add_compile_options` command
-to add other flags).
+preprocessor definitions.
+
+.. note::
+
+  This command has been superseded by alternatives:
+
+  * Use :command:`add_compile_definitions` to add preprocessor definitions.
+  * Use :command:`include_directories` to add include directories.
+  * Use :command:`add_compile_options` to add other options.
+
 Flags beginning in -D or /D that look like preprocessor definitions are
 automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory
 property for the current directory.  Definitions with non-trivial values
diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst
index b7b4dc1..194d008 100644
--- a/Help/command/target_compile_options.rst
+++ b/Help/command/target_compile_options.rst
@@ -19,8 +19,8 @@ instead of being appended.
 
 This command can be used to add any options, but
 alternative commands exist to add preprocessor definitions
-(:command:`target_compile_definitions` and :command:`add_definitions`) or
-include directories (:command:`target_include_directories` and
+(:command:`target_compile_definitions` and :command:`add_compile_definitions`)
+or include directories (:command:`target_include_directories` and
 :command:`include_directories`).  See documentation of the
 :prop_dir:`directory <COMPILE_OPTIONS>` and
 :prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties.
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index 50c4087..49375e9 100644
--- a/Help/manual/cmake-buildsystem.7.rst
+++ b/Help/manual/cmake-buildsystem.7.rst
@@ -821,7 +821,7 @@ Directory-Scoped Commands
 The :command:`target_include_directories`,
 :command:`target_compile_definitions` and
 :command:`target_compile_options` commands have an effect on only one
-target at a time.  The commands :command:`add_definitions`,
+target at a time.  The commands :command:`add_compile_definitions`,
 :command:`add_compile_options` and :command:`include_directories` have
 a similar function, but operate at directory scope instead of target
 scope for convenience.
diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst
index f8bfb32..408a3a0 100644
--- a/Help/manual/cmake-commands.7.rst
+++ b/Help/manual/cmake-commands.7.rst
@@ -70,6 +70,7 @@ These commands are available only in CMake projects.
 .. toctree::
    :maxdepth: 1
 
+   /command/add_compile_definitions
    /command/add_compile_options
    /command/add_custom_command
    /command/add_custom_target
diff --git a/Help/prop_dir/COMPILE_DEFINITIONS.rst b/Help/prop_dir/COMPILE_DEFINITIONS.rst
index 85adcb5..18f4567 100644
--- a/Help/prop_dir/COMPILE_DEFINITIONS.rst
+++ b/Help/prop_dir/COMPILE_DEFINITIONS.rst
@@ -4,7 +4,7 @@ COMPILE_DEFINITIONS
 Preprocessor definitions for compiling a directory's sources.
 
 This property specifies the list of options given so far to the
-:command:`add_definitions` command.
+:command:`add_compile_definitions` (or :command:`add_definitions`) command.
 
 The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated
 list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``.
diff --git a/Help/release/dev/command-add_compile_definitions.rst b/Help/release/dev/command-add_compile_definitions.rst
new file mode 100644
index 0000000..504481f
--- /dev/null
+++ b/Help/release/dev/command-add_compile_definitions.rst
@@ -0,0 +1,5 @@
+command-add_compile_definitions
+-------------------------------
+
+* The :command:`add_compile_definitions` command was added to set preprocessor
+  definitions at directory level.  This supersedes :command:`add_definitions`.