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)
committerBrian Dolbec <dolsen@gentoo.org>
Thu, 6 Jun 2013 16:00:38 +0000 (09:00 -0700)
commit2ca4c84bf8883cf7662294955e34ec3bbaae6a28
tree1c3375a97c8b2d70c15d874df997067bfbf19b55
parent1b5c5568e05db71b55268436a740bfff2363b939
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