[llvm] [CMake] Make precompiled headers opt-in for ccache builds (PR #141927)

[Kajetan Puchalski via llvm-commits]

https://github.com/mrkajetanp updated https://github.com/llvm/llvm-project/pull/141927

>From 31b413df98e7835a953e148ecf275aada1590239 Mon Sep 17 00:00:00 2001
From: Kajetan Puchalski <kajetan.puchalski at arm.com>
Date: Thu, 29 May 2025 10:59:51 +0000
Subject: [PATCH 1/2] [CMake] Make precompiled headers opt-in for ccache builds

Using precompiled headers in ccache builds seems to be causing
intermittent CI failures where CMake fails to rebuild the header
when it's supposed to, such as:

https://www.mail-archive.com/llvm-bugs@lists.llvm.org/msg88645.html

Add a new LLVM_CCACHE_PCH option, set to OFF by default, in order
to make using pch in ccache opt-in and avoid these failures in the CI.

Signed-off-by: Kajetan Puchalski <kajetan.puchalski at arm.com>
---
 llvm/CMakeLists.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/llvm/CMakeLists.txt b/llvm/CMakeLists.txt
index ed44b16bf9aeb..dbd43c3ece895 100644
--- a/llvm/CMakeLists.txt
+++ b/llvm/CMakeLists.txt
@@ -289,6 +289,12 @@ if(LLVM_CCACHE_BUILD)
     set(LLVM_CCACHE_PARAMS "CCACHE_CPP2=yes CCACHE_HASHDIR=yes CCACHE_SLOPPINESS=pch_defines,time_macros"
         CACHE STRING "Parameters to pass through to ccache")
 
+    # Using precompiled headers with ccache builds can result in intermittent CI failures
+    set(LLVM_CCACHE_PCH OFF CACHE BOOL "Use precompiled headers in ccache builds")
+    if (NOT LLVM_CCACHE_PCH)
+      set(CMAKE_DISABLE_PRECOMPILE_HEADERS "ON")
+    endif()
+
     if(NOT CMAKE_HOST_WIN32)
       set(CCACHE_PROGRAM "${LLVM_CCACHE_PARAMS} ${CCACHE_PROGRAM}")
       if (LLVM_CCACHE_MAXSIZE)

>From f75292a5d310c8872b81c16e42023e754178a1e3 Mon Sep 17 00:00:00 2001
From: Kajetan Puchalski <kajetan.puchalski at arm.com>
Date: Wed, 4 Jun 2025 12:43:37 +0000
Subject: [PATCH 2/2] Elaborate the comment, include flag in docs

---
 llvm/CMakeLists.txt | 4 +++-
 llvm/docs/CMake.rst | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/llvm/CMakeLists.txt b/llvm/CMakeLists.txt
index dbd43c3ece895..6015b5ccc868e 100644
--- a/llvm/CMakeLists.txt
+++ b/llvm/CMakeLists.txt
@@ -289,7 +289,9 @@ if(LLVM_CCACHE_BUILD)
     set(LLVM_CCACHE_PARAMS "CCACHE_CPP2=yes CCACHE_HASHDIR=yes CCACHE_SLOPPINESS=pch_defines,time_macros"
         CACHE STRING "Parameters to pass through to ccache")
 
-    # Using precompiled headers with ccache builds can result in intermittent CI failures
+    # FIXME: This is a workaround for an unknown underlying issue where the header file
+    # changes but then the pch does not get rebuilt before its dependencies.
+    # See: https://github.com/llvm/llvm-project/issues/142449
     set(LLVM_CCACHE_PCH OFF CACHE BOOL "Use precompiled headers in ccache builds")
     if (NOT LLVM_CCACHE_PCH)
       set(CMAKE_DISABLE_PRECOMPILE_HEADERS "ON")
diff --git a/llvm/docs/CMake.rst b/llvm/docs/CMake.rst
index 674e4969c6912..5828bfeff6d7e 100644
--- a/llvm/docs/CMake.rst
+++ b/llvm/docs/CMake.rst
@@ -412,7 +412,9 @@ enabled sub-projects. Nearly all of these variable names begin with
   Defaults to OFF.  The size and location of the cache maintained
   by ``ccache`` can be adjusted via the LLVM_CCACHE_MAXSIZE and LLVM_CCACHE_DIR
   options, which are passed to the CCACHE_MAXSIZE and CCACHE_DIR environment
-  variables, respectively.
+  variables, respectively. By default, enabling the ccache build will disable
+  using precompiled headers as they have been known to cause intermittent CI
+  failures. This can be adjusted via the LLVM_CCACHE_PCH option.
 
 **LLVM_CODE_COVERAGE_TARGETS**:STRING
   If set to a semicolon separated list of targets, those targets will be used