Skip to content

Installation

Haero builds and runs on the following platforms:

  • Mac and Linux laptops and workstations
  • NERSC Cori
  • Compy and Constance at PNNL

Required Software

To build Haero, you need:

  • CMake v3.12+
  • GNU Make
  • reliable C and C++ compilers
  • a good Fortran compiler, such as GNU gfortran or Intel's ifort compiler
  • a working MPI installation (like OpenMPI or Mpich).

You can obtain all of these (except perhaps your favorite Fortran compiler) freely on the Linux and Mac platforms. On Linux, just use your favorite package manager. On a Mac, you can get the Clang C/C++ compiler by installing XCode, and then use a package manager like Homebrew or MacPorts to get the rest.

For example, to download the relevant software on your Mac using Homebrew, type

brew install cmake gfortran openmpi

Clone the Repository

First, go get the source code at GitHub:

git clone git@github.com:eagles-project/haero.git

git clone https://github.com/eagles-project/haero.git

This places a haero folder into your current path.

Configure Haero

Haero uses CMake, and accepts a number of options that specify how it should be built. In order to simplify the build process, we've provided a simple setup script that generates a shell script you can run to invoke CMake with the appropriate options set.

To configure Haero:

  1. Create a build directory by running the setup script from the top-level source directory: 
    ./setup build
  2. Change to your build directory and edit the config.sh file to select configuration options. Then run ./config.sh to configure the model.

If you prefer, you can fish the options out of the setup script (or your generated config.sh file) and feed them directly to CMake.

Build, Test, and Install Haero

After you've configured Haero, you can build it:

  1. From the build directory, type make -j to build the library. (If you've configured your build for a GPU, place a number after the -j flag, as in make -j 8).
  2. To run tests for the library (and the driver, if configured), type make test.
  3. To install the model to the location indicated by PREFIX in your config.sh script (or CMAKE_INSTALL_PREFIX, if you specified it manually), type make install. By default, products are installed in include, lib, bin, and share Ñ•ubdirectories within your build directory.

Making code changes and rebuilding

Notice that you must build Haero in a build tree, separate from its source trees. This is standard practice in CMake-based build systems, and it allows you to build several different configurations without leaving generated and compiled files all over your source directory. However, you might have to change the way you work in order to be productive in this kind of environment.

When you make a code change, make sure you build from the build directory that you created in step 1 above:

cd /path/to/haero/build
make -j

You can also run tests from this build directory with make test.

This is very different from how some people like to work. One method of making this easier is to use an editor in a dedicated window, and have another window open with a terminal, sitting in your build directory. If you're using a fancy modern editor, it might have a CMake-based workflow that handles all of this for you.

The build directory has a structure that mirrors the source directory, and you can type make in any one of its subdirectories to do partial builds. In practice, though, it's safest to always build from the top of the build tree.

Generating Documentation

Haero's documentation is built using Material for Mkdocs, which is a static website generator with lots of features. Currently, though, the Haero repository is private, so we don't publish the documentation to a web site. Instead, if you've installed Mkdocs, you can run a local server to view the documentation.

FAQ

  • When I run config.sh, I see an error complaining about a bad fd number! You probably typed sh config.sh to run the configuration script. It's actually a bash script. Just type ./config.sh.
  • How do I "reconfigure my build"? If you want to change a compile-time parameter in your model, you must reconfigure and rebuild it. To do this, edit your config.sh and change the parameter as needed. Then rerun it with ./config.sh. After the script finishes, executing you can type make -j to rebuild the model.
  • A pull request has the reconfig required label. What does this mean? A pull request with the reconfig required label has made a change to the structure of the config.sh script, so you must rerun setup <build_dir> to regenerate your config.sh script. Once you've regenerated this script, you can reconfigure and build as usual.