Update docs related to build changes

doc/rst/usingchapel/QUICKSTART.rst

@@ -89,20 +89,22 @@ rebuild Chapel from source in a different configuration:
 * Open up a new shell to avoid inheriting the previous environment
   settings.
 
-* The Quickstart configuration described above sets ``CHPL_LLVM=none``
-  for simplicity and to save time.  This causes the Chapel compiler to
-  use its C back-end, which is not the preferred option; as of Chapel
-  1.25, LLVM is the default back-end, which needs to be available for
+* The Quickstart configuration attempts to detect if you have a compatable
+  system installation of LLVM and clang. If you do not, it will set
+  ``CHPL_LLVM=none`` for simplicity and to save time.  This causes
+  the Chapel compiler to use its C back-end, which is not the preferred
+  option; LLVM is the default back-end, which needs to be available for
   full functionality.  There are a few options for using LLVM:
 
-  - ensure that you have a compatible version of LLVM installed on
-    your system and set ``CHPL_LLVM=system`` (or leave it unset and
-    Chapel should find it if it's in your path.) Currently compatible
-    versions are LLVM-11, LLVM-12, LLVM-13, and LLVM-14.
+  - Ensure that you have a compatible version of LLVM installed on
+    your system and set ``CHPL_LLVM=system``. Once you have it working,
+    you can leave ``CHPL_LLVM`` unset and Chapel should detect it if it
+    is in your path. See :ref:`readme-prereqs` for details on the
+    currently supported LLVM versions.
 
-  - set ``CHPL_LLVM=bundled`` to have Chapel build and use the bundled
-    version of LLVM (note that building the bundled version of LLVM
-    can take a long time and requires CMake version 3.13.4 or higher)
+  - Or, set ``CHPL_LLVM=bundled`` to have Chapel build and use the bundled
+    version of LLVM. Note that building the bundled version of LLVM
+    can take a long time and requires CMake version 3.13.4 or higher.
 
   - set ``CHPL_LLVM=none`` to continue using the C back-end rather
     than LLVM

doc/rst/usingchapel/chplenv.rst

@@ -754,9 +754,11 @@ CHPL_LLVM
        Value          Description
        ============== ======================================================
        bundled        use the llvm/clang distribution in third-party
-       system         find a compatible LLVM in system libraries;
-                      note: the LLVM must be a version supported by Chapel
+       system         find a compatible LLVM and clang in system libraries;
+                      but note that it must be a version supported by Chapel
        none           do not support llvm/clang-related features
+                      (but note that the LLVM Support library will still
+                      be used -- see ``CHPL_LLVM_SUPPORT`` below)
        unset          indicates that no reasonable default has been
                       inferred, requiring the user to intentionally select
                       another option
@@ -767,32 +769,74 @@ CHPL_LLVM
      * ``none`` on linux32 where Chapel LLVM support is not yet implemented
      * ``bundled`` if you've already built the bundled llvm in
        `third-party/llvm`
-     *  ``system`` if a compatible system-wide installation of LLVM is detected
+     *  ``system`` if a compatible system-wide installation of LLVM and
+        clang is detected
      * ``unset`` otherwise
 
    If CHPL_LLVM is ``unset`` you will need to either add a system-wide
    installation of LLVM or set ``CHPL_LLVM`` to ``bundled`` or ``none``.
 
    See :ref:`readme-prereqs` for more information about currently
-   supported LLVM versions.
+   supported LLVM versions and how to install them. If you are having
+   trouble getting the build system to recognize your system install of
+   LLVM, try setting ``CHPL_LLVM=system`` and set ``CHPL_LLVM_CONFIG`` to
+   the ``llvm-config`` command from the LLVM version you have installed.
+   Temporarily setting these can help produce a different error message
+   that may may help you to diagnose the problem.
 
-   **CHPL_LLVM_CONFIG**
+.. _readme-chplenv.CHPL_LLVM_SUPPORT:
+
+CHPL_LLVM_SUPPORT
+~~~~~~~~~~~~~~~~~
+
+   This variable indicates where to find the LLVM support library. The
+   LLVM support library is required to build the ``chpl`` compiler. It
+   can only have two values:
+
+       ============== ======================================================
+       Value          Description
+       ============== ======================================================
+       bundled        build the LLVM support library from source using
+                      the bundled version in third-party
+       system         use a system-wide install of LLVM to get the
+                      LLVM support library
+       ============== ======================================================
+
+   If unset, ``CHPL_LLVM_SUPPORT`` defaults to the same value as
+   ``CHPL_LLVM`` if ``CHPL_LLVM=system`` or ``CHPL_LLVM=bundled``.
+   Otherwise:
+
+     * ``system`` if a compatible system-wide installation of LLVM is detected
+     * ``bundled`` otherwise
+
+.. _readme-chplenv.CHPL_LLVM_CONFIG:
+
+CHPL_LLVM_CONFIG
+~~~~~~~~~~~~~~~~
 
    In some cases, it is useful to be able to select a particular LLVM
-   installation for use with ``CHPL_LLVM=system``. In that event, in
-   addition to setting ``CHPL_LLVM=system``, you can set
-   ``CHPL_LLVM_CONFIG`` to the llvm-config command from the LLVM
-   installation you wish to use.
-
-   **CHPL_LLVM_GCC_PREFIX**
-
-   Additionally, in some cases, the configured ``clang`` will not work
-   correctly without a ``--gcc-toolchain`` flag. The Chapel compiler
-   tries to infer this flag but it does not always do so correctly. As a
-   result, it is sometimes necessary to override it.  You can set
-   ``CHPL_LLVM_GCC_PREFIX`` to ``none`` to  disable passing the
-   ``--gcc-toolchain`` flag; or you can set it to a directory to pass to
-   ``clang`` with the ``--gcc-toolchain`` flag.
+   installation for use with ``CHPL_LLVM=system`` or with
+   ``CHPL_LLVM_SUPPORT=system``. In that event, in addition to setting
+   one of those variables, you can set ``CHPL_LLVM_CONFIG`` to the
+   llvm-config command from the LLVM installation you wish to use.
+
+   Inspecting the value of this variable from ``printchplenv --all`` can
+   also help to identify problems with detection of a system install of
+   LLVM and clang.
+
+.. _readme-chplenv.CHPL_LLVM_GCC_PREFIX:
+
+CHPL_LLVM_GCC_PREFIX
+~~~~~~~~~~~~~~~~~~~~
+
+   In some cases, the configured ``clang`` will not work correctly
+   without a ``--gcc-toolchain`` flag. The Chapel compiler tries to infer
+   this flag based upon the ``gcc`` currently available in your ``PATH``
+   but sometimes that strategy does not work. As a result, it is
+   sometimes necessary to indicate the path to the GCC libraries.  You
+   can set ``CHPL_LLVM_GCC_PREFIX`` to ``none`` to  disable passing the
+   ``--gcc-toolchain`` flag; or you can set it to a particular directory
+   to pass to ``clang`` with the ``--gcc-toolchain`` flag.
 
 .. _readme-chplenv.CHPL_UNWIND:
 

doc/rst/usingchapel/prereqs.rst

@@ -37,9 +37,10 @@ for using Chapel:
   * CMake is available and ``cmake`` runs version 3.13.4 or later.
 
   * The LLVM backend is now the default and it is easiest to use it with
-    a system-wide installation of LLVM. LLVM 11,12,13 and 14 are currently
-    supported. If a system-wide installation of LLVM 11/12/13/14 is not
-    available, you can use the bundled LLVM or disable LLVM support (see
+    a system-wide installation of LLVM. LLVM and clang versions 11, 12,
+    13 and 14 are currently supported. If a system-wide installation of
+    LLVM and clang with one of those versions is not available, you can
+    use the bundled LLVM or disable LLVM support (see
     :ref:`readme-chplenv.CHPL_LLVM`).
 
 In addition, several optional components have additional requirements: