Upgrade Instructions/1.2-release

Here are improved upgrade steps for the 1.2 release. First, please make sure that you have created a backup of your system. If you choose to proceed without a backup, then you are assuming the risk of a broken system and dealing with fixing it or re-installing. While these install steps are fairly robust, we will be removing what appear to be unused packages on the system, and in odd cases this could result in some packages being removed that you actually need. Typically this will not happen, but since the possibility exists, it is best to be prepared for this possibility, particularly on critical systems.

First, you will want to run ego sync and upgrade to ego-2.4.1. If you have difficulty satisfying deps for it for whatever reason, the following should work:

root # cd /var/git/meta-repo/kits/core-kit/app-admin/ego
root # ebuild ego-2.4.1.ebuild merge

Once the new ego is merged, edit your /etc/ego.conf to look like this:

   /etc/ego.conf

[global]

release = 1.2

Now, run the following steps as root.

root # ego sync

This will activate the new 1.2 kits. Now, time to start upgrading:

root # emerge -u1 isl gcc

This will upgrade gcc. Inclusion of libisl should eliminate the need to rebuild gcc twice. Next,

root # emerge -u1 glibc libnsl libtirpc rpcsvc-proto

Glibc and its dependencies/related packages will now be upgraded.

Since moving to 1.2 also includes moving to python-3.6, perform the following steps:

root # emerge -u1 =dev-lang/python-3.6*
root # emerge -C =dev-lang/python-3.4*

This will ensure that we have python-3.6 ready and installed, and the older python-3.4 removed.

Now, edit your /var/lib/portage/world file. Look for catpkgs (ie. "category/packagename") that you no longer use or need on your system and remove them. Also consider packages you may have installed with --oneshot that are not in the world file but should be, and add them. Portage will use /var/lib/portage/world as the master list of packages that should be on your system. We will now look into cleaning up any unnecessary packages that are not in the world set. We want to remove these packages for a couple of reasons. First, they will not get upgraded with a @world update. Second, because they are not included in @world, they could be outdated and have old and problematic dependencies that could hamper our upgrade, since portage will not want to "break" dependencies for these orphaned packages. Third, when we do an emerge @preserved-rebuild, we may end up rebuilding packages that we don't need. So removing unnecessary packages is a good idea for quite a few reasons.

Run the following command and carefully review its output. Do not say "y" at this point:

root # emerge -p --depclean --ignore-soname-deps=n

   Note

The --ignore-soname-deps=n option will prevent packages that provide necessary libraries from being removed, even if they appear to be "orphaned." This is an additional safety measure when cleaning dependencies from your system.

Now, review the list of packages that are going to be removed. See anything in this list that you know you need? This would indicate that you need to add the cat/pkg to /var/lib/portage/world before proceeding. Once the list looks OK, type:

root # emerge -a --depclean   --ignore-soname-deps=n

...And type "y" [enter] to remove old packages.

Now, you should have a still-functioning system, but with all "extra" packages removed. Now it is time to upgrade the packages that remain. For upgrading to 1.2, you have a couple of options. The first option is to just rebuild any packages in need of updates. The second option is to rebuild all packages, which will ensure that your system is fully optimized with the new gcc.

Here is the first, faster option:

root # revdep-rebuild --library 'libstdc++.so.6' -- --exclude sys-devel/gcc
root # emerge -auDN @world 
root # emerge @preserved-rebuild -a

The first revdep-rebuild command will rebuild any packages that depend on earlier versions of libstdc++.so.6. Next, we will perform a world update, and then we will rebuild any packages that are linking to old, preserved libraries.

   Note

Include the --jobs=3 (or higher number) option as a parameter to the emerge command if you have sufficient RAM and CPU cores to build several packages in parallel.

Here is the second, more comprehensive option:

root # emerge --emptytree -a @world

This will fully rebuild all packages on your system. It will take a lot more time, but will ensure everything is freshly rebuilt. Either option, once completed successfully, will result in an up-to-date system, but the second option will result in potentially better-optimized binaries, benefiting from more recent gcc improvements.

Finally, you will want to either run etc-update or dispatch-conf:

root # etc-update

If your kernel has been upgraded, make the necessary changes to /etc/boot.conf to make the new kernel the default, and then re-run boot-update:

root # boot-update

Now is a good time to perform a pre-check of any packages that have been installed that may require configuration file updates. One notable example is php-fpm -- you may need to perform the following steps if your system uses php-fpm:

root # cp /etc/php/fpm-php-7.1/php* /etc/php/fpm-php-7.3/php*

This will ensure that the settings you use for the previously-installed version of php-fpm will be applied to the current version.

   Note

If you find any other packages that need similar manual steps post-upgrade, please document them here for the benefit of others! Thanks.

At this point, the migration to 1.2 should be complete. At a convenient time, reboot your system, and perform a thorough check of all services to ensure they have started correctly:

root # reboot

After reboot:

root # rc-status

Now, perform a final check of any production services to ensure that they are operating properly, by loading web pages, sending test emails, etc.

At this point, you are now upgraded to Funtoo Linux 1.2! Please report any bugs to https://bugs.funtoo.org and let us know of any issues you experience, either as part of the upgrade, related to dependencies, or related to functionality on your upgraded system.