The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

ALPM - XS module, OO wrapper of libalpm, Archlinux's packaging system

SYNOPSIS

  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 ($msg, $lvl) = @_; print "[$lvl] $msg\n" };


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

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

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


  # Transactions
  my $trans = ALPM->transaction( type => 'upgrade' );
  $trans->add( 'perl', 'perl-alpm', 'pacman' );
  #$trans->prepare;  (unnecessary, commit does it if needed)
  $trans->commit;
  $trans = undef; # to force releasing, not required though

DESCRIPTION

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.

EXPORT

None.

Because all alpm functions have been converted to class methods, classes, and object methods, nothing is exported.

IMPORT OPTIONS

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
2. A hash of options to use for 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) expect an array reference as an argument. Similarly the same options return multiple values as an array reference.

Read-write options

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

Read-only options

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

Callback options

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.

CLASS METHODS

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.

set_options

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

set_opt

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

get_options

  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.

get_opt

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

register_db

  Usage   : my $localdb = ALPM->register_db;
            my $syncdb  = ALPM->register_db( 'core' =>
                                             'ftp://ftp.archlinux.org/$repo/os/i686' );
  Params  : No parameters will return the local database.
            Two parameters will register a sync database:
            1) The name of the repository to connect to.
            2) The URL to the repository's online files.
               Like with pacman's mirrorlist config file, $repo will be replaced
               with the repository name (argument 1) ... use single quotes!
  Precond : You must set options before using register_db.
  Throws  : An 'ALPM DB Error: ...' message is croaked on errors.
  Returns : An ALPM::DB object.

See ALPM::DB

local_db

  Returns : The local system database as an ALPM::DB object.
  Precond : You must set certain options first.

  This is what is called by register_db without arguments.

get_repo_db

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

See ALPM::DB

load_pkgfile

  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.

See ALPM::Package

load_config

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

transaction

  Usage   : my $t = ALPM->transaction( type => 'sync',
                                       flags => qw/ nodeps / );
  Purpose : Initializes a transaction
  Params  : A hash of the transaction settings
            type  => A string, can be upgrade, remove, removeupgrade, or sync.
            flags => A list of strings, valid flags are:
                nodeps, force, nosave, 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.  Events are explained in
                detail in the ALPM::Transaction document.
  Throws  : An 'ALPM Error: ...' is thrown if a transaction is
            already active.
  Returns : An ALPM::Transaction object.

See ALPM::Transaction

ERRORS

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: .

TODO: List of error messages.

TROUBLESHOOTING

TODO: Common error messages and how to fix them.

SEE ALSO

AUTHOR

Justin Davis, <jrcd83 at gmail dot com>

COPYRIGHT AND LICENSE

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