Add some comments about the whole "common shared library" thing

because a) it's confusing, and b) I'm sure it's only the first.  :-)

This commit was SVN r1939.

src/mca/common/sm/Makefile.am

@@ -2,6 +2,25 @@
 # $HEADER$
 #
 
+# A word of explanation...
+#
+# This library is linked against various MCA components because all
+# shared-memory based components (e.g., mpool, ptl, etc.)  need to
+# share some common code and data.  There's two cases:
+#
+# 1. libmca_common_sm.la is a shared library.  By linking that shared
+# library to all components that need it, the OS linker will
+# automatically load it into the process as necessary, and there will
+# only be one copy (i.e., all the components will share *one* copy of
+# the code and data).
+#
+# 2. libmca_common_sm.la is a static library.  In this case, it will
+# be rolled up into the top-level libmpi.la.  It will also be rolled
+# into each component, but then the component will also be rolled up
+# into the upper-level libmpi.la.  Linkers universally know how to
+# "figure this out" so that we end up with only one copy of the code
+# and data.
+
 # Use the top-level Makefile.options
 
 include $(top_ompi_srcdir)/config/Makefile.options

src/mca/mpool/sm/Makefile.am

@@ -2,6 +2,25 @@
 # $HEADER$
 #
 
+# A word of explanation...
+#
+# We link this component to common/sm/libmca_common_sm.la. This is
+# because all shared-memory based components (e.g., mpool, ptl, etc.)
+# need to share some common code and data.  There's two cases:
+#
+# 1. libmca_common_sm.la is a shared library.  By linking that shared
+# library to all components that need it, the OS linker will
+# automatically load it into the process as necessary, and there will
+# only be one copy (i.e., all the components will share *one* copy of
+# the code and data).
+#
+# 2. libmca_common_sm.la is a static library.  In this case, it will
+# be rolled up into the top-level libmpi.la.  It will also be rolled
+# into each component, but then the component will also be rolled up
+# into the upper-level libmpi.la.  Linkers universally know how to
+# "figure this out" so that we end up with only one copy of the code
+# and data.
+
 # Use the top-level Makefile.options
 
 include $(top_ompi_srcdir)/config/Makefile.options

src/mca/ptl/sm/src/Makefile.am

@@ -2,6 +2,25 @@
 # $HEADER$
 #
 
+# A word of explanation...
+#
+# We link this component to common/sm/libmca_common_sm.la. This is
+# because all shared-memory based components (e.g., mpool, ptl, etc.)
+# need to share some common code and data.  There's two cases:
+#
+# 1. libmca_common_sm.la is a shared library.  By linking that shared
+# library to all components that need it, the OS linker will
+# automatically load it into the process as necessary, and there will
+# only be one copy (i.e., all the components will share *one* copy of
+# the code and data).
+#
+# 2. libmca_common_sm.la is a static library.  In this case, it will
+# be rolled up into the top-level libmpi.la.  It will also be rolled
+# into each component, but then the component will also be rolled up
+# into the upper-level libmpi.la.  Linkers universally know how to
+# "figure this out" so that we end up with only one copy of the code
+# and data.
+
 include $(top_ompi_srcdir)/config/Makefile.options
 
 noinst_LTLIBRARIES = libmca_ptl_sm.la