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 theany_arch
parameter for this as well (recommended).Setting this to
any_arch
is slightly different from using the parameter of the same name. Settingarch=
'any_arch'> actually puts the file into theany_arch
directory. Setting only the parameterany_arch
creates a symlink there. - perlversion
-
The version of perl. Note that it has to be in the
5.8.7
and not in the5.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 theany_version
tree of the repository. You can also achieve this by using theany_version
parameter which is recommended.Setting this to
any_version
is slightly different from using the parameter of the same name. Settingperlversion=
'any_version'> actually puts the file into theany_version
directory. Setting only the parameterany_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 theinject
method. - perlversion
-
The version of perl. Note that it has to be in the
5.8.7
and not in the5.008007
form!It can be
any_version
instead of an actual perl version. For details, see the discussion in the manual entry for theinject
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.
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.