8.8.2. Installation options
The following are general installation command line options that can
be used with configure:
--prefix=DIR: Install PMIx into the base directory namedDIR. Hence, PMIx will place its executables inDIR/bin, its header files inDIR/include, its libraries inDIR/lib, etc.Note
Also see the section on installation location for more information on the installation prefix.
--disable-shared: By default, PMIx builds a shared library, and all components are included as part of those shared library. This switch disables this default; it is really only useful when used with--enable-static. Specifically, this option does not imply--enable-static; enabling static libraries and disabling shared libraries are two independent options.Tip
See this section for advice to packagers about this CLI option.
--enable-static: Build PMIx as a static library, and statically link in all components. Note that this option does not imply--disable-shared; enabling static libraries and disabling shared libraries are two independent options.Tip
See this section for advice to packagers about this CLI option.
--disable-wrapper-runpath/--disable-wrapper-rpath: By default, the wrapper compiler (pmixcc) will explicitly add “runpath” and “rpath” linker flags when linking user executables on systems that support them. That is, the created executables will include a filesystem path reference to the location of PMIx’s libraries in the application executable itself. This means that the user does not have to setLD_LIBRARY_PATHto find PMIx’s libraries, which can be helpful if they are installed in a location that the run-time linker does not search by default.Using the
--disable-wrapper-r*pathoptions will prevent the wrappers from explicitly adding one or both of these linker flags.Note
By default, the wrapper compiler prefers “runpath” behavior over “rpath” behavior.
Using
--disable-wrapper-runpathalters this preference: explicit “runpath” linker flags will not be added by the wrapper. However, “rpath” flags may still be added, if the platform supports them.Using both
--disable-wrapper-runpathand--disable-wrapper-rpathwill prevent the wrapper from explicitly adding “runpath” and “rpath” linker flags.
Caution
Even if the wrapper compiler does not explicitly add “runpath” or “rpath” linker flags, the local compiler, linker, and/or operating system may implicitly enable either “runpath” or “rpath” behavior when linking.
Important
The
--disable-wrapper-runpathand--disable-wrapper-rpathCLI options only affect the flags that the wrapper compiler uses when building PMIx-based applications. These options do not affect how PMIx is built (to include the wrapper compiler itself).See the Linker “rpath” and “runpath” functionality section for details on how “rpath” and “runpath” affect the building and linking of PMIx itself.
When either of “runpath” or “rpath” behaviors are enabled, the applications will have the filesystem path location of the PMIx library hard-coded into a PMIx-based application. The most notable differences between “runpath” and “rpath” behavior are:
runpath
The run-time linker first searches the paths in the
LD_LIBRARY_PATHenvironment variable for the relevant PMIx library.If not found there, the run-time linker falls back to checking the hard-coded location for the relevant PMIx library.
rpath
The run-time linker first checks the hard-coded location for the relevant PMIx library.
If not found there, the run-time linker falls back to searching the paths in the
LD_LIBRARY_PATHenvironment variable for the relevant PMIx library.
Warning
There are other, subtle differences between “runpath” and “rpath” which are out of scope for this documentation. You may wish to consult other sources for more information.
For example, a decent set of explanations can be found in the slides for a Linux course entitled “Building and Using Shared Libraries on Linux // Shared Libraries: The Dynamic Linker”.
For example, consider that you install PMIx vA.B.0 and compile/link your PMIx-based application against it. Later, you install PMIx vA.B.1 to a different installation prefix (e.g.,
/opt/pmix/A.B.1vs./opt/pmix/A.B.0), and you leave the old installation intact.In the runpath case, you can set the
LD_LIBRARY_PATHenvironment variable to point to the A.B.1 installation, and then your application will use those libraries, since the runtime will search the paths inLD_LIBRARY_PATHfirst.In the rpath case, since the run-time linker searches the
/opt/pmix/A.B.0location that is hard-coded in your application first, your application will use the libraries from your A.B.0 installation (regardless of the value of theLD_LIBRARY_PATHenvironment variable).Note that in both cases, however, if you remove the original A.B.0 installation and set
LD_LIBRARY_PATHto point to the A.B.1 installation, your application will use the A.B.1 libraries.As noted above, both runpath/rpath behaviors can be disabled via
--disable-wrapper-rpath.Note
You can also customize the compiler/linker flags that are used by the wrapper compilers to build PMIx-based applications.
--enable-dlopen: Enable PMIx to load components as standalone Dynamic Shared Objects (DSOs) at run-time. This option is enabled by default.The opposite of this option,
--disable-dlopen, causes the following:PMIx will not attempt to open any DSOs at run-time.
configure behaves as if the
--enable-mca-staticargument was set.configure will ignore the
--enable-mca-dsoargument.
See the description of
--enable-mca-static/--enable-mca-dsofor more information.Note
This option does not change how PMIx’s libraries (
libpmix, for example) will be built. You can change whether PMIx builds static or dynamic libraries via the--enable|disable-staticand--enable|disable-sharedarguments.
--enable-mca-dso[=LIST]and--enable-mca-static[=LIST]These two options, along with--enable-mca-no-build, govern the behavior of how PMIx’s frameworks and components are built.The
--enable-mca-dsooption specifies which frameworks and/or components are built as Dynamic Shared Objects (DSOs). Specifically, DSOs are built as “plugins” outside of the core PMIx library, and are loaded by PMIx at run time.The
--enable-mca-staticoption specifies which frameworks and/or components are built as part of the core PMIx library (i.e., they are not built as DSOs, and therefore do not need to be separately discovered and opened at run time).Both options can be used one of two ways:
--enable-mca-OPTION(with no value)--enable-mca-OPTION=LIST
--enable-mca-OPTION=noor--disable-mca-OPTIONare both legal options, but have no impact on the selection logic described below. Only affirmative options change the selection process.LISTis a comma-delimited list of PMIx frameworks and/or framework+component tuples. Examples:psecspecifies the entire PSEC frameworkpsec-nativespecifies just the NATIVE component in the PSEC frameworkplog,psec-nativespecifies the entire PLOG framework and the NATIVEcomponent in the PSEC framework
PMIx’s
configurescript uses the values of these two options when evaluating each component to determine how it should be built by evaluating these conditions in order:If an individual component’s build behavior has been specified via these two options,
configureuses that behavior.Otherwise, if the component is in a framework whose build behavior has been specified via these two options,
configureuses that behavior.Otherwise,
configureuses the global default build behavior.
At each level of the selection process, if the component is specified to be built as both a static and dso component, the static option will win.
Note
As of PMIx v4.2.3,
configure’s global default is to build all components as static (i.e., part of the PMIx core library, not as DSOs). Prior to PMIx 4.2.3, the global default behavior was to build most components as DSOs.Important
If the
--disable-dlopenoption is specified, then PMIx will not be able to search for DSOs at run time, and the value of the--enable-mca-dsooption will be silently ignored.Some examples:
Default to building all components as static (i.e., as part of the PMIx core libraries – no DSOs):
shell$ ./configure
Build all components as static, except the NATIVE PSEC, which will be built as a DSO:
shell$ ./configure --enable-mca-dso=psec-native
Build all components as static, except all PSEC components, which will be built as DSOs:
shell$ ./configure --enable-mca-dso=psec
Build all components as static, except all PLOG components and the NATIVE PSEC component, which will be built as DSOs:
shell$ ./configure --enable-mca-dso=plog,psec-native
Build all PSECs as static, except the NATIVE PSEC, as the
<framework-component>option is more specific than the<framework>option:shell$ ./configure --enable-mca-dso=psec --enable-mca-static=psec-native
Build the NATIVE PSEC as static, because the static option at the same level always wins:
shell$ ./configure --enable-mca-dso=psec-native --enable-mca-static=psec-native
Tip
See this section for advice to packagers about this CLI option.
--enable-mca-no-build=LIST: Comma-separated list of<framework>-<component>pairs that will not be built. For example,--enable-mca-no-build=plog-syslog,psensor-filewill disable building both thesyslogPLOG component and thefilePSENSOR component.Note
This option is typically only useful for components that would otherwise be built. For example, if you are on a machine without OmniPath support, it is not necessary to specify:
shell$ ./configure --enable-mca-no-build=pnet-opa
because the
configurescript will naturally see that you do not have support for OmniPath and will automatically skip theopaPNET component.Note
The
usockPTL component is always built, andconfigurestops with an error if it is excluded: a process of this release reaches a server on its host overusock. Thetcpcomponent carries every connection with a peer of an earlier release, so it is built - and cannot be excluded - whenever either of the two options below is enabled, and is left out when neither is.
PMIx releases before v7.0 reach a server over TCP, and speak wire formats of their own. Support for them comes in two directions, each with its own option:
--enable-legacy-clients: Build with support for a server taking clients and tools of PMIx releases before v7.0, which connect to it over TCP. With it, a server takes them only when theptl_base_legacy_clientsMCA parameter, or its host’sPMIX_SERVER_LEGACY_PEERSattribute, says so; the parameter defaults tofalse. Without it - the default - a server never takes them, and asking for them fails its init: clients and tools are to be updated along with their servers. A client of an earlier release - an Open MPI 5 process, say - run by a server that does not take legacy clients does not fail: it comes up as a singleton (see clients of earlier releases).--enable-legacy-servers: Build with support for a client or tool connecting to a server of PMIx v3.2 through v6.x. With it, such a server is connected to whenever a process is started by one or told of one - which a client in a container image needs if it may run under an older resource manager. Without it - the default - a process refuses such a server, and any server address over TCP, at which only such a server is reached, and says so; a client fails its init rather than coming up as a singleton. Theptl_base_legacy_serversMCA parameter, off by default, has a process that was told of no server look for one of an earlier release where those write their rendezvous files, anywhere below the system temporary directory. Set true in a build without legacy servers, it makes every client and tool fail to initialize.--enable-legacy-peers: Both of the above.--disable-legacy-peersdisables both; either option given beside it decides its own direction. With neither direction built - the default - nothing in the library speaks an earlier release’s wire format or transport, and thetcpPTL component and everybfropscomponent butv70are left out of the library.A build without legacy clients - the default - refuses the run-time settings that ask for them by name. Setting
ptl_base_legacy_clientstrue there, or a host passingPMIX_SERVER_LEGACY_PEERStrue, makes every server, launcher and scheduler fail to start.ptl_base_legacy_peersturns on only the directions the build has, so it is safe in any build. See Processes of releases before v7.0.--disable-show-load-errors-by-default: Set the default value of themca_base_component_show_load_errorsMCA variable: the--enableform of this option sets the MCA variable to true, the--disableform sets the MCA variable to false. The MCAmca_base_component_show_load_errorsvariable can still be overridden at run time via the usual MCA-variable-setting mechanisms; this configure option simply sets the default value.The
--disableform of this option is intended for PMIx packagers who tend to enable support for many different types of networks and systems in their packages. For example, consider a packager who includes support for both the FOO and BAR networks in their PMIx package, both of which require support libraries (libFOO.soandlibBAR.so). If an end user only has BAR hardware, they likely only havelibBAR.soavailable on their systems – notlibFOO.so. Disabling load errors by default will prevent the user from seeing potentially confusing warnings about the FOO components failing to load becauselibFOO.sois not available on their systems.Conversely, system administrators tend to build a PMIx that is targeted at their specific environment, and contains few (if any) components that are not needed. In such cases, they might want their users to be warned that the FOO network components failed to load (e.g., if
libFOO.sowas mistakenly unavailable), because PMIx may otherwise silently fail to provide support for that network.--with-platform=FILE: Load configure options for the build fromFILE. Options on the command line that are not inFILEare also used. Options on the command line and inFILEare replaced by what is inFILE.--with-libpmix-name=STRING: Replacelibpmix.*withlibSTRING.*. This is provided as a convenience mechanism for third-party packagers of PMIx that might want to rename these libraries for their own purposes. This option is not intended for typical users of PMIx.