User:Hfern/Drafts/Overdue maintenance

One Gentoo's characteristics is that it has a rolling release model. There is no upgrade 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.

However when an upgrade is not done for quite a while, like for half a year or longer, it can happen that the package and versions 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 anymore.

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

Syncing portage
Upgrades are initiated with:

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

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

Make sure to read and understand what is shared.

Evaluate what needs upgrading
The command to evaluate what all needs upgrading everything:

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.

Upgrade toolstack
Gentoo's toolstack is the software that builds the packages. It is important to upgrade the toolstack before anything else.

portage
Portage is the heart of Gentoo's dependency system. Always make sure the latest in is installed:

gcc
Is 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:

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

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

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