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 2.17
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   "cannot open shared object file" trying to load XS
318       The error looks something like this:
319
320        t/acme_alien_dontpanic2.t ....... 1/?
321        # Failed test 'xs'
322        # at t/acme_alien_dontpanic2.t line 13.
323        #   XSLoader failed
324        #     Can't load '/home/cip/.cpanm/work/1581635869.456/Acme-Alien-DontPanic2-2.0401/_alien/tmp/test-alien-lyiQNX/auto/Test/Alien/XS/ Mod0/Mod0.so' for module Test::Alien::XS::Mod0: libdontpanic.so.0: cannot open shared object file: No such file or directory at /opt /perl/5.30.1/lib/5.30.1/x86_64-linux/DynaLoader.pm line 193.
325        #  at /home/cip/perl5/lib/perl5/Test/Alien.pm line 414.
326        # Compilation failed in require at /home/cip/perl5/lib/perl5/Test/Alien.pm line 414.
327        # BEGIN failed--compilation aborted at /home/cip/perl5/lib/perl5/Test/Alien.pm line 414.
328        t/acme_alien_dontpanic2.t ....... Dubious, test returned 1 (wstat 256, 0x100)
329        Failed 1/6 subtests
330        t/acme_alien_dontpanic2__ffi.t .. ok
331
332       This error happened at test time for the Alien, but depending on your
333       environment and Alien it might happen later and the actual diagnostic
334       wording might vary.
335
336       This is usually because your XS or Alien tries to use dynamic libraries
337       instead of dynamic libraries.  Please consult the section about dynamic
338       vs. static libraries in Alien::Build::Manual::AlienAuthor.  The TL;DR
339       is that Alien::Build::Plugin::Gather::IsolateDynamic might help.  If
340       you are the Alien author and the package you are alienizing doesn't
341       have a static option you can use Alien::Role::Dino, but please note the
342       extended set of caveats!
343
344   599 Internal Exception errors downloading packages from the internet
345        Alien::Build::Plugin::Fetch::HTTPTiny> 599 Internal Exception fetching http://dist.libuv.org/dist/v1.15.0
346        Alien::Build::Plugin::Fetch::HTTPTiny> exception: IO::Socket::SSL 1.42 must be installed for https support
347        Alien::Build::Plugin::Fetch::HTTPTiny> exception: Net::SSLeay 1.49 must be installed for https support
348        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.
349        Alien::Build::Plugin::Fetch::HTTPTiny> Please see: https://metacpan.org/pod/Alien::Build::Manual::FAQ#599-Internal-Exception-errors-downloading-packages-from-the-internet
350        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.
351
352       (Older versions of Alien::Build produced a less verbose more confusing
353       version of this diagnostic).
354
355       TL;DR, instead of this:
356
357        share {
358          start_url => 'http://example.org/dist';
359          ...
360        };
361
362       do this:
363
364        share {
365          start_url => 'https://example.org/dist';
366        };
367
368       If the website is going to redirect to a secure URL anyway.
369
370       The "599 Internal Exception" indicates an "internal" exception from
371       HTTP::Tiny and is not a real HTTP status code or error.  This could
372       mean a number of different problems, but most frequently indicates that
373       a SSL request was made without the required modules (Net::SSLeay and
374       IO::Socket::SSL).  Normally the
375       Alien::Build::Plugin::Download::Negotiate and
376       Alien::Build::Plugin::Fetch::HTTPTiny will make sure that the
377       appropriate modules are added to your prerequisites for you if you
378       specify a "https" URL.  Some websites allow an initial request from
379       "http" but then redirect to "https".  If you can it is better to
380       specify "https", if you cannot, then you can instead use the "ssl"
381       property on either of those two plugins.
382
383   Network fetch is turned off
384       If you get an error like this:
385
386        Alien::Build> install type share requested or detected, but network fetch is turned off
387        Alien::Build> see see https://metacpan.org/pod/Alien::Build::Manual::FAQ#Network-fetch-is-turned-off
388
389       This is because your environment is setup not to install aliens that
390       require the network.  You can turn network fetch back on by setting
391       "ALIEN_INSTALL_NETWORK" to true, or by unsetting it.  This environment
392       variable is designed for environments that don't ever want to install
393       aliens that require downloading source packages over the internet.
394
395   I would really prefer you not download stuff off the internet
396       The idea of Alien is to download missing packages and build them
397       automatically to make installing easier.  Some people may not like
398       this, or may even have security requirements that they not download
399       random package over the internet (caveat, downloading random stuff off
400       of CPAN may not be any safer, so make sure you audit all of the open
401       source software that you use appropriately).  Another reason you may
402       not want to download from the internet is if you are packaging up an
403       alien for an operating system vendor, which will always want to use the
404       system version of a library.  In that situation you don't want
405       Alien::Build to go off and download something from the internet because
406       the probe failed for some reason.
407
408       This is easy to take care of, simply set "ALIEN_INSTALL_TYPE" to
409       "system" and a build from source code will never be attempted.  On
410       systems that do not provide system versions of the library or tool you
411       will get an error, allowing you to install the library, and retry the
412       alien install.  You can also set the environment variable on just some
413       aliens.
414
415        % export ALIEN_INSTALL_TYPE=system  # for everyone
416
417        % env ALIEN_INSTALL_TYPE=system cpanm -v Alien::libfoo
418
419   For testing I would like to test both system and share installs!
420       You can use the "ALIEN_INSTALL_TYPE" environment variable.  It will
421       force either a "share" or "system" install depending on how it is set.
422       For travis you can do something like this:
423
424        env:
425          matrix:
426            - ALIEN_INSTALL_TYPE=share
427            - ALIEN_INSTALL_TYPE=system
428
429   How do I use Alien::Build from Dist::Zilla?
430       For creating Alien::Base and Alien::Build based dist from Dist::Zilla
431       you can use the dzil plugin Dist::Zilla::Plugin::AlienBuild.
432
433   Cannot find either a share directory or a ConfigData module
434       If you see an error like this:
435
436        Cannot find either a share directory or a ConfigData module for Alien::libfoo.
437        (Alien::libfoo loaded from lib/Alien/libfoo.pm)
438        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
439        Can't locate Alien/libfoo/ConfigData.pm in @INC (you may need to install the Alien::libfoo::ConfigData module) (@INC contains: ...)
440
441       it means you are trying to use an Alien that hasn't been properly
442       installed.  An Alien::Base based Alien needs to have either the share
443       directory build during the install process or for older legacy
444       Alien::Base::ModuleBuild based Aliens, a ConfigData module generated by
445       Module::Build.
446
447       This usually happens if you try to use an Alien module from the lib
448       directory as part of the Alien's distribution.  You need to build the
449       alien and use "blib/lib" instead of "lib" or install the alien and use
450       the installed path.
451
452       It is also possible that your Alien installer is not set up correctly.
453       Make sure your "Makefile.PL" is using Alien::Build::MM correctly.
454
455   I have a question not listed here!
456       There are a number of forums available to people working on Alien,
457       Alien::Base and Alien::Build modules:
458
459       "#native" on irc.perl.org
460           This is intended for native interfaces in general so is a good
461           place for questions about Alien generally or Alien::Base and
462           Alien::Build specifically.
463
464       mailing list
465           The "perl5-alien" google group is intended for Alien issues
466           generally, including Alien::Base and Alien::Build.
467
468           <https://groups.google.com/forum/#!forum/perl5-alien>
469
470       Open a support ticket
471           If you have an issue with Alie::Build itself, then please open a
472           support ticket on the project's GitHub issue tracker.
473
474           <https://github.com/plicease/Alien-Build/issues>
475

SEE ALSO

477       Alien::Build, Alien::Build::MM, Alien::Build::Plugin, alienfile
478

AUTHOR

480       Author: Graham Ollis <plicease@cpan.org>
481
482       Contributors:
483
484       Diab Jerius (DJERIUS)
485
486       Roy Storey (KIWIROY)
487
488       Ilya Pavlov
489
490       David Mertens (run4flat)
491
492       Mark Nunberg (mordy, mnunberg)
493
494       Christian Walde (Mithaldu)
495
496       Brian Wightman (MidLifeXis)
497
498       Zaki Mughal (zmughal)
499
500       mohawk (mohawk2, ETJ)
501
502       Vikas N Kumar (vikasnkumar)
503
504       Flavio Poletti (polettix)
505
506       Salvador Fandiño (salva)
507
508       Gianni Ceccarelli (dakkar)
509
510       Pavel Shaydo (zwon, trinitum)
511
512       Kang-min Liu (劉康民, gugod)
513
514       Nicholas Shipp (nshp)
515
516       Juan Julián Merelo Guervós (JJ)
517
518       Joel Berger (JBERGER)
519
520       Petr Pisar (ppisar)
521
522       Lance Wicks (LANCEW)
523
524       Ahmad Fatoum (a3f, ATHREEF)
525
526       José Joaquín Atria (JJATRIA)
527
528       Duke Leto (LETO)
529
530       Shoichi Kaji (SKAJI)
531
532       Shawn Laffan (SLAFFAN)
533
534       Paul Evans (leonerd, PEVANS)
535
537       This software is copyright (c) 2011-2020 by Graham Ollis.
538
539       This is free software; you can redistribute it and/or modify it under
540       the same terms as the Perl 5 programming language system itself.
541
542
543
544perl v5.30.2                      2020-03-20      Alien::Build::Manual::FAQ(3)
Impressum