diff --git a/docs/build.rst b/docs/build.rst index e62b5550..c269c02c 100644 --- a/docs/build.rst +++ b/docs/build.rst @@ -2,8 +2,10 @@ Build UnifyFS ============= -This section describes how to build UnifyFS and its dependencies. -There are three options: +This section describes how to build UnifyFS and its dependencies, and what +:ref:`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 @@ -22,7 +24,7 @@ If you use a clone of the Spack develop branch, be sure to pull the latest chang .. warning:: **Thallium, Mochi Suite, and SDS Repo Users** The available and UnifyFS-compatible Mochi-Margo versions that are in the - ``mochi-margo`` Spack package do not match up with the latest/default + ``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 @@ -60,17 +62,18 @@ variants. .. table:: UnifyFS Build Variants :widths: auto - ========== ============================= ======= =========================== + ========== ============================= ======= ================================= Variant Command Default Description (``spack install ``) - ========== ============================= ======= =========================== + ========== ============================= ======= ================================= Auto-mount ``unifyfs+auto-mount`` True Enable transparent mounting - Boostsys ``unifyfs+boostsys` False Have Mercury use Boost + 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:: @@ -219,6 +222,7 @@ after ``./autogen.sh`` has been run. ---------- +.. _configure-options-label: ----------------- Configure Options ----------------- diff --git a/docs/conf.py b/docs/conf.py index 335c89a6..e3b40523 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,9 +54,9 @@ # built documents. # # The short X.Y version. -version = u'1.0.1' +version = u'1.1' # The full version, including alpha/beta/rc tags. -release = u'1.0.1' +release = u'1.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/examples.rst b/docs/examples.rst index 9d3f642e..507cfb9c 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -7,6 +7,8 @@ build into static, GOTCHA, and pure POSIX (not linked with UnifyFS) versions depending on how they are linked. Several of the example programs are also used in the UnifyFS :doc:`intregraton testing `. +---------- + Locations of Examples ===================== @@ -174,6 +176,8 @@ One form of running this example could be: $ srun -N4 -n4 write-static -m /unifyfs -f myTestFile +---------- + Producer-Consumer Workflow ========================== diff --git a/docs/limitations.rst b/docs/limitations.rst index c81274a8..424470c3 100644 --- a/docs/limitations.rst +++ b/docs/limitations.rst @@ -56,6 +56,8 @@ Directory Operations UnifyFS does not support directory operations. +---------- + --------------------------- MPI-IO Limitations --------------------------- @@ -151,6 +153,8 @@ standard and execute a full sync-barrier-sync construct. There exist potential optimizations such that future implementations of UnifyFS may require the full sequence of calls. +---------- + --------------------------- ROMIO Limitations --------------------------- @@ -272,6 +276,8 @@ Functions that use shared file pointers include:: MPI_File_write_ordered() MPI_File_read_ordered() +---------- + --------------------------- HDF5 Limitations --------------------------- @@ -328,6 +334,8 @@ environment variable ``HDF5_DO_MPI_FILE_SYNC=1``. Enabling this option can decrease write performance since it may induce more file flush operations than necessary. +---------- + ------------------- PnetCDF Limitations ------------------- diff --git a/docs/link.rst b/docs/link.rst index 7d07e372..8b29429d 100644 --- a/docs/link.rst +++ b/docs/link.rst @@ -7,7 +7,7 @@ The UnifyFS library contains symbols for the UnifyFS API, like unifyfs_mount, as well as wrappers for I/O routines, like open, write, and close. In the examples below, replace with the path to your UnifyFS install. ---------------------------- +---------- ----------- Static link @@ -25,6 +25,8 @@ To make this easier, UnifyFS installs a unifyfs-config script that one should in test_write.c \ `/bin/unifyfs-config --post-ld-flags` +---------- + ------------ Dynamic link ------------ diff --git a/docs/run.rst b/docs/run.rst index e0f7bec3..1ed88935 100644 --- a/docs/run.rst +++ b/docs/run.rst @@ -17,6 +17,8 @@ Overall, the steps to run an application with UnifyFS include: 5. Terminate the UnifyFS servers using ``unifyfs`` +---------- + ------------- Start UnifyFS ------------- @@ -95,6 +97,8 @@ Only applications that explicitly call ``unifyfs_mount()`` and access files under the specified mountpoint prefix will utilize UnifyFS for their I/O. All other applications will operate unchanged. +---------- + ------------ Stop UnifyFS ------------ @@ -104,6 +108,8 @@ After all UnifyFS-enabled applications have completed running, use ``unifyfs start`` to have the servers remove temporary data locally stored on each node after termination. +---------- + -------------------------------- Resource Manager Job Integration -------------------------------- @@ -121,9 +127,11 @@ within the source repository at ``util/scripts/lsfcsm``. Support for the SLURM resource manager is under development. ------------------------------------------ +---------- + +--------------------------------------- Transferring Data In and Out of UnifyFS ------------------------------------------ +--------------------------------------- Data can be transferred in/out of UnifyFS during server startup and termination, or at any point during a job using two stand-alone applications. @@ -254,9 +262,11 @@ Examples: $ srun -N 4 -n 8 unifyfs-stage --parallel $MY_MANIFEST_FILE +---------- +--------------------- UnifyFS LS Executable -^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------- The ``unifyfs-ls`` program is installed in the same directory as the ``unifyfs`` utility (i.e., ``$UNIFYFS_INSTALL/bin``). This tool will provide