From e68a639a539795d0e80caac48608c8e397b6829c Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Wed, 28 Oct 2020 12:27:32 -0400 Subject: [PATCH] README: Update --enable-mca-dso|static docs Document/clarify the --enable-mca-dso and --enable-mca-static behavior, and also clarify the --enable-dlopen behavior. Signed-off-by: Jeff Squyres --- README | 102 +++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 89 insertions(+), 13 deletions(-) diff --git a/README b/README index dbdf34ab42f..2db85c0d0c7 100644 --- a/README +++ b/README @@ -966,20 +966,25 @@ INSTALLATION OPTIONS --disable-wrapper-runpath. --enable-dlopen - Build all of Open MPI's components as standalone Dynamic Shared - Objects (DSO's) that are loaded at run-time (this is the default). - The opposite of this option, --disable-dlopen, causes two things: + Enable Open MPI to search for additional components at run time + (i.e., components outside of the core Open MPI libraries). This is + the default. - 1. All of Open MPI's components will be built as part of Open MPI's - normal libraries (e.g., libmpi). - 2. Open MPI will not attempt to open any DSO's at run-time. + The opposite of this option, --disable-dlopen, causes the following: + + 1. Open MPI will not attempt to open any DSO's at run-time. + 2. configure behaves as if --enable-mca-static was passed on the + command line. + 3. configure will ignore the --enable-mca-dso command line flag. + + See the descriptions of --enable-mca-static / --enable-mca-dso for + more information. Note that this option does *not* imply that OMPI's libraries will be built as static objects (e.g., libmpi.a). It only specifies the - location of OMPI's components: standalone DSOs or folded into the - Open MPI libraries. You can control whether Open MPI's libraries - are build as static or dynamic via --enable|disable-static and - --enable|disable-shared. + behavior described above. You can control whether Open MPI's + libraries are build as static or dynamic via --enable|disable-static + and --enable|disable-shared. --disable-show-load-errors-by-default Set the default value of the mca_base_component_show_load_errors MCA @@ -1022,9 +1027,80 @@ INSTALLATION OPTIONS typical users of Open MPI. --enable-mca-no-build=LIST - Comma-separated list of - pairs that will not be - built. For example, "--enable-mca-no-build=btl-portals,oob-ud" will - disable building the portals BTL and the ud OOB component. + Comma-separated list of - pairs that will not + be built. For example, "--enable-mca-no-build=btl-portals,oob-ud" + will disable building the portals BTL and the ud OOB component. + +--enable-mca-dso[=LIST] +--enable-mca-static[=LIST] + These two options govern the behavior of how Open MPI's frameworks + and components are built. + + The --enable-mca-dso option specifies which frameworks and/or + components are built as Dynamic Shared Objects (DSOs). + Specifically, DSOs are built as "plugins" outside of the core Open + MPI libraries, and are loaded by Open MPI at run time. + + The --enable-mca-static option specifies which frameworks and/or + components are built as part of the core Open MPI libraries (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 three ways: + + 1. --enable-mca-OPTION (with no value) + 2. --enable-mca-OPTION=LIST + 3. --disable-mca-OPTION (with no value) + + LIST is a comma-delimited list of Open MPI frameworks and/or + framework+component tuples. Examples: + + * "btl" specifies the entire BTL framework + * "btl-tcp" specifies just the TCP component in the BTL framework + * "mtl,btl-tcp" specifies the entire MTL framework and the TCP + component in the BTL framework + + Open MPI's configure script uses the values of these two options + when evaluating each component to determine how it should be built + by evaluating these conditions in order: + + 1. If an individual component's build behavior has been specified + via these two options, configure uses that behavior. + 2. Otherwise, if the component is in a framework whose build + behavior has been specified via these two options, configure uses + that behavior. + 3. Otherwise, configure uses the global default build behavior. + + Note that as of Open MPI v5.0.0, configure's global default is to + build all components as static (i.e., part of the Open MPI core + libraries, not as DSO's). Prior to Open MPI v5.0.0, the global + default behavior was to build most components as DSOs. + + Also note that if the --disable-dlopen option is specified, then + Open MPI will not be able to search for DSOs at run time, and the + value of the --enable-mca-dso option will be silently ignored. + + Some examples: + + 1. Default to building all components as static (i.e., as part of + the Open MPI core libraries -- no DSOs): + + $ ./configure + + 2. Build all components as static, except the TCP BTL, which will be + built as a DSO: + + $ ./configure --enable-mca-dso=btl-tcp + + 3. Build all components as static, except all BTL components, which + will be built as DSOs: + + $ ./configure --enable-mca-dso=btl + + 4. Build all components as static, except all MTL components and the + TCP BTL component, which will be built as DSOs: + + $ ./configure --enable-mca-dso=mtl,btl-tcp NETWORKING SUPPORT / OPTIONS