1CPAN::Plugin::Sysdeps(3U)ser Contributed Perl DocumentatiCoPnAN::Plugin::Sysdeps(3)
2
3
4

NAME

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

SYNOPSIS

10       In the CPAN.pm shell:
11
12           o conf plugin_list push CPAN::Plugin::Sysdeps
13           o conf commit
14

DESCRIPTION

16       CPAN::Plugin::Sysdeps is a plugin for CPAN.pm (version >= 2.07) to
17       install non-CPAN dependencies automatically. Currently, the list of
18       required system dependencies is maintained in a static data structure
19       in CPAN::Plugin::Sysdeps::Mapping. Supported operations systems and
20       distributions are FreeBSD and Debian-like Linux distributions. There
21       are also some module rules for Fedora-like Linux distributions, Windows
22       through chocolatey, and Mac OS X through homebrew.
23
24       The plugin may be configured like this:
25
26           o conf plugin_list CPAN::Plugin::Sysdeps=arg1,arg2,...
27
28       Possible arguments are:
29
30       "apt-get", "aptitude", "pkg", "yum", "dnf", "homebrew"
31           Force a particular installer for system packages. If not set, then
32           the plugin find a default for the current operating system or linux
33           distributions:
34
35           Debian-like distributions: "apt-get"
36           Fedora-like distributions: "yum" or "dnf"
37           FreeBSD: "pkg"
38           DragonFly BSD: "pkg"
39           Windows: "chocolatey"
40           Mac OS X: "homebrew"
41
42           Additionally, sudo(8) is prepended before the installer programm if
43           the current user is not a privileged one, and the installer
44           requires elevated privileges.
45
46       "batch"
47           Don't ask any questions.
48
49       "interactive"
50           Be interactive, especially ask for confirmation before installing a
51           system package.
52
53       "dryrun"
54           Only log installation actions.
55
56       "debug"
57           Turn debugging on. Alternatively the environment variable
58           "CPAN_PLUGIN_SYSDEPS_DEBUG" may be set to a true value.
59
60       "mapping=perlmod|file"
61           Prepend another static mapping from cpan modules or distributions
62           to system packages. This should be specified as a perl module
63           (Foo::Bar) or an absolute file name. The mapping file is supposed
64           to just return the mapping data structure as described below.
65
66   MAPPING
67       !This implementation is subject to change!
68
69       A mapping is tree-like data structure expressed as nested arrays. The
70       top-level nodes usually specify a cpan module or distribution to match,
71       and a leaf should specify the dependent system packages.
72
73       A sample mapping may look like this:
74
75           (
76            [cpanmod => ['BerkeleyDB', 'DB_File'],
77             [os => 'freebsd',
78              [package => 'db48']],
79             [linuxdistro => '~debian',
80              [linuxdistrocodename => 'squeeze',
81               [package => 'libdb4.8-dev']],
82              [linuxdistrocodename => 'wheezy',
83               [package => 'libdb5.1-dev']],
84              [package => 'libdb5.3-dev']]],
85           );
86
87       The nodes are key-value pairs. The values may be strings, arrays of
88       strings (meaning that any of the strings may match), or compiled
89       regular expressions.
90
91       Supported keywords are:
92
93       cpanmod => $value
94           Match a CPAN module name (e.g. "Foo::Bar").
95
96       cpandist => $value
97           Match a CPAN distribution name (e.g. "Foo-Bar-1.23"). Note that
98           currently only the base_id is matched; this may change!
99
100       os => $value
101           Match a operating system (perl's $^O value).
102
103       linuxdistro => $value
104           Match a linux distribution name, as returned by "lsb_release -is".
105           The distribution name is lowercased.
106
107           There are special values "~debian" to match Debian-like
108           distributions (Ubuntu and LinuxMint) and "~fedora" to match Fedora-
109           like distributions (RedHat and CentOS).
110
111       linuxdistrocodename => $value
112           Match a linux distribution version using its code name (e.g.
113           "jessie").
114
115           TODO: it should be possible to express comparisons with code names,
116           e.g. '>=squeeze'.
117
118       linuxdistroversion => $value
119           Match a linux distribution versions. Comparisons like '>=8.0' are
120           possible.
121
122       package => $value
123           Specify the dependent system packages.
124
125           For some distributions (currently: debian-like ones) it is possible
126           to specify alternatives in the form "package1 | package2 | ...".
127
128   PLUGIN HOOKS
129       The module implements the following CPAN plugin hooks:
130
131       new
132       post_get
133

USE CASES

135   CPAN TESTERS
136       Install system packages automatically while testing CPAN modules. If
137       the smoke system runs under an unprivileged user, then a sudoers rule
138       has to be added. For such a user named "cpansand" on a Debian-like
139       system this could look like this (two rules for batch and non-batch
140       mode):
141
142           cpansand ALL=(ALL) NOPASSWD: /usr/bin/apt-get -y install *
143           cpansand ALL=(ALL) NOPASSWD: /usr/bin/apt-get install *
144
145   USE WITHOUT CPAN.PM
146       It's possible to use this module also without CPAN.pm through the cpan-
147       sysdeps script.
148
149       For example, just list the system prereqs for Imager on a FreeBSD
150       system:
151
152           $ cpan-sysdeps --cpanmod Imager
153           freetype2
154           giflib-nox11
155           png
156           tiff
157           jpeg
158
159       On a Debian system the output will look like:
160
161           libfreetype6-dev
162           libgif-dev
163           libpng12-dev
164           libjpeg-dev
165           libtiff5-dev
166
167       Just show the packages which are yet uninstalled:
168
169           $ cpan-sysdeps --cpanmod Imager --uninstalled
170
171       Show what CPAN::Plugin::Sysdeps would execute if it was run:
172
173           $ cpan-sysdeps --cpanmod Imager --dryrun
174
175       And actually run and install the missing packages:
176
177           $ cpan-sysdeps --cpanmod Imager --run
178
179   USE WITH CPAN_SMOKE_MODULES
180       "cpan_smoke_modules" is another "CPAN.pm" wrapper specially designed
181       for CPAN Testing (to be found at
182       <https://github.com/eserte/srezic-misc>. If "CPAN.pm" is already
183       configured to use the plugin, then "cpan_smoke_modules" will also use
184       this configuration. But it's also possible to use "cpan_smoke_modules"
185       without changes to "CPAN/MyConfig.pm", and even with an uninstalled
186       "CPAN::Plugin::Sysdeps". This is especially interesting when testing
187       changes in the Mapping.pm file. A sample run:
188
189           cd .../path/to/CPAN-Plugin-Sysdeps
190           perl Makefile.PL && make all test
191           env PERL5OPT="-Mblib=$(pwd)" cpan_smoke_modules -perl /path/to/perl --sysdeps Imager
192
193       Or alternatively without any interactive questions:
194
195           env PERL5OPT="-Mblib=$(pwd)" cpan_smoke_modules -perl /path/to/perl --sysdeps-batch Imager
196

NOTES, LIMITATIONS, BUGS, TODO

198       •   Minimal requirements
199
200           CPAN.pm supports the plugin system since 2.07. If the CPAN.pm is
201           older, then still the "cpan-sysdeps" script can be used.
202
203           It is assumed that some system dependencies are still installed: a
204           "make", a suitable C compiler, maybe "sudo", "patch" (e.g. if there
205           are distroprefs using patch files) and of course "perl". On linux
206           systems, "lsb-release" is usually required (there's limited support
207           for lsb-release-less operation on some Debian-like distributions).
208           On Mac OS X systems "homebrew" has to be installed.
209
210       •   Batch mode
211
212           Make sure to configure the plugin with the "batch" keyword (but
213           read also "Conflicting packages"). In CPAN/MyConfig.pm:
214
215             'plugin_list' => [q[CPAN::Plugin::Sysdeps=batch]],
216
217           Installation of system packages requires root priviliges. Therefore
218           the installer is run using sudo(8) if the executing user is not
219           root. To avoid the need to enter a password either make sure that
220           running the installer program ("apt-get" or so) is made password-
221           less in the sudoers file, or run a wrapper like sudo_keeper
222           <https://github.com/eserte/srezic-
223           misc/blob/master/scripts/sudo_keeper>.
224
225       •   Error handling
226
227           Failing things in the plugin are causing "die()" calls. This can
228           happen if packages cannot be installed (e.g. because of a bad
229           network connection, the package not existing for the current os or
230           distribution, package exists only in a "non-free" repository which
231           needs to be added to /etc/apt/sources.list, another installer
232           process having the exclusive lock...).
233
234       •   Conflicting packages
235
236           System prerequisites specified in the mapping may conflict with
237           already installed packages. Please note that with the "batch"
238           configuration already installed conflicting packages are actually
239           removed, at least on Debian systems.
240
241       •   Support for more OS and Linux distributions
242
243           Best supported systems are FreeBSD and Debian-like systems (but
244           details may be missing for distributions like Ubuntu or Mint).
245           Support for Fedora-like systems and Mac OS X systems is fair, for
246           Windows quite limited and for other systems missing.
247
248       •   Support for cpanm
249
250           To my knowledge there's no hook support in cpanm. Maybe things will
251           change in cpanm 2.0. But it's always possible to use the cpan-
252           sysdeps script.
253
254       •   Should gnukfreebsd be handled like debian?
255
256           Maybe gnukfreebsd should be included in the "like_debian"
257           condition?
258

CREDITS

260       This module was developed at the Perl QA Hackathon 2016
261       <http://act.qa-hackathon.org/qa2016/> which was made possible by the
262       generosity of many sponsors:
263
264       <https://www.fastmail.com> FastMail, <https://www.ziprecruiter.com>
265       ZipRecruiter, <http://www.activestate.com> ActiveState,
266       <http://www.opusvl.com> OpusVL, <https://www.strato.com> Strato,
267       <http://www.surevoip.co.uk> SureVoIP, <http://www.cv-library.co.uk> CV-
268       Library, <https://www.iinteractive.com/> Infinity,
269       <https://opensource.careers/perl-careers/> Perl Careers,
270       <https://www.mongodb.com> MongoDB, <https://www.thinkproject.com>
271       thinkproject!, <https://www.dreamhost.com/> Dreamhost,
272       <http://www.perl6.org/> Perl 6, <http://www.perl-services.de/> Perl
273       Services, <https://www.evozon.com/> Evozon, <http://www.booking.com>
274       Booking, <http://eligo.co.uk> Eligo, <http://www.oetiker.ch/>
275       Oetiker+Partner, <http://capside.com/en/> CAPSiDE,
276       <https://www.procura.nl/> Procura, <https://constructor.io/>
277       Constructor.io, <https://metacpan.org/author/BABF> Robbie Bow,
278       <https://metacpan.org/author/RSAVAGE> Ron Savage,
279       <https://metacpan.org/author/ITCHARLIE> Charlie Gonzalez,
280       <https://twitter.com/jscook2345> Justin Cook.
281

CONTRIBUTORS

283       Max Maischein (CORION) - Windows/chocolatey support
284
285       David Dick (DDICK) - OpenBSD, DragonFly BSD and Fedora support
286

AUTHOR

288       Slaven Rezic
289
291       Copyright (C) 2016,2017,2018,2019 by Slaven Rezić
292
293       This library is free software; you can redistribute it and/or modify it
294       under the same terms as Perl itself, either Perl version 5.8.8 or, at
295       your option, any later version of Perl 5 you may have available.
296

SEE ALSO

298       cpan-sysdeps, CPAN, apt-get(1), aptitude(1), pkg(8), yum(1), dnf(1).
299
300
301
302perl v5.34.0                      2022-01-20          CPAN::Plugin::Sysdeps(3)
Impressum