[CMake] Deprecate DEFAULT_SYSROOT and GCC_INSTALL_PREFIX

[MaskRay]

Summary

Specifying DEFAULT_SYSROOT and GCC_INSTALL_PREFIX can cause many
clang/test/Driver failures, e.g. non-empty DEFAULT_SYSROOT causes:

Failed Tests (14):
  Clang :: Driver/baremetal.cpp
  Clang :: Driver/csky-toolchain.c
  Clang :: Driver/freebsd-include-paths.c
  Clang :: Driver/hexagon-toolchain-elf.c
  Clang :: Driver/hexagon-toolchain-linux.c
  Clang :: Driver/mips-cs.cpp
  Clang :: Driver/mips-fsf.cpp
  Clang :: Driver/mips-img-v2.cpp
  Clang :: Driver/mips-img.cpp
  Clang :: Driver/riscv32-toolchain-extra.c
  Clang :: Driver/riscv64-toolchain-extra.c
  Clang :: Driver/rocm-detect.hip
  Clang :: Driver/solaris-ld.c
  Clang :: Driver/sysroot.c

The two CMake variables are partially responsible for many
--sysroot=/ --sysroot=""/--gcc-toolchain=/--gcc-toolchain=""` in
clang/test/Driver: some contributors add them to fix tests and some just
do cargo culting.
This is not healthy for contributors adding cross compilation support.

Configuration files are perfect replacement.

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

I hope that people can help port some docs:
clang/cmake/caches/CrossWinToARMLinux.cmake
libc/docs/full_host_build.rst

[smeenai]

Conceptually this seems like a great direction to go in. We should just leave it up for a while so that anyone using these can comment on any potential issues.

[tbaeder]

CC @tstellar @tuliom since we use GCC_INSTALL_PREFIX at least in RHEL/CentOS.

[DavidSpickett]

I do cross build lldb a lot but never needed to set either of these, so I have no opinion on this.

clang/cmake/caches/CrossWinToARMLinux.cmake

Is not one of Linaro's, there's a buildbot for it (https://lab.llvm.org/buildbot/#/builders/60) owned by Vladimir Vereschaka <[e-mail]>.

Of course Linaro can help if porting it, if it proves difficult.

[bcain]

clang/CMakeLists.txt

179–183

At one time I believe that the clang configuration files could not specify paths relative to the clang executable. AFAICT DEFAULT_SYSROOT does support this.

But if I'm mistaken about that can we add an example to the docs at https://clang.llvm.org/docs/UsersManual.html#configuration-files illustrating how to use a relative sysroot?

[MaskRay]

clang/CMakeLists.txt

179–183

Clang configuration files just complement user-specified command line options. As one can do --sysroot=./sysroot, one can add --sysroot=./sysroot to a configuration file, too.

If you think having a sysroot example is useful, I can add

# Relative --sysroot
--sysroot=./sysroot

before
clang/docs/UsersManual.rst:1018 -c --target=x86_64-unknown-linux-gnu

[bcain]

clang/CMakeLists.txt

179–183

IIUC: when clang takes a --sysroot=./sysroot argument, it will interpret that path as a prefix to the files it wants to access. So the system will treat it as relative to the environment's cwd, correct?

But when DEFAULT_SYSROOT is set to a relative path, that relative path is considered to be relative to clang. Therefore a convenient feature that we take advantage of is setting it to something like ../target/hexagon-unknown-linux-musl in order to have anyone who invokes hexagon-unknown-linux-clang from any path be able to find the includes and libraries distributed with the toolchain without having to specify the sysroot.

Maybe there's a better way to achieve this without the need for a relative DEFAULT_SYSROOT but it's been very useful and the config files do not seem suited to replace it.

[MaskRay]

clang/CMakeLists.txt

179–183

--sysroot= is used as a prefix to certain files, primarily libc and GCC installations.

-DDEFAULT_SYSROOT=... just changes clang/lib/Driver/Driver.cpp:203 SysRoot(DEFAULT_SYSROOT).
There is no magic related to the clang executable path. CMake doesn't do any magic, either.

[MaskRay]

clang/CMakeLists.txt

179–183

Ah, sorry. There is magic: D76653 (@sbc100).

[bcain]

clang/CMakeLists.txt

179–183

Ah, sorry. There is magic: D76653 (@sbc100).

Okay, so should we abandon the plan to deprecate DEFAULT_SYSROOT? Or could we add a corresponding feature to config files if we want to get rid of it?

[MaskRay]

clang/CMakeLists.txt

179–183

The way relative DEFAULT_SYSROOT looks strange to me as it is not exactly equivalent to user-specified --sysroot=. I hope that there is a way to achieve @sbc100's goal.

I think a proper mechanism will take time, and we probably can just deprecated GCC_INSTALL_PREFIX for now.
And I wish that RHEL/CentOS can migrate to a modern practice.

[sbc100]

clang/CMakeLists.txt

179–183

We use DEFAULT_SYSROOT in wasi-sdk to add clang-relative default sysroot: https://github.com/WebAssembly/wasi-sdk/blob/f3b43c703f1a3b6a93fcbdac9cb2b8439adcf0c1/Makefile#L78-L82

You can see that before D76653 landed it was not possible to make a relocatable version of the SDK that was independent of its installation path. The clang-relative path is pretty useful for this purpose and avoids the need to modify a config file to include that installation path, or have the user specify --sysroot each time.

If we could find a way to specify a clang-relative path in the config file I think we could remove DEFAULT_SYSROOT completely.

clang/CMakeLists.txt

set(CLANG_RESOURCE_DIR "" CACHE STRING
   "Relative directory from the Clang binary to its resource files.")
 
 set(C_INCLUDE_DIRS "" CACHE STRING
   "Colon separated list of directories clang will search for headers.")
 
 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(DEFAULT_SYSROOT)
+  message(WARNING "DEFAULT_SYSROOT is deprecated and will be removed. Use "
+    "configuration files (https://clang.llvm.org/docs/UsersManual.html#configuration-files)"
+    "to specify the default --sysroot=")
+endif()
+if(GCC_INSTALL_PREFIX)
+  message(WARNING "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=. --gcc-toolchain= is discouraged. "
+    "The option is often unneeded or better replaced with --gcc-install-dir=.")
+endif()
 
 set(ENABLE_LINKER_BUILD_ID OFF CACHE BOOL "pass --build-id to ld")
 
 set(ENABLE_X86_RELAX_RELOCATIONS ON CACHE BOOL
     "enable x86 relax relocations by default")
 
 set(PPC_LINUX_DEFAULT_IEEELONGDOUBLE OFF CACHE BOOL
     "Enable IEEE binary128 as default long double format on PowerPC Linux.")