Build the executable

Note

Another useful resource for HEMCO build instructions is our YouTube tutorial.

Once you have created a run directory, you may proceed to compile the HEMCO standalone source code into an executable file. You will compile HEMCO standalone from your run directory.

There are two steps to build HEMCO. The first step is to configure your build settings with CMake. Build settings cover options like enabling or disabling components or whether HEMCO should be compiled in Debug mode.

The second step is to compile the source code into an executable. For this, you will use make, which builds the executable according to your build settings.

Navigate to your build directory

A subdirectory named build is included in each HEMCO standalone run directory that you create. You can use this directory (known as a build directory) to create the HEMCO executable file.

You are not limited to using the build directory that is created inside the run directory. In fact, you can create as many build directories you wish in whatever location you wish. For example, if you want to compare HEMCO standalone performance on both GNU and Intel compilers, you could create two different build directories, one named build_gnu and the other build_intel. Build directories do not necessarily need to be kept in the run directory, but it is convenient to do so.

Each build directory is self-contained, so you can delete it at any point to erase the HEMCO standalone build and its configuration. Most users will typically only need to build HEMCO standalone once, so we recommend using the build subdirectory of the run directory as the location to create the HEMCO standalone exectuable.

Important

There is one rule for build directories: a build directory should be a new directory.

In the example below, we will use the build directory within the run directory to build the HEMCO standalone executable.

Navigate to the run directory:

$ cd /path/to/hemco/run/dir

Then navigate to the build folder within:

$ cd build

Initialize the build directory

Run CMake to initialze the build directory.

$ cmake ../CodeDir -DRUNDIR=..

CodeDir is a symbolic link to the HEMCO source code directory.

The option -DRUNDIR=.. specifies that the directory where we will run HEMCO standalone is one level above us. This makes sense as our build folder is a subdirectory of the run directory. (More about build options below:

You will see output similar to this:

-- The Fortran compiler identification is GNU 11.2.0
-- Detecting Fortran compiler ABI info
-- Detecting Fortran compiler ABI info - done
-- Check for working Fortran compiler: /path/to/gfortran - skipped
-- Checking whether /path/to/gfortran supports Fortran 90
-- Checking whether /path/to/gfortran supports Fortran 90 - yes
=================================================================
HEMCO X.Y.Z
Current status: X.Y.Z
=================================================================
-- Found OpenMP_Fortran: -fopenmp (found version "4.5")
-- Found OpenMP: TRUE (found version "4.5")
-- Found NetCDF: /path/to/netcdf/lib/libnetcdff.so
-- Bootstrapping  /path/to/hemco/run/dir
-- Settings:
  * OMP:          ON  OFF
  * USE_REAL8:    ON  OFF
-- Configuring done
-- Generating done
-- Build files have been written to: /path/to/hemco/run/dir/build

In the above example output, the version number X.Y.Z will refer to the actual HEMCO version number (e.g. 3.4.0, 3.5.0, etc.). Also the paths /path/to/... in your output instead be the actual paths to the compiler and libraries.

Configuring your build

Build settings are controlled by CMake commands with the following form:

$ cmake . -D<NAME>=<VALUE>

where <NAME> is the name of the setting, and <VALUE> is the value that you are assigning it. These settings are persistent and saved in your build directory. You can set multiple variables in a single command, and you can run CMake as many times as you need to configure your desired settings.

Note

The . argument is important. It is the path to your build directory which is . here.

HEMCO has no required build settings. You can find the complete list of HEMCO’s build settings here. The most frequently used build setting is RUNDIR which lets you specify one or more run directories where CMake will install HEMCO. Here, “install” refers to copying the compiled executable, and some supplemental files with build settings, to your run directories.

Since there are no required build settings, for this tutorial we will stick with the default settings.

You should notice that when you run CMake it ends with:

...
-- Configuring done
-- Generating done
-- Build files have been written to: /path/to/hemco/run/dir/build

This tells you the configuration was successful, and that you are ready to compile.

Compile HEMCO standalone

Compile HEMCO standalone with this command

$ make -j

The -j option will tell GNU Make to compile several source code files in parallel. This reduces overall compilation time.

Optionally, you can use the VERBOSE=1 argument to see the compiler commands.

This step creates ./bin/hemco_standalone which is the compiled executable. You can copy this executable to your run directory manually, or you can do

$ make install

which copies ./bin/hemco_standalone (and some supplemental files) to the run directories specified in RUNDIR.

Now you have compiled HEMCO! You can now navigate back from the build folder to the run directory (which we remember is one level higher):

$ cd ..

Recompile when you change the source code

You need to recompile HEMCO if you update a build setting or make a modification to the source code. However, with CMake, you don’t need to clean before recompiling. The build system automatically figure out which files need to be recompiled based on your modification. This is known as incremental compiling.

To recompile HEMCO standalone, simply do

$ make -j
$ make install

which will recompile HEMCO standalone and copy the new executable file to the run directory.

HEMCO standalone build options

RUNDIR

Paths to run directories where make install installs HEMCO standalone. Multiple run directories can be specified by a semicolon separated list. A warning is issues if one of these directories does not look like a run directory.

These paths can be relative paths or absolute paths. Relative paths are interpreted as relative to your build directory.

CMAKE_BUILD_TYPE

Specifies the build type. Allowable values are:

Release: The default option. Compiles HEMCO standalone for speed.

Debug: Compiles HEMCO standalone with several debugging flags turned on. This may help you find common errors such as array-out-of-bounds, division-by-zero, or not-a-number.

Important

The additional error checks that are applied with Debug will cause HEMCO standalone to run much more slowly! Do not use Debug for long production simulations.

HEMCO_Fortran_FLAGS_<COMPILER_ID>

Additional compiler options for HEMCO standalone for build type <BUILD_TYPE>.

<COMPILER_ID>: Valid values are GNU and Intel.

HEMCO_Fortran_FLAGS_<CMAKE_BUILD_TYPE>_<COMPILER_ID>

Compiler options for HEMCO standalone for the given CMAKE_BUILD_TYPE.

<COMPILER_ID>: Valid values are GNU and Intel.