MSVC: Add properties to configure compiler PDB files (#14762)

Since commit v2.8.12~437^2~2 (VS: Separate compiler and linker PDB files
2013-04-05) we no longer set /Fd with the PDB_NAME or PDB_OUTPUT_DIRECTORY
properties.  Those properties now exclusively handle linker PDB files.
Since STATIC libraries do not link their compiler PDB file becomes more
important.  Add new target properties "COMPILE_PDB_NAME[_<CONFIG>]" and
"COMPILE_PDB_OUTPUT_DIRECTORY[_<CONFIG>]" to specify the compiler PDB
file location and pass the value to the MSVC /Fd option.

15 files changed, 98 insertions, 1 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 333c865..479dec3 100644
--- a/Help/prop_tgt/PDB_NAME.rst
+++ b/Help/prop_tgt/PDB_NAME.rst
@@ -7,4 +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
diff --git a/Help/prop_tgt/PDB_NAME_CONFIG.rst b/Help/prop_tgt/PDB_NAME_CONFIG.rst
index 7bf9e43..cb3121c 100644
--- a/Help/prop_tgt/PDB_NAME_CONFIG.rst
+++ b/Help/prop_tgt/PDB_NAME_CONFIG.rst
@@ -6,4 +6,5 @@ generated by the linker for an executable or shared library target.
 
 This is the configuration-specific version of :prop_tgt:`PDB_NAME`.
 
+.. |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 c03bd3a..f90ea81 100644
--- a/Help/prop_tgt/PDB_NOTE.txt
+++ b/Help/prop_tgt/PDB_NOTE.txt
@@ -6,7 +6,7 @@
  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.
- This property does not influence the latter.
+ 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 4877368..730cf57 100644
--- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst
+++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst
@@ -9,4 +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
diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst
index 7bbc237..6037fa0 100644
--- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst
+++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst
@@ -11,4 +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.
 
+.. |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.