add_compile_definitions: add new command

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

Fixes: #15374

4 files changed, 36 insertions, 5 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.