/ 
ALPM-3.03
River stage zero No dependents
/ ALPM

NAME

ALPM - readonly access to pacman's libalpm.

VERSION

3.03

This version of ALPM is compatible with pacman 4.

SYNOPSIS

## We can start by setting options all by ourselves.
use ALPM;
my $alpm = ALPM->new('/', '/var/lib/db'); # root and dbpath
$alpm->set_cachedirs('/var/cache/pacman/pkg');
$alpm->set_logfile('/var/log/pacman.log');

## Or use ALPM::Conf, a handy module for pacman.conf parsing.
use ALPM::Conf qw(/etc/pacman.conf);
## ALPM::Conf loads an object into "our" package variable.
our $alpm;

## Querying databases & packages
my $localdb = $alpm->localdb;
my $pkg = $localdb->find('perl') or die 'wtfbbq';
printf "%s %s %s %d\n", $pkg->name, $pkg->version,
    $pkg->arch, $pkg->size;

my $extradb = $alpm->register('extra') or die $alpm->strerror;
$extradb->add_mirror('ftp://ftp.archlinux.org/extra/os/i686')
    or die $alpm->strerror;
$extradb->update or die $alpm->strerror;
my @perlpkgs = $extradb->search('perl');
printf "%d perl packages found.\n", scalar @perlpkgs;

## libalpm's version comparison function. (a classy method)
my $cmp = ALPM->vercmp('0.01', '0.02');
if($cmp == -1){
	print "less than\n";
}elsif($cmp == 0){
	print "equal\n";
}elsif($cmp == 1){
	print "greater than\n";
}

## $found is undef or the package object for findme.
my @syncdbs = $alpm->syncdbs;
my $found = $alpm->find_dbs_satisfier('findme', @syncdbs);
$found = $alpm->find_satisfier('findme', $extradb->pkgs);

## These are perl wrappers around localdb and syncdbs:

## Search all databases/repos (includes localdb).
printf "%10s: %s %s\n", $_->db->get_name, $_->name,
	$_->version for $alpm->search('perl');

## Find a database by name of repository.
my $coredb = $alpm->db('core');

DESCRIPTION

Archlinux uses a package manager called pacman. Pacman internally uses the alpm library for handling its database of packages. This module creates a perlish object-oriented interface to the libalpm C library.

In the past this module implemented transactions as well, allowing you to modify the system/database. This is no longer implemented because I grew tired of rewriting this module every time the pacman API was changed.

CLASS METHODS

new

$OBJ = ALPM->new($ROOTDIR, $DBDIR);
$ROOTDIR

The root directory for all deployed packages managed by libalpm.

$DBDIR

The database directory where the local database and sync databases are kept.

$OBJ

An ALPM object which is used for all other method calls. This is referenced in the object method definitions below.

version

$VERSTR = ALPM->version()
$VERSION

libalpm's internal version string, as returned by the alpm_version C function.

caps

@CAPS = ALPM->caps()
@CAPS

Corresponds to the alpm_capabilities C function. A list of strings, describing capabilities of libalpm. Any of the following capabilities may or may not be present:

nls

Foreign language support.

downloader

If libcurl is installed then a downloader is embedded.

signatures

If gpgme is installed then package/database signatures are supported.

ALPM OBJECT METHODS

These methods can be used with ALPM objects created from the "new" method above. In the following methods, $OBJ represents an ALPM object.

errno

$ERRNO = $OBJ->errno()
$ERRNO

The internal libalpm error number. If no error occurs this is zero.

strerror

$ERRSTR = $OBJ->strerror()
$ERRSTR

The error string describing the last error that occurred. Note: the language of the error messages depends on the value of $ENV{LC_ALL}.

find_satisfier

$PKG | undef = $OBJ->find_satisfier($DEPSTR, @PKGS)
$DEPSTR

The dependency that libalpm should attempt to satisfy (e.g. 'foo', 'foo>2.0', etc.)

@PKGS

A list of ALPM::Package objects that are potential satisfiers.

$PKG

If a package satisfies the dependency, it is returned.

undef

Returned if no satisfier is found.

find_dbs_satisfier

$PKG | undef = $OBJ->find_dbs_satisfier($DEPSTR, @DBS)
$DEPSTR

The dependency that libalpm should attempt to satisfy (e.g. 'foo', 'foo>2.0', etc.)

@DBS

A list of ALPM::DB objects whose packages will be searched for satisfiers

$PKG

If a package satisfies the dependency, it is returned.

undef

Returned if no satisfier is found.

check_conflicts

@CONFLICTS = $OBJ->check_conflicts(@PKGS)
@PKGS

A list of ALPM::Package objects which are checked for inter-conflicts.

@CONFLICTS

A list of hashrefs describing any conflicts. See "Conflict".

fetch_pkgurl

$PATH | undef = $OBJ->fetch_pkgurl($URL)
$URL

The url to a package file which will be downloaded to our default package cache location.

$PATH

The path to our package file if the download succeeds.

undef

If the download fails. Check "strerror".

load_pkgfile

$PKG | undef = $PM->load_pkgfile($PATH, $FULL, $SIGLEVEL);

These parameters are kind of funky but they match the alpm_pkg_load function.

$PATH

The path to a package file (i.e. pkg.tar.xz).

$FULL

Full (1) or partial load (0). Trust me, don't install partial loads. That happened with clyde once.

$SIGLEVEL

Signature level hashref or the string "default". See "Signature Level".

$PKG

On success, an ALPM::Package object.

undef

On failure. Check "strerror".

localdb

$DB = $OBJ->localdb()
$DB

An ALPM::DB::Local object.

register

$DB | undef = $OBJ->register($NAME, $SIGLEVEL?)

Registers a remote synchronizable database.

$NAME

The name to use for the database (e.g. core, extra, community.)

$SIGLEVEL (Optional)

The signature level to use for the database, including the database file and each package file downloaded from the database mirror. If none is specified, then the signature level is set to 'default' which is equivalent to the signature level set with the set_defsiglvl method.

$DB

On success, an ALPM::DB::Sync object.

undef

On failure. Check "strerror".

syncdbs

@DBS = $OBJ->syncdbs()

Retrieve a list of sync databases that have previously been registered.

@DBS

A list of ALPM::DB::Sync objects.

unregister_all

1 | undef = $OBJ->unregister_all()

Unregisters all sync databases. If you try to use previously registered ALPM::DB::Sync objects, they will probable cause a segfault...

Returns 1 on success or undef on error. Check "strerror" on error.

ALPM OPTIONS

ALPM has a number of options corresponding to the alpm_option_get_... and alpm_option_set... C functions in the library. Options which take multiple values (hint: they have a plural name) accept multiple arguments in the corresponding methods. Similarly the same options return a list.

Read-write options

logfile - path to the pacman logfile
arch - the machine architecture to use
gpgdir - path to gpg stuff
cachedirs* - paths containing package caches
noupgrades* - a list of package names to not upgrade
noextracts* - a list of package names to not extract
ignorepkgs* - a list of package names to ignore for upgrade
ignoregroups* - a list of groups to ignore for upgrade
usesyslog - if true, log to the system log as well
deltaratio - accepts a decimal from 0 to 1
checkspace - check for available diskspace
defsiglvl - the default signature level. See "Signature Level". This name was shortened from alpm_option_set_default_signature_level. You're welcome.

Read-only options

lockfile - path to the lockfile
* = the option is set with (and gets you) a list

Callback options

Callbacks can only be set to code references.

logcb - Generic logging

The log level and message are passed to the provided code ref as arguments.

1. level

This is one of the following strings: error, warning, debug, function, or unknown.

2. message

This is the message itself.

DATA TYPES

Several libalpm data types have been converted into hash references. The alternative is to turn them into full-blown objects, which seems pointless considering the only methods are data accessors.

Dependency

Dependencies specify constraints on a set of packages. Only certain packages satisfy a dependency. These can be used in places other than dependencies, such as conflicts. Dependencies have the following keys:

name

The name of a package.

version

A version string, which can be empty.

mod

A boolean operator used to compare package versions to our dependency version, must be either an empty string (which allows any version), =, >=, <=, >, <, or ? if an internal error occurred.

desc

If the dependency is optional this key gives a description of the dependency. This key does not exist on a regular dependency.

Conflict

Conflicts have the following keys:

package1

An ALPM::Package object.

package2

An ALPM::Package object.

reason

A hashref that is identical to a dependency. See "Dependency".

Signature Level

Signature levels describe the level of security which is required for packages files and by databases files. Different degrees of signature checking can be used for either type of file. The signature checking is performed after the file is downloaded in order to verify the original packager. When gpg is not available an invalid argument error will be raised from libalpm if you try to set the siglevel.

A "siglvl" can either be the string "default" or a hash reference. A value of "default" can be used when registering a database to instruct libalpm to use the default siglevel that is set by set_defsiglvl. A siglvl hashref must contain a "pkg" key and a "db" key. Other keys are ignored.

Possible hash values include:

"never"

No signature verification is performed.

"optional"

Signatures are optional. They are checked if they are available.

"required"

Signatures are required.

The string "trustall", preceded by a space, can be added to "optional" or "required" options to specify that signatures from anyone are to be trusted.

Here are some example siglevels:

$alpm->set_defsiglvl({ 'pkg' => 'never', 'db' => 'never' });
$alpm->set_defsiglvl({ 'pkg' => 'optional', 'db' => 'required trustall' });
$alpm->set_defsiglvl({ 'pkg' => 'required', 'db' => 'optional' });

ERRORS

In previous version of this module, errors were thrown automatically. Since then, errors are no longer stored in a global variable (like UNIX's errno) but are instead stored inside of the libalpm handle structure. In order to preserve the old functionality I will have to either store a copy of the ALPM object inside every other object or use the internal C representation which I'm technically not supposed to know.

Whatever. I'm too lazy for either of those. What this means for you is you really really should check for errors yourself. If a method call returns undef you should follow it up with an "or die". Something like this:

$db->force_update or die $alpm->strerror;

This is annoying but not unlike most other perl error checking. If you find yourself calling methods on an undefined value then an error most likely occurred.

But wait there's more! Errors are actually thrown when getting/setting options and an error condition occurs.

SEE ALSO

AUTHOR

Justin Davis, <juster at cpan dot org>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Justin Davis

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