Rework the comment I initially wrote when SHLIB_LDSCRIPT was introduced.

The build system is really intricate and I had a hard time to remind the
whole picture even when reading my own words.  This one will hopefully
be better.

1 files changed, 14 insertions, 9 deletions

diff --git a/share/mk/bsd.lib.mk b/share/mk/bsd.lib.mk
index 38c8de3..cb2544c 100644
--- a/share/mk/bsd.lib.mk
+++ b/share/mk/bsd.lib.mk
@@ -294,16 +294,21 @@ _libinstall:
 .if defined(SHLIB_LINK)
 # ${_SHLIBDIRPREFIX} and ${_LDSCRIPTROOT} are both needed when cross-building
 # and when building 32 bits library shims.  ${_SHLIBDIRPREFIX} is the directory
-# prefix where shared objects will be installed.  ${_LDSCRIPTROOT} is the
-# directory prefix that will be used in generated ld(1) scripts.  They cannot
-# be coalesced because of the way ld(1) handles the sysroot prefix (used in the
-# cross-toolchain):
-# - 64 bits libs are located under sysroot, so ${_LDSCRIPTROOT} must be empty.
+# prefix where shared objects will be installed by the install target.
+#
+# ${_LDSCRIPTROOT} is the directory prefix that will be used when generating
+# ld(1) scripts.  The crosstools' ld is configured to lookup libraries in an
+# alternative directory which is called "sysroot", so during buildworld binaries
+# won't be linked against the running system libraries but against the ones of
+# the current source tree.  ${_LDSCRIPTROOT} behavior is twisted because of
+# the location where we store them:
+# - 64 bits libs are located under sysroot, so ${_LDSCRIPTROOT} must be empty
+#   because ld(1) will manage to find them from sysroot;
 # - 32 bits shims are not, so ${_LDSCRIPTROOT} is used to specify their full
-#   path.  Note that ld(1) scripts are generated both during buildworld and
-#   installworld; in the later case ${_LDSCRIPTROOT} must be obviously empty.
-# On the other hand, the use of ${_SHLIBDIRPREFIX} is more consistent since it
-# does not involve the logic of a tool we do not own.
+#   path, outside of sysroot.
+# Note that ld(1) scripts are generated both during buildworld and
+# installworld; in the later case ${_LDSCRIPTROOT} must be obviously empty
+# because on the target system, libraries are meant to be looked up from /.
 .if defined(SHLIB_LDSCRIPT) && !empty(SHLIB_LDSCRIPT) && exists(${.CURDIR}/${SHLIB_LDSCRIPT})
 	sed -e 's,@@SHLIB@@,${_LDSCRIPTROOT}${SHLIBDIR}/${SHLIB_NAME},g' \
 	    -e 's,@@LIBDIR@@,${_LDSCRIPTROOT}${LIBDIR},g' \