doc/catalyst-config.5.txt: Document linking issues with binary packages

This gives users a heads up explaining why they might see linking
errors when pkgcache is enabled.  I first saw this when I build a
stage1 without update_seed.  Because my seed stage3 linked against
libmpc.so.2, some of my stage1 files linked against the older mpc.
However, the mpc-1.0.1 built for the stage1 installed libmpc.so.3.
When I tried to use this stage1 to build a stage2, it died with:

  /usr/libexec/gcc/i686-pc-linux-gnu/4.6.3/cc1:
    error while loading shared libraries: libmpc.so.2:
    cannot open shared object file: No such file or directory

To fix this, I enabled update_seed, but binary packages built during
my first pass were used to populate the stage1, so even though I'd
updated the seed stage3 toolchain, I still had a stage1 with cc1
linked against libmpc.so.2.

After clearing the binary package cache, I got a stage1 *built* with
the updated seed stage3, which gave a cc1 linked against libmpc.so.3
(hurray!).

This commit adds a warning in the pkgcache documentation that should
help people understand what might be going wrong if they see similar
linking errors.  For more details, see the thread following
http://thread.gmane.org/gmane.linux.gentoo.catalyst/2137/focus=2193

1 files changed, 43 insertions, 1 deletions

diff --git a/doc/catalyst-config.5.txt b/doc/catalyst-config.5.txt
index 27bc0bb7..63a015f8 100644
--- a/doc/catalyst-config.5.txt
+++ b/doc/catalyst-config.5.txt
@@ -126,7 +126,8 @@ build dies during `livecd-stage2`.
 pkgcache::
 Enable `--usepkg` and `--buildpkg` for most *emerge(1)* runs.  This is
 useful if your build dies prematurely.  However, you may experience
-linking problems.
+linking problems.  See the *BINARY PACKAGE DEPENDENCIES* section for
+details.
 
 seedcache::
 Use the build output of a previous target if it exists to speed up the
@@ -174,6 +175,47 @@ ripemd256, ripemd320, sha1, sha224, sha256, sha384, sha512, snefru128,
 snefru256, tiger, tiger128, tiger160, whirlpool.
 
 
+BINARY PACKAGE DEPENDENCIES
+---------------------------
+This section is only important if you are using binary packages to
+build your stages (by enabling the `pkgcache` option and restarting
+incomplete builds).
+
+Before EAPI-5 introduced ABI sub-slots, the build-time compatibility
+of packages was not recorded.  This leads to problems such as binary
+GCC packages built against mpc-0.8.2 (which installs libmpc.so.2)
+being installed on systems that only have mpc-1.0.1 (which installs
+libmpc.so.3), resulting in:
+
+---------------------------------
+/usr/libexec/gcc/i686-pc-linux-gnu/4.6.3/cc1:
+  error while loading shared libraries: libmpc.so.2:
+  cannot open shared object file: No such file or directory
+---------------------------------
+
+As long as there are packages in your stage that don't use ABI
+sub-slots, you may experience errors like this due to untracked ABI
+missmatches in binary packages.  Packages generated by catalyst builds
+are currently namespaced:
+
+---------------------------------
+.../packages/<rel_type>/<target>-<subarch>-<version_stamp>/Packages
+---------------------------------
+
+so running into these out-of-date packages is unlikely.  You may run
+into problems if:
+
+* you enable `update_seed` in your stage1 spec after a previous run
+  which generated packages linking against out-of-date seed libraries
+  or
+* you update your snapshot and an untracked ABI dependency is bumped
+  without a similar bump in the dependent package.
+
+without also bumping any of the package namespace variables in your
+spec.  If you do make such a change, it's a good idea to clear the
+package cache in question and rebuild the packages from scratch.
+
+
 FILES
 -----
 An example configuration file can be found at