User:Kangie/Funtoo Migration Guide

  Important note to editors - plans for article

• Brief overview of both Funtoo and Gentoo
• Reasons for migrating from Funtoo to Gentoo (e.g., stability, support, community)
• Target audience (Funtoo refugees)
• How to make Gentoo more like Funtoo ?
• Scope of the guide (focus on key differences and migration steps)

In light of the recent news about the end of the Funtoo project from it's founder, this article aims to give Funtoo users a brief overview of Gentoo, of how Funtoo deviated from the original, of features since-gained by Gentoo that cover some of Funtoo's original functionality, what reasons one might now have for moving from Funtoo to Gentoo, and a brief outline of one possible procedure for migration.

The hope is that this information might reassure any users who are considering switching to Gentoo that there is a smooth path for migration and that the differences aren't as great as one might expect.

To follow this article in order to migrate a preexisting installation from Funtoo to Gentoo, a basic understanding of Gentoo and its package management system will be required, as well as basic familiarity with Funtoo.

Important
Always backup all essential data and configuration files before attempting intervention on any lower-level OS components.

A very short history of Gentoo and Funtoo

The Gentoo project traces it's origins to the end of the 1990's, when a Stampede Linux developer named Daniel Robbins created an independent software distribution from scratch.

Soon, the Gentoo project would be managed through a for-profit corporation called Gentoo Technologies Inc., with a permanent chief architect and project-leads appointed through various processes.

In 2004 the Gentoo Foundation was formed, taking over from Gentoo Technologies Inc., to oversee the administrative side of the project. In 2005, the Gentoo Council was created to manage more technical considerations and day-to-day activity; members are elected from the pool of Gentoo developers.

As a full-blown OS, Gentoo now exclusively targets the Linux kernel. The software distribution remains installable on other operating systems through Gentoo Prefix (e.g. on MS Windows, Darwin (macOS/OS X), Android, etc.).

See also
For more in-depth Gentoo history, see the Gentoo History article.

Differences between Funtoo and Gentoo

• Profiles: Funtoo used 'ego' to manage and assemble "profile snippets" into a user specified profile
  • It's possible to accomplish this in Gentoo by combining your own profile.
• Stage Creation: Funtoo used Metro to build and customise stage images.
  • Gentoo uses Catalyst to accomplish the same tasks.
• Udev: Funtoo uses eudev while Gentoo uses sys-apps/systemd-utils[udev]
• Binary Packages: Gentoo provides official binary package support for several arches, including a subarch of x86-64-v3 to cater to modern systems.
  • This is a great way to quickly bootstrap or repair a system. Modern stage3 images ship with this configured and the appropriate FEATURE can be enabled to start using binpkgs.

Potential challenges and workarounds:

• None yet. Gentoo is awesome.

Migrating a Funtoo installation to Gentoo Linux

Note
It is imperative that a full system backup be performed before proceeding. While it is unlikely that any Funtoo user will inadvertently wipe an important partition, this risk can mitigated by having a recent full system backup available.

Recommended Path

• Backup /home, either in its entirety or for specific users.

root #tar cJf home_backup.tar.xz /home

• Backup /etc to restore app configuration.

root #tar cJf etc_backup.tar.xz /etc

• Inspect the 'world' file /var/lib/portage/world and note down installed packages.
  • Most of these will come from Gentoo indirectly and should just work, some overlays may be required: try searching GPO

• Inspect your profile and note down any USE flags (etc). If this is confusing, a Gentoo 'Desktop' profile is pretty fully featured and is a safe starting point for most interactive (gui) systems.

• Follow the standard Gentoo Handbook installation, selecting appropriate options where necessary.

• After the Stage3 tarball has been unpacked, also unpack the homes. Fix the ownership if required after creating new user(s).

• Install the required packages from the previously saved world file.

• Unpack the /etc backup to a temporary location and restore any necessary configuration files. Beware that configuration between Funtoo and Gentoo may differ; it may be wise to ``diff`` configuration files.

In-place migration

Warning
While some Funtoo users have reported success in migrating their system to use Gentoo repositories this is unsupported. The faint of heart should use the supported migration option outlined above. Hic sunt dracones.

It may be useful to run the usr-merge script, however this _should_ not be required, just note that 23.0 profiles are merged-usr by default with split-usr called out explicitly (i.e. inverse of 17.x)

It may be worth referencing an appropriate Stage 3 for the profile that is intended to be used. Ensure that there is recovery media available to chroot into the system in the event that something goes wrong.

The below is a general outline of the steps that need to be taken to migrate a Funtoo system to use the Gentoo repositories:

• Disable any non-core repositories (i.e. overlays)
• Get an updated Portage ebuild from Gentoo
  • Change PYTHON_COMPAT and python_gen_cond_dep to python3.9
  • Install with `ebuild portage-3.0.65-r1.ebuild merge` and disregard dependencies)
• Back up /etc/portage and modify /etc/portage/make.conf to suit a Gentoo system.
  • The defaults from a stage3 will be fine as a basis, maybe check git or the wiki.
• Install Gentoo GPG keys
  • Try the 'getuto' ebuild
  • TODO: Manual steps
• Replace Funtoo's Portage tree with a Gentoo Portage snapshot.
  • emerge-webrsync
• Install python 3.12 or other supported version (3.10 may be an easier stepping stone)

root #emerge -av1 --nodeps mpdecimal python:3.12

Note
This may not work without editing some ebuilds.

If python3.12 install fails there are a few possible alternatives:

• use brute force: copy /usr/lib/python3.12 , /usr/lib/python-exec from a stage3
  • Fix any conflicts
  • This will probably need a chroot or binpkgs to fix. That might be a better option.

• Binpkgs?
• Portage from source?

The result that we need is portage, python, and ebuilds in alignment.

• Select an appropriate profile, Update glibc and binutils; Reference the Profile Migration instructions: [1]:
  • Run "emerge --info" and note down the value of the CHOST variable.
  • Edit /etc/portage/make.conf; if there is a line defining the CHOST variable, remove it. Also delete all lines defining CHOST_... variables.
  • Select the 23.0 profile corresponding to your current profile, either using "eselect profile" or by manually setting the profile symlink.

Note
Old (17.x, funtoo?) profiles are by default split-usr and the 23.0 profiles by default merged-usr. Do NOT change directory scheme now, since this will mess up your system.

Instead, make sure that the new profile has the same property, e.g.

CODE

OLD default/linux/amd64/17.1  
     ==>  NEW default/linux/amd64/23.0/split-usr
          (added "split-usr")
OLD default/linux/amd64/17.1/systemd/merged-usr  
     ==>  NEW default/linux/amd64/23.0/systemd
          (removed "merged-usr")

• • Delete the contents of the binary package cache at ${PKGDIR}: rm -r /var/cache/binpkgs/*
  • In the file or directory /etc/portage/binrepos.conf (if existing), update the URI in all configuration such that they point to 23.0 profile binhost directories.
  • Rebuild or reinstall from binary (if available) the following packages in this order, with the same version as already active:

root #emerge --ask --oneshot sys-devel/binutils

root ## may have to run binutils-config and re-select binutils now

root #emerge --ask --oneshot sys-devel/gcc

Warning
If this command wants to rebuild glibc first, do not let it do that; instead, abort and try again with --nodeps added to the command line. It may be necessary to run gcc-config and re-select gcc now.

• • Finally re-emerge the C library.

root #emerge --ask --oneshot sys-libs/glibc

• • Re-run "emerge --info" and check if CHOST has changed. If the CHOST has NOT changed, skip to env-update. Otherwise:
    • Recheck with binutils-config and gcc-config that valid installed versions of binutils and gcc are selected.
    • Check /etc/env.d, /etc/env.d/binutils, and /etc/env.d/gcc for files that refer to the *OLD* CHOST value, and remove them.
  • Run env-update && source /etc/profile

root #env-update && source /etc/profile

• • Re-emerge libtool:

root #emerge --ask --oneshot libtool

• • Just for safety, delete the contents of the binary package cache at ${PKGDIR} again:

root #rm -r /var/cache/binpkgs/*

• • Do any required migrations (e.g. eudev -> sys-apps/systemd-utils[udev])
  • Emerge World.

root #emerge --ask --emptytree @world

• Deal with any breakage:
  • wrong/missing use flags,
  • files owned by other packages due upgrades,
  • nodeps installs,
  • removed packages
• Have Fun!
• Adapt Funtoo-specific ebuild overlays to Gentoo standards, and re-enable the overlays.
  • Issues that are likely to be encountered:
    • PYTHON_* variables
    • ACCEPT_KEYWORDS.
    • Differing USE flags

For users with a significant attachment to their existing installation, or those with a great deal of Funtoo experience (particularly around resolving dependency conflicts),

Troubleshooting

• Common issues encountered during migration
• Troubleshooting steps and potential solutions

Tips

• Using Gentoo's package management effectively
• Leveraging Gentoo's community and resources
• Optimizing system performance and security