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.
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-g54e2b03
=================================================================
-- 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 useDebug
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
andIntel
.
-
-
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
andIntel
.
-