summaryrefslogtreecommitdiffstats
path: root/src/H5FDsubfiling/mercury/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'src/H5FDsubfiling/mercury/README.md')
-rw-r--r--src/H5FDsubfiling/mercury/README.md230
1 files changed, 230 insertions, 0 deletions
diff --git a/src/H5FDsubfiling/mercury/README.md b/src/H5FDsubfiling/mercury/README.md
new file mode 100644
index 0000000..d159548
--- /dev/null
+++ b/src/H5FDsubfiling/mercury/README.md
@@ -0,0 +1,230 @@
+Mercury
+=======
+[![Build status][github-ci-svg]][github-ci-link]
+[![Latest version][mercury-release-svg]][mercury-release-link]
+[![Spack version][spack-release-svg]][spack-release-link]
+
+Mercury is an RPC framework specifically designed for use in HPC systems
+that allows asynchronous transfer of parameters and execution requests,
+as well as direct support of large data arguments. The network implementation
+is abstracted, allowing easy porting to future systems and efficient use
+of existing native transport mechanisms. Mercury's interface is generic
+and allows any function call to be serialized.
+Mercury is a core component of the [Mochi][mochi-link] ecosystem of
+microservices.
+
+Please see the accompanying LICENSE.txt file for license details.
+
+Contributions and patches are welcomed but require a Contributor License
+Agreement (CLA) to be filled out. Please contact us if you are interested
+in contributing to Mercury by subscribing to the
+[mailing lists][mailing-lists].
+
+Architectures supported
+=======================
+
+Architectures supported by MPI implementations are generally supported by the
+network abstraction layer.
+
+The OFI libfabric plugin as well as the SM plugin
+are stable and provide the best performance in most workloads. Libfabric
+providers currently supported are: `tcp`, `verbs`, `psm2`, `gni`.
+
+The UCX plugin is also available as an alternative transport on platforms
+for which libfabric is either not available or not recommended to use,
+currently supported protocols are tcp and verbs.
+
+MPI and BMI (tcp) plugins are still supported but gradually being moved as
+deprecated, therefore should only be used as fallback methods.
+The CCI plugin is deprecated and no longer supported.
+
+See the [plugin requirements](#plugin-requirements) section for
+plugin requirement details.
+
+Documentation
+=============
+
+Please see the documentation available on the mercury [website][documentation]
+for a quick introduction to Mercury.
+
+Software requirements
+=====================
+
+Compiling and running Mercury requires up-to-date versions of various
+software packages. Beware that using excessively old versions of these
+packages can cause indirect errors that are very difficult to track down.
+
+Plugin requirements
+-------------------
+
+To make use of the OFI libfabric plugin, please refer to the libfabric build
+instructions available on this [page][libfabric].
+
+To make use of the UCX plugin, please refer to the UCX build
+instructions available on this [page][ucx].
+
+To make use of the native NA SM (shared-memory) plugin on Linux,
+the cross-memory attach (CMA) feature introduced in kernel v3.2 is required.
+The yama security module must also be configured to allow remote process memory
+to be accessed (see this [page][yama]). On MacOS, code signing with inclusion of
+the na_sm.plist file into the binary is currently required to allow process
+memory to be accessed.
+
+To make use of the BMI plugin, the most convenient way is to install it through
+spack or one can also do:
+
+ git clone https://github.com/radix-io/bmi.git && cd bmi
+ ./prepare && ./configure --enable-shared --enable-bmi-only
+ make && make install
+
+To make use of the MPI plugin, Mercury requires a _well-configured_ MPI
+implementation (MPICH2 v1.4.1 or higher / OpenMPI v1.6 or higher) with
+`MPI_THREAD_MULTIPLE` available on targets that will accept remote
+connections. Processes that are _not_ accepting incoming connections are
+_not_ required to have a multithreaded level of execution.
+
+Optional requirements
+---------------------
+
+For optional automatic code generation features (which are used for generating
+serialization and deserialization routines), the preprocessor subset of the
+BOOST library must be included (Boost v1.48 or higher is recommended).
+The library itself is therefore not necessary since only the header is used.
+Mercury includes those headers if one does not have BOOST installed and
+wants to make use of this feature.
+
+Building
+========
+
+If you install the full sources, put the tarball in a directory where you
+have permissions (e.g., your home directory) and unpack it:
+
+ bzip2 -dc mercury-X.tar.bz2 | tar xvf -
+
+Replace `'X'` with the version number of the package.
+
+(Optional) If you checked out the sources using git (without the `--recursive`
+option) and want to build the testing suite (which requires the kwsys
+submodule) or use checksums (which requires the mchecksum submodule), you need
+to issue from the root of the source directory the following command:
+
+ git submodule update --init
+
+Mercury makes use of the CMake build-system and requires that you do an
+out-of-source build. In order to do that, you must create a new build
+directory and run the `ccmake` command from it:
+
+ cd mercury-X
+ mkdir build
+ cd build
+ ccmake .. (where ".." is the relative path to the mercury-X directory)
+
+Type `'c'` multiple times and choose suitable options. Recommended options are:
+
+ BUILD_SHARED_LIBS ON (or OFF if the library you link
+ against requires static libraries)
+ BUILD_TESTING ON
+ Boost_INCLUDE_DIR /path/to/include/directory
+ CMAKE_INSTALL_PREFIX /path/to/install/directory
+ MERCURY_ENABLE_DEBUG ON/OFF
+ MERCURY_ENABLE_PARALLEL_TESTING ON/OFF
+ MERCURY_USE_BOOST_PP ON
+ MERCURY_USE_CHECKSUMS ON
+ MERCURY_USE_SYSTEM_BOOST ON/OFF
+ MERCURY_USE_SYSTEM_MCHECKSUM ON/OFF
+ MERCURY_USE_XDR OFF
+ NA_USE_BMI ON/OFF
+ NA_USE_MPI ON/OFF
+ NA_USE_CCI ON/OFF
+ NA_USE_OFI ON/OFF
+ NA_USE_SM ON/OFF
+ NA_USE_UCX ON/OFF
+
+Setting include directory and library paths may require you to toggle to
+the advanced mode by typing `'t'`. Once you are done and do not see any
+errors, type `'g'` to generate makefiles. Once you exit the CMake
+configuration screen and are ready to build the targets, do:
+
+ make
+
+(Optional) Verbose compile/build output:
+
+This is done by inserting `VERBOSE=1` in the `make` command. E.g.:
+
+ make VERBOSE=1
+
+Installing
+==========
+
+Assuming that the `CMAKE_INSTALL_PREFIX` has been set (see previous step)
+and that you have write permissions to the destination directory, do
+from the build directory:
+
+ make install
+
+Testing
+=======
+
+Tests can be run to check that basic RPC functionality (requests and bulk
+data transfers) is properly working. CTest is used to run the tests,
+simply run from the build directory:
+
+ ctest .
+
+(Optional) Verbose testing:
+
+This is done by inserting `-V` in the `ctest` command. E.g.:
+
+ ctest -V .
+
+Extra verbose information can be displayed by inserting `-VV`. E.g.:
+
+ ctest -VV .
+
+Some tests run with one server process and X client processes. To change the
+number of client processes that are being used, the `MPIEXEC_MAX_NUMPROCS`
+variable needs to be modified (toggle to advanced mode if you do not see
+it). The default value is automatically detected by CMake based on the number
+of cores that are available.
+Note that you need to run `make` again after the makefile generation
+to use the new value.
+
+FAQ
+===
+
+Below is a list of the most common questions.
+
+- _Q: Why am I getting undefined references to libfabric symbols?_
+
+ A: In rare occasions, multiple copies of the libfabric library are installed
+ on the same system. To make sure that you are using the correct copy of the
+ libfabric library, do:
+
+ ldconfig -p | grep libfabric
+
+ If the library returned is not the one that you would expect, make sure to
+ either set `LD_LIBRARY_PATH` or add an entry in your `/etc/ld.so.conf.d`
+ directory.
+
+- _Q: Is there any logging mechanism?_
+
+ A: To turn on error/warning/debug logs, the `HG_LOG_LEVEL` environment
+ variable can be set to either `error`, `warning` or `debug` values. Note that
+ for debugging output to be printed, the CMake variable `MERCURY_ENABLE_DEBUG`
+ must also be set at compile time. Specific subsystems can be selected using
+ the `HG_LOG_SUBSYS` environment variable.
+
+[mailing-lists]: http://mercury-hpc.github.io/help#mailing-lists
+[documentation]: http://mercury-hpc.github.io/documentation/
+[cci]: http://cci-forum.com/?page_id=46
+[libfabric]: https://github.com/ofiwg/libfabric
+[ucx]: https://openucx.readthedocs.io/en/master/running.html#ucx-build-and-install
+[github-ci-svg]: https://github.com/mercury-hpc/mercury/actions/workflows/ci.yml/badge.svg?branch=master
+[github-ci-link]: https://github.com/mercury-hpc/mercury/actions/workflows/ci.yml
+[mercury-release-svg]: https://img.shields.io/github/release/mercury-hpc/mercury/all.svg
+[mercury-release-link]: https://github.com/mercury-hpc/mercury/releases
+[spack-release-svg]: https://img.shields.io/spack/v/mercury.svg
+[spack-release-link]: https://spack.readthedocs.io/en/latest/package_list.html#mercury
+[yama]: https://www.kernel.org/doc/Documentation/security/Yama.txt
+[mochi-link]: https://github.com/mochi-hpc/
+