[CMake] Change GCC_INSTALL_PREFIX from warning to fatal error

[MaskRay]

unless USE_DEPRECATED_GCC_INSTALL_PREFIX (temporary escape hatch) is
set. Setting GCC_INSTALL_PREFIX leads to a warning for Clang 18.1
(#77537) and will be completely removed for Clang 20.

Link: discourse.llvm.org/t/add-gcc-install-dir-deprecate-gcc-toolchain-and-remove-gcc-install-prefix/65091
Link: discourse.llvm.org/t/correct-cmake-parameters-for-building-clang-and-lld-for-riscv/72833

[llvmbot]

@llvm/pr-subscribers-clang

Author: Fangrui Song (MaskRay)

Changes

unless USE_DEPRECATED_GCC_INSTALL_PREFIX (temporary escape hatch) is
set. Setting GCC_INSTALL_PREFIX leads to a warning for Clang 18.1
(#77537) and will be completely removed for Clang 20.

Link: discourse.llvm.org/t/add-gcc-install-dir-deprecate-gcc-toolchain-and-remove-gcc-install-prefix/65091
Link: discourse.llvm.org/t/correct-cmake-parameters-for-building-clang-and-lld-for-riscv/72833

---

Full diff: https://github.com/llvm/llvm-project/pull/85891.diff

2 Files Affected:

• (modified) clang/CMakeLists.txt (+3-2)
• (modified) clang/docs/ReleaseNotes.rst (+3)

diff --git a/clang/CMakeLists.txt b/clang/CMakeLists.txt
index 47fc2e4886cfc2..761dab8c28c134 100644
--- a/clang/CMakeLists.txt
+++ b/clang/CMakeLists.txt
@@ -190,11 +190,12 @@ set(CLANG_RESOURCE_DIR "" CACHE STRING
 set(C_INCLUDE_DIRS "" CACHE STRING
   "Colon separated list of directories clang will search for headers.")
 
+set(USE_DEPRECATED_GCC_INSTALL_PREFIX OFF CACHE BOOL "Temporary workaround before GCC_INSTALL_PREFIX is completely removed")
 set(GCC_INSTALL_PREFIX "" CACHE PATH "Directory where gcc is installed." )
 set(DEFAULT_SYSROOT "" CACHE STRING
   "Default <path> to all compiler invocations for --sysroot=<path>." )
-if(GCC_INSTALL_PREFIX)
-  message(WARNING "GCC_INSTALL_PREFIX is deprecated and will be removed. Use "
+if(GCC_INSTALL_PREFIX AND NOT USE_DEPRECATED_GCC_INSTALL_PREFIX)
+  message(FATAL_ERROR "GCC_INSTALL_PREFIX is deprecated and will be removed. Use "
     "configuration files (https://clang.llvm.org/docs/UsersManual.html#configuration-files)"
     "to specify the default --gcc-install-dir= or --gcc-triple=. --gcc-toolchain= is discouraged. "
     "See https://github.com/llvm/llvm-project/pull/77537 for detail.")
diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index 0ce3cbe3266efd..862aec323899ce 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -37,6 +37,9 @@ These changes are ones which we think may surprise users when upgrading to
 Clang |release| because of the opportunity they pose for disruption to existing
 code bases.
 
+- Setting the deprecated CMake variable ``GCC_INSTALL_PREFIX`` (which sets the
+  default ``--gcc-toolchain=``) now leads to a fatal error.
+
 C/C++ Language Potentially Breaking Changes
 -------------------------------------------
 

[ye-luo]

The term deprecated refers to a functionality that still exists in software whose use is not recommended. Contradictorily, GCC_INSTALL_PREFIX got me fatal error now without a clear message explaining how to keep it working. I had to dig deep to figure it out.

Will "temporary" USE_DEPRECATED_GCC_INSTALL_PREFIX make its way to 19 release? Then it should be documented.

Why USE_DEPRECATED_GCC_INSTALL_PREFIX is even needed in the first place? It adds further complexity. Why not just delete GCC_INSTALL_PREFIX?

[jhuber6]

What's the suggested way to handle this in a standard build? The documents state to use -DCMAKE_CXX_FLAGS=--gcc-isntall-dir=<dir> but that doesn't work if you build LLVM with gcc initially. You'd need to somehow only pass that flag to the invocations that use clang. We also have some code in the OpenMP project that doesn't respect CMAKE_CXX_FLAGS because it needs to be very carefully controlled to generate valid GPU code. I don't think what's suggested anywhere is a valid replacement for the old behavior and is a regression for anyone unfortunate enough to need to build this on a cluster machine where they don't control the global GCC installation.

Realistically we could make an LLVM flag that appends the flags to the compile options only if the compiler is clang. This would work in the case of a runtimes build I guess? I think the GPU builds might be workable since they're freestanding so it probably won't error on missing libraries.

[jhuber6]

@petrhosek Is there a way to pass flags only to the runtimes portion of the build within the normal workflow? I know we have -DRUNTIMES_x86_64-unknown-linux-gnu_CMAKE_CXX_COMPILE_FLAGS= that might work, but I don't think this is respected if we're using the default target.

[petrhosek]

@petrhosek Is there a way to pass flags only to the runtimes portion of the build within the normal workflow? I know we have -DRUNTIMES_x86_64-unknown-linux-gnu_CMAKE_CXX_COMPILE_FLAGS= that might work, but I don't think this is respected if we're using the default target.

You can use RUNTIMES_CMAKE_ARGS, see for example:

llvm-project/clang/cmake/caches/Fuchsia-stage2.cmake

Line 90 in c6a65e4

set(RUNTIMES_CMAKE_ARGS "-DCMAKE_OSX_DEPLOYMENT_TARGET=10.13;-DCMAKE_OSX_ARCHITECTURES=arm64|x86_64" CACHE STRING "")

[ye-luo]

-DRUNTIMES_CMAKE_ARGS="-DCMAKE_C_FLAGS=--gcc-install-dir=$GCC_ROOT;-DCMAKE_CXX_FLAGS=--gcc-install-dir=$GCC_ROOT" worked for me

[jhuber6]

-DRUNTIMES_CMAKE_ARGS="-DCMAKE_C_FLAGS=--gcc-install-dir=$GCC_ROOT;-DCMAKE_CXX_FLAGS=--gcc-install-dir=$GCC_ROOT" worked for me

Great, we should probably document this somewhere.

[haampie]

Users of GCC_INSTALL_PREFIX typically have GCC installed in a unique, non-standard prefix, where clang's search for GCC just worked.

Now those users have to generate config files for post-install, AND figure out how to make clang behave correctly when building runtimes. That's not ideal.

@MaskRay can you please make the error message more informative? It should probably say that users additionally have to set RUNTIMES_CMAKE_ARGS=... as well as generating clang.cfg, clang++.cfg config files. (And what about flang.cfg and/or flang-new.cfg?)

More clarity please :)

[MaskRay]

@MaskRay can you please make the error message more informative? It should probably say that users additionally have to set RUNTIMES_CMAKE_ARGS=... as well as generating clang.cfg, clang++.cfg config files. (And what about flang.cfg and/or flang-new.cfg?)

I haven't used RUNTIMES_CMAKE_ARGS= myself. The purpose of the message is to provide brief information to help users to find a solution. Covering everything is probably out of scope... If they find this PR and your comment, it will have provided sufficient information.

I tried grepping RUNTIMES_CMAKE_ARGS and did not get many results. The documentation can be independently improved.

[haampie]

I disagree, --gcc-install-dir is sure an improvement over --gcc-toolchain, but they're both weaker than the compile time option GCC_INSTALL_PREFIX because of runtimes.

You're looking to remove GCC_INSTALL_PREFIX, then give a clear alternative that's equivalent. The current error message about config files is misleading since runtimes are potentially compiled with undesired gcc toolchain before a config file has any effect, that's rather opaque.

A different point: flang-new does not accept --gcc-install-dir. Is that an oversight? (Edit: doesn't accept --gcc-toolchain either) Edit: was fixed in #87360 :)

[jhuber6]

I disagree, --gcc-install-dir is sure an improvement over --gcc-toolchain, but they're both weaker than the compile time option GCC_INSTALL_PREFIX because of runtimes.

You're looking to remove GCC_INSTALL_PREFIX, then give a clear alternative that's equivalent. The current error message about config files is misleading since it potentially runtimes will use an undesired gcc version when they're built, which is rather opaque.

A different point: flang-new does not accept --gcc-install-dir. Is that an oversight?

Should've been added in #87360. I agree overall that this change made made runtime builds unnecessarily complex.