Build UnifyFS

This section describes how to build UnifyFS and its dependencies, and what configure time options are available.

There are three build options:

build both UnifyFS and 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 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.

Warning

Thallium, Mochi Suite, and SDS Repo Users

The available and UnifyFS-compatible Mochi-Margo versions that are in the mochi-margo Spack package may not match up with the latest/default versions in the Mochi Suite, SDS Repo, and mochi-thallium Spack packages. It is likely that a different version of mochi-margo will need to be specified in the install command of UnifyFS (E.g.: spack install unifyfs ^mochi-margo@0.13.1).

Install Spack

$ git clone https://github.com/spack/spack
$ # create a packages.yaml specific to your machine
$ . spack/share/spack/setup-env.sh

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

Build and Install UnifyFS

$ 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 information on available variants.

UnifyFS Build Variants
Variant	Command (`spack install <package>`)	Default	Description
Auto-mount	`unifyfs+auto-mount`	True	Enable transparent mounting
Boostsys	`unifyfs+boostsys`	False	Have Mercury use Boost
Fortran	`unifyfs+fortran`	True	Enable Fortran support
PMI	`unifyfs+pmi`	False	Enable PMI2 support
PMIx	`unifyfs+pmix`	False	Enable PMIx support
Preload	`unifyfs+preload`	False	Enable LD_PRELOAD library support
SPath	`unifyfs+spath`	True	Normalize relative paths

Attention

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@0.13.1 ^libfabric fabrics=rxm,sockets,tcp
$ spack install spath~mpi

Tip

Run spack install --only=dependencies unifyfs to install all UnifyFS dependencies without installing UnifyFS itself.

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 (‘dev’) from the UnifyFS repository https://github.com/LLNL/UnifyFS.

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
$
$ gotcha_install=$(spack location -i gotcha)
$ spath_install=$(spack location -i spath)
$
$ ./autogen.sh # skip if using release tarball
$ ./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

To see all available build configuration options, run ./configure --help after ./autogen.sh 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 (‘dev’) from the UnifyFS repository https://github.com/LLNL/UnifyFS.

Build the Dependencies

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

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

$ ./bootstrap.sh

Note

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

Before building the UnifyFS dependencies, the bootstrap.sh 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 bootstrap.sh 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
$ export LD_LIBRARY_PATH=$INSTALL_DIR/lib:$INSTALL_DIR/lib64:$LD_LIBRARY_PATH
$ ./autogen.sh # skip if using release tarball
$ ./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 ./autogen.sh has been run.

Note

On Cray systems, the detection of MPI compiler wrappers requires passing the following flags to the configure command: MPICC=cc MPIFC=ftn

Configure Options

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

Fortran

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.

Note

UnifyFS requires GOTCHA when Fortran support is enabled

GOTCHA

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.

Warning

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.

HDF5

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.

SPATH

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.

Intercepting I/O Calls from Shell Commands

An optional preload library can be used to intercept I/O function calls made by shell commands, which allows one to run shell commands as a client to interact with UnifyFS. To build this library, use the --enable-preload configure option. At run time, one should start the UnifyFS server as normal. One must then set the LD_PRELOAD environment variable to point to the installed library location within the shell. For example, a bash user can set:

$ export LD_PRELOAD=/path/to/install/lib/libunifyfs_preload_gotcha.so

One can then interact with UnifyFS through subsequent shell commands, such as:

$ touch /unifyfs/file1
$ cp -pr /unifyfs/file1 /unifyfs/file2
$ ls -l /unifyfs/file1
$ stat /unifyfs/file1
$ rm /unifyfs/file1

The default mountpoint used is /unifyfs. This can be changed by setting the UNIFYFS_PRELOAD_MOUNTPOINT environment variable.

Note

Due to the variety and variation of I/O functions that may be called by different commands, there is no guarantee that a given invocation is supported under UnifyFS semantics. This feature is experimental, and it should be used at one’s own risk.