Merge pull request #5973 from nilsvu/installation_instructions

Upgrade to Apple Silicon on CI, simplify Apple Silicon installation instructions
sxs-collaboration · Aug 27, 2024 · d5db196 · d5db196
2 parents 806c656 + 4c9c10b
commit d5db196
Show file tree

Hide file tree

Showing 8 changed files with 110 additions and 94 deletions.
diff --git a/.github/workflows/Tests.yaml b/.github/workflows/Tests.yaml
@@ -598,7 +598,7 @@ jobs:
         run: |
           apt-get install -y libopenmpi-dev
           cd /work/charm_7_0_0 && ./build charm++ mpi-linux-x86_64-smp clang \
-          -j4 -g0 -O1 --build-shared --with-production
+          -j ${NUMBER_OF_CORES} -g0 -O1 --build-shared --with-production
 
       # Assign a unique cache key for every run.
       # - We will save the cache using this unique key, but only on the develop
@@ -874,18 +874,27 @@ ${{ matrix.build_type }}-pch-${{ matrix.use_pch || 'ON' }}"
   # Build all test executables and run unit tests on macOS
   unit_tests_macos:
     name: Unit tests on macOS
-    runs-on: macos-13
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # The number of cores is given at:
+          # https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources
+          - arch: x86
+            macos-version: 13  # Intel
+            NUM_CORES: 4
+          - arch: arm64
+            macos-version: 14  # Apple Silicon
+            NUM_CORES: 3
+    runs-on: macos-${{ matrix.macos-version }}
     env:
       # We install some low-level dependencies with Homebrew. They get picked up
       # by `spack external find`.
       SPECTRE_BREW_DEPS: >-  # Line breaks are spaces, no trailing newline
-        autoconf automake catch2 ccache cmake pkg-config boost
+        autoconf automake boost catch2 ccache cmake gsl hdf5 openblas yaml-cpp
       # We install these packages with Spack and cache them. The full specs are
-      # listed in support/DevEnvironments/spack.yaml. This list is only needed
-      # to create the cache.
-      SPECTRE_SPACK_DEPS: >-
-        blaze brigand charmpp gsl hdf5 libsharp libxsmm openblas
-        yaml-cpp
+      # listed below. This list is only needed to create the cache.
+      SPECTRE_SPACK_DEPS: blaze charmpp libxsmm
       CCACHE_DIR: $HOME/ccache
       CCACHE_TEMPDIR: $HOME/ccache-tmp
       CCACHE_MAXSIZE: "2G"
@@ -894,6 +903,7 @@ ${{ matrix.build_type }}-pch-${{ matrix.use_pch || 'ON' }}"
       CCACHE_COMPILERCHECK: content
       SPACK_SKIP_MODULES: true
       SPACK_COLOR: always
+      NUM_CORES: ${{ matrix.NUM_CORES }}
     steps:
       - name: Record start time
         id: start
@@ -903,7 +913,7 @@ ${{ matrix.build_type }}-pch-${{ matrix.use_pch || 'ON' }}"
         uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.12'
       - name: Install Homebrew dependencies
         run: |
           brew install $SPECTRE_BREW_DEPS
@@ -912,17 +922,22 @@ ${{ matrix.build_type }}-pch-${{ matrix.use_pch || 'ON' }}"
       - name: Restore dependency cache
         uses: actions/cache/restore@v4
         id: restore-dependencies
+        env:
+          CACHE_KEY_PREFIX: "dependencies-macos-${{ matrix.macos-version }}"
         with:
           path: ~/dependencies
-          key: "dependencies-macos-${{ github.run_id }}"
+          key: "${{ env.CACHE_KEY_PREFIX }}-${{ github.run_id }}"
           restore-keys: |
-            dependencies-macos-
+            ${{ env.CACHE_KEY_PREFIX }}-
       - name: Install Spack
+        # Pin a specific version of Spack to avoid breaking CI builds when
+        # Spack changes.
         run: |
           cd $HOME
-          git clone -c feature.manyFiles=true --depth=1 \
-            --branch releases/v0.18 --single-branch \
+          git clone -c feature.manyFiles=true \
             https://github.com/spack/spack.git
+          cd spack
+          git checkout 7d1de58378fa210b7db887964fcc17187a504ad8
       - name: Configure Spack
         # - To avoid re-building packages that are already installed by Homebrew
         #   we let Spack find them.
@@ -931,7 +946,7 @@ ${{ matrix.build_type }}-pch-${{ matrix.use_pch || 'ON' }}"
           source $HOME/spack/share/spack/setup-env.sh
           spack debug report
           spack compiler find && spack compiler list
-          spack external find && spack external find perl python
+          spack external find
           spack config get packages
           spack mirror add dependencies file://$HOME/dependencies/spack
       # Install the remaining dependencies from source with Spack. We install
@@ -940,9 +955,12 @@ ${{ matrix.build_type }}-pch-${{ matrix.use_pch || 'ON' }}"
       - name: Install Spack dependencies
         run: |
           source $HOME/spack/share/spack/setup-env.sh
-          spack env create spectre support/DevEnvironments/spack.yaml
+          spack env create spectre
           spack env activate spectre
-          spack remove catch2 doxygen jemalloc boost
+          spack add blaze@3.8.2 ~blas ~lapack smp=none
+          spack add charmpp@7.0.0 +shared backend=multicore build-target=charm++
+          # Use main branch until spack has 2.0 release
+          spack add libxsmm@main
           spack concretize --reuse
           spack install --no-check-signature
           spack find -v
@@ -980,11 +998,13 @@ ${{ matrix.build_type }}-pch-${{ matrix.use_pch || 'ON' }}"
       - name: Restore ccache
         uses: actions/cache/restore@v4
         id: restore-ccache
+        env:
+          CACHE_KEY_PREFIX: "ccache-macos-${{ matrix.macos-version }}"
         with:
           path: ~/ccache
-          key: "ccache-macos-${{ github.run_id }}"
+          key: "${{ env.CACHE_KEY_PREFIX }}-${{ github.run_id }}"
           restore-keys: |
-            ccache-macos-
+            ${{ env.CACHE_KEY_PREFIX }}-
       - name: Configure ccache
         run: |
           ccache -pz
@@ -1009,29 +1029,28 @@ ${{ matrix.build_type }}-pch-${{ matrix.use_pch || 'ON' }}"
             -D CMAKE_CXX_COMPILER=clang++ \
             -D CMAKE_Fortran_COMPILER=gfortran-14 \
             -D CMAKE_CXX_FLAGS="-Werror" \
-            -D OVERRIDE_ARCH=x86-64 \
             -D BUILD_SHARED_LIBS=ON \
             -D BUILD_PYTHON_BINDINGS=ON \
             -D MEMORY_ALLOCATOR=SYSTEM \
             -D CHARM_ROOT=$(spack location --install-dir charmpp) \
+            -D BLAS_ROOT=$(brew --prefix openblas) \
+            -D LAPACK_ROOT=$(brew --prefix openblas) \
             -D CMAKE_BUILD_TYPE=Debug \
             -D DEBUG_SYMBOLS=OFF \
             -D UNIT_TESTS_IN_TEST_EXECUTABLES=OFF \
             -D STUB_EXECUTABLE_OBJECT_FILES=ON \
             -D STUB_LIBRARY_OBJECT_FILES=ON \
             -D USE_PCH=ON \
             -D USE_CCACHE=ON \
-            -D SPECTRE_TEST_TIMEOUT_FACTOR=5 \
+            -D SPECTRE_TEST_TIMEOUT_FACTOR=10 \
             -D CMAKE_INSTALL_PREFIX=../install \
             -D BUILD_DOCS=OFF \
             -D USE_XSIMD=OFF \
             $GITHUB_WORKSPACE
       - name: Build unit tests
         working-directory: build
-        # Build on 4 threads because GitHub's macOS VMs have 4 cores:
-        # https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources
         run: |
-          make -j4 unit-tests
+          make -j${NUM_CORES} unit-tests
       - name: Build executables
         working-directory: build
         run: |
@@ -1059,7 +1078,7 @@ ${{ matrix.build_type }}-pch-${{ matrix.use_pch || 'ON' }}"
       - name: Run unit tests
         working-directory: build
         run: |
-          ctest -j4 --repeat after-timeout:3 --output-on-failure
+          ctest -j${NUM_CORES} --repeat after-timeout:3 --output-on-failure
       - name: Install
         working-directory: build
         run: |

diff --git a/docs/Installation/BuildSystem.md b/docs/Installation/BuildSystem.md
@@ -470,13 +470,10 @@ dev_guide_creating_executables "how to create executables".
 ## Adding External Dependencies {#adding_external_dependencies}
 
 To add an external dependency, first add a `SetupDEPENDENCY.cmake`
-file to the `cmake` directory. You should model this after the
-existing one for `Brigand` if you're adding a header-only
-library and `yaml-cpp` if the library is not header-only. If CMake
+file to the `cmake` directory. If CMake
 does not already support `find_package` for the library you're adding
-you can write your own. These should be modeled after `FindBrigand`
-for header-only libraries, and `FindYAMLCPP` for compiled
-libraries. The `SetupDEPENDENCY.cmake` file must then be included in
+you can write your own `FindDEPENDENCY.cmake` file.
+The `SetupDEPENDENCY.cmake` file must then be included in
 the root `spectre/CMakeLists.txt`. Be sure to test both that setting
 `LIBRARY_ROOT` works correctly for your library, and also that if the
 library is required that CMake fails gracefully if the library is not

diff --git a/docs/Installation/Installation.md b/docs/Installation/Installation.md
@@ -144,7 +144,7 @@ The following dependencies will be fetched automatically if you set
 
 #### Bundled:
 * [Brigand](https://github.com/edouarda/brigand)
-* [libsharp](https://github.com/Libsharp/libsharp)
+* [libsharp](https://github.com/Libsharp/libsharp) \cite Libsharp
 
 ## Clone the SpECTRE repository
 
@@ -350,11 +350,6 @@ with a plain `spack install` if you prefer.
   [LMod](https://github.com/TACC/Lmod). See the [Spack documentation on
   modules](https://spack.readthedocs.io/en/latest/module_file_support.html) for
   details.
-- On macOS:
-  - Brigand has an issue with AppleClang 13 when compiling tests (see
-    https://github.com/edouarda/brigand/issues/274). Since it is header-only,
-    you can simply clone the [Brigand repository](https://github.com/edouarda/brigand)
-    instead of installing it with Spack.
 
 ## Building Charm++ {#building-charm}
 

diff --git a/docs/Installation/InstallationOnAppleSilicon.md b/docs/Installation/InstallationOnAppleSilicon.md
@@ -23,20 +23,13 @@ Run the following command in the terminal:
 xcode-select --install
 ```
 
-### 1. Clone spectre and make a directory to install prerequisites
+### 1. Clone spectre
 
-First, make a directory to hold some prerequisites that spectre depends on.
-Name this directory whatever you like, and set `SPECTRE_DEPS_ROOT` to its value.
-These instructions, as an example, set this to the `apps` directory in the
-user's home folder.
-```
-cd $HOME
+Clone the SpECTRE repository in a directory of your choice:
+
+```sh
 git clone git@github.com:sxs-collaboration/spectre.git
-cd spectre
-export SPECTRE_HOME=$(pwd)
-export SPECTRE_DEPS_ROOT=$HOME/apps
-mkdir $SPECTRE_DEPS_ROOT
-cd $SPECTRE_DEPS_ROOT
+export SPECTRE_HOME=$PWD/spectre
 ```
 
 ### 2. Install python dependencies
@@ -64,31 +57,48 @@ pip install jupyterlab
 
 ### 3. Install dependencies with Homebrew
 
-Most of spectre's dependencies beyond python can be installed using the
-[homebrew](https://brew.sh) package manager. First, if you haven't
-already, install Homebrew by
-following the instructions on the [homebrew](https://brew.sh) homepage. Then,
-run the following to install a fortran compiler and other dependencies:
+Most of spectre's dependencies can be installed using the
+[Homebrew](https://brew.sh) package manager. First, if you haven't already,
+install Homebrew by following the instructions on the
+[Homebrew](https://brew.sh) homepage. Then, run the following to install a
+Fortran compiler and other dependencies:
+
 ```
-brew install gcc
-brew install boost gsl cmake doxygen catch2 openblas
-brew install ccache autoconf automake jemalloc hdf5 yaml-cpp
+brew install gcc autoconf automake ccache cmake
+brew install boost catch2 doxygen gsl hdf5 openblas yaml-cpp
 ```
 
+\note We use OpenBLAS instead of Apple's Accelerate framework here because
+Accelerate fails to reach the same floating point accuracy as OpenBLAS in some
+of our tests (specifically partial derivatives).
+
 ### 4. Install remaining dependencies
 
-Here, install the remaining dependencies that cannot be installed
-with homebrew or miniforge. You can install them from source manually, or use
-the [Spack](https://github.com/spack/spack) package manager.
+Here, install the remaining dependencies that cannot be installed with Homebrew.
+You can install them from source manually, or use the
+[Spack](https://github.com/spack/spack) package manager (see below).
 
 #### Install manually
 
-```
+```sh
 export SPECTRE_DEPS_ROOT=$HOME/apps
-```
-
-```
+mkdir -p $SPECTRE_DEPS_ROOT
 cd $SPECTRE_DEPS_ROOT
+
+# Install Charm++
+git clone https://github.com/UIUC-PPL/charm
+pushd charm
+git checkout v7.0.0
+git apply $SPECTRE_HOME/support/charm/v7.0.0.patch
+./build charm++ multicore-darwin-arm8 --with-production -g3 -j --build-shared
+popd
+
+# The following dependencies are optional! They will be installed in the build
+# directory automatically if needed in the next step. You can install them
+# manually like this if you want control over where or how they are installed.
+# If you don't care, you can skip ahead.
+
+# Install Blaze
 mkdir blaze
 pushd blaze
 curl -L https://bitbucket.org/blaze-lib/blaze/downloads/blaze-3.8.tar.gz \
@@ -97,24 +107,14 @@ tar -xf blaze-3.8.tar.gz
 mv blaze-3.8 include
 popd
 
+# Install libxsmm
 # Need master branch of libxsmm to support Apple Silicon
 git clone https://github.com/hfp/libxsmm.git
 pushd libxsmm
 make
 popd
 ```
 
-Next, clone, patch, and install charm++ v7.0.0.
-```
-git clone https://github.com/UIUC-PPL/charm
-pushd charm
-git checkout v7.0.0
-git apply $SPECTRE_HOME/support/charm/v7.0.0.patch
-./build LIBS multicore-darwin-arm8 --with-production -g3 -j \
---without-romio --build-shared
-popd
-```
-
 #### Install with Spack
 
 ```sh
@@ -128,28 +128,31 @@ git checkout releases/latest
 . ./share/spack/setup-env.sh
 # Find some system packages so we don't have to install them all from source
 spack external find
-spack external find python
 # Install dependencies
 spack install \
-  blaze@3.8.2 \
-  charmpp@7.0.0: +shared backend=multicore \
-  libxsmm@main \
+  charmpp@7.0.0: +shared backend=multicore build-target=charm++ \
+  blaze@3.8.2 ~blas ~lapack smp=none \
+  libxsmm@1.16.1: \
 ```
 
 ### 5. Configure and build SpECTRE
 
 Create a build directory in a location of your choice, e.g.
-```
-cd ${SPECTRE_HOME}
+
+```sh
+cd $SPECTRE_HOME
 mkdir build
 cd build
 ```
 
 Next, configure SpECTRE using the following CMake command. If you installed
 dependencies with Spack, you can use `spack find -p` to retrieve the root
 directories of the packages and replace them in the command below.
+You only need to specify `LIBXSMM_ROOT` and `BLAZE_ROOT` if you installed
+those packages yourself above. The option `SPECTRE_FETCH_MISSING_DEPS` will
+take care of downloading these if you haven't installed them above.
 
-```
+```sh
 cmake \
 -D CMAKE_C_COMPILER=clang \
 -D CMAKE_CXX_COMPILER=clang++ \
@@ -158,21 +161,26 @@ cmake \
 -D BUILD_SHARED_LIBS=ON \
 -D MEMORY_ALLOCATOR=SYSTEM \
 -D CHARM_ROOT=${SPECTRE_DEPS_ROOT}/charm/multicore-darwin-arm8 \
+-D SPECTRE_FETCH_MISSING_DEPS=ON \
 -D SPECTRE_TEST_TIMEOUT_FACTOR=5 \
+-D BLAS_ROOT=$(brew --prefix openblas) \
+-D LAPACK_ROOT=$(brew --prefix openblas) \
 -D LIBXSMM_ROOT=${SPECTRE_DEPS_ROOT}/libxsmm/ \
 -D BLAZE_ROOT=${SPECTRE_DEPS_ROOT}/blaze/ \
 ..
 ```
 
 Finally, build and test SpECTRE. E.g., on a Mac with 10 cores,
-```
+
+```sh
 make -j10 unit-tests
 make -j10 test-executables
 ctest --output-on-failure -j10
 ```
 
 Optionally, to install the python bindings in your python environment,
-```
-make all-pybindings
+
+```sh
+make -j10 all-pybindings
 pip install -e ${SPECTRE_HOME}/build/bin/python
 ```