ALPM - ArchLinux Package Manager backend library.

2.01

This version of ALPM is compatible with pacman 3.5.

  use ALPM ( root        => '/',
             dbpath      => '/var/lib/pacman/',
             cachedirs   => [ '/var/cache/pacman/pkg' ],
             logfile     => '/var/log/pacman.log',
             xfercommand => '/usr/bin/wget --passive-ftp -c -O %o %u' );

  # It's easier just to load a configuration file:
  use ALPM qw(/etc/pacman.conf);

  # My new favorite way to get/set options.  A tied hash.  (TMTOWTDI)
  my %alpm;
  tie %alpm, 'ALPM';
  $alpm{root} = '/';
  printf "Root Dir = %s\n", $alpm{root};
  my ($root, $dbpath, $cachedir) = @alpm{qw/root dbpath cachedir/};

  # Callback options...
  $alpm{logcb} = sub { my ($lvl, $msg) = @_; print "[$lvl] $msg\n" };

  # Querying databases & packages
  my $localdb = ALPM->localdb;
  my $pkg     = $localdb->find('perl');

  # Lots of different ways to get package attributes...
  my $attribs_ref    = $pkg->attribs_ref;
  my $name           = $pkg->name;
  my ($size, $isize) = $pkg->attribs('size', 'isize');
  print "$name $attribs_ref->{version} $attribs_ref->{arch} $size/$isize";

  my $syncdb   = ALPM->register( 'extra',
                                 'ftp://ftp.archlinux.org/$repo/os/$arch' );
  my @perlpkgs = $syncdb->search('perl');
  printf "%d perl packages found.\n", scalar @perlpkgs;

  # Search all databases/repos.
  print map { sprintf "%10s: %s %s\n", $_->db->get_name, $_->name,
              $_->version } ALPM->search('perl');

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

  # Transactions
  my $trans = ALPM->trans( type => 'sync' );
  $trans->sync( 'perl', 'perl-alpm', 'pacman' );
  $trans->prepare;
  $trans->commit;
  undef $trans; # this forces releasing the transaction

  # Miscellanious functions
  my $cmp = ALPM->vercmp( '0.01', '0.02' );
  print ( $cmp == -1 ? "less than\n" :
          $cmp ==  0 ? "equal\n"     :
          $cmp ==  1 ? "greater than\n" );

  my @syncdbs = ALPM->syncdbs;
  my $found   = ALPM->find_dbs_satisfier( \@syncdbs, 'findme' );

  # $found is undef or package object for findme

  $found = ALPM->find_satisfier( [ ALPM->db('extra')->pkgs ],
                                 'findme' );

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

There are a few different options you can specify after use ALPM. These help to set configuration options for ALPM. These options are global for everyone who is using the module. You can specify either:

1. The path to a pacman.conf configuration file.

Example:

  use ALPM qw( /etc/pacman.conf );

This is particularly useful on the command-line:

  perl -MALPM=/etc/pacman.conf -e '$i=0;
  printf qq{%d %d %s\n}, ++$i, $_->size, $_->name
      for sort { $a->size <=> $b->size } ALPM->localdb->pkgs'

2. A hash of options to use for ALPM.

Example:

  use ALPM qw( root        => '/',
               dbpath      => '/var/lib/pacman/',
               cachedirs   => [ '/var/cache/pacman/pkg' ],
               logfile     => '/var/log/pacman.log' );

It is important to set options as soon as possible. Or stuff breaks.

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) expect an array reference as an argument. Similarly the same options return multiple values as an array reference.

root

root directory of entire system

dbpath

path to the ALPM/pacman database

cachedirs*

paths containing package caches

logfile

path to the pacman logfile

usesyslog

if true, log to the system log as well

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

holdpkgs*

a list of package names to hold off upgrading

ignoregrps*

a list of groups to ignore for upgrade

xfercommand

shell command to use for downloading (ie wget)

nopassiveftp+

if true, do not use passive ftp mode

usedelta+

should you use deltas? not really sure, never tried it...

lockfile

path to the lockfile

localdb

the ALPM::DB object representing the local database

syncdbs*

an array-ref of sync databases as ALPM::DB objects

  * = the option is set with (and returns) an arrayref
  + = the option is boolean and is either 0 or 1

Callbacks can only be set to code references.

logcb - Generic logging

The log message and level are passed to the provided code ref as arguments. level can be: error, warning, debug, function, or unknown.

dlcb - Download callback

The filename, bytes transfered, and bytes total are passed to the provided code ref as arguments.

totaldlcb - Total download callback

The total number of bytes downloaded so far is passed to the provided code ref as the only argument.

This is probably the easiest way to manipulate ALPM's options. Perl has an old mechanism which allows reading or writing to hashes act sort of like objects. Basically, you can tie ALPM's options to a hash variable and any changes to that hash change the same option.

  # Taken from SYNOPSIS
  tie my %alpm, 'ALPM';
  $alpm{root} = '/';
  print "Root Dir = $alpm{root}\n";
  my ($root, $dbpath, $cachedir) = @alpm{qw/root dbpath cachedir/};

But you cannot delete a key or empty the hash. In fact assigning undef also does not work for options that don't use arrayrefs.

  # Doesn't work!
  delete $alpm{root};
  undef $alpm{root};
  %alpm = ();

ALPM has all its package specific and database specific functions inside the package and database classes as methods. Everything else is accessed through class methods to ALPM.

As far as I can tell you cannot run multiple instances of libalpm. Class methods help remind you of this. The class method notation also helps to differentiate between globally affecting ALPM functions and package or database-specific functions.

  Usage   : print ALPM->version(), "\n";
  Returns : The version of libalpm being used, a string.

  Params  : Pass set_options a hash or hashref to set many options at
            once.
  Returns : 1

  Usage   : ALPM->set_opt( 'root', '/' );
  Params  : An option name and new option value.
  Returns : 1

  Usage   : my %alpm_opts = ALPM->get_options();
            my ($root, $dbpath) = ALPM->get_options( 'root', 'dbpath' );
  Params  : * When no params are given, returns a hash of all options.
            * Otherwise, return a list of option values in the same order
              as the parameters.
  Notes   : Unset options are undefined.
  Returns : A hashref or list.

  Usage   : my $root = ALPM->get_opt('root');
  Params  : An option name.
  Returns : The given option's value or undef if it is unset.

  Usage   : my $syncdb = ALPM->register
                ( 'core' => 'ftp://ftp.archlinux.org/$repo/os/$arch' );
  Params  : 1) The name of the repository to connect to.
            2) The URL to the repository's online files.
  Notes   : Like with pacman's mirrorlist config file, $repo will be
            replaced with the repository name (argument 1) and
            $arch will be replaced with the architecture.
            Use single quotes when using $'s!
  Precond : You must set options before using register.
  Throws  : An 'ALPM DB Error: ...' message is croaked on errors.
  Returns : An ALPM::DB object.

See ALPM::DB

  Usage   : my $db = ALPM->localdb;
  Returns : The local system database as an ALPM::DB object.
  Precond : You must set certain options first.
  Notes   : This is what is called by register_db without arguments.

  Usage   : my @dbs = ALPM->syncdbs;
  Purpose : Nicer looking wrapper to ALPM->get_option('syncdbs');
  Params  : None.
  Returns : A list (not an arrayref) of sync databases.

  Usage   : my $comm_db = ALPM->db('community');
            my $comm_db = ALPM->repodb('community');
  Params  : The name of a repository.
  Returns : An ALPM::DB object matching the repo name.

  Usage   : my @dbs = ALPM->dbs;
  Params  : None
  Returns : A list of each database that is registered.

See ALPM::DB

  Usage   : my $pkgfile = ALPM->load_pkgfile('perl-alpm-0.2.pkg.tar.gz');
  Params  : The path to a package tarball.
  Returns : An ALPM::Package object.
  Notes   : Technically we return an ALPM::PackageFree object that will
            automatically free itself from memory when it goes out of scope.

See ALPM::Package

  Usage   : ALPM->load_config('/etc/pacman.conf');
  Params  : The path to a pacman.conf configuration file.
  Returns : 1

See also ALPM::LoadConfig for more advanced needs.

  Usage   : my $t = ALPM->trans( flags    => 'nodeps force',
                                 event    => sub { ... },
                                 conv     => sub { ... },
                                 progress => sub { ... } );
  Purpose : Initializes a transaction
  Params  : A hash of the transaction settings
  Throws  : An 'ALPM Error: ...' is thrown if a transaction is
            already active.
  Returns : An ALPM::Transaction object.

See ALPM::Transaction.

Transactions have many named parameters, passed as a hash.

flags - A string of flags, each separated by whitespace.

* nodeps

* force

* nosave

* nodepver

* cascade

* recurse

* dbonly

* alldeps

* dlonly

* noscriptlet

* noconflicts

* printuris

* needed

* allexplicit

* unneeded

* recurseall

event - A coderef, used as an event callback.

When an event occurs, the coderef is passed a hashref representing the event.

conv - A coderef, used as a conversation callback.

This callback is called when a question should be asked to the user. It is passed a hashref representing the question. The callback returns 1 or 0 to answer yes or no.

progress - A coderef, used as a progress callback.

This callback is called to report on the progress of the operations of the transaction.

Callbacks are explained in greater detail in the ALPM::Transaction document.

  Usage   : if ( ALPM->vercmp( $leftver, $rightver ) == -1 ) { ... }
  Purpose : Compare two version strings, similiar to strcmp.
  Returns : -1 if left version is below right version,
             0 if both versions are equal
             1 if left version is above right version

  Usage   : my $found = ALPM->find_satisfier( $pkgs_ref, "pkgname>1" );
  Purpose : Searches through the provided package objects ($pkgs_ref,
            an arrayref) for a package that satisfies the given
            dependency.
  Params  : 1) An arrayref of ALPM::Package objects.
            2) A dependency string that must be satisfied.
  Returns : undef if no satisfier was found or an ALPM::Package object.
  Notes   : The conversation callback of an active transaction is used
            to ask about ignoring a package if a matching satisfier
            is on the ignore list.

  Usage   : my $found = ALPM->find_dbs_satisfier( $dbs_ref, "pkgname>1" );
  Purpose : Same as find_satisfier, except we search the provided
            databases.
  Params  : 1) An arrayref of ALPM::DB objects.
            2) A dependency string that must be satisfied.
  Returns : undef if no satisfier was found or an ALPM::Package object.
  Notes   : The conversation callback of an active transaction is used
            to ask about ignoring a package if a matching satisfier
            is on the ignore list.

Global ALPM errors are thrown with croak. The error messages match the errors that the C library provides. These errors are prefixed with ALPM Error:. Errors that occur when using a ALPM::DB object are prefixed with ALPM DB Error:.

Transaction errors are prefixed with ALPM Transaction Error:. These are described fully at ALPM::Transaction.

TODO: Common error messages and how to fix them?

Unimplemented functions:

  alpm_checkdeps, alpm_dep_compute_string, alpm_trans_interrupt,
  alpm_checkconflicts, alpm_compute_md5sum, alpm_sync_newversion,
  alpm_delta_... functions

* ALPM::DB, ALPM::Package, ALPM::Transaction

* http://projects.archlinux.org/pacman.git/ - git repository for pacman/libalpm

* http://code.toofishes.net/pacman/doc/ - libalpm doxygen docs

* http://wiki.archlinux.org/index.php/Pacman

* http://github.com/juster/perl-alpm - git repo for this module.

Justin Davis, <juster at cpan dot org>

Copyright (C) 2011 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.