<<

NAME

Lintian::Lab -- Interface to the Lintian Lab

SYNOPSIS

 use Lintian::Lab;
 
 # Static lab
 my $lab = Lintian::Lab->new;

 if (!$lab->exists) {
     $lab->create;
 }
 $lab->open;
 
 # Fetch a package from the lab
 my $lpkg = $lab->get_package ('lintian', 'binary', '2.5.4', 'all');
 
 my $visitor = sub {
     my ($lpkg, $pkg_name, $pkg_ver, $pkg_arch) = @_;
     # do stuff with that entry
 };
 $lab->visit_packages ($visitor, 'source');
 
 $lab->close;

DESCRIPTION

This module provides an abstraction from "How and where" packages are placed. It handles creation and deletion of the Lintian Lab itself as well as providing access to the entries.

CLASS METHODS

new

Creates a new Lab instance. The lab will be temporary and will point to a temporary directory.

INSTANCE METHODS

is_open

Returns a truth value if this lab is open.

Note: If the lab is open, it also exists. However, if the lab is closed then the lab may or may not exist (see "exists").

exists

Returns a truth value if the instance points to an existing lab.

Note: This never implies that the lab is open. Though it may imply the lab is closed (see "is_open").

get_package (NAME, TYPE[, EXTRA]), get_package (PROC)

Fetches an existing package from the lab.

The first argument can be a processable. In that case all other arguments are ignored.

If the first calling convention is used then this method will search for an existing package. The EXTRA argument can be used to narrow the search or even to add a new entry.

EXTRA consists of (in order):

If version or arch is omitted (or if it is undef) then that search parameter is consider a wildcard for "any". Example:

 # Returns all eclipse-platform packages with architecture i386 regardless
 # of their version (if any)
 @ps  = $lab->get_package ('eclipse-platform', 'binary', undef, 'i386');
 # Returns all eclipse-platform packages with version 3.5.2-11 regardless
 # of their architecture (if any)
 @ps  = $lab->get_package ('eclipse-platform', 'binary', '3.5.2-11');
 # Return the eclipse-platform package with version 3.5.2-11 and architecture
 # i386 (or undef)
 $pkg = $lab->get_package ('eclipse-platform', 'binary', '3.5.2-11', 'i386');

In list context, this returns a list of matches. In scalar context this returns the first match (if any). Note there is no guaranteed order (e.g. the returned list is not ordered).

If the second calling convention is used, then this method will search for an entry matching the processable passed. If such an entry does not exists, a new "non-existing" entry will be returned. This entry can be created by using the create method on the entry.

visit_packages (VISITOR[, TYPE])

Passes each lab entry to VISITOR. If TYPE is passed, then only entries of that type are passed.

VISITOR is given a reference to the entry, the package name, the package version and the package architecture (may be undef for source packages).

generate_diffs (LIST)

Each member of LIST must be a Lintian::Lab::Manifest.

The lab will generate a diff between the given member and its state for the given package type.

The diffs are accurate until the original manifest is modified or a package is added or removed to the lab.

repair

Checks the lab contents against the current meta-data and syncs them. The lab must be open and should not be access while this method is running.

This returns the number of corrections done by this process. If there were any corrections, the state files are written before returning.

The method may croak if it is unable to do a full check of the lab or if it is unable to write the corrected metadata.

Note: This may (and generally will) correct "broken" entries by removing them.

create ([OPTS])

Creates a basic empty lab. Will also set up the temporary dir for the lab.

The lab will not be opened by this method. This should be done afterwards by invoking the "open" method.

OPTS (if present) is a hashref containing options. The following options are accepted:

keep-lab

If "keep-lab" points to a truth value the temporary directory will not be removed by closing the lab (nor exiting the application). However, explicitly calling "remove" will remove the lab.

mode

If present, this will be used as mode for creating directories. Will default to 0777 if not specified. It is passed to mkdir and is thus subject to umask settings.

Note: This does nothing if the lab appears to already exists.

open

Opens the lab and reads the contents into caches. If the lab does not exist, this method will call create to initialize it.

This will croak if the lab is already open. It may also croak for the same reasons as "create".

Note: It is not possible to pass options to the creation of the lab. If special options are required, please use "create" directly.

close

Close the lab - all state caches will be flushed to the disk and the lab can no longer be used. All references to entries in the lab should be considered invalid.

Note: The lab will be deleted unless it was created with "keep-lab" (see "create").

remove

Removes the lab and everything in it. Any reference to an entry returned from this lab will immediately become invalid.

The lab root dir will be removed as well on success.

On success, this will return a truth value. The directory path will be set to the empty string.

On error, this method will croak.

If the lab has already been removed (or does not exist), this will return a truth value.

Changes to the lab format.

Lab formats up to (and including) "10" used to store the lab format with each entry. The files in $LAB/info/ were used to list packages from a mirror (dist).

In lab format 11 the lab format is stored in $LAB/info/lab-info. The rest of the files in $LAB/info/* have been re-purposed to be a list of packages in the lab.

The $LAB/info/lab-info is parsed as a debian control file (See Debian Policy Manual §5.1 for syntax). The consists of a single paragraph and only the following fields are allowed:

Lab-Format (simple, mandatory)

This field contains the lab format of this lab. Generally this is simply an integer (though during development non-integers have been used).

Layout (simple, optional)

The layout parameter describes how packages are stored in the lab. Currently the only accepted value is "pool" and the value is not case-sensitive.

The pool format dictates that packages are stored in:

 pool/$l/${name}/${name}_${version}[_${arch}]_${type}/

Note that $arch is left out for source packages, $l is the first letter of the package name (except if the name starts with "lib", then it is the first 4 letters of the package name). Whitespace (e.g. " ") are replaced with dashes ("-") and colons (":") with underscores ("_").

If the field is missing, it defaults to "pool".

It is allowed to use comments in $LAB/info/lab-info as described in the Debian Policy Manual §5.1.

AUTHOR

Niels Thykier <niels@thykier.net>

Based on the work of various others.

<<