Add CHPL_LLVM_GCC_INSTALL_DIR as an alternative to CHPL_LLVM_GCC_PREF…

…IX (#25913)

This PR adds `CHPL_LLVM_GCC_INSTALL_DIR` as an alternative to
`CHPL_LLVM_GCC_PREFIX`.

This PR is motivated by the discussion in
https://chapel.discourse.group/t/cannot-make-gpu-enabled-chapel/37046/12
.

`CHPL_LLVM_GCC_PREFIX` allows one to select a GCC installation. The
trouble is, on some systems (E.g. Ubuntu 24.04), there can be multiple
versions of GCC installed at the same time, with the same prefix (`/usr`
in this case).

`clang` actually supports `--gcc-install-dir` as of `clang` 16. That
flag can be used to request a particular version of GCC on Ubuntu.

To understand what one might want to include:
* run `clang++ -v hello.cc` where `hello.cc` might just contain `int
main() { return 0; }`
 * you can see the GCC installations it considers at the beginning, e.g.
   ```
Found candidate GCC installation:
/usr/bin/../lib/gcc/x86_64-linux-gnu/11
Found candidate GCC installation:
/usr/bin/../lib/gcc/x86_64-linux-gnu/12
Found candidate GCC installation:
/usr/bin/../lib/gcc/x86_64-linux-gnu/13
Found candidate GCC installation:
/usr/bin/../lib/gcc/x86_64-linux-gnu/14
   Selected GCC installation: /usr/bin/../lib/gcc/x86_64-linux-gnu/14
   ```
* you can try to change which version should be used, e.g. with `clang++
-v hello.cc --gcc-install-dir=/usr/bin/../lib/gcc/x86_64-linux-gnu/13 `

Reviewed by @e-kayrakli - thanks!

- [x] able to build a GPU-enabled runtime on Ubuntu 24.04 with GCC 14
installed
- [x] full comm=none testing

doc/rst/usingchapel/chplenv.rst

@@ -860,6 +860,52 @@ CHPL_LLVM_GCC_PREFIX
    ``--gcc-toolchain`` flag; or you can set it to a particular directory
    to pass to ``clang`` with the ``--gcc-toolchain`` flag.
 
+   Please note that, on some systems, it's possible to install multiple
+   versions of gcc to ``/usr``. In that event, ``CHPL_LLVM_GCC_PREFIX``
+   and ``--gcc-toolchain`` cannot distinguish between these multiple versions.
+   Use the next option, ``CHPL_LLVM_GCC_INSTALL_DIR``, instead for such
+   cases.
+
+.. _readme-chplenv.CHPL_LLVM_GCC_INSTALL_DIR:
+
+CHPL_LLVM_GCC_INSTALL_DIR
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+   Sometimes it's necessary to request that ``clang`` work with a
+   particular version of GCC. If many versions are installed at the same
+   prefix (e.g. ``/usr``) then ``CHPL_LLVM_GCC_PREFIX`` won't be able to
+   differentate between them. That is where ``CHPL_LLVM_GCC_INSTALL_DIR``
+   comes in!
+
+   To understand what to set ``CHPL_LLVM_GCC_INSTALL_DIR`` to in such
+   cases, try a test compile:
+
+      * ``echo int main() { return 0; } > hello.cc``
+      * ``clang++ -v hello.cc``
+
+   This will print out lines along these lines::
+
+      Found candidate GCC installation: /usr/bin/../lib/gcc/x86_64-linux-gnu/11
+      Found candidate GCC installation: /usr/bin/../lib/gcc/x86_64-linux-gnu/12
+      Found candidate GCC installation: /usr/bin/../lib/gcc/x86_64-linux-gnu/13
+      Found candidate GCC installation: /usr/bin/../lib/gcc/x86_64-linux-gnu/14
+      Selected GCC installation: /usr/bin/../lib/gcc/x86_64-linux-gnu/14
+
+   The paths printed here are suitable for use with
+   ``CHPL_LLVM_GCC_INSTALL_DIR``. Choose the path that corresponds to the
+   ``g++`` version that you are trying to use. If you are not sure which
+   ``g++`` version to use -- the version that comes with your system is a
+   good starting point. You can use
+   ``/usr/bin/g++ --version`` or just ``g++ --version`` to find that
+   version.
+
+   .. note::
+
+      ``CHPL_LLVM_GCC_INSTALL_DIR`` works with the clang flag
+      ``--gcc-install-dir`` which was added in LLVM / clang 16. As a
+      result, ``CHPL_LLVM_GCC_INSTALL_DIR`` will not work for earlier
+      versions of LLVM / clang.
+
 .. _readme-chplenv.CHPL_UNWIND:
 
 CHPL_UNWIND

util/chplenv/chpl_llvm.py

@@ -649,7 +649,7 @@ def llvm_enabled():
     return False
 
 @memoize
-def get_gcc_prefix():
+def get_gcc_prefix_dir():
     gcc_prefix = overrides.get('CHPL_LLVM_GCC_PREFIX', '')
 
     # allow CHPL_LLVM_GCC_PREFIX=none to disable inferring it
@@ -710,6 +710,20 @@ def get_gcc_prefix():
 
     return gcc_prefix
 
+@memoize
+def get_gcc_install_dir():
+    gcc_dir = overrides.get('CHPL_LLVM_GCC_INSTALL_DIR', '')
+
+    if gcc_dir:
+        llvm_version = get_llvm_version()
+        if llvm_version in ('11', '12', '13', '14', '15'):
+            warning("This LLVM / clang version {0} is too old to use "
+                    "CHPL_LLVM_GCC_INSTALL_DIR -- "
+                    "it will be ignored".format(llvm_version))
+            return ''
+
+    return gcc_dir
+
 
 # The bundled LLVM does not currently know to look in a particular Mac OS X SDK
 # so we provide a -isysroot arg to indicate which is used.
@@ -808,9 +822,13 @@ def get_system_llvm_built_sdkroot():
 def get_clang_basic_args():
     clang_args = [ ]
 
-    gcc_prefix = get_gcc_prefix()
-    if gcc_prefix:
-        clang_args.append('--gcc-toolchain=' + gcc_prefix)
+    gcc_install_dir = get_gcc_install_dir();
+    if gcc_install_dir:
+        clang_args.append('--gcc-install-dir=' + gcc_install_dir)
+    else:
+        gcc_prefix = get_gcc_prefix_dir()
+        if gcc_prefix:
+            clang_args.append('--gcc-toolchain=' + gcc_prefix)
 
     sysroot_args = get_sysroot_resource_dir_args()
     if sysroot_args: