Upgrade Instructions/1.2-release

   Important

The goal of these instructions is to provide Funtoo Linux users with a reliable, consistent set of instructions for upgrading Funtoo Linux from 1.0 to 1.2. Please assist in ensuring that these instructions are complete and guide users through any potential complications. Since this is a wiki, make changes to the page that are needed to make these instructions 100% reliable. Thank you!

These instructions will guide you through the process of upgrading your system from Funtoo Linux 1.0 to 1.2. 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 while every precaution is taken to avoid breaking packages, 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.

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.

   Note

You may be wondering -- what are these packages on my system that are not part of the world set? They could be a number of things. First, they could be build dependencies for certain packages. They could possibly be old slots of packages you already use -- for example, an old version of PHP. The could also be packages that were dependencies of certain packages, but are no longer needed by those packages -- possibly due to changes in USE flags. Often, virtuals are part of this group of packages, and it is generally safe for virtuals to be removed. They will get re-emerged in the future if referenced by an ebuild.

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.

Now you will want to run ego sync and upgrade to the latest ego-2.4.x series available.

root #  ego sync
root #  emerge -C boot-update
root #  emerge -v1 ego

If you have difficulty satisfying deps for it for whatever reason, the following should work:

root #  emerge -C boot-update
root #  emerge -v1 --nodeps ego

If you still cannot merge using emerge, the following should work (note that this will fail if you don't have the ebuild in your tree, and ego thinks it is at its highest revision):

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

If the foregoing fails, this will definitely pull in the latest ego and allow you to sync properly:

root #  git clone https://github.com/funtoo/ego.git
root #  cd ego
root #  ./ego sync

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 gcc

This will upgrade gcc.

This is an ideal time to review the subarch setting of your Funtoo Linux installation. Funtoo Linux 1.2 now has optimizations available for 5th and 6th-generation Intel Core processors, as well as Ryzen processors. View your current subarch, as well as available subarches, by typing the following command:

root # ego profile list subarch

=== subarch: ===

    amd64-bulldozer, amd64-excavator, amd64-jaguar, amd64-k10
    amd64-k8, amd64-k8+sse3, amd64-piledriver, amd64-steamroller
    amd64-zen, atom_64, btver1_64, core-avx-i, core2_64, corei7
    generic_64, intel64-broadwell, intel64-haswell, intel64-ivybridge
    intel64-nehalem, intel64-sandybridge, intel64-silvermont, intel64-skylake
    intel64-westmere*, native_64, nocona, opteron_64, xen-pentium4+sse3_64

root #

If desired and supported by your CPU, you can now update your subarch to a more optimized subarch for your hardware. The new subarch profiles available are:

• intel64-skylake - Optimized for Intel Core 6th Generation Processors (see intel64-skylake for more info.)
• intel64-broadwell - Optimized for Intel Core 5th Generation Processors (see intel64-broadwell for more info.)
• amd64-zen - Optimized for AMD Ryzen Processors.

Use the lscpu command to view information about your CPU and do a web search for its name to determine what generation CPU it is. Then, the system's subarch can be changed as follows:

root # ego profile subarch intel64-skylake
=== Enabled Profiles: ===

        arch: x86-64bit
       build: current
     subarch: intel64-skylake
      flavor: core

>>> Set subarch to intel64-skylake.
root ##b##Updating profiles at /etc/portage/make.profile/parent...

root #

Now that we have ensured that we have an optimal subarch set for your system, it's time to begin the process of rebuilding critical packages with the new compiler. We will start with glibc. Enter the following command:

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. Removing python-3.4 is important to ensure that python modules upgrade properly.

Some packages rely on a current ruby being available on the system, and having stale versions on your system can cause problems. To remove these from your system, run:

root # emerge -C \<=dev-lang/ruby-2.3.0

For upgrading to 1.2, you have to rebuild all packages, which will ensure that your system is fully optimized with the new gcc.

   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 what you need to run:

root # emerge --emptytree -a @world

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

   Note

If the preceding command fails, you should run 'emerge -uDN1 --keep-going @world' to ensure that all dependencies are fully resolved and rebuilt, then run the 'emerge --emptytree -a @world' command again to ensure that every package is rebuilt with the new gcc compiler. If *that* fails, you might need to run revdep-rebuild --library 'libstdc++.so.6' -- --exclude gcc in order to update the C++ abi for the new gcc.

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 ego boot update:

root # ego 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.