Add information (caveats) for [email protected] support to documenta…

…tion (#1035) * Updated MacOS instructions with a workaround for the [email protected] linker/loader issues. * Fixed typo, and added the apple ticket number for the linker/loader issues. * Added caveats about building spack-stack on MacOS using apple-clang%15.x compilers.
JCSDA · Mar 19, 2024 · 27d9a66 · 27d9a66
1 parent af39109
commit 27d9a66
Showing 1 changed file with 8 additions and 1 deletion.
diff --git a/doc/source/NewSiteConfigs.rst b/doc/source/NewSiteConfigs.rst
@@ -19,11 +19,17 @@ It is also instructive to peruse the GitHub actions scripts in ``.github/workflo
 +-------------------------------------------+----------------------------------------------------------------------+---------------------------+
 | GNU (gcc, g++, gfortran)                  | 9.2.0 to 12.2.0 (note: 13.x.y is **not** yet supported)              | ``gcc@``                  |
 +-------------------------------------------+----------------------------------------------------------------------+---------------------------+
-| Apple clang (clang, clang++, w/ gfortran) | 13.1.6 to 15.0.0                                                     | ``apple-clang@``          |
+| Apple clang (clang, clang++, w/ gfortran) | 13.1.6 to 15.0.0 [#fn1]_                                             | ``apple-clang@``          |
 +-------------------------------------------+----------------------------------------------------------------------+---------------------------+
 | LLVM clang (clang, clang++, w/ gfortran)  | 10.0.0 to 14.0.3                                                     | ``clang@``                |
 +-------------------------------------------+----------------------------------------------------------------------+---------------------------+
 
+.. rubric:: Footnotes
+
+.. [#fn1]
+  Note that [email protected] compiler versions are fully supported, and [email protected] will work but requires the :ref:`workaround noted below<apple-clang-15-workaround>`.
+  Also, when using [email protected] you must use Command Line Tools version 15.1, and the Command Line Tools versions 15.3 and newer are not yet supported.
+
 ..  _NewSiteConfigs_macOS:
 
 ------------------------------
@@ -244,6 +250,7 @@ Remember to activate the ``lua`` module environment and have MacTeX in your sear
 
    spack compiler find --scope system
 
+.. _apple-clang-15-workaround:
 .. note::
   When using [email protected] (or newer) compilers, you need to manually add the following ldflags spec in the `site/compilers.yaml` file.
   There are known issues with new features in the Apple linker/loader that comes with the 15.0.0 compiler set, and this change tells the linker/loader to use its legacy features which work fine.