Line data    Source code

       1           0 : \cond NEVER
       2             : Distributed under the MIT License.
       3             : See LICENSE.txt for details.
       4             : \endcond
       5             : ## Installing SpECTRE on Apple Silicon {#installation_on_apple_silicon}
       6             : 
       7             : \tableofcontents
       8             : 
       9             : The following instructions show how to install SpECTRE and its dependencies
      10             : on Apple Silicon Macs. Apple Silicon is an arm64 architecture, in contrast
      11             : to the x86-64 architecture that SpECTRE usually targets. These instructions
      12             : will result in an Apple Silicon native build of SpECTRE.
      13             : 
      14             : \note Floating-point exception trapping is not currently
      15             : supported on Apple Silicon.
      16             : 
      17             : ### 0. Install the xcode command-line tools.
      18             : 
      19             : Install the xcode command-line tools, which include the clang compiler, etc.
      20             : Run the following command in the terminal:
      21             : 
      22             : ```
      23             : xcode-select --install
      24             : ```
      25             : 
      26             : ### 1. Clone spectre and make a directory to install prerequisites
      27             : 
      28             : First, make a directory to hold some prerequisites that spectre depends on.
      29             : Name this directory whatever you like, and set `SPECTRE_DEPS_ROOT` to its value.
      30             : These instructions, as an example, set this to the `apps` directory in the
      31             : user's home folder.
      32             : ```
      33             : cd $HOME
      34             : git clone git@github.com:sxs-collaboration/spectre.git
      35             : cd spectre
      36             : export SPECTRE_HOME=$(pwd)
      37             : export SPECTRE_DEPS_ROOT=$HOME/apps
      38             : mkdir $SPECTRE_DEPS_ROOT
      39             : cd $SPECTRE_DEPS_ROOT
      40             : ```
      41             : 
      42             : ### 2. Install python dependencies
      43             : 
      44             : Spectre depends on python and some python packages. There are different ways to
      45             : install an arm64-native python stack. The following instructions show how
      46             : to do this using the Python 3 interpreter bundled with macOS.
      47             : 
      48             : ```sh
      49             : cd $SPECTRE_HOME
      50             : 
      51             : # Create a Python environment
      52             : python3 -m venv ./env --upgrade-deps
      53             : 
      54             : # Activate the Python environment
      55             : . ./env/bin/activate
      56             : 
      57             : # Install Python packages
      58             : pip install -r support/Python/requirements.txt \
      59             :   -r support/Python/dev_requirements.txt
      60             : 
      61             : # Optionally install additional packages you might want, like Jupyter
      62             : pip install jupyterlab
      63             : ```
      64             : 
      65             : ### 3. Install dependencies with Homebrew
      66             : 
      67             : Most of spectre's dependencies beyond python can be installed using the
      68             : [homebrew](https://brew.sh) package manager. First, if you haven't
      69             : already, install Homebrew by
      70             : following the instructions on the [homebrew](https://brew.sh) homepage. Then,
      71             : run the following to install a fortran compiler and other dependencies:
      72             : ```
      73             : brew install gcc
      74             : brew install boost gsl cmake doxygen catch2 openblas
      75             : brew install ccache autoconf automake jemalloc hdf5 yaml-cpp
      76             : ```
      77             : 
      78             : ### 4. Install remaining dependencies
      79             : 
      80             : Here, install the remaining dependencies that cannot be installed
      81             : with homebrew or miniforge. You can install them from source manually, or use
      82             : the [Spack](https://github.com/spack/spack) package manager.
      83             : 
      84             : #### Install manually
      85             : 
      86             : ```
      87             : export SPECTRE_DEPS_ROOT=$HOME/apps
      88             : ```
      89             : 
      90             : ```
      91             : cd $SPECTRE_DEPS_ROOT
      92             : mkdir blaze
      93             : pushd blaze
      94             : curl -L https://bitbucket.org/blaze-lib/blaze/downloads/blaze-3.8.tar.gz \
      95             : > blaze-3.8.tar.gz
      96             : tar -xf blaze-3.8.tar.gz
      97             : mv blaze-3.8 include
      98             : popd
      99             : 
     100             : # Need master branch of libxsmm to support Apple Silicon
     101             : git clone https://github.com/hfp/libxsmm.git
     102             : pushd libxsmm
     103             : make
     104             : popd
     105             : ```
     106             : 
     107             : Next, clone, patch, and install charm++ v7.0.0.
     108             : ```
     109             : git clone https://github.com/UIUC-PPL/charm
     110             : pushd charm
     111             : git checkout v7.0.0
     112             : git apply $SPECTRE_HOME/support/charm/v7.0.0.patch
     113             : ./build LIBS multicore-darwin-arm8 --with-production -g3 -j \
     114             : --without-romio --build-shared
     115             : popd
     116             : ```
     117             : 
     118             : #### Install with Spack
     119             : 
     120             : ```sh
     121             : # Download spack
     122             : cd ~
     123             : git clone -c feature.manyFiles=true https://github.com/spack/spack.git
     124             : cd spack
     125             : # Switch to latest release
     126             : git checkout releases/latest
     127             : # Load shell support
     128             : . ./share/spack/setup-env.sh
     129             : # Find some system packages so we don't have to install them all from source
     130             : spack external find
     131             : spack external find python
     132             : # Install dependencies
     133             : spack install \
     134             :   blaze@3.8.2 \
     135             :   charmpp@7.0.0: +shared backend=multicore \
     136             :   libxsmm@main \
     137             : ```
     138             : 
     139             : ### 5. Configure and build SpECTRE
     140             : 
     141             : Create a build directory in a location of your choice, e.g.
     142             : ```
     143             : cd ${SPECTRE_HOME}
     144             : mkdir build
     145             : cd build
     146             : ```
     147             : 
     148             : Next, configure SpECTRE using the following CMake command. If you installed
     149             : dependencies with Spack, you can use `spack find -p` to retrieve the root
     150             : directories of the packages and replace them in the command below.
     151             : 
     152             : ```
     153             : cmake \
     154             : -D CMAKE_C_COMPILER=clang \
     155             : -D CMAKE_CXX_COMPILER=clang++ \
     156             : -D CMAKE_Fortran_COMPILER=gfortran \
     157             : -D CMAKE_BUILD_TYPE=Debug \
     158             : -D BUILD_SHARED_LIBS=ON \
     159             : -D MEMORY_ALLOCATOR=SYSTEM \
     160             : -D CHARM_ROOT=${SPECTRE_DEPS_ROOT}/charm/multicore-darwin-arm8 \
     161             : -D SPECTRE_TEST_TIMEOUT_FACTOR=5 \
     162             : -D LIBXSMM_ROOT=${SPECTRE_DEPS_ROOT}/libxsmm/ \
     163             : -D BLAZE_ROOT=${SPECTRE_DEPS_ROOT}/blaze/ \
     164             : ..
     165             : ```
     166             : 
     167             : Finally, build and test SpECTRE. E.g., on a Mac with 10 cores,
     168             : ```
     169             : make -j10 unit-tests
     170             : make -j10 test-executables
     171             : ctest --output-on-failure -j10
     172             : ```
     173             : 
     174             : Optionally, to install the python bindings in your python environment,
     175             : ```
     176             : make all-pybindings
     177             : pip install -e ${SPECTRE_HOME}/build/bin/python
     178             : ```