Tools for inspecting portage state and generating upgrade sets
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



  • Gentoo
  • app-portage/portage-utils (qatom)
  • sys-apps/coreutils (sort)
  • sys-apps/findutils (xargs)
  • sys-apps/grep (grep)
  • sys-apps/portage (portageq)
  • sys-apps/sed (sed)


This is now installable from portage by

emerge -va app-admin/gentoo-perl-helpers

USAGE From Git Checkout

If using Git sources, running the helpers requires you be in a specific location for paths to load properly.

Specific steps and specific assumed working directories are needed to work directly from Git, as this tool is designed to be installed to /usr/bin/ where library paths are hard-coded at installtime.

git clone
pushd gentoo-perl-helpers

Invoking it from a directory other than the project root will have unexpected side effects.

Generating the sets automatically in /etc/portage/sets

Where 5.20 is your existing perl(ABI/SUBSLOT) and 5.22 is your target perl

bin/gentoo-perl gen-upgrade-sets 5.20 5.22

Generating the sets in another dir as a non-privlegled user

ETC_PORTAGE_SETS="/tmp/sets/" bin/gentoo-perl gen-upgrade-sets 5.20 5.22
sudo cp /tmp/sets/* /etc/portage/sets/*

Performing the upgrade

sudo emerge -va1 -k n @perl-upgrade


If portage gets stuck with perl-core/* ( it shouldn't, but it might )

sudo emerge -C -va @perl-cleanup

Will purge them for you, and a subsequent retry should then work.

Mid-Upgrade Failures

If portage fails midway though installing a package and aborts the upgrade, resuming it somehow is necessary.

If portage gets confused by a reattempt at

sudo emerge -va1 -k n @perl-upgrade

Then rexecuting

bin/gentoo-perl gen-upgrade-sets 5.20 5.22

Will regenerate a smaller installation target, containing only packages that are still necessary for a portage upgrade

Post Install

It is strongly encouraged to run perl-cleaner --all after upgrading Perl in the event there are any stragglers with secret Perl dependencies that are not visible to portage.

Advanced Usage

Most of the internals of this tool can be used directly to facilitate generating your own sets if it doesn't quite meet your needs.

  • bin/gentoo-perl list-commands-desc will give you a list of tools that you can use
  • bin/gentoo-perl help $toolname will give you detailed help on that tool

For example, for the most part, gen-upgrade-sets is implemented in terms of:

bin/gentoo-perl installed-deps-subslot-rebuild ${perl_target}
bin/gentoo-perl installed-perl-virtuals

And the @perl-cleanup target is mostly just

bin/gentoo-perl installed-perl-core

Some of these tools may be useful in fixing weird edge-cases, or simply reporting problems back to gentoo devs.