The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
lib-archive-0.92
River stage zero No dependents
/ lib::archive

NAME

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

SYNOPSIS

  use lib::archive ("../external/*.tgz", "lib/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;

or

  use lib::archive '__DATA__';

  __DATA__
  <followed by base64 encoded tar or tgz blocks separated by an empty line>

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.

Relative paths will be interpreted as relative to the directory the calling script or module resides in. So don't do a chdir() before using lib::archive when you call your script with a relative path and use releative paths for lib::archive.

In standard mode the module will not create any files, not even temporary. Everything is extracted on the fly. When running under a debugger or the environment variable PERL_LIB_ARCHIVE_EXTRACT is set to a directory name the directories and files will be extracted to the filesystem. I case of running under a debugger without PERL_LIB_ARCHIVE_EXTRACT being set the extracted modules will be saved to the .lib_archive_extract directory in the user's home directory (determined by glob('~')). The home directory can be overwritten by setting the environment variable PERL_LIB_ARCHIVE_HOME.

An attempt will be made to create the directory should it not already exist.

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>