[llvm] [cmake] Document and suggest LLVM_ENABLE_PDB (PR #102887)

[via llvm-commits]

https://github.com/zmodem created https://github.com/llvm/llvm-project/pull/102887

As suggested in #101533. @rnk added the flag in b97ff922a9eeea6efbf12deba907848e5002cc76

>From 021edd228118403ed1d7f1aea3e25e18440ddf90 Mon Sep 17 00:00:00 2001
From: Hans Wennborg <hans at chromium.org>
Date: Mon, 12 Aug 2024 14:06:32 +0200
Subject: [PATCH] [cmake] Document and suggest LLVM_ENABLE_PDB

---
 llvm/docs/CMake.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/llvm/docs/CMake.rst b/llvm/docs/CMake.rst
index 2a80813999ea1e..f4fe0952ac7dbb 100644
--- a/llvm/docs/CMake.rst
+++ b/llvm/docs/CMake.rst
@@ -218,6 +218,11 @@ used variables that control features of LLVM and enabled subprojects.
   If you are using an IDE such as Visual Studio or Xcode, you should use
   the IDE settings to set the build type.
 
+  Note: on Windows (building with MSVC or clang-cl), CMake's **RelWithDebInfo**
+  setting does not enable the same optimizations as **Release**. Using the
+  **Release** build type with :ref:`LLVM_ENABLE_PDB <llvm_enable_pdb>` set
+  may be a better option.
+
 **CMAKE_INSTALL_PREFIX**:PATH
   Path where LLVM will be installed when the "install" target is built.
 
@@ -548,6 +553,12 @@ enabled sub-projects. Nearly all of these variable names begin with
   Compile with `Clang Header Modules
   <https://clang.llvm.org/docs/Modules.html>`_.
 
+.. _llvm_enable_pdb:
+
+**LLVM_ENABLE_PDB**:BOOL
+  For Windows builds using MSVC or clang-cl, generate PDB files regardless of
+  CMAKE_BUILD_TYPE.
+
 **LLVM_ENABLE_PEDANTIC**:BOOL
   Enable pedantic mode. This disables compiler-specific extensions, if
   possible. Defaults to ON.