/ 
CPANPLUS-Dist-Arch-0.08
River stage zero No dependents
/ CPANPLUS::Dist::Arch

NAME

CPANPLUS::Dist::Arch - CPANPLUS backend for building Archlinux pacman packages

VERSION

Version 0.08

SYNOPSIS

This module is not meant to be used directly. Instead you should use it through the cpanp shell or the cpan2dist utility that is included with CPANPLUS.

$ cpan2dist --format CPANPLUS::Dist::Arch Acme::Bleach

This lengthly command line can be shortened by specifying CPANPLUS::Dist::Arch as the default 'Dist' type to use in CPANPLUS's configuration. A utility script name 'setupdistarch' is included with this module that can be used to quickly enable or disable packaging perl modules into pacman packages:

$ setupdistarch
This script will now setup CPANPLUS to automatically package all
modules into pacman packages when installing.
Are you sure you want to do this? [y/N] y
Set CPANPLUS to package all modules through CPANPLUS::Dist::Arch
$

See setupdistarch(1) for more information about setupdistarch. If you are having trouble running it, your PATH may not be set properly, there are instructions in the manual page.

Or you can setup CPANPLUS manually:

$ cpanp

... CPANPLUS's startup output here ...

CPAN Terminal> s conf dist_type CPANPLUS::Dist::Arch

Key 'dist_type' was set to 'CPANPLUS::Dist::Arch'
CPAN Terminal> s save

Configuration successfully saved to CPANPLUS::Config::User
    (/home/<yournamehere>/.cpanplus/lib/CPANPLUS/Config/User.pm)
CPAN Terminal> q

Exiting CPANPLUS shell

Now you do not have to use the explicit --format flag:

$ cpan2dist Acme::Bleach

After dist_type is set, CPANPLUS will automatically package anything you install using cpanp. Score! You could then package and install the Acme::Bleach module like so:

$ cpanp i Acme::Bleach

WHERE IS THE PACKAGE

Packages are stored under the user's home directory in the .cpanplus directory. Two seperate directories are created for building packages and for storing the resulting package file.

Build Directory

~/.cpanplus/5.10.0/pacman/build

Package Directory

~/.cpanplus/5.10.0/pacman/pkg

Where 5.10.0 represents the version of perl you used to build the package and ~/.cpanplus represents the base directory chosen in your CPANPLUS config.

You can change the destination by setting PKGDEST in your /etc/makepkg.conf file. The PACKAGER in /etc/makepkg.conf is inserted into the PKGBUILD comment header. If there is no PACKAGER set, then 'Anonymous' is used, instead.

COMMAND LINE OPTIONS

There are many command line options to cpan2dist and cpanp. You can find these by typing cpan2dist --help or cpanp --help on the command line or reading the man page with man cpan2dist or man cpanp. A small number of these options are recognized by CPANPLUS::Dist::Arch.

--verbose

This classic option allows for more verbose messages. Otherwise you get next to no output. Useful for debugging and neurosis.

--skiptest

This will comment out the tests in PKGBUILD files that are generated. I actually think testing is a good idea and would not recommend this unless you know what you are doing.

WARNING: This affects all pre-requisite module/packages that are
         built and installed; not just the module you specify.

DIST OPTIONS

cpan2dist allows you specify CPANPLUS::Dist::Arch specific options on the command line. I'm not sure how or if cpanp does the same. Look at the source code of the cpan2aur script to see how they also work programmatically.

pkgtype

This specifies whether to make a source package or a binary package. The default is to make a binary package.

destdir

Specifies where to store the resulting package. The default is to store under the ~/.cpanp/pacman/pkg directory, or the directory specified by PKGDEST in the /etc/makepkg.conf config file.

PUBLIC METHODS

When using the CPANPLUS module in a perl script to create packages, these public methods are available. See the cpanpkgbuild.pl script included in the examples folder for an example.

set_destdir

Usage   : $dist->set_destdir('~/pkg/perl');
Purpose : Sets the directory to store the resulting package.
Returns : The directory that was set.

get_destdir

Usage   : my $dest = $dist->get_destdir;
Returns : The directory where the package is going to end up.

get_pkgvars

Usage   : my %pkgvars = $dist->get_pkgvars;
Returns : A hash containing all the PKGBUILD variables.
          Keys are the bash variable names in the PKGBUILD.
          Dependencies are converted to their pacman names.

          One new key is 'depshash' whose value is a hashref.
          The hashref keys are packages and values are required versions,
          or 0 if there is no required version.

get_pkgvars_ref

Usage    : my $pkgvars_ref = $dist->get_pkgvars_ref;
Returns  : The same as C<get_pkgvars> except as a hashref.

get_pkgbuild

Usage    : my $pkgbuildtext = $dist->get_pkgbuild;
Returns  : A scalar containing the full text of the PKGBUILD that would
           be generated in the perl pacman package.

create_pkgbuild

Usage   : $self->_create_pkgbuild( '/tmp' );
Purpose : Creates a PKGBUILD file in the specified directory.
Params  : The directory to put the new PKGBUILD in.
Precond : You must first call prepare or have CPANPLUS do it automatically.
Throws  : unknown installer type: '...'
          failed to write PKGBUILD: ...
          Invalid arguments to create_pkgbuild
          Invalid directoy passed to create_pkgbuild: ...
Returns : Nothing.

LIMITATIONS

There are some limitations in the way CPANPLUS and pacman works together that I am not sure can be fixed automatically. Instead you might need a human to intervene. I called these limitations because they aren't exactly bugs. More specific bugs with exact error messages are in the "BUGS" section.

Cannot detect non-perl dependencies

If the module you are building is an XS module, and it depends on external, non-perl libraries, CPANPLUS::Dist::Arch will not include those libraries in the PKGBUILD depends.

This means if you plan on distributing a perl module package (ie uploading to AUR) you should edit the PKGBUILD by hand to include the libraries needed by the XS module.

A module is installed, but pacman says it isn't

CPAN[PLUS] considers a module installed if it can be used. That is, if it is in @INC somewhere on your system.

Pacman considers a module installed if it has been packaged and installed with pacman.

So if you installed some modules in the past without packaging them first, they don't exist as far as pacman is concerned. Usually, you can just reinstall them using this module because CPANPLUS::Dist::Arch installs modules under the vendor_perl/ directories, such as /usr/share/perl5/vendor_perl/..., and CPAN installs under the site_perl/ directories, such as /usr/share/perl5/site_perl/....

Installing with this module will appease pacman, but you may want to manually delete the previously installed modules to prevent version mismatch problems.

Pacman says a required dependency I installed package for is missing

Pacman is much more strict with its 'package' versions than CPAN is. pacman may rarely complain about you not having the required version when you obviously just installed them from CPAN!

This is because CPAN module versions are wacky and can be just about anything, while pacman's versioning is much more methodical. CPANPLUS::Dist::Arch simply extract's CPAN's version and inserts it into the PKGBUILD for pacman's version. You may have to go in and edit the PKGBUILD manually to translate the version from CPAN to pacman.

(TODO: example here, I forgot what did this)

Pre-requisites are always installed

CPANPLUS by default installs the pre-requisite modules before the module you requested. This module does the same only it creates an Arch package and installs it with pacman instead.

You should be able to run pacman under sudo for this to work properly. Or you could run cpan2dist as root, but I wouldn't recommend it.

All module packages are installed explicitly

This has to do with how Pacman categorizes automatically installed dependencies implicitly installed package. Explicitly installed packages are packages installed by the user, by request.

So, logically, all pre-requisite perl modules should be installed implicitly but right now everything is installed explicitly.

If this is a big problem, tell me and I will try to make some hackish solution. I can't think of an elegant way to do this.

INTERFACE METHODS

See CPANPLUS::Dist::Base's documentation for a description of the purpose of these functions. All of these "interface" methods override Base's default actions in order to create our packages.

These methods are called by the CPANPLUS::Backend object that controls building new packages (ie, via the cpanp or cpan2dist commands). You should not call these methods directly, unless you know what you are doing. (This is mostly here to appease Test::POD::Coverage)

format_available

Purpose  : Checks if we have makepkg and pacman installed
Returns  : 1 - if we have the tools needed to make a pacman package.
           0 - if we don't think so.

init

Purpose  : Initializes our object internals to get things started
Returns  : 1 always

prepare

Purpose  : Prepares the files and directories we will need to build a
           package.  Also prepares any data we expect to have later,
           on a per-object basis.
Return   : 1 if ok, 0 on error.
Postcond : Sets $self->status->prepare to 1 or 0 on success or
           failure.

create

Purpose  : Creates the pacman package using the 'makepkg' command.

install

Purpose  : Installs the package file (.pkg.tar.gz) using sudo and
           pacman.
Comments : Called automatically on pre-requisite packages

BUILD ERRORS

Naturally, there are sometimes problems when trying to fool a module into thinking that you are installing it on the root (/) filesystem. Or just problems in general with compiling any software targeted to a broad range of systems!

The solution is to look for a custom-made package online using pacman or checking the AUR. If this fails, well, hack the package yourself! Sometimes patches or other fiddling are needed.

As a last resort, you could ask nicely on the Archlinux forums for someone to make you a custom PKGBUILD.

BUGS

Please report any bugs or feature requests to bug-cpanplus-dist-arch at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CPANPLUS-Dist-Arch. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

Known Bugs

Dist creation of '...' skipped, build time exceeded: 300 seconds

If compiling a module takes a long time, this message will pop up. Interestingly, though, the module keeps compiling in the background...?

This is something CPANPLUS does automatically. If you had been trying to install the module, the install step will be aborted. The package will still be created in the usual directory, so you can install it manually.

I haven't been able to track this down yet... I think it has only happened with cpan2dist so far. It happened when building PDL, by the way.

TODO

  • Extract license information from META.yml, maybe use a YAML module.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc CPANPLUS::Dist::Arch

If you are confused why the build process failed, CPANPLUS keeps logs of every build in ~/.cpanplus/install_logs/.

You can also look for information at:

ACKNOWLEDGEMENTS

This module was inspired by the perl-cpanplus-pacman package and CPANPLUS::Dist::Pacman by Firmicus which is available at http://aur.archlinux.org/.

This mostly started from CPANPLUS::Dist::RPM which is on Google Code at http://code.google.com/p/cpanplus-dist-rpm/. This was a very helpful starting point to try to understand the internals of CPANPLUS.

Notice the helpful variable comments at the beginning of methods? Stolen!

SEE ALSO

AUTHOR

Justin Davis, <jrcd83 at gmail.com>, juster on http://bbs.archlinux.org

COPYRIGHT & LICENSE

Copyright 2009 Justin Davis, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.