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 <jsquyres@cisco.com>

Author: jsquyres

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 <type>-<component> 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 <framework>-<component> 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