1Alien::Build::Manual::FUAsQe(r3)Contributed Perl DocumenAtlaiteino:n:Build::Manual::FAQ(3)
2
3
4

NAME

6       Alien::Build::Manual::FAQ - Frequently Asked Questions about
7       Alien::Build
8

VERSION

10       version 1.93
11

SYNOPSIS

13        perldoc Alien::Build::Manual::FAQ
14

DESCRIPTION

16       This document serves to answer the most frequently asked questions made
17       by developers creating Alien modules using Alien::Build.
18

QUESTIONS

20   What is Alien, Alien::Base and Alien::Build?
21       Alien in a Perl namespace for defining dependencies in CPAN for
22       libraries and tools which are not "native" to CPAN.  For a manifesto
23       style description of the Why, and How see Alien.  Alien::Base is a base
24       class for the Alien runtime.  Alien::Build is a tool for probing the
25       operating system for existing libraries and tools, and downloading,
26       building and installing packages.  alienfile is a recipe format for
27       describing how to probe, download, build and install a package.
28
29   How do I build a package that uses build system
30       autoconf
31
32       Use the autoconf plugin (Alien::Build::Plugin::Build::Autoconf).  If
33       your package provides a pkg-config ".pc" file, then you can also use
34       the PkgConfig plugin (Alien::Build::Plugin::PkgConfig::Negotiate).
35
36        use alienfile
37        plugin PkgConfig => 'libfoo';
38        share {
39          start_url => 'http://example.org/dist';
40          plugin Download => (
41            version => qr/libfoo-([0-9\.])\.tar\.gz$/,
42          );
43          plugin Extract => 'tar.gz';
44          plugin 'Build::Autoconf';
45        };
46
47       If you need to provide custom flags to configure, you can do that too:
48
49        share {
50          plugin 'Build::Autoconf';
51          build [
52            '%{configure} --disable-shared --enable-foo',
53            '%{make}',
54            '%{make} install',
55          ];
56        };
57
58       If your package requires GNU Make, use "%{gmake}" instead of "%{make}".
59
60       autoconf-like
61
62       If you see an error like this:
63
64        Unknown option "--with-pic".
65
66       It is because the autoconf plugin uses the "--with-pic" option by
67       default, since it makes sense most of the time, and autoconf usually
68       ignores options that it does not recognize.  Some autoconf style build
69       systems fail when they see an option that they do not recognize.  You
70       can turn this behavior off for these packages:
71
72        plugin 'Build::Autoconf' => (
73          with_pic => 0,
74        );
75
76       Another thing about the autoconf plugin is that it uses "DESTDIR" to do
77       a double staged install.  If you see an error like "nothing was
78       installed into destdir", that means that your package does not support
79       "DESTDIR".  You should instead use the MSYS plugin and use a command
80       sequence to do the build like this:
81
82        share {
83          plugin 'Build::MSYS';
84          build [
85            # explicitly running configure with "sh" will make sure that
86            # it works on windows as well as UNIX.
87            'sh configure --prefix=%{.install.prefix} --disable-shared',
88            '%{make}',
89            '%{make} install',
90          ];
91        };
92
93       CMake
94
95       There is an alien Alien::cmake3 that provides "cmake" 3.x or better (It
96       is preferred to the older Alien::CMake).  Though it is recommended that
97       you use the "cmake" (Alien::Build::Plugin::Build::CMake) plugin instead
98       of using Alien::cmake3.
99
100        use alienfile;
101
102        share {
103          plugin 'Build::CMake';
104          build [
105            # this is the default build step, if you do not specify one.
106            [ '%{cmake}',
107                @{ meta->prop->{plugin_build_cmake}->{args} },
108                # ... put extra cmake args here ...
109                '.'
110            ],
111            '%{make}',
112            '%{make} install',
113          ];
114        };
115
116       vanilla Makefiles
117
118       Alien::Build provides a helper ("%{make}") for the "make" that is used
119       by Perl and ExtUtils::MakeMaker (EUMM).  Unfortunately the "make"
120       supported by Perl and EUMM on Windows ("nmake" and "dmake") are not
121       widely supported by most open source projects.  (Thankfully recent
122       perls and EUMM support GNU Make on windows now).
123
124       You can use the "make" plugin (Alien::Build::Plugin::Build::Make) to
125       tell the Alien::Build system know which make the project that you are
126       alienizing requires.
127
128        plugin 'Build::Make' => 'umake';
129        # umake makes %{make} either GNU Make or BSD Make on Unix and GNU Make on Windows.
130        build {
131          build [
132            # You can use the Perl config compiler and cflags using the %{perl.config...} helper
133            [ '%{make}', 'CC=%{perl.config.cc}', 'CFLAGS=%{perl.config.cccdlflags} %{perl.config.optimize}' ],
134            [ '%{make}', 'install', 'PREFIX=%{.install.prefix}' ],
135          ],
136        };
137
138       Some open source projects require GNU Make, and you can specify that,
139       and Alien::gmake will be pulled in on platforms that do not already
140       have it.
141
142        plugin 'Build::Make' => 'gmake';
143        ...
144
145   How do I probe for a package that uses pkg-config
146       Use the "pkg-config" plugin
147       (Alien::Build::Plugin::PkgConfig::Negotiate):
148
149        use alienfile;
150        plugin 'PkgConfig' => (
151          pkg_name => 'libfoo',
152        );
153
154       It will probe for a system version of the library.  It will also add
155       the appropriate "version" "cflags" and "libs" properties on either a
156       "system" or "share" install.
157
158   How do I specify a minimum or exact version requirement for packages that
159       use pkg-config?
160       The various pkg-config plugins all support atleast_version,
161       exact_version and maximum_version fields, which have the same meaning
162       as the "pkg-config" command line interface:
163
164        use alienfile;
165
166        plugin 'PkgConfig', pkg_name => foo, atleast_version => '1.2.3';
167
168       or
169
170        use alienfile;
171
172        plugin 'PkgConfig', pkg_name => foo, exact_version => '1.2.3';
173
174   How to create an Alien module for a packages that do not support pkg-
175       config?
176       Packages that provide a configuration script
177
178       Many packages provide a command that you can use to get the appropriate
179       version, compiler and linker flags.  For those packages you can just
180       use the commands in your alienfile.  Something like this:
181
182        use alienfile;
183
184        probe [ 'foo-config --version' ];
185
186        share {
187          ...
188
189          build [
190            '%{make} PREFIX=%{.runtime.prefix}',
191            '%{amek} install PREFIX=%{.runtime.prefix}',
192          ];
193        };
194
195        gather [
196          [ 'foo-config', '--version', \'%{.runtime.version}' ],
197          [ 'foo-config', '--cflags',  \'%{.runtime.cflags}'  ],
198          [ 'foo-config', '--libs',    \'%{.runtime.libs}'    ],
199        ];
200
201       Packages that require a compile test
202
203       Some packages just expect you do know that "-lfoo" will work.  For
204       those you can use the "cbuilder" plugin
205       (Alien::Build::Plugin::Probe::CBuilder.
206
207        use alienfile;
208        plugin 'Probe::CBuilder' => (
209          cflags => '-I/opt/libfoo/include',
210          libs   => '-L/opt/libfoo/lib -lfoo',
211        );
212
213        share {
214          ...
215          gather sub {
216            my($build) = @_;
217            my $prefix = $build->runtime_prop->{prefix};
218            $build->runtime_prop->{cflags} = "-I$prefix/include ";
219            $build->runtime_prop->{libs}   = "-L$prefix/lib -lfoo ";
220          };
221        }
222
223       This plugin will build a small program with these flags and test that
224       it works.  (There are also options to provide a program that can make
225       simple tests to ensure the library works).  If the probe works, it will
226       set the compiler and linker flags.  (There are also options for
227       extracting the version from the test program).  If you do a share
228       install you will need to set the compiler and linker flags yourself in
229       the gather step, if you aren't using a build plugin that will do that
230       for you.
231
232   Can/Should I write a tool oriented Alien module?
233       Certainly.  The original intent was to provide libraries, but tools are
234       also quite doable using the Alien::Build toolset.  A good example of
235       how to do this is Alien::nasm.  You will want to use the
236       'Probe::CommandLine':
237
238        use alienfile;
239
240        plugin 'Probe::CommandLine' => (
241          command => 'gzip',
242        );
243
244   How do I test my package once it is built (before it is installed)?
245       Use Test::Alien.  It has extensive documentation, and integrates nicely
246       with Alien::Base.
247
248   How do I patch packages that need alterations?
249       If you have a diff file you can use patch:
250
251        use alienfile;
252
253        probe sub { 'share' }; # replace with appropriate probe
254
255        share {
256          ...
257          patch [ '%{patch} -p1 < %{.install.patch}/mypatch.diff' ];
258          build [ ... ] ;
259        }
260
261        ...
262
263       You can also patch using Perl if that is easier:
264
265        use alienfile;
266
267        probe sub { 'share' };
268
269        share {
270          ...
271          patch sub {
272            my($build) = @_;
273            # make changes to source prior to build
274          };
275          build [ ... ];
276        };
277
278   The flags that a plugin produces are wrong!
279       Sometimes, the compiler or linker flags that the PkgConfig plugin comes
280       up with are not quite right.  (Frequently this is actually because a
281       package maintainer is providing a broken ".pc" file).  (Other plugins
282       may also have problems).  You could replace the plugin's "gather" step
283       but a better way is to provide a subroutine callback to be called after
284       the gather stage is complete.  You can do this with the alienfile
285       "after" directive:
286
287        use alienfile;
288
289        plugin 'PlgConfig' => 'libfoo';
290
291        share {
292          ...
293          after 'gather' => sub {
294            my($build) = @_;
295            $build->runtime_prop->{libs}        .= " -lbar";        # libfoo also requires libbar
296            $build->runtime_prop->{libs_static} .= " -lbar -lbaz";  # libfoo also requires libbaz under static linkage
297          };
298        };
299
300       Sometimes you only need to do this on certain platforms.  You can
301       adjust the logic based on $^O appropriately.
302
303        use alienfile;
304
305        plugin 'PlgConfig' => 'libfoo';
306
307        share {
308          ...
309          after 'gather' => sub {
310            my($build) = @_;
311            if($^O eq 'MSWin32') {
312              $build->runtime_prop->{libs} .= " -lpsapi";
313            }
314          };
315        };
316
317   599 Internal Exception errors downloading packages from the internet
318        Alien::Build::Plugin::Fetch::HTTPTiny> 599 Internal Exception fetching http://dist.libuv.org/dist/v1.15.0
319        Alien::Build::Plugin::Fetch::HTTPTiny> exception: IO::Socket::SSL 1.42 must be installed for https support
320        Alien::Build::Plugin::Fetch::HTTPTiny> exception: Net::SSLeay 1.49 must be installed for https support
321        Alien::Build::Plugin::Fetch::HTTPTiny> An attempt at a SSL URL https was made, but your HTTP::Tiny does not appear to be able to use https.
322        Alien::Build::Plugin::Fetch::HTTPTiny> Please see: https://metacpan.org/pod/Alien::Build::Manual::FAQ#599-Internal-Exception-errors-downloading-packages-from-the-internet
323        error fetching http://dist.libuv.org/dist/v1.15.0: 599 Internal Exception at /Users/ollisg/.perlbrew/libs/perl-5.26.0@test1/lib/perl5/Alien/Build/Plugin/Fetch/HTTPTiny.pm line 68.
324
325       (Older versions of Alien::Build produced a less verbose more confusing
326       version of this diagnostic).
327
328       TL;DR, instead of this:
329
330        share {
331          start_url => 'http://example.org/dist';
332          ...
333        };
334
335       do this:
336
337        share {
338          start_url => 'https://example.org/dist';
339        };
340
341       If the website is going to redirect to a secure URL anyway.
342
343       The "599 Internal Exception" indicates an "internal" exception from
344       HTTP::Tiny and is not a real HTTP status code or error.  This could
345       mean a number of different problems, but most frequently indicates that
346       a SSL request was made without the required modules (Net::SSLeay and
347       IO::Socket::SSL).  Normally the
348       Alien::Build::Plugin::Download::Negotiate and
349       Alien::Build::Plugin::Fetch::HTTPTiny will make sure that the
350       appropriate modules are added to your prerequisites for you if you
351       specify a "https" URL.  Some websites allow an initial request from
352       "http" but then redirect to "https".  If you can it is better to
353       specify "https", if you cannot, then you can instead use the "ssl"
354       property on either of those two plugins.
355
356   Network fetch is turned off
357       If you get an error like this:
358
359        Alien::Build> install type share requested or detected, but network fetch is turned off
360        Alien::Build> see see https://metacpan.org/pod/Alien::Build::Manual::FAQ#Network-fetch-is-turned-off
361
362       This is because your environment is setup not to install aliens that
363       require the network.  You can turn network fetch back on by setting
364       "ALIEN_INSTALL_NETWORK" to true, or by unsetting it.  This environment
365       variable is designed for environments that don't ever want to install
366       aliens that require downloading source packages over the internet.
367
368   I would really prefer you not download stuff off the internet
369       The idea of Alien is to download missing packages and build them
370       automatically to make installing easier.  Some people may not like
371       this, or may even have security requirements that they not download
372       random package over the internet (caveat, downloading random stuff off
373       of CPAN may not be any safer, so make sure you audit all of the open
374       source software that you use appropriately).  Another reason you may
375       not want to download from the internet is if you are packaging up an
376       alien for an operating system vendor, which will always want to use the
377       system version of a library.  In that situation you don't want
378       Alien::Build to go off and download something from the internet because
379       the probe failed for some reason.
380
381       This is easy to take care of, simply set "ALIEN_INSTALL_TYPE" to
382       "system" and a build from source code will never be attempted.  On
383       systems that do not provide system versions of the library or tool you
384       will get an error, allowing you to install the library, and retry the
385       alien install.  You can also set the environment variable on just some
386       aliens.
387
388        % export ALIEN_INSTALL_TYPE=system  # for everyone
389
390        % env ALIEN_INSTALL_TYPE=system cpanm -v Alien::libfoo
391
392   For testing I would like to test both system and share installs!
393       You can use the "ALIEN_INSTALL_TYPE" environment variable.  It will
394       force either a "share" or "system" install depending on how it is set.
395       For travis you can do something like this:
396
397        env:
398          matrix:
399            - ALIEN_INSTALL_TYPE=share
400            - ALIEN_INSTALL_TYPE=system
401
402   How do I use Alien::Build from Dist::Zilla?
403       For creating Alien::Base and Alien::Build based dist from Dist::Zilla
404       you can use the dzil plugin Dist::Zilla::Plugin::AlienBuild.
405
406   Cannot find either a share directory or a ConfigData module
407       If you see an error like this:
408
409        Cannot find either a share directory or a ConfigData module for Alien::libfoo.
410        (Alien::libfoo loaded from lib/Alien/libfoo.pm)
411        Please see https://metacpan.org/pod/distribution/Alien-Build/lib/Alien/Build/Manual/FAQ.pod#Cannot-find-either-a-share-directory-or-a-ConfigData-module
412        Can't locate Alien/libfoo/ConfigData.pm in @INC (you may need to install the Alien::libfoo::ConfigData module) (@INC contains: ...)
413
414       it means you are trying to use an Alien that hasn't been properly
415       installed.  An Alien::Base based Alien needs to have either the share
416       directory build during the install process or for older legacy
417       Alien::Base::ModuleBuild based Aliens, a ConfigData module generated by
418       Module::Build.
419
420       This usually happens if you try to use an Alien module from the lib
421       directory as part of the Alien's distribution.  You need to build the
422       alien and use "blib/lib" instead of "lib" or install the alien and use
423       the installed path.
424
425       It is also possible that your Alien installer is not set up correctly.
426       Make sure your "Makefile.PL" is using Alien::Build::MM correctly.
427
428   I have a question not listed here!
429       There are a number of forums available to people working on Alien,
430       Alien::Base and Alien::Build modules:
431
432       "#native" on irc.perl.org
433           This is intended for native interfaces in general so is a good
434           place for questions about Alien generally or Alien::Base and
435           Alien::Build specifically.
436
437       mailing list
438           The "perl5-alien" google group is intended for Alien issues
439           generally, including Alien::Base and Alien::Build.
440
441           <https://groups.google.com/forum/#!forum/perl5-alien>
442
443       Open a support ticket
444           If you have an issue with Alie::Build itself, then please open a
445           support ticket on the project's GitHub issue tracker.
446
447           <https://github.com/plicease/Alien-Build/issues>
448

SEE ALSO

450       Alien::Build, Alien::Build::MM, Alien::Build::Plugin, alienfile
451

AUTHOR

453       Author: Graham Ollis <plicease@cpan.org>
454
455       Contributors:
456
457       Diab Jerius (DJERIUS)
458
459       Roy Storey (KIWIROY)
460
461       Ilya Pavlov
462
463       David Mertens (run4flat)
464
465       Mark Nunberg (mordy, mnunberg)
466
467       Christian Walde (Mithaldu)
468
469       Brian Wightman (MidLifeXis)
470
471       Zaki Mughal (zmughal)
472
473       mohawk (mohawk2, ETJ)
474
475       Vikas N Kumar (vikasnkumar)
476
477       Flavio Poletti (polettix)
478
479       Salvador Fandiño (salva)
480
481       Gianni Ceccarelli (dakkar)
482
483       Pavel Shaydo (zwon, trinitum)
484
485       Kang-min Liu (劉康民, gugod)
486
487       Nicholas Shipp (nshp)
488
489       Juan Julián Merelo Guervós (JJ)
490
491       Joel Berger (JBERGER)
492
493       Petr Pisar (ppisar)
494
495       Lance Wicks (LANCEW)
496
497       Ahmad Fatoum (a3f, ATHREEF)
498
499       José Joaquín Atria (JJATRIA)
500
501       Duke Leto (LETO)
502
503       Shoichi Kaji (SKAJI)
504
505       Shawn Laffan (SLAFFAN)
506
507       Paul Evans (leonerd, PEVANS)
508
510       This software is copyright (c) 2011-2019 by Graham Ollis.
511
512       This is free software; you can redistribute it and/or modify it under
513       the same terms as the Perl 5 programming language system itself.
514
515
516
517perl v5.30.1                      2019-12-10      Alien::Build::Manual::FAQ(3)
Impressum