Doc updates for macOS 14.5 Sonoma (#1205)

This change updates the documentation to have additional information on installing spack-stack in a macOS 14.5 Sonoma environment. Some additional helpful info has been added on selecting a working clang compiler and several other smaller updates were added.

---------

Co-authored-by: Stephen Herbener <[email protected]>

.github/workflows/macos-ci-aarch64.yaml

@@ -6,6 +6,7 @@ on:
       - 'doc/**'
       - '**.md'
       - '.github/ISSUE_TEMPLATE/*'
+      - '.github/workflows/macos-ci-aarch64-notest.yaml'
       - '.gitignore'
   workflow_dispatch:
 

.github/workflows/ubuntu-ci-x86_64-gnu.yaml

@@ -6,6 +6,7 @@ on:
       - 'doc/**'
       - '**.md'
       - '.github/ISSUE_TEMPLATE/*'
+      - '.github/workflows/ubuntu-ci-x86_64-gnu-notest.yaml'
       - '.gitignore'
   workflow_dispatch:
 

.github/workflows/ubuntu-ci-x86_64-intel.yaml

@@ -6,6 +6,7 @@ on:
       - 'doc/**'
       - '**.md'
       - '.github/ISSUE_TEMPLATE/*'
+      - '.github/workflows/ubuntu-ci-x86_64-intel-notest.yaml'
       - '.gitignore'
   workflow_dispatch:
 

doc/source/KnownIssues.rst

@@ -109,9 +109,9 @@ macOS
 
    Can happen when trying to use the raster plotting scripts in ``fv3-jedi-tools``. In that case, exporting ``DYLD_LIBRARY_PATH=/usr/lib/:$DYLD_LIBRARY_PATH`` can help. If ``git`` commands fail after this, you might need to verify where ``which git`` points to (Homebrew vs module) and unload the ``git`` module.
 
-6. ``apple-clang@15.0.0`` not yet supported
+6. Not all versions of ``apple-clang@15.0.0`` are currently supported.
 
-   Building with ``apple-clang@15.0.0`` is under development and should be working soon. In the meantime, please use ``apple-clang@14.x`` or older versions.
+   If you are running macOS Sonoma 14.5 you may have a recent version of clang that does not yet build spack packages. On the console you should run ``clang --version`` and verify that the underlying clang compiler is ``clang-1500.1.0.2.5`` which is the version provided with Command Line Tools for XCode 15.1. You can downgrade your Command Line Tool packages by first running ``sudo rm -rf /Library/Developer/CommandLineTools`` then you can download and install the Command Line Tools 15.1 APK from `developer.apple.com <https://developer.apple.com/download/all/>`_. The Apple Developer site requires an iCloud login.
 
 ==============================
 Ubuntu

doc/source/NewSiteConfigs.rst

@@ -93,6 +93,9 @@ These instructions are meant to be a reference that users can follow to set up t
 .. note::
    If you encounter build errors for gdal later on in spack-stack (see :numref:`Section %s <KnownIssues>`), you may need to install the full ``Xcode`` application and then switch ``xcode-select`` over with ``sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`` (change the path if you installed Xcode somewhere else).
 
+.. note::
+   If you have clang 15.x, please read the Known Issues entry on clang 15.x (see :numref:`Section %s <KnownIssues>`).
+
 2. Set up an environment using the native architecture
 
     a. Arm
@@ -146,6 +149,7 @@ These instructions are meant to be a reference that users can follow to set up t
    brew install curl
    brew install cmake
    brew install openssl
+   brew install libiconv
    # Note - need to pin to version 5
    brew install qt@5
 
@@ -226,20 +230,23 @@ Remember to activate the ``lua`` module environment and have MacTeX in your sear
    spack external find --scope system \
        --exclude bison --exclude openssl \
        --exclude python --exclude gettext
-   spack external find --scope system libiconv
    spack external find --scope system perl
    spack external find --scope system wget
 
    # Note - only needed for running JCSDA's
    # JEDI-Skylab system (using R2D2 localhost)
    spack external find --scope system mysql
 
+   # Some dependency paths may be complicated by the use of homebrew casks.
+   # These dependencies require PATH modification to enable spack external find.
+   PATH="$HOMEBREW_ROOT/opt/libiconv/bin:$PATH" \
+        spack external find --scope system libiconv
+
    PATH="$HOMEBREW_ROOT/opt/curl/bin:$PATH" \
         spack external find --scope system curl
 
-   # Note - Path to qt can differ by homebrew version. Check path if qt is not found.
    PATH="$HOMEBREW_ROOT/opt/qt@5/bin:$PATH" \
-       spack external find --scope system qt
+        spack external find --scope system qt
 
    # Optional, only if planning to build jedi-tools environment with LaTeX support
    # The texlive bin directory must have been added to PATH (see above)