The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
PAR-Repository-0.21
River stage zero No dependents
1 ++
/ PAR::Repository

NAME

PAR::Repository - Create and modify PAR repositories

SYNOPSIS

  # Usually, you want to use the 'parrepo' script which comes with
  # this distribution.
  use PAR::Repository;
  
  my $repo = PAR::Repository->new( path => '/path/to/repository' );
  # creates a new repository if it doesn't exist, opens it if it
  # does exist.
  
  $repo->inject(
    file => 'Foo-Bar-0.01-x86_64-linux-gnu-thread-multi-5.8.7.par'
  );
  $repo->remove(
    file => '...'
  );
  $repo->query_module(regex => 'Foo::Bar');

DESCRIPTION

This module is intended for creation and maintenance of PAR repositories. A PAR repository is collection of .par archives which contain Perl code and associated libraries for use on specific platforms. In the most common case, these archives differ from CPAN distributions in that they ship the (possibly compiled) output of make in the blib/ subdirectory of the CPAN distribution's build directory.

You can access a PAR repository using the PAR::Repository::Client module or the PAR module which provides syntactic sugar around the client. PAR allows you to load libraries from repositories on demand.

PAR REPOSITORIES

A PAR repository is, basically, just a directory with certain stuff in it. It contains:

modules_dists.dbm.zip

An index that maps module names to file names. Details can be found in PAR::Repository::DBM.

symlinks.dbm.zip

An index that maps file names to other files. You shouldn't have to care about it. Details can be found in PAR::Repository::DBM.

scripts_dists.dbm.zip

An index that maps script names to file names. Details can be found in PAR::Repository::DBM.

repository_info.yml

A simple YAML file which contains meta information for the repository. It currently contains the following bits of information:

dbm_checksums.txt

A text file associating the DBM files with their MD5 checksums. (new in 0.15)

repository_version

The version of PAR::Repository this repository was created with. When opening an existing repository, PAR::Repository checks that the repository was created by a compatible PAR::Repository version.

Similarily, PAR::Repository::Client checks that the repository has a compatible version.

arch/perl-version directories

Your system architecture is identified with a certain string. For example, my development box is x86_64-linux-gnu-thread-multi. For every such architecture for which there are PAR archives in the repository, there is a directory with the name of the architecture.

There is one special directory called any_arch which is meant for PAR archives that are architecture independent. (Usually pure-perl modules.)

In every such architecture directory, there is a number of directories for every Perl version. (5.6.0, 5.6.1, 5.8.0, ...) Again, there is a special directory for modules that work with any version of Perl. This directory is called any_version.

Of course, a module won't run with Perl 4 and probably not even with 5.001. Whether a module works with any version of perl is something you need to decide when injecting modules into the repository and depends on the scope of the repository.

These inner directories contain the PAR archives. The directories exist mostly because large repositories with a lot of modules for a lot of architectures would otherwise have too large directory lists.

PAR archives

Within the arch/perl-version directories come the actual PAR archives. The name of each such file is of the following form:

Distribution-Name-Distribution-Version-Architecture-Perl-Version.par

METHODS

Following is a list of class and instance methods. (Instance methods until otherwise mentioned.)

Other methods callable on PAR::Repository objects are inherited from classes listed in the SEE ALSO section.

new

Creates a new PAR::Repository object. Takes named arguments.

Mandatory paramater:

path should be the path to the PAR repository. If the repository does not exist yet, it is created empty. If the repository exists, it is opened. That means any modifications you apply to the repository object are applied to the opened repository on disk.

Optional parameters:

Additionally, you may supply the fake_symlinks => 1 or convert_symlinks => 1 parameters. Both default to false. convert_symlinks will convert an existing repository that uses symbolic links to using no symbolic links as if it had been created with the fake_symlinks option. If the repository has to be created, fake_symlinks flags it as using no symbolic links. Copies will be used instead. this may result is a larger but more portable repository. convert_symlinks implies fake_symlinks. See also CAVEATS below.

fake_symlinks is the default for creating new repositories on platforms which do not support symlinks.

inject

Injects a new PAR distribution into the repository. Takes named parameters.

Mandatory parameters: file, the path and filename of the PAR distribution to inject. The name of the file can be used to automatically determine the distname, distversion, arch, and perlversion parameters if the form of the file name is as follows:

Dist-Name-0.01-x86_64-linux-gnu-thread-multi-5.8.7.par

This would set distname = 'Dist-Name', distversion => '0.01', arch => 'linux-gnu-thread-multi', perlversion => '5.8.7'>. You can override this automatic detection using the corresponding parameters.

If the file exists in the repository, inject returns false. If the file was added successfully, inject returns true. See the overwrite parameter for details.

inject() scans the distribution for modules and indexes these in the modules-dists dbm. Additionally, it scans the distribution for scripts in the script and bin subdirectories of the distribution. (All files in these folders are considered executables. main.pl is skipped.) You can turn the indexing of scripts off with the no_scripts parameter.

Optional parameters:

distname

The distribution name.

distversion

The distribution version.

arch

The architecture string. It can be any_arch in order to inject this distribution as an architecture independent distribution. You can use the any_arch parameter for this as well (recommended).

Setting this to any_arch is slightly different from using the parameter of the same name. Setting arch='any_arch'> actually puts the file into the any_arch directory. Setting only the parameter any_arch creates a symlink there.

perlversion

The version of perl. Note that it has to be in the 5.8.7 and not in the 5.008007 form!

There is a special case of setting this to any_version meaning that the distribution can run on any version of perl. The distribution will then be injected into the any_version tree of the repository. You can also achieve this by using the any_version parameter which is recommended.

Setting this to any_version is slightly different from using the parameter of the same name. Setting perlversion='any_version'> actually puts the file into the any_version directory. Setting only the parameter any_version creates a symlink there.

any_arch

Specifies that this distribution is suitable for any architecture. (Default: no.)

If set, a symlink to the distribution file is created in the any_arch directory.

any_version

Specifies that this distribution is suitable for any version of perl. (Default: no.)

If set, a symlink to the distribution file is created in the any_version directory.

overwrite

If this is set to a true value, if the file exists in the repository, it will be overwritten.

no_scripts

By default, PAR::Repository indexes all modules found in a distribution as well as all scripts. Set this parameter to a true value to skip indexing scripts.

ignore_provides

Set this to true if you want to ignore the META.yml provides section which should normally list all modules in the distribution. In that case, a manual scan for packages is performed.

no_dependencies

Set this to true if you want to skip inserting dependency information into the database. You'd better have a good idea why you want this.

remove

Removes a distribution from the repository.

The information needed for this consists of four pieces: The distribution name, the distribution version, the architecture name and the perl version.

This information can be gathered from either a file name (see the file parameter) or from individual parameters (see below) or from a mixture of these. The explicit parameters take precedence before the file name parsing.

If the specified distribution isn't in the repository, the method returns false. If the specified distribution is a symlink to another distribution, the symlink will be removed, but not the linked distribution. If the specified distribution is an actual distribution in the repository that has other symlinks, the distribution as well as any symlinks are removed.

Returns true on success.

Parameters:

file

The file name of the distribution to remove. The file name should not include any path information. That means you must not worry about the way it is stored in the repository.

Any paths are stripped and the .par extension is appended if it's not explicitly specified. The format must be as with the inject() method.

distname

The distribution name.

distversion

The distribution version.

arch

The architecture string. It can be any_arch or an actual architecture name. For details, see the discussion in the manual entry for the inject method.

perlversion

The version of perl. Note that it has to be in the 5.8.7 and not in the 5.008007 form!

It can be any_version instead of an actual perl version. For details, see the discussion in the manual entry for the inject method.

You may omit the file parameter if the full file name can be constructed from the individual pieces of information.

verbose

Print a verbose status message. First argument should be an integer, second argument should be the message. If the global variable $PAR::Repository::VERBOSE is set to a value equal to or higher than the integer passed as first argument, the verbose message will be sent to STDOUT.

The global verbose variable defaults to 0. Setting it to a negative value should suppress any output except fatal errors.

Valid values are:

  0 => Non-fatal errors.
  1 => Short status messages.
  2 => Method entry messages.-
  3 => Full debug output.

A newline is attached to all output. If the verbosity global variable is set to a "4", all status messages are sent to STDERR instead via warn. That means the source line of the status message is attached.

_cmp_dist_versions

Compares the versions of two files. Takes two file names as arguments. Parses the distribution version from those file names and compares those versions.

Returns -1 if the version of the first file is less than that of the second file.

Returns 0 if the versions are equal.

Returns 1 if the version of the first file is greater than that of the second file.

For internal use only.

_add_packages

Adds a number of package <-> file associations to the modules<->dists DBM file.

Parameters: packages = \%pkg_hash> a hash of package names as keys and their versions (optionally) as values. file = $target_file> the file in the repository to associate these packages with.

For internal use only!

_add_scripts

Adds a number of script <-> file associations to the scripts<->dists DBM file.

Parameters: scripts = \%script_hash> a hash of script names as keys and their versions (optionally) as values. file = $target_file> the file in the repository to associate these scripts with.

For internal use only!

_add_symlink

Adds a symlink to the repository. Parameters: file = "file"> and sym = "symlink">.

file and symlink must not include any path. The path in the repository is generated from the file name! (Paths in the repository do not carry any additional information. They are for grouping only and reduce the number of files in a single directory.)

Optional parameter: overwrite = bool>. If true, overwrites old symlinks. Never overwrites files.

This is a private method.

_add_dependencies

Adds a number of distribution <-> module associations to the dependencies DBM file.

Parameters: file => 'DistName-0.01-.....par', dependencies => \%deps_hash where \%deps_hash the returned structure from PAR::Indexer::dependencies_from_meta_yml: module names associated to their minimal required versions.

For internal use only!

_update_info_version

Writes the YAML repository info file and upgrades the repository version to the current version.

Should be used with care and considered a private method.

_remove_files_from_db

First argument is the reference to the modules or scripts DBM hash. Second argument is an array reference to an array of file names. Removes all mention of those distribution files (symlinks or actual files) from the DBM hash. This is a slow operation because the hash associates in the opposite direction.

If any occurrances have been deleted, this method cleans up the DBM file.

Returns 1 on success.

This is a private method.

_remove_symlink

Removes a symlink from the repository. Parameters: sym = "full/path/in/repo">. Or: sym = "foo.par"> (omitting the path).

This is a private method.

CAVEATS

By default, PAR::Repository uses symlinks to save space. However, on some systems, there are no symlinks. Thus, you can use the option fake_symlinks => 1 to the constructor to disable the use of symlinks.

Converting existing repositories with the convert_symlinks => 1 option is believed but not proven to be somewhat fragile, so back up your repository first.

At some point in the future, fake_symlinks may become the default. Principle of least surprise. But this isn't clear yet.

SEE ALSO

This module inherits from PAR::Repository::DBM, PAR::Repository::Zip, PAR::Repository::Query,

This module is directly related to the PAR project. You need to have basic familiarity with it.

See PAR, PAR::Dist, etc.

PAR::Indexer does the indexing of the contents of a .par file. The code used to be part of this distribution as PAR::Repository::ScanPAR.

PAR::WebStart is doing something similar but is otherwise unrelated.

AUTHOR

Steffen Mueller, <smueller@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2006-2009 by Steffen Mueller

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6 or, at your option, any later version of Perl 5 you may have available.