jkt 05/12/08 19:21:13 Added: xml/htdocs/doc/en gcc-upgrading.xml Log: New generic GCC upgrading guide, replacement of gentoo/xml/htdocs/proj/en/base/x86/gcc-upgrading-guide.xml
Revision Changes Path 1.1 xml/htdocs/doc/en/gcc-upgrading.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/gcc-upgrading.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/gcc-upgrading.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo Index: gcc-upgrading.xml =================================================================== <?xml version='1.0' encoding="UTF-8"?> <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gcc-upgrading.xml,v 1.1 2005/12/08 19:21:13 jkt Exp $ --> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <guide link="/doc/en/gcc-upgrading.xml"> <title>Gentoo Linux GCC Upgrade Guide</title> <author title="Author"> <mail link="[EMAIL PROTECTED]">Wernfried Haas</mail> </author> <author title="Author"> <mail link="[EMAIL PROTECTED]">Jan Kundrát</mail> </author> <author title="Editor"> <mail link="[EMAIL PROTECTED]">Mark Loeser</mail> </author> <author title="Editor"> <mail link="[EMAIL PROTECTED]">Chris Gianelloni</mail> </author> <abstract> This document will guide the user through the process of upgrading GCC on their Gentoo Linux machines. </abstract> <!-- The content of this document is licensed under the CC-BY-SA license --> <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> <version>1</version> <date>2005-12-08</date> <chapter id="intro"> <title>Introduction</title> <section> <title>GCC Upgrading</title> <body> <p> Why should you upgrade? Well, GCC is quite similar to any other package on your system, just a bit more critical. You should upgrade GCC whenever a new version fixes some bug that annoys you, new functionality you need is introduced, or if you want to keep your system up-to-date. If none of the previous cases apply to you, you can safely postpone upgrade as long as your GCC version is supported by Gentoo developers. </p> <p> If you install a newer version of GCC, the system will not switch over to use it automatically. You'll have to explicitly request the change because the migration process might require some additional steps. If you decide not to switch, Portage will continue to use older version of your compiler until you change your mind, or remove the old compiler from the system. </p> <p> This guide will document the necessary steps required to perform a seamless upgrade of the compiler used by your Gentoo box. A specific section is dedicated to the <uri link="#upgrade-3.3-to-3.4">upgrade from GCC 3.3 to the 3.4 version</uri> and issues with <c>libstdc++</c>. </p> </body> </section> </chapter> <chapter id="upgrade-general"> <title>General Upgrade Instructions</title> <section> <title>Introduction</title> <body> <impo> If you're looking for instructions specific to upgrades from GCC-3.3 to GCC-3.4, please consult the <uri link="#upgrade-3.3-to-3.4">dedicated section</uri>. </impo> <p> Generally speaking, upgrades to <e>bug fix releases</e>, like from 3.3.5 to 3.3.6, should be quite safe -- just emerge new version, switch your system to use it and rebuild the only affected package, <c>libtool</c>. However, some GCC upgrades break binary compatibility; in such cases a rebuild of the affected packages (or even whole toolchain and system) might be required. </p> <p> When we spoke about the need to switch your compiler to the newer version by hand, we said it won't happen automatically. However, there is one exception -- upgrades to bug fix releases, like from 3.3.5 to 3.3.6 in case you don't use the "multislot" feature allowing them to coexist on one system. Multislot is disabled by default as the majority of users won't benefit from it. </p> <pre caption="Upgrading GCC"> # <i>emerge -uav gcc</i> <comment>(Please substitute "i686-pc-linux-gnu-3.4.4" with the GCC version and CHOST settings you've upgraded to:)</comment> # <i>gcc-config i686-pc-linux-gnu-3.4.4</i> # <i>source /etc/profile</i> <comment>(Rebuilding libtool)</comment> # <i>emerge --oneshot -av libtool</i> </pre> <p> Now let's rebuild toolchain and then world so we will make use of the new compiler. </p> <pre caption="Rebuilding system"> # <i>emerge -eav system</i> # <i>emerge -eav world</i> </pre> <p> It is safe to remove older GCC version at this time. If you feel the need, please issue the following command (as usual, substitute <c>=sys-devel/gcc-3.3*</c> with the version you want to uninstall): </p> <pre caption="Removing older GCC version"> # <i>emerge -aC =sys-devel/gcc-3.3*</i> </pre> </body> </section> </chapter> <chapter id="upgrade-3.3-to-3.4"> <title>Upgrading from GCC-3.3 to 3.4</title> <section> <title>Introduction</title> <body> <p> The upgrade from GCC/3.3 to 3.4 is not so seamless as the C++ ABI changed between these two versions so there is an issue with <c>libstdc++</c> library which must be taken care of as well. </p> </body> </section> <section id="upgrade-3.3-to-3.4-choices"> <title>The Choices</title> <body> <p> You have two possibilities on how to upgrade your system. <uri link="#upgrade-3.3-to-3.4-revdep-rebuild">First method</uri> is faster and requires use of <c>revdep-rebuild</c> tool from package <c>gentoolkit</c> while the <uri link="#upgrade-3.3-to-3.4-emerge-e">second one</uri> rebuilds the entire system from scratch so it will make use of new GCC features. It's up to you to decide which of these two ways you will choose. </p> </body> </section> <section id="upgrade-3.3-to-3.4-revdep-rebuild"> <title>Using revdep-rebuild</title> <body> <p> This method requires that you first install <c>gentoolkit</c> if you have not already done so. Then we will upgrade GCC and switch to the new compiler. We will also rebuild the <c>libtool</c> package to ensurethat toolchain is in healthy state. </p> <pre caption="Installing gentoolkit and upgrading GCC"> # <i>emerge -an gentoolkit</i> # <i>emerge -uav gcc</i> # <i>gcc-config i686-pc-linux-gnu-3.4.4</i> # <i>source /etc/profile</i> <comment>(Rebuilding libtool)</comment> # <i>emerge --oneshot -av libtool</i> </pre> <note> This assumes that you have <c>CHOST="i686-pc-linux-gnu"</c> set. If you are using another CHOST, please use the appropriate gcc-config line. </note> <p> Now, we want to see which packages that revdep-rebuild will want to rebuild. Then we will tell revdep-rebuild to actually rebuild the packages. This may take some time, so have some patience. </p> <pre caption="Using revdep-rebuild"> # <i>revdep-rebuild --library libstdc++.so.5 -- -p -v</i> # <i>revdep-rebuild --library libstdc++.so.5</i> </pre> <note> It is possible that you might have problems with non-existing package versions due to them being outdated or masked. If this is the case, you will want to use the <c>--package-names</c> option to <c>revdep-rebuild</c>. This causes packages to be recompiled based on the package name, rather than the exact name and version. </note> <p> To provide compatibility with older binary C++ applications and any packages that revdep-rebuild might have missed, <c>sys-libs/libstdc++-v3</c> needs to be merged before you unmerge GCC 3.3 from your system. </p> <pre caption="Installing libstdc++-v3 and cleaning up"> # <i>emerge --oneshot sys-libs/libstdc++-v3</i> # <i>emerge -aC =sys-devel/gcc-3.3*</i> </pre> </body> </section> <section id="upgrade-3.3-to-3.4-emerge-e"> <title>Using emerge -e</title> <body> <p> This method, while much slower, will rebuild your whole system to ensure that everything has been rebuilt with your new compiler, and therefore safer. At first, you will upgrade GCC and libtool and switch to your new compiler. </p> <pre caption="Upgrading GCC"> # <i>emerge -uav gcc</i> # <i>gcc-config i686-pc-linux-gnu-3.4.4</i> # <i>source /etc/profile</i> <comment>(Rebuilding libtool)</comment> # <i>emerge --oneshot -av libtool</i> </pre> <note> This assumes that you have <c>CHOST="i686-pc-linux-gnu"</c> set. If you are using another CHOST, please use the appropriate gcc-config line. </note> <p> To provide compatibility with older binary C++ applications, <c>sys-libs/libstdc++-v3</c> needs to be merged onto your system. </p> <pre caption="Installing libstdc++-v3"> # <i>emerge --oneshot sys-libs/libstdc++-v3</i> </pre> <p> Now we will go about first rebuilding the system target, then the world target. This will take a very long time, depending on the number of packages that you have installed, as it will rebuild your entire toolchain and supporting system files, followed by every package on your system, including the toolchain. This is necessary to ensure that all packages have been compiled with the new toolchain, including the toolchain itself. </p> <pre caption="Rebuilding system and world"> # <i>emerge -e system</i> # <i>emerge -e world</i> </pre> <p> It is also safe to remove older GCC versions at this time: </p> <pre caption="Cleaning up"> # <i>emerge -aC =sys-devel/gcc-3.3*</i> </pre> </body> </section> </chapter> <chapter id="common-pittfalls"> <title>Common Pittfalls</title> <section> <body> <p> It's important to disable <c>distcc</c> during upgrade. Mixing compiler versions on your nodes <e>will</e> cause build issues. This is not required for ccache, as the cache objects will be invalidated anyway. </p> <p> Always use same GCC version for your kernel and additional kernel modules. Once you rebuild your world with new GCC, external modules (like <c>app-emulation/qemu-softmmu</c>) will fail to load. Please rebuild your kernel with new GCC to fix that. </p> </body> </section> <section> <title>Frequent Error Messages</title> <body> <p> If your system complains about something like <e>libtool: link: `/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.6/libstdc++.la' is not a valid libtool archive</e>, please run <c>/sbin/fix_libtool_files.sh 3.3.6</c> (substitute "3.3.6" with the version numbers from the error message). </p> <p> If you see the <e>error: /usr/bin/gcc-config: line 632: /etc/env.d/gcc/i686-pc-linux-gnu-3.3.5: No such file or directory</e>, then try deleting <path>/etc/env.d/gcc/config-i686-pc-linux-gnu</path> and running <c>gcc-config</c> again, followed by <c>source /etc/profile</c>. Only do this if you do not have any cross-compilers set up, though. </p> <p> If a package fails during <c>emerge -e system/world</c>, you can resume operation with <c>emerge --resume</c>. If a package fails repeatedly, skip it with <c>emerge --resume --skipfirst</c>. Don't run any other instances of emerge in between or you will lose the resume information. </p> <p> If you get an error message <e>spec failure: unrecognized spec option</e> while upgrading your compiler, try to switch back to your default compiler, unset the <c>GCC_SPECS</c> variable and upgrade GCC again: </p> <pre caption="Restoring primary specs"> # <i>gcc-config 1</i> # <i>source /etc/profile</i> # <i>unset GCC_SPECS</i> # <i>emerge -uav gcc</i> </pre> </body> </section> </chapter> </guide> -- [email protected] mailing list
