This directory contains a cmake system for building most of the third party packages needed by Truchas. While we endeavor to make this as robust as possible, especially for the platforms we use and test on, it is inevitable that this will not work for some people. In that circumstance remember that you can build them manually (or obtain them otherwise); you don't have to make this system work. All that matters is that the Truchas cmake step can find them.
These are the third-party libraries that Truchas requires and where they can be obtained. This repository contains tar files of specific versions of each as a convenience.
- HDF5: https://www.hdfgroup.org/downloads/hdf5/
- NetCDF: https://www.unidata.ucar.edu/downloads/netcdf/
- Exodus: https://github.com/gsjaardema/seacas/
- Hypre: https://github.com/hypre-space/hypre/
- Petaca: https://github.com/nncarlson/petaca/
- YAJL: https://lloyd.github.io/yajl/
- Metis: http://glaros.dtc.umn.edu/gkhome/metis/metis/download
Truchas requires modified versions of the following libraries, which can be obtained from indicated repositories. This repository also contains tar files of the modified versions of each as a convenience.
- Chaco: https://gitlab.com/truchas/chaco/
- Chaparral: https://gitlab.com/truchas/chaparral/
- Scorpio: https://gitlab.com/truchas/scorpio/
Optional third-party libraries that Truchas may use:
- Portage: https://github.com/laristra/portage/
To build (or find) Portage include the CMake option -D BUILD_PORTAGE=ON.
This library is extra picky about compilers and dependent libraries, and
it may be difficult to get it to compile without error.
Although individually the TPLs can be built with any number of different compilers, it is strongly recommended that they be built with the same compilers used to build Truchas (the Fortran compiler vendor must be the same). Please see the BUILDING file in the Truchas distribution for a list of compilers supported by Truchas.
The packages that can be built are HDF5, NetCDF, Exodus, HYPRE, Petaca,
YAJL, Chaco, Chaparral, Scorpio, METIS, and Portage. Compressed tar files
of their source distributions can be found in the tarfiles subdirectory.
The basic procedure is simple (when it works). You create a build directory, run cmake from that directory, and then run make. What you choose for a build directory is irrelevant (other than it can't be this directory). You will also provide cmake command line arguments that customize the build in several ways. Here's an example:
$ mkdir build
$ cd build
$ cmake -C ../config/linux-intel.cmake ..
$ make
The -C argument preloads the cmake cache with settings from the following
file. The config subdirectory contains many examples. If none of those
are right for your situation, create your own, or simply define the various
variables directly on the cmake command line (using the -D flag). By
default the packages are installed into the install subdirectory of the
build directory. Add -D CMAKE_INSTALL_PREFIX=<tpl_dir> to the cmake
command line to specify a different directory (replace <tpl_dir>
with the directory path; it must be an absolute path.) Note that no make install command is necessary; the packages are automatically installed by the
make command. Also note that moving the libraries after they are installed
will often break things, so it is better to decide where you want them before
starting.
By default cmake will configure the build of all packages. You can have cmake
search for and use an existing installation of a package by setting
-D SEARCH_FOR_<pkg>=yes on the cmake command line. Here <pkg> can be
HDF5, NETCDF, EXODUS, HYPRE, YAJL, PETACA, METIS, or PORTAGE.
If it cannot find a suitable version it will go ahead and configure the
build of the package. Note that that when searching, cmake always looks first
in the installation directory.
Another command line variables is ENABLE_SHARED. The default is yes.
Setting ENABLE_SHARED to no, meaning find and build static libraries,
generally doesn't work currently except on platforms that provide a "full"
set of static system libraries (Cray, for example).
You may optionally use ninja instead of make; the main benefit is that
Ninja builds in parallel by default, while make -jX will not build the
TPL packages in parallel. To do so, you need to add a flag to the cmake
command line, and call ninja instead of make.
$ cmake -G Ninja <other flags>
$ ninja
If you find you have to build some packages manually (or obtain pre-built
ones), here are some points to keep in mind. Also look at the files in the
cmake directory to see how we are configuring them.
- Only the C interface is needed.
- The high-level library (HL) is needed.
- Be sure to enable parallel HDF5.
- Use
--with-netcdf-4 - We only use the C interface; neither the separately-distributed Fortran nor C++ libraries are needed.
- We use and test with a relative old version 5.14. There are reported incompatibilities with current 6.x versions.
- Only the C interface is needed (
--disable-fortran) - Use
--with-MPI. - Use
--without-fei; it is not needed and may have compilation problems. - Version 2.15.1 or newer is required. Note that numerical differences in different versions may produce enough variation in the output to cause some regression tests to report failures.
- We currently use version 3.0.0. The Portage API is unstable, so other versions are unlikely to work.