The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CPAN-Plugin-Sysdeps-0.31
River stage zero No dependents
4 ++
/ CPAN::Plugin::Sysdeps

NAME

CPAN::Plugin::Sysdeps - a CPAN.pm plugin for installing system dependencies

SYNOPSIS

In the CPAN.pm shell:

    o conf plugin_list push CPAN::Plugin::Sysdeps
    o conf commit

DESCRIPTION

CPAN::Plugin::Sysdeps is a plugin for CPAN.pm (version >= 2.07) to install non-CPAN dependencies automatically. Currently, the list of required system dependencies is maintained in a static data structure in CPAN::Plugin::Sysdeps::Mapping. Supported operations systems and distributions are FreeBSD and Debian-like Linux distributions. There are also some module rules for Fedora-like Linux distributions, Windows through chocolatey, and Mac OS X through homebrew.

The plugin may be configured like this:

    o conf plugin_list CPAN::Plugin::Sysdeps=arg1,arg2,...

Possible arguments are:

apt-get, aptitude, pkg, yum, homebrew

Force a particular installer for system packages. If not set, then the plugin find a default for the current operating system or linux distributions:

Debian-like distributions: apt-get
Fedora-like distributions: yum
FreeBSD: pkg
Windows: chocolatey
Mac OS X: homebrew

Additionally, sudo(1) is prepended before the installer programm if the current user is not a privileged one, and the installer requires elevated privileges.

batch

Don't ask any questions.

interactive

Be interactive, especially ask for confirmation before installing a system package.

dryrun

Only log installation actions.

debug

Turn debugging on. Alternatively the environment variable CPAN_PLUGIN_SYSDEPS_DEBUG may be set to a true value.

mapping=perlmod|file

Prepend another static mapping from cpan modules or distributions to system packages. This should be specified as a perl module (Foo::Bar) or an absolute file name. The mapping file is supposed to just return the mapping data structure as described below.

MAPPING

!This implementation is subject to change!

A mapping is tree-like data structure expressed as nested arrays. The top-level nodes usually specify a cpan module or distribution to match, and a leaf should specify the dependent system packages.

A sample mapping may look like this:

    (
     [cpanmod => ['BerkeleyDB', 'DB_File'],
      [os => 'freebsd',
       [package => 'db48']],
      [linuxdistro => '~debian',
       [linuxdistrocodename => 'squeeze',
        [package => 'libdb4.8-dev']],
       [linuxdistrocodename => 'wheezy',
        [package => 'libdb5.1-dev']],
       [package => 'libdb5.3-dev']]],
    );

The nodes are key-value pairs. The values may be strings, arrays of strings (meaning that any of the strings may match), or compiled regular expressions.

Supported keywords are:

cpanmod => $value

Match a CPAN module name (e.g. Foo::Bar).

cpandist => $value

Match a CPAN distribution name (e.g. Foo-Bar-1.23). Note that currently only the base_id is matched; this may change!

os => $value

Match a operating system (perl's $^O value).

linuxdistro => $value

Match a linux distribution name, as returned by lsb_release -is. The distribution name is lowercased.

There are special values ~debian to match Debian-like distributions (Ubuntu and LinuxMint) and ~fedora to match Fedora-like distributions (RedHat and CentOS).

linuxdistrocodename => $value

Match a linux distribution version using its code name (e.g. jessie).

TODO: it should be possible to express comparisons with code names, e.g. '>=squeeze'.

linuxdistroversion => $value

Match a linux distribution versions. Comparisons like '>=8.0' are possible.

package => $value

Specify the dependent system packages.

For some distributions (currently: debian-like ones) it is possible to specify alternatives in the form package1 | package2 | ....

PLUGIN HOOKS

The module implements the following CPAN plugin hooks:

new
post_get

USE CASES

CPAN TESTERS

Install system packages automatically while testing CPAN modules. If the smoke system runs under an unprivileged user, then a sudoers rule has to be added. For such a user named cpansand on a Debian-like system this could look like this (two rules for batch and non-batch mode):

    cpansand ALL=(ALL) NOPASSWD: /usr/bin/apt-get -y install *
    cpansand ALL=(ALL) NOPASSWD: /usr/bin/apt-get install *

USE WITHOUT CPAN.PM

It's possible to use this module also without CPAN.pm through the cpan-sysdeps script.

For example, just list the system prereqs for Imager on a FreeBSD system:

    $ cpan-sysdeps --cpanmod Imager
    freetype2
    giflib-nox11
    png
    tiff
    jpeg

On a Debian system the output will look like:

    libfreetype6-dev
    libgif-dev
    libpng12-dev
    libjpeg-dev
    libtiff5-dev

Just show the packages which are yet uninstalled:

    $ cpan-sysdeps --cpanmod Imager --uninstalled

Show what CPAN::Plugin::Sysdeps would execute if it was run:

    $ cpan-sysdeps --cpanmod Imager --dryrun

And actually run and install the missing packages:

    $ cpan-sysdeps --cpanmod Imager --run

USE WITH CPAN_SMOKE_MODULES

cpan_smoke_modules is another CPAN.pm wrapper specially designed for CPAN Testing (to be found at https://github.com/eserte/srezic-misc. If CPAN.pm is already configured to use the plugin, then cpan_smoke_modules will also use this configuration. But it's also possible to use cpan_smoke_modules without changes to CPAN/MyConfig.pm, and even with an uninstalled CPAN::Plugin::Sysdeps. This is especially interesting when testing changes in the Mapping.pm file. A sample run:

    cd .../path/to/CPAN-Plugin-Sysdeps
    perl Makefile.PL && make all test
    env PERL5OPT="-Mblib=$(pwd)" cpan_smoke_modules -perl /path/to/perl --sysdeps Imager

Or alternatively without any interactive questions:

    env PERL5OPT="-Mblib=$(pwd)" cpan_smoke_modules -perl /path/to/perl --sysdeps-batch Imager

NOTES, LIMITATIONS, BUGS, TODO

  • Minimal requirements

    CPAN.pm supports the plugin system since 2.07. If the CPAN.pm is older, then still the cpan-sysdeps script can be used.

    It is assumed that some system dependencies are still installed: a make, a suitable C compiler, maybe sudo, patch (e.g. if there are distroprefs using patch files) and of course perl. On linux systems, lsb-release is usually required (there's limited support for lsb-release-less operation on some Debian-like distributions). On Mac OS X systems homebrew has to be installed.

  • Batch mode

    Make sure to configure the plugin with the batch keyword (but read also "Conflicting packages"). In CPAN/MyConfig.pm:

      'plugin_list' => [q[CPAN::Plugin::Sysdeps=batch]],

    Installation of system packages requires root priviliges. Therefore the installer is run using sudo(1) if the executing user is not root. To avoid the need to enter a password either make sure that running the installer program (apt-get or so) is made password-less in the sudoers file, or run a wrapper like sudo_keeper.

  • Error handling

    Failing things in the plugin are causing die() calls. This can happen if packages cannot be installed (e.g. because of a bad network connection, the package not existing for the current os or distribution, package exists only in a "non-free" repository which needs to be added to /etc/apt/sources.list, another installer process having the exclusive lock...).

  • Conflicting packages

    System prerequisites specified in the mapping may conflict with already installed packages. Please note that with the "batch" configuration already installed conflicting packages are actually removed, at least on Debian systems.

  • Support for more OS and Linux distributions

    Best supported systems are FreeBSD and Debian-like systems (but details may be missing for distributions like Ubuntu or Mint). Support for Fedora-like systems and Mac OS X systems is fair, for Windows quite limited and for other systems missing.

  • Support for cpanm

    To my knowledge there's no hook support in cpanm. Maybe things will change in cpanm 2.0. But it's always possible to use the cpan-sysdeps script.

  • Should gnukfreebsd be handled like debian?

    Maybe gnukfreebsd should be included in the "like_debian" condition?

CREDITS

This module was developed at the Perl QA Hackathon 2016 http://act.qa-hackathon.org/qa2016/ which was made possible by the generosity of many sponsors:

https://www.fastmail.com FastMail, https://www.ziprecruiter.com ZipRecruiter, http://www.activestate.com ActiveState, http://www.opusvl.com OpusVL, https://www.strato.com Strato, http://www.surevoip.co.uk SureVoIP, http://www.cv-library.co.uk CV-Library, https://www.iinteractive.com/ Infinity, https://opensource.careers/perl-careers/ Perl Careers, https://www.mongodb.com MongoDB, https://www.thinkproject.com thinkproject!, https://www.dreamhost.com/ Dreamhost, http://www.perl6.org/ Perl 6, http://www.perl-services.de/ Perl Services, https://www.evozon.com/ Evozon, http://www.booking.com Booking, http://eligo.co.uk Eligo, http://www.oetiker.ch/ Oetiker+Partner, http://capside.com/en/ CAPSiDE, https://www.procura.nl/ Procura, https://constructor.io/ Constructor.io, https://metacpan.org/author/BABF Robbie Bow, https://metacpan.org/author/RSAVAGE Ron Savage, https://metacpan.org/author/ITCHARLIE Charlie Gonzalez, https://twitter.com/jscook2345 Justin Cook.

CONTRIBUTORS

Max Maischein (CORION) - Windows/chocolatey support

AUTHOR

Slaven Rezic

COPYRIGHT AND LICENSE

Copyright (C) 2016,2017 by Slaven Rezić

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

SEE ALSO

cpan-sysdeps, CPAN, apt-get(1), aptitude(1), pkg(8), yum(1).