User:Hfern/Drafts/Overdue maintenance

From Gentoo Wiki
Jump to:navigation Jump to:search
This article is a stub. Please help out by expanding it - how to get started.

Distinctive characteristics of Gentoo's are that it has a rolling release model and configurable options per package by means of USE flags.

With a rolling release model there are no upgrades from one release to the next like with many other distributions. Instead Gentoo is aware of package and version dependencies for every package that is installed on a Gentoo system. When the software is frequently upgraded then this poses no problem: portage can handle small upgrades well.

Gentoo's USE flags make it possible to configure each package to compile in the desired features and functions. Gentoo provides typically sane defaults for USE flags, but these may have to be adjusted depending on the installed set of packages on a system.

When an upgrade is not performed for quite a while, like for half a year or longer, it can happen that the package, versions, and USE flags don't match any more. Some packages have a quicker release schedule than others, and the software compatibility matrix between what is installed on the system and what is available in portage does not match any more.

This wiki page aims at helping Gentoo users to overcome the issues that arise because of overdue maintenance.

Preparing the upgrade

Syncing portage

Portage will need to be told what new packages are available, which have been removed, and which might have different USE flags or other changes. for this purpose Portage's tree of ebuilds will need to be synchronized with Gentoo's servers or mirrors:

root #emerge --sync

This will sync the portage tree with the latest and greatest ebuilds.


Portage is the heart of Gentoo's dependency system. Always make sure the latest in is installed. Portage will signal when it needs upgrading once you have synced:

root #emerge --sync
 * An update to portage is available. It is _highly_ recommended
 * that you update portage now, before any other packages are updated.

 * To update portage, run 'emerge --oneshot portage' now.

Go ahaead and upgrade portage immediately whenever you see the above message:

root #emerge --oneshot portage

Reading news

Gentoo's maintainers will let you know when something major changes. The command to read such news is:

root #eselect new read

Make sure to read and understand what is shared.

Evaluate what needs upgrading

The command to evaluate what all needs upgrading everything:

root #emerge -vpuDN @world

The options used are:

  • -v (or --verbose): show what needs to be done
  • -p (or --pretend): don't do it for real, this is just a dry-run
  • -u (or --upgrade): select packages that need upgrading
  • -D (or --deep): also evaluate packages that are a dependency
  • -N (or --newuse): also check for package that have new USE flags. Newer packages may have new or different use flags

When trying this command on a system that has not been upgraded for a while, all kinds of problems can occur. In a next chapter it is explained to deal with the issues. First take an opportunistic view and try to upgrade the toolstack.

Review USE flags

Package' USE flags evolve over time. A to be upgraded package may make use of a different features of other packages and therefore require additional or different USE flags. Make sure to adapt the USE flags to your liking: portage's suggestion may not always be what you want.

Upgrade toolstack

Gentoo's toolstack is the software that builds the packages. It is important to upgrade the toolstack before anything else, but aware that these packages may need to be re-emerged later on again because they link to other packages that will be upgraded too.


It is smart to upgrade the compiler early in the process. Many software packages will be recompiled, so why not with a new compiler?

Check if this needs to be done with:

root #emerge -vpu sys-devel/gcc

If a gcc upgrade is available then follow the instructions here.


Linux' kernel also gets upgraded once in a while. Follow the instructions here.


Perl has many packages and it is quite easy to have many package compatibilities. It is typically resolvable with perl_cleaner:

root #perl-cleaner --all

Resolving issues

Resolving issues is always a pain, but there are various techniques that may provide help.

Slot conflicts

When you see something like this:

root #emerge -vauDN --verbose-conflicts @world
!!! Multiple package instances within a single package slot have been pulled
!!! into the dependency graph, resulting in a slot conflict:


  (dev-libs/icu-64.2:0/64.2::gentoo, ebuild scheduled for merge) pulled in by
    (no parents that aren't satisfied by other packages in this slot)

  (dev-libs/icu-63.1-r1:0/63.1::gentoo, installed) pulled in by
    >=dev-libs/icu-51.2-r1:0/63.1=[abi_x86_64(-)] required by (media-libs/harfbuzz-2.3.1:0/0.9.18::gentoo, installed)

What you see is that portage wants to upgrade dev-libs/icu to version 64.2, but it cannot because an installed package media-libs/harfbuzz had installed a icu but a lower version, namely 51.2-r1.

Often the easiest way is to just upgrade both packages that have the conflict:

root #emerge --ask --oneshot --verbose dev-libs/icu media-libs/harfbuzz

Adding the --oneshot option or (-1 for short), will prevent these packages to be added to the world set.

Keyword changes

It can happen that a package needs a newer version that is not yet marked as stable. An example is:

root #emerge -vauDN --verbose-conflicts @world
The following keyword changes are necessary to proceed:
 (see "package.accept_keywords" in the portage(5) man page for more details)
# required by x11-libs/pango-1.42.4-r1::gentoo
# required by www-client/firefox-68.0.1::gentoo
# required by @selected
# required by @world (argument)
=media-libs/harfbuzz-2.5.3 ~amd64
# required by www-client/firefox-68.0.1::gentoo
# required by @selected
# required by @world (argument)
=dev-util/cbindgen-0.9.0 ~amd64
# required by www-client/firefox-68.0.1::gentoo
# required by @selected
# required by @world (argument)
=dev-libs/nss-3.45 ~amd64

Would you like to add these changes to your config files? [Yes/No]

The last sentence is only added if FIXME option is enabled. In this case firefox requires unstable versions of pango, harfbuzz, and cbindgen. The reason could be that the to be installed version of firefox itself is not in the stable branch. Review if you want this unstable version of firefox, and if so then accept also the unstable version of its dependencies.

After the upgrade of the software packages

After completing updating the world set, there is still some work to be done.

Read news

Upgraded packages may have specific instructions. Make sure to read them and follow-up:

root #eselect news read

Rebuild packages that link to old versions

After the upgrade you might see something

root #emerge -vauDN --verbose-conflicts @world
!!! existing preserved libs:
>>> package: dev-libs/icu-64.2
 *  - /usr/lib64/
 *  - /usr/lib64/
 *      used by /usr/lib64/ (media-libs/libcdr-0.1.5)
 *      used by /usr/lib64/ (app-text/libmspub-0.1.4)
 *      used by /usr/lib64/ (app-text/libqxp-0.0.2)
 *      used by 2 other files
 *  - /usr/lib64/
 *  - /usr/lib64/
 *      used by /usr/lib64/ (dev-qt/qtcore-5.11.3-r2)
 *      used by /usr/lib64/ (media-libs/libcdr-0.1.5)
 *      used by /usr/lib64/ (app-text/libebook-0.1.2-r1)
 *      used by /usr/lib64/ (app-text/libmspub-0.1.4)
 *  - /usr/lib64/
 *  - /usr/lib64/
 *      used by /usr/lib64/ (dev-qt/qtcore-5.11.3-r2)
 *      used by /usr/lib64/ (media-libs/libcdr-0.1.5)
 *      used by /usr/lib64/ (app-text/libebook-0.1.2-r1)
 *      used by 5 other files
>>> package: sys-fs/cryptsetup-2.1.0
 *  - /usr/lib64/
 *  - /usr/lib64/
 *      used by /usr/lib64/ (dev-libs/volume_key-0.3.11)
 *      used by /usr/lib64/python3.6/site-packages/ (dev-libs/volume_key-0.3.11)
>>> package: sys-libs/zlib-1.2.11-r2
 *  - /usr/lib32/
 *  - /usr/lib32/
 *      used by /usr/lib/gcc/x86_64-pc-linux-gnu/8.3.0/32/ (sys-devel/gcc-8.3.0-r1)
Use emerge @preserved-rebuild to rebuild packages using these libraries

It indicates that some packages may still be linked to either upgraded or removed packages. Resolve it by executing:

root #emerge --ask @preserved-rebuild

Update config files

When packages are upgraded, new configuration files might be delivered as well. Portage won't overwrite the already installed once, but will offer to keep the old ones, use the new ones, or merge them. After the upgrade you might see something like this:

root #emerge -vauDN --verbose-conflicts @world
 IMPORTANT: config file '/etc/conf.d/zram-init' needs updating.
 * sections of the emerge man page to learn how to update config files.

The simplest command to process the new config files is etc-update.

Clean up old packages

There maybe some debris left after a world upgrade. It does not harm but it occupies disk space.


After upgrading everything there may still be old libraries and executables installed. Remove them with

root #emerge --verbose --ask --depclean

Review very carefully which of the package you agree to have removed. If there is a package that you would like to keep then add it to the world set:

root #emerge --verbose --noreplace app-editors/nano


Portage does not remove software and configuration files that are created outside of portage. A good example are linux kernels that are built after installing sys-kernel/gentoo-sources

clean up /boot

Review which kernels you would like to keep with with:

root #ls /boot
config-4.14.83-gentoo      initramfs-genkernel-x86_64-4.18.14-gentoo
config-4.17.14-gentoo      lost+found                                 vmlinuz-4.14.83-gentoo
config-4.18.14-gentoo                  vmlinuz-4.17.14-gentoo
config-4.18.14-gentoo                  vmlinuz-4.18.14-gentoo
config-4.19.9-gentoo                  vmlinuz-4.18.14-gentoo.old
config-4.19.9-gentoo.old              vmlinuz-4.19.9-gentoo
config-5.0.3-gentoo                   vmlinuz-4.19.9-gentoo.old
config-5.0.4-gentoo               vmlinuz-5.0.3-gentoo
config-5.0.5-gentoo                    vmlinuz-5.0.4-gentoo
config-5.0.5-gentoo.old                    vmlinuz-5.0.5-gentoo
config-5.1.15-gentoo                    vmlinuz-5.0.5-gentoo.old
config-5.1.15-gentoo.old                vmlinuz-5.1.15-gentoo
config-5.1.6-gentoo                   vmlinuz-5.1.15-gentoo.old
config-5.1.6-gentoo.old                   vmlinuz-5.1.6-gentoo-thinkpad-E485

Delete them from /boot. Do not forget to update the boot script, e.g. for grub:

root #grub-mkconfig -o /boot/grub/grub.cfg

clean up /usr/src

The same kernels that you have removed can also be removed from /usr/src.

cleanup modules

The modules are located per kernel version at /lib/modules:

root #ls /lib/modules
4.14.83-gentoo  4.18.14-gentoo  5.0.3-gentoo  5.0.5-gentoo  5.1.15-gentoo
4.17.14-gentoo  4.19.9-gentoo   5.0.4-gentoo  5.1.0-gentoo  5.1.6-gentoo

Remove the ones for which you have removed the kernel software.