Merge topic 'msvc-compiler-pdb-files'

fba51b09 MSVC: Add properties to configure compiler PDB files (#14762)
3737860a cmTarget: Add per-config compilation info
718a9532 cmTarget: Refactor ComputePDBOutputDir interface
aae5184c Help: Refactor PDB_NAME and PDB_OUTPUT_DIRECTORY docs
b4aac0ca Makefile: Fix per-config linker PDB output directory

15 files changed, 106 insertions, 13 deletions

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index d315fcb..6ea5839 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -100,6 +100,10 @@ Properties on Targets
    /prop_tgt/COMPILE_DEFINITIONS
    /prop_tgt/COMPILE_FLAGS
    /prop_tgt/COMPILE_OPTIONS
+   /prop_tgt/COMPILE_PDB_NAME
+   /prop_tgt/COMPILE_PDB_NAME_CONFIG
+   /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY
+   /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG
    /prop_tgt/CONFIG_OUTPUT_NAME
    /prop_tgt/CONFIG_POSTFIX
    /prop_tgt/DEBUG_POSTFIX
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index c4ae193..5f2ba28 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -198,6 +198,8 @@ Variables that Control the Build
    /variable/CMAKE_AUTOUIC
    /variable/CMAKE_AUTOUIC_OPTIONS
    /variable/CMAKE_BUILD_WITH_INSTALL_RPATH
+   /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
+   /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG
    /variable/CMAKE_CONFIG_POSTFIX
    /variable/CMAKE_DEBUG_POSTFIX
    /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG
diff --git a/Help/prop_tgt/COMPILE_PDB_NAME.rst b/Help/prop_tgt/COMPILE_PDB_NAME.rst
new file mode 100644
index 0000000..24a9f62
--- /dev/null
+++ b/Help/prop_tgt/COMPILE_PDB_NAME.rst
@@ -0,0 +1,11 @@
+COMPILE_PDB_NAME
+----------------
+
+Output name for the MS debug symbol ``.pdb`` file generated by the
+compiler while building source files.
+
+This property specifies the base name for the debug symbols file.
+If not set, the default is unspecified.
+
+.. |PDB_XXX| replace:: :prop_tgt:`PDB_NAME`
+.. include:: COMPILE_PDB_NOTE.txt
diff --git a/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst b/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst
new file mode 100644
index 0000000..e4077f5
--- /dev/null
+++ b/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst
@@ -0,0 +1,10 @@
+COMPILE_PDB_NAME_<CONFIG>
+-------------------------
+
+Per-configuration output name for the MS debug symbol ``.pdb`` file
+generated by the compiler while building source files.
+
+This is the configuration-specific version of :prop_tgt:`COMPILE_PDB_NAME`.
+
+.. |PDB_XXX| replace:: :prop_tgt:`PDB_NAME_<CONFIG>`
+.. include:: COMPILE_PDB_NOTE.txt
diff --git a/Help/prop_tgt/COMPILE_PDB_NOTE.txt b/Help/prop_tgt/COMPILE_PDB_NOTE.txt
new file mode 100644
index 0000000..5941d72
--- /dev/null
+++ b/Help/prop_tgt/COMPILE_PDB_NOTE.txt
@@ -0,0 +1,8 @@
+.. note::
+ The compiler-generated program database files are specified by the
+ ``/Fd`` compiler flag and are not the same as linker-generated
+ program database files specified by the ``/pdb`` linker flag.
+ Use the |PDB_XXX| property to specify the latter.
+
+ This property is not implemented by the :generator:`Visual Studio 6`
+ generator.
diff --git a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst
new file mode 100644
index 0000000..34f49be
--- /dev/null
+++ b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst
@@ -0,0 +1,13 @@
+COMPILE_PDB_OUTPUT_DIRECTORY
+----------------------------
+
+Output directory for the MS debug symbol ``.pdb`` file
+generated by the compiler while building source files.
+
+This property specifies the directory into which the MS debug symbols
+will be placed by the compiler.  This property is initialized by the
+value of the :variable:`CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY` variable
+if it is set when a target is created.
+
+.. |PDB_XXX| replace:: :prop_tgt:`PDB_OUTPUT_DIRECTORY`
+.. include:: COMPILE_PDB_NOTE.txt
diff --git a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst
new file mode 100644
index 0000000..52ef013
--- /dev/null
+++ b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst
@@ -0,0 +1,16 @@
+COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>
+-------------------------------------
+
+Per-configuration output directory for the MS debug symbol ``.pdb`` file
+generated by the compiler while building source files.
+
+This is a per-configuration version of
+:prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY`,
+but multi-configuration generators (VS, Xcode) do NOT append a
+per-configuration subdirectory to the specified directory.  This
+property is initialized by the value of the
+:variable:`CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>` variable
+if it is set when a target is created.
+
+.. |PDB_XXX| replace:: :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`
+.. include:: COMPILE_PDB_NOTE.txt
diff --git a/Help/prop_tgt/PDB_NAME.rst b/Help/prop_tgt/PDB_NAME.rst
index e8fc3be..479dec3 100644
--- a/Help/prop_tgt/PDB_NAME.rst
+++ b/Help/prop_tgt/PDB_NAME.rst
@@ -7,7 +7,5 @@ linker for an executable or shared library target.
 This property specifies the base name for the debug symbols file.
 If not set, the logical target name is used by default.
 
+.. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_NAME`
 .. include:: PDB_NOTE.txt
-
-This property is not implemented by the :generator:`Visual Studio 6`
-generator.
diff --git a/Help/prop_tgt/PDB_NAME_CONFIG.rst b/Help/prop_tgt/PDB_NAME_CONFIG.rst
index c846b57..cb3121c 100644
--- a/Help/prop_tgt/PDB_NAME_CONFIG.rst
+++ b/Help/prop_tgt/PDB_NAME_CONFIG.rst
@@ -6,5 +6,5 @@ generated by the linker for an executable or shared library target.
 
 This is the configuration-specific version of :prop_tgt:`PDB_NAME`.
 
-This property is not implemented by the :generator:`Visual Studio 6`
-generator.
+.. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_NAME_<CONFIG>`
+.. include:: PDB_NOTE.txt
diff --git a/Help/prop_tgt/PDB_NOTE.txt b/Help/prop_tgt/PDB_NOTE.txt
index e55aba2..f90ea81 100644
--- a/Help/prop_tgt/PDB_NOTE.txt
+++ b/Help/prop_tgt/PDB_NOTE.txt
@@ -3,6 +3,10 @@
  is invoked to produce them so they have no linker-generated ``.pdb`` file
  containing debug symbols.
 
- The compiler-generated program database files specified by the MSVC
- ``/Fd`` flag are not the same as linker-generated program database
- files and so are not influenced by this property.
+ The linker-generated program database files are specified by the
+ ``/pdb`` linker flag and are not the same as compiler-generated
+ program database files specified by the ``/Fd`` compiler flag.
+ Use the |COMPILE_PDB_XXX| property to specify the latter.
+
+ This property is not implemented by the :generator:`Visual Studio 6`
+ generator.
diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst
index 9a863a1..730cf57 100644
--- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst
+++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst
@@ -9,7 +9,5 @@ will be placed by the linker.  This property is initialized by the
 value of the :variable:`CMAKE_PDB_OUTPUT_DIRECTORY` variable if it is
 set when a target is created.
 
+.. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY`
 .. include:: PDB_NOTE.txt
-
-This property is not implemented by the :generator:`Visual Studio 6`
-generator.
diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst
index caec2de..6037fa0 100644
--- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst
+++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst
@@ -11,5 +11,5 @@ property is initialized by the value of the
 :variable:`CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>` variable if it is
 set when a target is created.
 
-This property is not implemented by the :generator:`Visual Studio 6`
-generator.
+.. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>`
+.. include:: PDB_NOTE.txt
diff --git a/Help/release/dev/msvc-compiler-pdb-files.rst b/Help/release/dev/msvc-compiler-pdb-files.rst
new file mode 100644
index 0000000..d06d202
--- /dev/null
+++ b/Help/release/dev/msvc-compiler-pdb-files.rst
@@ -0,0 +1,10 @@
+msvc-compiler-pdb-files
+-----------------------
+
+* New :prop_tgt:`COMPILE_PDB_NAME` and
+  :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` target properties
+  were introduced to specify the MSVC compiler program database
+  file location (``cl /Fd``).  This complements the existing
+  :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY`
+  target properties that specify the linker program database
+  file location (``link /pdb``).
diff --git a/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst
new file mode 100644
index 0000000..ea33c7d
--- /dev/null
+++ b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst
@@ -0,0 +1,8 @@
+CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
+----------------------------------
+
+Output directory for MS debug symbol ``.pdb`` files
+generated by the compiler while building source files.
+
+This variable is used to initialize the
+:prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` property on all the targets.
diff --git a/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst
new file mode 100644
index 0000000..fdeb9ab
--- /dev/null
+++ b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst
@@ -0,0 +1,11 @@
+CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>
+-------------------------------------------
+
+Per-configuration output directory for MS debug symbol ``.pdb`` files
+generated by the compiler while building source files.
+
+This is a per-configuration version of
+:variable:`CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY`.
+This variable is used to initialize the
+:prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>`
+property on all the targets.