
## REQUIREMENTS

- 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)

### USAGE From Git Checkout

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.

```bash
git clone https://github.com/gentoo-perl/gentoo-perl-helpers
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

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

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

```bash
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

```bash
sudo emerge -va1 -k n @perl-upgrade
```

### Blockers

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

```bash
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 

```bash
sudo emerge -va1 -k n @perl-upgrade
```

Then rexecuting 

```bash
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:

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

And the `@perl-cleanup` target is mostly just

```bash
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.
