☰
Navigation :

MacOS CMake Installation with Homebrew

Here we give the instructions on installing Octopus using packages provided by Homebrew. MacPorts should also work, but is untested and not documented.

Preparing the homebrew environment

Installing homebrew

You can install homebrew by following the instructions on HomeBrew.

We recommend adding the following line to your .zprofile (default shell) or ~/.bash_profile (bash shell):

eval "$(/opt/homebrew/bin/brew shellenv)"

Installing the build tools and compilers

First, install CMake itself, the ninja build system and pkg-config:

brew install cmake ninja pkg-config

You also need a GNU compiler suite. Octopus supports GCC versions 12 to 15, and any of these will work — you do not need one specific version. Note however that the default gcc formula currently installs GCC 16.1, which cannot be used due to a compiler bug (see Known failures), so at the time of writing you should install a versioned formula:

brew install gcc@15

Installing mandatory packages

The following mandatory dependencies of Octopus should be installed with brew:

brew install fftw gsl

and, if you want a parallel build, also MPI:

brew install open-mpi

BLAS and LAPACK are taken from Apple’s Accelerate framework, which is part of MacOS, so they do not have to be installed.

The remaining mandatory dependencies — libxc, spglib and (for MPI builds) metis — are also available from brew:

brew install libxc spglib metis

However, when using the mac preset these packages are instead fetched and built from source automatically by CMake, and the brew versions are ignored.

We recommend **not** using the brew-installed `libxc`. While it works with sequential builds, MPI builds have a problem, which requires building `libxc` itself with `CMake`. More generally, Fortran libraries and modules are **not** compatible between different compilers: brew bottles are built with Apple clang, which can conflict with a GNU-compiled Octopus. See the [cmake README](https://gitlab.com/octopus-code/octopus/-/blob/main/cmake/README.md) for details.

Installing optional packages

Of the optional Octopus dependencies, the following are available from brew:

brew install cgal netcdf-fortran nlopt scalapack adios2

The remaining optional packages (BerkeleyGW, DFTB+, ELPA, libvdwxc, NFFT, ParMETIS, PFFT, PNFFT, PSolver, SPARSKIT) are not available in homebrew-core and must be built manually if you need them.

The mac preset disables the detection of most optional packages, to guarantee a known-good build. To use an optional package you have installed, re-enable its detection at configure time with `-DCMAKE_DISABLE_FIND_PACKAGE_=FALSE` (the package `` is case-sensitive). ScaLAPACK support is instead enabled with `-DOCTOPUS_ScaLAPACK=ON`.

Setting the compiler environment variables

When using the cmake mac preset, it is a requirement to tell CMake which compilers to use, by exporting the FC, CC, CXX and CPP environment variables (see the cmake README for more details). For GCC 15, the exports are:

export FC=$(brew --prefix)/bin/gfortran-15
export CC=$(brew --prefix)/bin/gcc-15
export CXX=$(brew --prefix)/bin/g++-15
export CPP=$(brew --prefix)/bin/cpp-15

Adjust the version suffix to match the GCC version you installed.

To make this permanent, add the lines to your shell start-up file:

The export syntax is identical in both shells; only the start-up file differs.

Alternatively, the compilers can be passed directly to CMake at configure time:

-DCMAKE_Fortran_COMPILER=$(brew --prefix)/bin/gfortran-15
-DCMAKE_C_COMPILER=$(brew --prefix)/bin/gcc-15
-DCMAKE_CXX_COMPILER=$(brew --prefix)/bin/g++-15

Note that there is no CMake variable corresponding to CPP, so exporting the environment variables is the more robust option.

Configuring and compiling with CMake

Octopus ships a mac-specific CMake preset, mac-brew-gcc, defined in cmake/CMakePresets-mac.json. It selects the ninja generator and Accelerate, disables optional packages that are known to be problematic on MacOS, and builds libxc, spglib and metis from source. With the environment in place, you can configure Octopus simply by

cmake --preset mac-brew-gcc --install-prefix=<dir>

This configures a serial build of Octopus in the cmake-build-gcc directory. If you want to enable MPI, you need to add the option

-DOCTOPUS_MPI=ON

to the above command.

The mac preset fetches and builds `libxc` from source, configured with default values, which disables the 3rd order kernels. These are needed for a subset of Octopus features, such as some Sternheimer or Casida calculations (and their corresponding tests). In case you need these kernels, add `-DLIBXC_DISABLE_KXC=OFF` to the command line.

If you want to check the result of the configuration, you can inspect the file `cmake-build-gcc/CMakeCache.txt`, which contains more details on installed packages, etc. This can also be inspected with `ccmake`: ```shell ccmake ./cmake-build-gcc ```

You can now compile the code using:

cmake --build --preset mac-brew-gcc -j

The first compilation might take a while, as it also will compile remaining dependencies, such as libxc.

Testing the compiled code

To test the code, you can invoke ctest, pointing at the build directory:

ctest --test-dir ./cmake-build-gcc -j $(sysctl -n hw.ncpu) -L short-run

This will run a subset of the tests, which should complete in about 20 minutes (depending on your machine).

Do not be surprised if a few tests fail. In some cases, floating point precision can cause calculated values to fall slightly outside the set tolerances. If most tests fail, the most likely candidate is an issue with caused by an external package. See [Known failures](#known-failures), below. For additional troubleshooting, please refer directly to the cmake README in `OCTROOT/cmake/README.md`.

Known failures

GCC 16.0 and 16.1

GCC 16.0 and 16.1 contain a compiler bug and cannot be used to build Octopus. As the default brew gcc formula currently installs GCC 16.1, make sure to install a supported version (12 to 15) via a versioned formula, e.g. brew install gcc@15, and point the compiler environment variables at it.

GSL

The brew gsl bottle is compiled with Apple clang. Linking it into a GNU-compiled Octopus is known to break the evaluation of some mathematical expressions in the input file (e.g. sqrt(n)), which shows up as input-parsing errors and testsuite failures. If you hit this, rebuild GSL from source with the same GCC used for Octopus:

brew install --build-from-source --cc=gcc-15 gsl

SPARSKIT

SPARSKIT on Mac can accidentally link to /Library/Developer/CommandLineTools/SDKs/.../usr/lib/libskit.tbd. Please disable “SPARSKIT” if that happens via CMAKE_DISABLE_FIND_PACKAGE_SPARSKIT=On, or point to a user-installed version.

Homebrew with XCode 14.x.x

XCode 14.x.x has a known bug in its linker, which causes a failure in the linking of binaries at the end of the cmake build:

A linker snapshot was created at:
	/tmp/oct-casida_spectrum-2024-03-18-130900.ld-snapshot
ld: Assertion failed: (_file->_atomsArrayCount == computedAtomCount && "more atoms allocated than expected"), function parse, file macho_relocatable_file.cpp, line 2061.
collect2: error: ld returned 1 exit status

If you are on an older version of Mac OS (12 or 13), and using Homebrew as your package manager, you may experience this problem. You may either: