This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.
Please visit our production wiki at https://wiki.gentoo.org
Changing the CHOST variable
This document explains how to change the CHOST variable of an existing system.
Introduction
Changing the CHOST is a big issue that can seriously screw up a system - so why is there a guide for that if it can cause that much havoc?
There are certain situations where changing the CHOST variable is inevitable, e.g. when upgrading to glibc 2.4 which only supports NTPL and the user finds out that the current CHOST is i386, which makes it impossible to use NTPL. In this case, there are not a lot of options, and changing CHOST is one of them.
Even after following these instructions, problems may arise, so please make sure to read and execute them very carefully. In this example the CHOST variable will be changed from i386 to i686. Please change the commands according to the specific situation.
Changing the CHOST variable
Updating make.conf
To start out with the CHOST variable change, edit the /etc/portage/make.conf file and add/change the CHOST value to suit the requirements.
/etc/portage/make.confCHOST="i686-pc-linux-gnu"
Please note that if you are planning to use another value of CHOST than the profile default, you may need to update the CHOST_${ABI} variable as well. You can query the current value of these variable via portageq tool:
user $portageq envvar ABIuser $portageq envvar CHOST_x86If this value is equal to your CHOST, you're good. Otherwise, you should override it as well, e.g.:
/etc/portage/make.confCHOST_x86="i686-pc-linux-gnu"
Building the packages
It is generally a good idea to rebuild the packages to the same versions as before the CHOST switch, i.e. avoiding combining upgrades with it. If you have multiple slots installed, either uninstall extraneous slots or rebuild all of them. If you can't do that, please upgrade the packages first (with old CHOST). While it may not be impossible to do so, it is hard to predict which potential problems may arise and almost impossible to document them in this guide.
On a system with CHOST set to an i386 value, mask glibc 2.4 (or newer) during the gcc upgrade as it cannot be used with i386. Unmask it once the change has been performed completely.
Rebuild the following packages in this order:
root #emerge --ask --oneshot sys-devel/binutilsIt may be necessary to run binutils-config before compiling gcc.
root #emerge --ask --oneshot sys-devel/gccroot #emerge --ask --oneshot sys-libs/glibcVerifying things work
Now it is time to make sure that the gcc-config and binutils-config settings are sane and that there are no leftovers in /etc/env.d/.
The output of gcc-config and binutils-config should look like the following:
The output may, or even will differ according to the gcc version and CHOST settings. The example below uses gcc 4.1.1 on i686.
root #gcc-config -l[1] i686-pc-linux-gnu-4.1.1 *
root #gcc-config -ci686-pc-linux-gnu-4.1.1
root #binutils-config -l[1] i686-pc-linux-gnu-2.16.1 * # binutils-config -c i686-pc-linux-gnu-2.16.1
Next, check to see if there are references to the old CHOST variable in /etc/env.d/:
root #cd /etc/env.d/
root #grep 386 *05gcc-i386-pc-linux-gnu:PATH="/usr/i386-pc-linux-gnu/gcc-bin/4.1.1" 05gcc-i386-pc-linux-gnu:ROOTPATH="/usr/i386-pc-linux-gnu/gcc-bin/4.1.1"
This may not happen in every case, but in this case 05gcc-i386-pc-linux-gnu contains references to the old CHOST value. Things may look differently on each system depending on which CHOST value the system is changing to/from. In some cases, no references are left at all. The name may also be 05gcc-new_CHOST-pc-linux-gnu.
Before deleting the file, let's check for files with the updated CHOST value:
root #grep 686 *05binutils:MANPATH=/usr/share/binutils-data/i686-pc-linux-gnu/2.16.1/man 05binutils:INFOPATH=/usr/share/binutils-data/i686-pc-linux-gnu/2.16.1/info 05binutils:LDPATH=/usr/i686-pc-linux-gnu/lib 05gcc:PATH="/usr/i686-pc-linux-gnu/gcc-bin/4.1.1" 05gcc:ROOTPATH="/usr/i686-pc-linux-gnu/gcc-bin/4.1.1" 05gcc:MANPATH="/usr/share/gcc-data/i686-pc-linux-gnu/4.1.1/man" 05gcc:INFOPATH="/usr/share/gcc-data/i686-pc-linux-gnu/4.1.1/info" 05gcc:LDPATH="/usr/lib/gcc/i686-pc-linux-gnu/4.1.1"
This one looks good as there should always be only one file for gcc in /etc/env.d/ (05gcc in this example), so delete the one with the wrong references:
root #rm 05gcc-i386-pc-linux-gnuThe same also applies to binutils - if there's an extra one, see which is the outdated one and delete it. Next, check the contents of /etc/env.d/binutils/:
root #cd /etc/env.d/binutils/
root #ls -latotal 8 -rw-r--r-- 1 root root 15 Sep 3 13:48 config-i686-pc-linux-gnu -rw-r--r-- 1 root root 126 Sep 3 13:48 i686-pc-linux-gnu-2.16.1
root #cat config-i686-pc-linux-gnuCURRENT=2.16.1
root #cat i686-pc-linux-gnu-2.16.1TARGET="i686-pc-linux-gnu" VER="2.16.1" LIBPATH="/usr/lib/binutils/i686-pc-linux-gnu/2.16.1" FAKE_TARGETS="i686-pc-linux-gnu"
That one looks good, those two files should be there. Time to move on to the gcc/ directory.
root #cd /etc/env.d/gcc# ls -la total 12 -rw-r--r-- 1 root root 32 Sep 3 16:43 config -rw-r--r-- 1 root root 32 Aug 3 14:25 config-i386-pc-linux-gnu -rw-r--r-- 1 root root 292 Sep 3 16:43 i686-pc-linux-gnu-4.1.1
root #cat configCURRENT=i686-pc-linux-gnu-4.1.1
root #cat config-i386-pc-linux-gnuCURRENT=i386-pc-linux-gnu-4.1.1
root #cat i686-pc-linux-gnu-4.1.1PATH="/usr/i686-pc-linux-gnu/gcc-bin/4.1.1" ROOTPATH="/usr/i686-pc-linux-gnu/gcc-bin/4.1.1" LDPATH="/usr/lib/gcc/i686-pc-linux-gnu/4.1.1" GCCBITS="32" MANPATH="/usr/share/gcc-data/i686-pc-linux-gnu/4.1.1/man" INFOPATH="/usr/share/gcc-data/i686-pc-linux-gnu/4.1.1/info" STDCXX_INCDIR="g++-v4"
config and i686-pc-linux-gnu-4.1.1 are fine, but config-i386-pc-linux-gnu is another leftover that needs removal.
Again, the name of the file containing references to an outdated gcc version may have a different name, e.g. config-i686-pc-linux-gnu even though the system is being changed to (in this case) i686. It is important to identify the file on its content, not only the name.
root #rm config-i386-pc-linux-gnuNow run the following commands to update the environment:
root #env-update && source /etc/profileNext, verify everything is fixed:
root #grep -r 386 /etc/env.d/If there are still files found, try to track it down before going on.
Finishing The Change
Now it is necessary to re-emerge sys-devel/libtool and run fix_libtool_files.sh which can be found in /usr/share/gcc-data/$CHOST/<gcc-version>/. Make sure to use the correct gcc version (the current one, 4.1.1 here) and pass the old architecture (i386 here) as argument. Replace $CHOST with the new CHOST value, and <gcc-version> with the gcc version. This example assumes a CHOST value applicable to i686.
root #emerge --ask --oneshot libtoolroot #/usr/share/gcc-data/i686-pc-linux-gnu/4.1.1/fix_libtool_files.sh 4.1.1 --oldarch i386-pc-linux-gnuIt is now possible to rebuild all the packages:
root #emerge --ask --emptytree @worldIn theory, it should not be necessary to do so, but it cannot be 100% guaranteed that this is actually the case. Alternatively, you can manually rebuild all the known problematic packages:
- multilib packages using CHOST prefixing or header wrapping,
- Perl, Python and other tools that store configured compiler path.
root #emerge --ask --oneshot /usr/bin/i386-pc-linux-gnu-* /usr/include/i386-pc-linux-gnu /usr/lib/llvm/*/bin/i386-pc-linux-gnu-* dev-lang/perl dev-lang/pythonNote that you may need to remove paths that do not apply to your system from the above invocation.
When encountering other packages that need recompiling, please let us know through the discussion page of this guide.
Common problems
When upgrading from gcc 3.3 to 4.1 at the same time as changing the CHOST variable (please don't do that anyway), a couple of users reported broken packages that need recompiling, such as sys-apps/groff and mail-mta/courier:
error while loading shared libraries: libstdc++.so.5: cannot open shared object file: No such file or directory
This happens because during the upgrade, the CHOST variable doesn't exactly match the CTARGET variable value, making the compiler assume that the system is using cross-compiling. As a consequence, LDPATH isn't inserted into ld.so.conf, resulting in this error.
Please see the GCC upgrade guide for what needs to be rebuilt after a GCC upgrade.
In some rare cases, this can break old versions of python, too. This may be fixed by adding /usr/lib/gcc-lib/i386-pc-linux-gnu/3.3.6 (change accordingly to the old CHOST and gcc version) to /etc/ld.so.conf, running ldconfig and then emerge libstdc++-v3. However, as can be seen, this situation needs to be avoided - don't change CHOST and gcc at the same time.
Feedback
That should be all, feedback (both if it worked, failed or other problems were encountered) is welcome, please use the discussion page or post to this forum thread. Much in this guide comes from vapier, thanks for your help!
This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Wernfried Haas, Mike Frysinger (vapier), Chris White
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.