doc/catalyst-config.5.txt: Document linking issues with binary packages
authorW. Trevor King <wking@tremily.us>
Fri, 12 Apr 2013 18:13:57 +0000 (14:13 -0400)
committerW. Trevor King <wking@tremily.us>
Tue, 4 Jun 2013 16:34:42 +0000 (12:34 -0400)
commite887545cf86baf8b9c52f07764ae927ce667fed2
tree1c3375a97c8b2d70c15d874df997067bfbf19b55
parentdf8682b65d9e3f6fc71022ec970f1e0236664cb2
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
doc/catalyst-config.5.txt