NAME

lib::archive - load pure-Perl modules directly from TAR archives

SYNOPSIS

  use FindBin qw($Bin);
  use lib::archive qw("$Bin/external/*.tgz", "$Bin/extra.tar");

  use MyModule; # the given tar archives will be searched first

or

  use lib::archive qw(
    https://www.cpan.org/modules/by-module/JSON/JSON-PP-2.97001.tar.gz
    CPAN://YAML-PP-0.007.tar.gz
  );

  use JSON::PP;
  use YAML::PP;

DESCRIPTION

Specify TAR archives to directly load modules from. The TAR files will be searched like include dirs. Globs are expanded, so you can use wildcards (not for URLs). If modules are present in more than one TAR archive, the first one will be used.

The module will not create any files, not even temporary. Everything is extracted on the fly.

You can use every file format Archive::Tar supports.

If the archive contains a toplevel directory 'lib' the module search path will start there. Otherwise it will start from the root of the archive.

If the archive is a gzipped TAR archive with the extension '.tar.gz' and the archive contains a toplevel directory matching the archive name without the extension the module search path starts with this directory. The above rule for the subdirectory 'lib' applies from there. This means that e.g. for 'JSON-PP-2.97001.tar.gz' the modules will only be included from 'JSON-PP-2.97001/lib'.

You can use URLs for loading modules directly from CPAN. Either specify the complete URL like:

  use lib::archive 'https://www.cpan.org/modules/by-module/JSON/JSON-PP-2.97001.tar.gz';

or use a shortcut like:

  use lib::archive 'CPAN://JSON-PP-2.97001.tar.gz';

which will do exactly the same thing (at least in most cases: there seem to be modules without an entry under 'modules/by-module/<toplevel>'; in that case you have to use an URL pointing to the file under 'authors/id').

If the environment variable CPAN_MIRROR is set, it will be used instead of 'https://www.cpan.org'.

WHY

There are two use cases that motivated the creation of this module:

1. bundling various self written modules as a versioned release

2. quickly switching between different versions of a module for debugging purposes

AUTHOR

Thomas Kratz <tomk@cpan.org>