Migrating Portage Repository Locations

Content:

In 2018, the Gentoo Council agreed on a new set of defaults for several directories used by Portage. The new directory layout into effect in 2019.

If you’re still running the old directory layout, you won’t have been impacted by the change. Should the old directories still be in use, Portage will detect this, and continue using them.

You’ll notice, though, that Gentoo documentation now refers to the new locations. This means that, if you’re following Gentoo documentation, you’ll need to keep in mind the difference in directories.

It’s not too difficult to convert your system to use the new directories. This guide will show you how to make this change.

Rationale

The reason these directories have been changed is to better adhere to the Unix Filesystem Hierarchy Standard (FHS).

FHS defines the core filesystem hierarchy used by adopting Unix/Linux OS’s. Adhering to the FHS (or at least, most of the FHS) provides a common system hierarchy for installable packages to target.

FHS a trailing standard, with updates to the standard reflecting common practices. It’s common to see distros deviate slightly from the standard, with commonly-adopted changes becoming part of the standard down the line.

In Gentoo, the old Portage repository locations clearly did not adhere to FHS, which is the rationale behind the change.

Changes

This change impacted three directories.

The change moves the directories used to cache package sources to /var/cache, with the PKDIR folder being renamed to binpkgs to better reflect its purpose.

PORTDIR, used to store the list of ebuilds available in the Gentoo package tree, moves to /var/db/repos/gentoo. /var/db/repos/ is also the home for any third-party repositories that are added to the system.

Migrating Your System

Follow these steps to migrate your system to use the new directories.

Preparation

First, make a note of the current profile your system is running. You can do this by running

$ eselect profile show
Current /etc/portage/make.profile symlink:
  default/linux/amd64/17.1/desktop/gnome/systemd

Take a look in /etc/portage/make.conf, and ensure any references to PORTDIR, DISTDIR and PKGDIR are commented out (or removed entirely).

If you’re mounting /var/cache as a separate tmpfs partition, consider whether any changes need to be made to accommodate the new distfiles folder. This is likely to be a large folder.

The final preparatory step is to ensure the /var/db/repos directory exists. If it doesn’t create it.

Making the Change

Now, you’re ready to start moving the directories. Run the following commands to move each directory to the new location. You’ll need root permissions to do this.

Be sure to move /usr/portage after the other two, as distfiles and packages reside inside this directory.

mv /usr/portage/distfiles /var/cache/distfiles
mv /usr/portage/packages /var/cache/binpkgs
mv /usr/portage /var/db/repos/gentoo

In /etc/portage/repos.conf/gentoo.conf, change the location value from /usr/portage, to /var/db/repos/gentoo.

With that complete, you’ll need to re-enable your profile.

eselect profile set default/linux/amd64/17.1/desktop/gnome/systemd

Replace the profile path with the one recorded earlier.

The final step is to reinstall Portage, using the new DISTDIR and PKGDIR directories.

DISTDIR=/var/cache/distfiles PKGDIR=/var/cache/binpkgs emerge --oneshot portage

Once Portage has been reinstalled, your system is ready to go.