From e887545cf86baf8b9c52f07764ae927ce667fed2 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 12 Apr 2013 14:13:57 -0400 Subject: [PATCH] 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 | 44 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) 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//--/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 -- 2.26.2