=pod

=head1 NAME

perl-migrate-modules - Migrate installed CPAN modules from one Perl to another

=head1 SYNOPSIS

perl-migrate-modules [OPTIONS] []

perl-migrate-modules /path/to/perl-5.28.0 /path/to/perl-5.28.1
perl-migrate-modules -nq -Ilib /usr/bin/perl ~/bin/perl
perl-migrate-modules --from ~/perl5/lib/perl5 ~/perls/5.20.0

Options: -c, --include-core Install core modules from source Perl -h, --help Show this message -f , --from= Search only these path(s) for source modules -I , --lib= Additional search path(s) for source modules -n, --notest Skip testing and test dependencies -q, --quiet Show only installation successes and failures -v, --version Show the version of this script

=head1 DESCRIPTION

Reinstalls all modules found in the source Perl into the destination Perl, similar to the C command for L or the C command for L<plenv|https://github.com/tokuhirom/plenv>. The Perls may be passed as paths to the base installation directory or paths to the F executable itself. If only one path is passed, it will be used as both the source and destination, but the search and install paths can be influenced.

Modules are found in the source Perl's standard C<@INC> search paths by default. To specify additional search paths, such as L directories, use the C<-I>/C<--lib> option. To specify search paths to use and omit the standard search paths, use the C<-f>/C<--from> option.

Modules are installed to the destination Perl using L. To influence the install location, activate a L in your environment, or use the standard Perl and L environment variables, such as L<ExtUtils::MakeMaker/PERL_MM_OPT>, L<Module::Build/PERL_MB_OPT>, and L<cpanm/PERL_CPANM_OPT>.

=head1 EXAMPLES

=over

=item *

Basic migration of modules to a newly installed Perl from an existing one:

$ perl-migrate-modules /opt/perl-5.20.3 /opt/perl-5.22.0

=item *

Migrate modules from an old (inactive) local::lib directory, using F</usr/bin/perl> both to find source modules and to install:

$ perl-migrate-modules --from ~/perl5-old/lib/perl5 /usr/bin/perl

=item *

Migrate modules from the sitelib of a Perl that can no longer be executed, using the active Perl executable both to find source modules and to install:

$ perl-migrate-modules --from ~/.plenv/versions/5.24.0/lib/perl5/site_perl/5.24.0/ $(which perl)

=item *

Migrate modules to a custom local::lib location, using F</opt/perl-5.28.0> to find modules within its search paths and using F</opt/perl-5.28.1> to install to F</opt/project/local>:

$ env PERL_CPANM_OPT='-l /opt/project/local' perl-migrate-modules /opt/perl-5.28.0 /opt/perl-5.28.1

=item *

Update all modules installed in the active Perl:

$ perl-migrate-modules --include-core $(which perl)

=back

=head1 CAVEATS

Only modules with F<.packlist> will be migrated, this will include any module installed by CPAN clients, but generally not modules installed by vendor packages or core modules. Core modules available from CPAN can be included via L with the C<--include-core> option.

Migrated modules will be installed at their latest indexed version, not the existing version when found.

Any environment settings that affect Perl's library search and module install locations, such as C or an active L, will be ignored while searching for modules with the source Perl but will have their normal effect on installation into the destination Perl.

=head1 BUGS

Report any issues on the public bugtracker.

=head1 AUTHOR

Dan Book dbook@cpan.org

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 by Dan Book.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

=head1 SEE ALSO

L<perlbrew/"COMMAND: CLONE-MODULES">

=cut