doc/catalyst-config.5.txt: Document linking issues with binary packages pkgcache-warning
authorW. Trevor King <wking@tremily.us>
Fri, 12 Apr 2013 18:13:57 +0000 (14:13 -0400)
committerW. Trevor King <wking@tremily.us>
Fri, 12 Apr 2013 19:10:31 +0000 (15:10 -0400)
commit5b37766b61df45c8e7776dec082a1ca41e13c63b
tree340d1ef2f3f14b24284b3e266b731c449bfb77b0
parent0d02179a4ff3f0bfb422bf5260aa020f4921d709
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