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

NAME

CPANPLUS::Dist::Arch - Creates Archlinux packages from Perl's CPAN repository.

VERSION

Version 0.01 -- First Public Release

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 DBIx::Class

This lengthly command line can be shortened by specifying CPANPLUS::Dist::Arch as the default 'Dist' type to use in CPANPLUS's configuration.

$ 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/justin/.cpanplus/lib/CPANPLUS/Config/User.pm)
CPAN Terminal> q

Exiting CPANPLUS shell

$ cpan2dist DBIx::Class

$ cpan2dist --install DBIx::Class

Now there is also the added advantage that CPANPLUS will automatically package anything you install using cpanp. Score!

$ cpanp i DBIx::Class

$ cpanp i DBIx::Class

Or you can edit the User.pm file mentioned above manually (replacing my name with yours, of course!). See also CPANPLUS::Config for more configuration options.

WHERES THE PACKAGE?

Packages are stored under the user's home directory, (the HOME environment variable) under the .cpanplus directory. Two seperate directories are created for building packages and for storing the resulting package file.

Build Directory

$HOME/.cpanplus/5.10.0/pacman/build

Package Directory

$HOME/.cpanplus/5.10.0/pacman/pkg

Where 5.10.0 represents the version of perl you used to build the package.

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.

HOW THINGS [DON'T?] WORK

This module is just a simple wrapper around (well, inside really) CPANPLUS. CPANPLUS handles all the downloading and pre-requisite calculations itself and then calls this module to build, package up the module with makepkg, and usually install it with pacman.

CPAN doesn't know anything about pacman packages, and pacman doesn't give a damn if CPAN thinks something is installed. They both keep their own list of what's installed and what isn't. Well, at least pacman keeps a list!

Skip down the MORAL OF THE STORY if you don't want to read a list of how things work:

1. CPANPLUS downloads the distribution (.tar.gz) file, extracts it
   and finds which modules this distribution depends on.

2. If the dependency cannot be found in @INC, find the
   distribution that owns that module, and go to Step 1 for all
   missing dependencies

3. CPANPLUS calls CPANPLUS::Dist::Arch to start installing the
   dist.

4. CPANPLUS::Dist::Arch runs the makepkg program to build the
   package

5. CPANPLUS::Dist::Arch runs the pacman program to install the
   package.  Pacman checks if the _package_ for each dependency
   is installed.

Obviously, dependencies are checked twice. This can be a problem if you have a module installed, but it does not have a package!

MORAL TO THE STORY

It's all or nothing. Install every Perl module (other than those included in the core) as pacman packages or pacman will probably complain there is a missing dependency, even though CPAN will cheerfully point out there isn't any problem.

This even includes CPANPLUS itself!

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'm not sure if these are bugs, but they are close.

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 fix it.

Pacman says a required dependency I SAW INSTALLED 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)

Package descriptions are sometimes missing

Right now this module searches in the META.xml and README file for a package description. The description may also be inside the module in POD documentation. Needless to say because there is no centralized location for perl module descriptions, they can be iffy and hard to find.

Again, you may have to edit the PKGBUILD if you really, really, care. Until I add more complex handling, anyways.

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.

SUPPORT

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

perldoc CPANPLUS::Dist::Arch

You can also look for information at:

ERROR MESSAGES

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 specified the --install flag, 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.

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.

Compilation fails

Use the source, Luke! See next item, too.

Tests fail

Perl modules come with tests to make sure that the module built correctly and will run in the same way that the module maker expects it to. Occassionaly these tests will fail (whether you use CPANPLUS, CPAN, or this module) due to differences in your system and the developer's system, or who knows why!

The hackish unrecommended way to fix this is to use the --skiptest option to cpanp -i or cpan2dist.

The recommended way to fix this is to get down to the root of the problem and maybe write a patch, modify the generated PKGBUILD file, and submit your changes on the AUR! :)

Examples

Writing System-wide Config File

I had this error message at the end of building XML::LibXML. It tries to create a system-wide config variable:

Cannot write to /usr/share/perl5/vendor_perl/XML/SAX/ParserDetails.ini: Permission denied at /usr/share/perl5/vendor_perl/XML/SAX.pm line 191.

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 and if you
           specify the --install flag

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.

AUTHOR

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

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

Much was learned from CPANPLUS::Dist::RPM which is on Google Code at http://code.google.com/p/cpanplus-dist-rpm/.

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.