Building on MacOS Mojave

Oct 01, 2018

Build instructions for native Mac 2018 (but we still think docker is a good idea)

The 2018 releases of MacOS brings a new suite of compilers: homebrew binaries and any python packages involving C / Fortran will need to be rebuilt. There are also some changes to our build process.

We recommend building all the core dependencies using petsc which ensures that only compatible versions are used. This also ensures that we can use the compatible petsc version specified by underworld2 and appropriate (tested) versions of the extension packages.

When upgrading the OS , we always recommend purging homebrew altogether.

brew update
brew remove --force $(brew list)
brew doctor

if this is not an option, start with this:

brew update
brew upgrade
brew doctor

On a new machine, installing as follows:

ruby -e "$(curl -fsSL"
brew doctor

We recommend brew doctor even for a clean installation of homebrew as this will coach you through any compiler requirements. Follow the instructions until brew doctor tells you “ready to brew”.

A non-system python installation, libxml2, and swig are the only homebrew requirements, but you might also make sure that you have wget to grab a compatible version of petsc. The gcc requirement is to allow fortran dependencies to be installed. This takes a while but is worth having for later !

brew install python@2
brew install libxml2
brew install swig
brew install wget
brew install gcc   # this is needed if you choose the --download-scalapack option

If you have not done so already, you need to accept the Xcode licence (even for gcc as it builds upon the apple compilers). Try gcc --help to see if there is any issue. There are a number of python dependencies which we install via pip. If upgrading, these packages should be uninstalled and reinstalled. Note: cython is required for petsc4py which is not an underworld dependency but is worthwhile having.

pip install lavavu
pip install cython
pip install numpy
pip install scipy
pip install matplotlib
pip install jupyter
pip install runipy # currently needed for testing

We currently test against petsc-3.9.4 and we support 3.7.x, 3.8.x. You can install anywhere: the following instructions assume /usr/local/src but you can change this as necessary If you need petsc-3.10.x, you will need to access the development branch where we are currently testing compatibility.


You should set the following environment variables

export PETSC_DIR=/usr/local/src/petsc-3.9.4      # or wherever you chose to untar petsc, and your version number !
export PETSC_ARCH=opt                            # arbitrary, for your own records if you have several builds
                                                 # and you can also let PETSc decide and it will tell you what to use here.

The following is a relatively bare-bones configuration for petsc that should work with all the example notebooks we provide. From the $PETSC_DIR run the configure script and make.

./config/ --download-mumps=1 --download-mpi4py=1 \
  --download-hdf5=1 --download-scalapack --download-parmetis \
  --download-metis --download-cmake --with-debugging=0 \
  --download-mpich=1 --enable-shared=1 \
make all
make test
export PATH=$PETSC_DIR/$PETSC_ARCH/bin:$PATH                # h5pcc and mpicc

To ensure that we use the compatible packages installed by petsc and by homebrew, set the following (this is only for the configure / compile phase, no need to set these permanently )

export PYTHON_DIR=/usr/local/opt/python2/Frameworks/Python.framework/Versions/Current
export LIBXML2_DIR=/usr/local/opt/libxml2

Obtain the underworld source code from github The installation path for underworld is not especially important but you can specify it explicitly at this stage. Your python path will need to include this directory explicitly so that you can import the underworld modules.

git clone underworld2-2018.10.01

The build process for underworld has been simplified slightly from earlier versions

cd underworld2-2018.10.01
cd libUnderworld

cd underworld2-2018.10.01

Assuming that works flawlessly

export PYTHONPATH=XXX/underworld2-2018.10.01:$PYTHONPATH    # XXX = wherever you put underworld !