5.6. Required support libraries

PMIx requires the following support libraries with the minimum listed versions:

Library

Minimum version

Notes

Hardware Locality

1.11.0

This library is required; PMIx will not build without it.

Libevent

2.0.21

Either libevent or libev must be provided

libev

no specified minimum

Either libevent or libev must be provided

These support libraries are fundamental to PMIx’s operation and pretty universally available in all environments. Worst case, they can easily be built from their respective source tarballs.

5.6.1. Library dependencies

These support libraries do not have dependencies upon each other. However, it often is true that another library being used by an application, or the application itself, can include a dependency on one or more of them.

At run time, it is critical that the run-time linker loads exactly one copy of each of these libraries. It is therefore vital that you have a clear understanding of the dependencies within your application.

5.6.2. Potential problems

Problems can (will) arise if multiple different copies of the above shared libraries are loaded into a single process. For example, consider if:

  • Loading the PMIx shared library causes the loading of Libevent shared library vA.B.C.

  • But then the subsequent loading of the FOO shared library causes the loading of Libevent shared library vX.Y.Z.

Since there are now two different versions of the Libevent shared library loaded into the same process (yes, this can happen!), unpredictable behavior can (will) occur.

Many variations on this same basic erroneous scenario are possible. All of them are bad, and can be extremely difficult to diagnose.

5.6.3. Avoiding the problems

A simple way to avoid these problems is to configure your system such that it has exactly one copy of each of the required support libraries.

Important

If possible, use your OS / environment’s package manager to install as many of these support libraries — including their development headers — as possible before invoking PMIx’s configure script.

Not all package managers provide all of the required support libraries. But even if your package manager installs — for example — only one of Libevent and Hwloc, that somewhat simplifies the final PMIx configuration, and therefore avoids some potentially erroneous configurations.

5.6.4. Overriding configure behavior

PMIx’s configure will (minus any configure flags) attempt to find the HWLOC and libevent packages in standard locations. Note that PMIx by default will look for libevent (and not libev), though either can be used. If a required package is not found and no flags were given, the configure operation will exit with a suitable error message.

If configure’s default searching behavior is not sufficient for your environment, you can use command line options to override its default behavior.

For example, if libevent and/or HWLOC are installed such that the default header file and linker search paths will not find them, you can provide command line options telling PMIx’s configure where to search. Here’s an example configure invocation where HWLOC and libevent have both been installed under the /opt directory:

./configure --prefix=$HOME/pmix-install \
    --with-libevent=/opt/libevent \
    --with-hwloc=/opt/hwloc ...

Danger

Be very, very careful when overriding configure’s default search behavior for these libraries. Remember the critical requirement: that PMIx infrastructure and applications load exactly one copy of each support library. For simplicity, it may be desirable to ensure to use exactly the support libraries that PMIx was compiled and built against.

For example, using the PMIx installed from the sample configure line (above), you may want to prefix your run-time linker search path (e.g., LD_LIBRARY_PATH on Linux) with $HOME/pmix-install/lib:/opt/libevent/lib:/opt/hwloc/lib. This will ensure that the linker finds the support libraries used by your PMIx installation tree, even if other copies of the same support libraries are present elsewhere on your system.