From c0897cfad0c8f1c7671ecc8b24bbfd189a9237de Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 2 Dec 2013 11:29:29 -0500 Subject: [PATCH] Help: Document PDB behavior w.r.t. static libraries explicitly (#14600) Document PDB_NAME and PDB_OUTPUT_DIRECTORY as applying only to shared libraries and executables. Add an explicit note to explain why they do not work for static libraries. --- Help/prop_tgt/PDB_NAME.rst | 10 ++++++---- Help/prop_tgt/PDB_NAME_CONFIG.rst | 3 ++- Help/prop_tgt/PDB_NOTE.txt | 8 ++++++++ Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst | 5 ++++- Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst | 3 ++- Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst | 3 ++- Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst | 3 ++- 7 files changed, 26 insertions(+), 9 deletions(-) create mode 100644 Help/prop_tgt/PDB_NOTE.txt diff --git a/Help/prop_tgt/PDB_NAME.rst b/Help/prop_tgt/PDB_NAME.rst index fa3f2ec74..e8fc3be52 100644 --- a/Help/prop_tgt/PDB_NAME.rst +++ b/Help/prop_tgt/PDB_NAME.rst @@ -1,11 +1,13 @@ PDB_NAME -------- -Output name for MS debug symbols ``.pdb`` file from linker. +Output name for the MS debug symbol ``.pdb`` file generated by the +linker for an executable or shared library target. -Set the base name for debug symbols file created for an executable or -shared library target. If not set, the logical target name is used by -default. +This property specifies the base name for the debug symbols file. +If not set, the logical target name is used by default. + +.. 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 571f16d49..c846b57d1 100644 --- a/Help/prop_tgt/PDB_NAME_CONFIG.rst +++ b/Help/prop_tgt/PDB_NAME_CONFIG.rst @@ -1,7 +1,8 @@ PDB_NAME_ ----------------- -Per-configuration name for MS debug symbols ``.pdb`` file. +Per-configuration output name for the MS debug symbol ``.pdb`` file +generated by the linker for an executable or shared library target. This is the configuration-specific version of :prop_tgt:`PDB_NAME`. diff --git a/Help/prop_tgt/PDB_NOTE.txt b/Help/prop_tgt/PDB_NOTE.txt new file mode 100644 index 000000000..e55aba285 --- /dev/null +++ b/Help/prop_tgt/PDB_NOTE.txt @@ -0,0 +1,8 @@ +.. note:: + This property does not apply to STATIC library targets because no linker + 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. diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst index 3cc075e2d..9a863a1d1 100644 --- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst @@ -1,12 +1,15 @@ PDB_OUTPUT_DIRECTORY -------------------- -Output directory for MS debug symbols ``.pdb`` file from linker. +Output directory for the MS debug symbols ``.pdb`` file +generated by the linker for an executable or shared library target. This property specifies the directory into which the MS debug symbols 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. +.. 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 024464626..caec2de25 100644 --- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -1,7 +1,8 @@ PDB_OUTPUT_DIRECTORY_ ----------------------------- -Per-configuration output directory for MS debug symbols ``.pdb`` files. +Per-configuration output directory for the MS debug symbol ``.pdb`` file +generated by the linker for an executable or shared library target. This is a per-configuration version of :prop_tgt:`PDB_OUTPUT_DIRECTORY`, but multi-configuration generators (VS, Xcode) do NOT append a diff --git a/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst index b38f0ecb2..763bcb34f 100644 --- a/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst +++ b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst @@ -1,7 +1,8 @@ CMAKE_PDB_OUTPUT_DIRECTORY -------------------------- -Where to put all the MS debug symbol files from linker. +Output directory for MS debug symbol ``.pdb`` files generated by the +linker for executable and shared library targets. This variable is used to initialize the :prop_tgt:`PDB_OUTPUT_DIRECTORY` property on all the targets. See that target property for additional diff --git a/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst index 2d7341de5..4d18eec5d 100644 --- a/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -1,7 +1,8 @@ CMAKE_PDB_OUTPUT_DIRECTORY_ ----------------------------------- -Per-configuration output directory for MS debug symbols ``.pdb`` files. +Per-configuration output directory for MS debug symbol ``.pdb`` files +generated by the linker for executable and shared library targets. This is a per-configuration version of :variable:`CMAKE_PDB_OUTPUT_DIRECTORY`. This variable is used to initialize the