Users new to Gentoo often end up breaking their system after their first global package update – particularly if they stopped reading the manual as soon as they got their system booting (I’m usually one of those). Over the years I have run into every problem that portage can imaginably throw at a person and from that I have formulated a fool-proof update process which, sometimes with a little intervention, always works and – assuming you take proper care of configuration – leaves you with a working system.
The first thing you need to do is think of any software you have installed where a version change might break something, for example: some fglrx driver versions will work with old cards and Xinerama, and some will not – in no particular order. I had the unfortunate experience of blindly upgrading my fglrx implementation to one that didn’t work only to find the version I had been using was no longer available in portage. Use quickpkg to make a quick standalone package of the existing files for a given atom:
# quickpkg cate-gory/package-name
The package will be available for later use in /usr/portage/packages.
Now let’s update portage:
# emerge –sync
If you are given a message instructing you to update the portage package it is important that you do so before continuing.
# emerge portage
Before we begin compiling anything I need to point out that if you use certain CFLAGS some packages may fail to compile. I always include -fstack-protector which adds buffer overflow protection to software at compile-time. Glibc in particular tends to have a problem with this feature. Updating world with this flag in would break the long update process when emerge gets to glibc and we want the newest GCC suite available to compile the rest of our system anyway – so let’s update glibc and gcc separately from world, and if we encounter any problems we’ll temporarily strip down our CFLAGS:
# emerge –update gcc glibc
Now we want to make sure your profile is set to use the latest version of GCC available on your system, it might look something like this:
# gcc-config -l
[1] x86_64-pc-linux-gnu-4.1.2 *
[2] x86_64-pc-linux-gnu-4.3.4
The asterisk indicates which version of GCC you are using. You can set the version by running gcc-config number where number is in the leftmost position of the output above, thus:
# gcc-config 2
You will be instructed to update your profile environment variables:
# source /etc/profile
It should be noted here that some software may not compile correctly with a given GCC version, requiring you to move up or down. At the time of writing Quemu requires GCC 3x and I have had a few isolated incidents of Xen being picky.
Before we get started let’s launch a screen instance (emerge screen if you have not already done so) so we can move from terminal to terminal without interrupting the build process:
# emerge screen
# screen -S update
You can detatch from the session with the key combination control+a, d. Returning to the session is as simple as logging in from anywhere as the user who spawned the session and typing:
# screen -x update
Multiple clients may attach to the same screen session at once. This is particularly useful if you want to be able to orchestrate some or all of the upgrade over secure shell.
Now we’re ready for the magic line:
# emerge –update –newuse –deep world –ask
Recent versions of portage have excellent automatic blocked package resolution, but it doesn’t work all the time. If you can’t continue due to blocked packages try to emerge either package one at a time. This often isn’t enough – particularly where one package has taken over “duties” for the same files an existing package used to provide. In these cases you will have to unmerge one or both of the conflicting packages – but sometimes unmerging the wrong one(s) may leave your system unusable. Google the package names and version numbers; without fail I have always found someone on the Gentoo bugtraq and elsewhere who has had the same problem and someone has usually posted the safest order of removal. Of course, nothing can’t be fixed by booting with the livecd.
If you get strange errors about file collision protection but you’re sure it’s safe to overwrite the listed files, you may add this line to your make.conf or precede your emerge command similarly:
FEATURES=”-collision-protect”
If you will be unable to attend the update process (going home for the weekend etc) you may find it useful to add –keep-going to the emerge flags; this will skip over packages that fail to build and continue emerging. If you can’t tell from the error messages repeated at the end of the build simply re-run the emerge command, making sure to use either –ask or –pretend and the missing packages will be neatly listed.
Often enough these packages fail to compile due to a missing reverse-dependency. The next stop on the line is revdep-rebuild, run simply:
# revdep-rebuild
This tool will scour your system for missing reverse dependencies, build a list then start compiling them if it finds any. This process can fail if it attempts to rebuild a package for which there is no longer a matching version in portage, in which case you may have to do some emerging/unmerging/updating of the given package’s dependants. If the builds themselves fail it is safe to move on to the next step then return to revdep-rebuild later.
Python is an integral part of the gentoo system so it is very, very important that when python is updated the python-updater tool is run:
# python-updater
If you just upgraded PERL, be sure to run:
# perl-cleaner all
Which will take care of removing old header files, renaming files and rebuilding perl modules. It usually ends up rebuilding net-snmp on my systems and not much else in the way of ebuilds.
Lafilefixer fixes libtool archives and may not be needed on your system (does not come installed by default, emerge lafilefixer if you have not already) but it won’t hurt to run it:
# lafilefixer –justfixit
Even if your first revdep-rebuild worked it is a good idea to run it again, in case any of the (possibly) newly installed packages have broken anything else. If some packages failed to build in the first world update you may now run it again.
It is now safe to clear out your old dependencies – should any exist. Most of the packages you will see listed are simply old versions of updated packages as a number of them occupy slots (such as GCC) for the sake of backwards compatibility. If you would like to retain a specific package, add it to your /var/lib/portage/world file, in full if you would like to target a specific version: =categ-gory/package-name-version.number
# emerge –depclean –deep –ask
Do not forget to update your configuration files. Be warned that simply overwriting all of the old configuration files may not be necessary and may render your system inaccessible:
# etc-update
That concludes my foolproof build order. If you followed it correctly there is a high probability your system is completely up-to-date and working, from a portage point of view. Of course, proper configuration is important and compile-stopping bugs are common and may require some mild footwork, but this usually amounts to copying and pasting the first error line into google or blocking/unblocking specific package versions with /etc/portage/package.mask, package.keywords and package.unmask. More information on package masking is available in the emerge man page.
Happy building!
