Build UnifyFS

This section describes how to build UnifyFS and its dependencies. There are three options:

  • build both UnifyFS and its dependencies with Spack,
  • build the dependencies with Spack, but build UnifyFS with autotools
  • build the dependencies with a bootstrap script, and build UnifyFS with autotools

Build UnifyFS and its dependencies with Spack

One may install UnifyFS and its dependencies with Spack. If you already have Spack, make sure you have the latest release. If you use a clone of the Spack develop branch, be sure to pull the latest changes.

Install Spack

$ git clone
$ # create a packages.yaml specific to your machine
$ . spack/share/spack/

Use Spack’s shell support to add Spack to your PATH and enable use of the spack command.

Build UnifyFS and its dependencies

$ spack install unifyfs
$ spack load unifyfs

If the most recent changes on the development branch (‘dev’) of UnifyFS are desired, then do spack install unifyfs@develop.

Include or remove variants with Spack when installing UnifyFS when a custom build is desired. Run spack info unifyfs for more info.

UnifyFS Build Variants
Variant Command (spack install <package>) Default Description
Auto-mount unifyfs+auto-mount True Enable transparent mounting


unifyfs+hdf5 ^hdf5~mpi



Build with parallel HDF5

Build with serial HDF5

Fortran unifyfs+fortran False Enable Fortran support
PMI unifyfs+pmi False Enable PMI2 support
PMIx unifyfs+pmix False Enable PMIx support
spath unifyfs+spath True Normalize relative paths


The initial install could take a while as Spack will install build dependencies (autoconf, automake, m4, libtool, and pkg-config) as well as any dependencies of dependencies (cmake, perl, etc.) if you don’t already have these dependencies installed through Spack or haven’t told Spack where they are locally installed on your system (i.e., through a custom packages.yaml). Run spack spec -I unifyfs before installing to see what Spack is going to do.

Build dependencies with Spack, build UnifyFS with autotools

One can install the UnifyFS dependencies with Spack and build UnifyFS with autotools. This is useful if one needs to modify the UnifyFS source code between builds. Take advantage of Spack Environments to streamline this process.

Build the dependencies

Once Spack is installed on your system (see above), the UnifyFS dependencies can then be installed.

$ spack install gotcha
$ spack install mochi-margo ^libfabric fabrics=rxm,sockets,tcp
$ spack install spath~mpi


You can run spack install --only=dependencies unifyfs to install all UnifyFS dependencies without installing UnifyFS.

Keep in mind this will also install all the build dependencies and dependencies of dependencies if you haven’t already installed them through Spack or told Spack where they are locally installed on your system via a packages.yaml.

Build UnifyFS

Download the latest UnifyFS release from the Releases page or clone the develop branch from the UnifyFS repository

Load the dependencies into your environment and then configure and build UnifyFS from its source code directory.

$ spack load gotcha
$ spack load argobots
$ spack load mercury
$ spack load mochi-margo
$ spack load spath
$ ./
$ ./configure --prefix=/path/to/install --with-gotcha=${gotcha_install} --with-spath=${spath_install}
$ make
$ make install

Alternatively, UnifyFS can be configured using CPPFLAGS and LDFLAGS:

$ ./configure --prefix=/path/to/install CPPFLAGS="-I${gotcha_install}/include -I{spath_install}/include" LDFLAGS="-L${gotcha_install}/lib64 -L${spath_install}/lib64

Spack package install location

The location where Spack installs any given package can be retrieved by running spack location -i <package_name>.

E.g.: gotcha_install=$(spack location -i gotcha)

To see all available build configuration options, run ./configure --help after ./ has been run.

Build dependencies with bootstrap and build UnifyFS with autotools

Download the latest UnifyFS release from the Releases page or clone the develop branch from the UnifyFS repository

Build the Dependencies

UnifyFS requires MPI, GOTCHA, Margo and OpenSSL. References to these dependencies can be found on our UnifyFS Dependencies page.

A script in the UnifyFS source distribution downloads and installs all dependencies. Simply run the script in the top level directory of the source code.

$ ./


UnifyFS requires automake version 1.15 or newer in order to build.

Before building the UnifyFS dependencies, the script will check the system’s current version of automake and attempt to build the autotools suite if an older version is detected.

Build UnifyFS

After installs the dependencies, it prints the commands one needs to execute to build UnifyFS. As an example, the commands may look like:

$ export PKG_CONFIG_PATH=$INSTALL_DIR/lib/pkgconfig:$INSTALL_DIR/lib64/pkgconfig:$PKG_CONFIG_PATH
$ ./
$ ./configure --prefix=/path/to/install CPPFLAGS=-I/path/to/install/include LDFLAGS="-L/path/to/install/lib -L/path/to/install/lib64"
$ make
$ make install

Alternatively, UnifyFS can be configured using --with options:

$ ./configure --prefix=/path/to/install --with-gotcha=$INSTALL_DIR --with-spath=$INSTALL_DIR

To see all available build configuration options, run ./configure --help after ./ has been run.

Configure Options

When building UnifyFS with autotools, a number of options are available to configure its functionality.


To use UnifyFS in Fortran applications, pass the --enable-fortran option to configure. Note that only GCC Fortran (i.e., gfortran) is known to work with UnifyFS. There is an open ifort_issue with the Intel Fortran compiler as well as an xlf_issue with the IBM Fortran compiler.


UnifyFS requires GOTCHA when Fortran support is enabled


GOTCHA is the preferred method for I/O interception with UnifyFS, but it is not available on all platforms. If GOTCHA is not available on your target system, you can omit it during UnifyFS configuration by using the --without-gotcha configure option. Without GOTCHA, static linker wrapping is required for I/O interception, see Link with the UnifyFS library.


UnifyFS requires GOTCHA for dynamic I/O interception of MPI-IO functions. If UnifyFS is configured using --without-gotcha, support will be lost for MPI-IO (and as a result, HDF5) applications.


UnifyFS includes example programs that use HDF5. If HDF5 is not available on your target system, it can be omitted during UnifyFS configuration by using the --without-hdf5 configure option.

PMI2/PMIx Key-Value Store

When available, UnifyFS uses the distributed key-value store capabilities provided by either PMI2 or PMIx. To enable this support, pass either the --enable-pmi or --enable-pmix option to configure. Without PMI support, a distributed file system accessible to all servers is required.


The spath library can be optionally used to normalize relative paths (e.g., ones containing “.”, “..”, and extra or trailing “/”) and enable the support of using relative paths within an application. To enable, use the --with-spath configure option or provide the appropriate CPPFLAGS and LDFLAGS at configure time.

Transparent Mounting for MPI Applications

MPI applications written in C or C++ may take advantage of the UnifyFS transparent mounting capability. With transparent mounting, calls to unifyfs_mount() and unifyfs_unmount() are automatically performed during MPI_Init() and MPI_Finalize(), respectively. Transparent mounting always uses /unifyfs as the namespace mountpoint. To enable transparent mounting, use the --enable-mpi-mount configure option.