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.80
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 without configure script
61
62       A number of Open Source projects are using autotools, but do not
63       provide the "configure" script.  When alienizing these types of
64       packages you have a few choices:
65
66       build configure using autotools
67           The Alien Alien::Autotools is designed to provide autotools for
68           building such packages from source.  The advantage is that this is
69           how the upstream developers intend on having their package built.
70           The downside is that it is also adds more prereqs to your Alien.
71           The silver lining is that if you require this Alien in the "share"
72           block (as you should), then these prereqs will only be pulled in
73           during a share install when they are needed.
74
75           Please see the Alien::Autotools documentation for specifics on how
76           it can be used in your alienfile.
77
78       patch the package locally before build
79           You can use the "patch" in alienfile directive to patch the
80           alienized package locally before building.  This can sometimes be
81           challenging because Autotools uses timestamps in order to decide
82           what needs to be rebuilt, and patching can sometimes confuse it
83           into thinking more needs to be rebuilt than what actually does.
84
85       build configure and tarball
86           You can also build the configure script during development of your
87           alien, generate the tarball and provide it somewhere like GitHub
88           and use that as the source instead of the original source.  This
89           should usually be a last resort if the other two methods prove too
90           difficult.
91
92       autoconf-like
93
94       If you see an error like this:
95
96        Unknown option "--with-pic".
97
98       It is because the autoconf plugin uses the "--with-pic" option by
99       default, since it makes sense most of the time, and autoconf usually
100       ignores options that it does not recognize.  Some autoconf style build
101       systems fail when they see an option that they do not recognize.  You
102       can turn this behavior off for these packages:
103
104        plugin 'Build::Autoconf' => (
105          with_pic => 0,
106        );
107
108       Another thing about the autoconf plugin is that it uses "DESTDIR" to do
109       a double staged install.  If you see an error like "nothing was
110       installed into destdir", that means that your package does not support
111       "DESTDIR".  You should instead use the MSYS plugin and use a command
112       sequence to do the build like this:
113
114        share {
115          plugin 'Build::MSYS';
116          build [
117            # explicitly running configure with "sh" will make sure that
118            # it works on windows as well as UNIX.
119            'sh configure --prefix=%{.install.prefix} --disable-shared',
120            '%{make}',
121            '%{make} install',
122          ];
123        };
124
125       CMake
126
127       There is an alien Alien::cmake3 that provides "cmake" 3.x or better (It
128       is preferred to the older Alien::CMake).  Though it is recommended that
129       you use the "cmake" (Alien::Build::Plugin::Build::CMake) plugin instead
130       of using Alien::cmake3.
131
132        use alienfile;
133
134        share {
135          plugin 'Build::CMake';
136          build [
137            # this is the default build step, if you do not specify one.
138            [ '%{cmake}',
139                @{ meta->prop->{plugin_build_cmake}->{args} },
140                # ... put extra cmake args here ...
141                '.'
142            ],
143            '%{make}',
144            '%{make} install',
145          ];
146        };
147
148       vanilla Makefiles
149
150       Alien::Build provides a helper ("%{make}") for the "make" that is used
151       by Perl and ExtUtils::MakeMaker (EUMM).  Unfortunately the "make"
152       supported by Perl and EUMM on Windows ("nmake" and "dmake") are not
153       widely supported by most open source projects.  (Thankfully recent
154       perls and EUMM support GNU Make on windows now).
155
156       You can use the "make" plugin (Alien::Build::Plugin::Build::Make) to
157       tell the Alien::Build system which make the project that you are
158       alienizing requires.
159
160        plugin 'Build::Make' => 'umake';
161        # umake makes %{make} either GNU Make or BSD Make on Unix and GNU Make on Windows.
162        build {
163          build [
164            # You can use the Perl config compiler and cflags using the %{perl.config...} helper
165            [ '%{make}', 'CC=%{perl.config.cc}', 'CFLAGS=%{perl.config.cccdlflags} %{perl.config.optimize}' ],
166            [ '%{make}', 'install', 'PREFIX=%{.install.prefix}' ],
167          ],
168        };
169
170       Some open source projects require GNU Make, and you can specify that,
171       and Alien::gmake will be pulled in on platforms that do not already
172       have it.
173
174        plugin 'Build::Make' => 'gmake';
175        ...
176
177   How do I probe for a package that uses pkg-config?
178       Use the "pkg-config" plugin
179       (Alien::Build::Plugin::PkgConfig::Negotiate):
180
181        use alienfile;
182        plugin 'PkgConfig' => (
183          pkg_name => 'libfoo',
184        );
185
186       It will probe for a system version of the library.  It will also add
187       the appropriate "version" "cflags" and "libs" properties on either a
188       "system" or "share" install.
189
190   How do I specify a minimum or exact version requirement for packages that
191       use pkg-config?
192       The various pkg-config plugins all support atleast_version,
193       exact_version and maximum_version fields, which have the same meaning
194       as the "pkg-config" command line interface:
195
196        use alienfile;
197
198        plugin 'PkgConfig', pkg_name => 'foo', atleast_version => '1.2.3';
199
200       or
201
202        use alienfile;
203
204        plugin 'PkgConfig', pkg_name => foo, exact_version => '1.2.3';
205
206   How do I probe for a package that uses multiple .pc files?
207       Each of the "PkgConfig" plugins will take an array reference instead of
208       a string:
209
210        use alienfile;
211
212        plugin 'PkgConfig' => ( pkg_name => [ 'foo', 'bar', 'baz' ] );
213
214       The first "pkg_name" given will be used by default once your alien is
215       installed.  To get the configuration for "foo" and "bar" you can use
216       the Alien::Base alt method:
217
218        use Alien::libfoo;
219
220        $cflags = Alien::libfoo->cflags;               # compiler flags for 'foo'
221        $cflags = Alien::libfoo->alt('bar')->cflags ;  # compiler flags for 'bar'
222        $cflags = Alien::libfoo->alt('baz')->cflags ;  # compiler flags for 'baz'
223
224   How to create an Alien module for packages that do not support pkg-config?
225       Packages that provide a configuration script
226
227       Many packages provide a command that you can use to get the appropriate
228       version, compiler and linker flags.  For those packages you can just
229       use the commands in your alienfile.  Something like this:
230
231        use alienfile;
232
233        probe [ 'foo-config --version' ];
234
235        share {
236          ...
237
238          build [
239            '%{make} PREFIX=%{.runtime.prefix}',
240            '%{make} install PREFIX=%{.runtime.prefix}',
241          ];
242        };
243
244        gather [
245          [ 'foo-config', '--version', \'%{.runtime.version}' ],
246          [ 'foo-config', '--cflags',  \'%{.runtime.cflags}'  ],
247          [ 'foo-config', '--libs',    \'%{.runtime.libs}'    ],
248        ];
249
250       Packages that require a compile test
251
252       Some packages just expect you do know that "-lfoo" will work.  For
253       those you can use the "cbuilder" plugin
254       (Alien::Build::Plugin::Probe::CBuilder).
255
256        use alienfile;
257        plugin 'Probe::CBuilder' => (
258          cflags => '-I/opt/libfoo/include',
259          libs   => '-L/opt/libfoo/lib -lfoo',
260        );
261
262        share {
263          ...
264          gather sub {
265            my($build) = @_;
266            my $prefix = $build->runtime_prop->{prefix};
267            $build->runtime_prop->{cflags} = "-I$prefix/include ";
268            $build->runtime_prop->{libs}   = "-L$prefix/lib -lfoo ";
269          };
270        }
271
272       This plugin will build a small program with these flags and test that
273       it works.  (There are also options to provide a program that can make
274       simple tests to ensure the library works).  If the probe works, it will
275       set the compiler and linker flags.  (There are also options for
276       extracting the version from the test program).  If you do a share
277       install you will need to set the compiler and linker flags yourself in
278       the gather step, if you aren't using a build plugin that will do that
279       for you.
280
281   Can/Should I write a tool oriented Alien module?
282       Certainly.  The original intent was to provide libraries, but tools are
283       also quite doable using the Alien::Build toolset.  A good example of
284       how to do this is Alien::nasm.  You will want to use the
285       'Probe::CommandLine':
286
287        use alienfile;
288
289        plugin 'Probe::CommandLine' => (
290          command => 'gzip',
291        );
292
293   How do I test my package once it is built (before it is installed)?
294       Use Test::Alien.  It has extensive documentation, and integrates nicely
295       with Alien::Base.
296
297   How do I patch packages that need alterations?
298       If you have a diff file you can use patch:
299
300        use alienfile;
301
302        probe sub { 'share' }; # replace with appropriate probe
303
304        share {
305          ...
306          patch [ '%{patch} -p1 < %{.install.patch}/mypatch.diff' ];
307          build [ ... ] ;
308        }
309
310        ...
311
312       You can also patch using Perl if that is easier:
313
314        use alienfile;
315
316        probe sub { 'share' };
317
318        share {
319          ...
320          patch sub {
321            my($build) = @_;
322            # make changes to source prior to build
323          };
324          build [ ... ];
325        };
326
327   The flags that a plugin produces are wrong!
328       Sometimes, the compiler or linker flags that the PkgConfig plugin comes
329       up with are not quite right.  (Frequently this is actually because a
330       package maintainer is providing a broken ".pc" file).  (Other plugins
331       may also have problems).  You could replace the plugin's "gather" step
332       but a better way is to provide a subroutine callback to be called after
333       the gather stage is complete.  You can do this with the alienfile
334       "after" directive:
335
336        use alienfile;
337
338        plugin 'PkgConfig' => 'libfoo';
339
340        share {
341          ...
342          after 'gather' => sub {
343            my($build) = @_;
344            $build->runtime_prop->{libs}        .= " -lbar";        # libfoo also requires libbar
345            $build->runtime_prop->{libs_static} .= " -lbar -lbaz";  # libfoo also requires libbaz under static linkage
346          };
347        };
348
349       Sometimes you only need to do this on certain platforms.  You can
350       adjust the logic based on $^O appropriately.
351
352        use alienfile;
353
354        plugin 'PkgConfig' => 'libfoo';
355
356        share {
357          ...
358          after 'gather' => sub {
359            my($build) = @_;
360            if($^O eq 'MSWin32') {
361              $build->runtime_prop->{libs} .= " -lpsapi";
362            }
363          };
364        };
365
366   "cannot open shared object file" trying to load XS
367       The error looks something like this:
368
369        t/acme_alien_dontpanic2.t ....... 1/?
370        # Failed test 'xs'
371        # at t/acme_alien_dontpanic2.t line 13.
372        #   XSLoader failed
373        #     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.
374        #  at /home/cip/perl5/lib/perl5/Test/Alien.pm line 414.
375        # Compilation failed in require at /home/cip/perl5/lib/perl5/Test/Alien.pm line 414.
376        # BEGIN failed--compilation aborted at /home/cip/perl5/lib/perl5/Test/Alien.pm line 414.
377        t/acme_alien_dontpanic2.t ....... Dubious, test returned 1 (wstat 256, 0x100)
378        Failed 1/6 subtests
379        t/acme_alien_dontpanic2__ffi.t .. ok
380
381       This error happened at test time for the Alien, but depending on your
382       environment and Alien it might happen later and the actual diagnostic
383       wording might vary.
384
385       This is usually because your XS or Alien tries to use dynamic libraries
386       instead of static ones.  Please consult the section about dynamic vs.
387       static libraries in Alien::Build::Manual::AlienAuthor.  The TL;DR is
388       that Alien::Build::Plugin::Gather::IsolateDynamic might help.  If you
389       are the Alien author and the package you are alienizing doesn't have a
390       static option you can use Alien::Role::Dino, but please note the
391       extended set of caveats!
392
393   599 Internal Exception errors downloading packages from the internet
394        Alien::Build::Plugin::Fetch::HTTPTiny> 599 Internal Exception fetching http://dist.libuv.org/dist/v1.15.0
395        Alien::Build::Plugin::Fetch::HTTPTiny> exception: IO::Socket::SSL 1.42 must be installed for https support
396        Alien::Build::Plugin::Fetch::HTTPTiny> exception: Net::SSLeay 1.49 must be installed for https support
397        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.
398        Alien::Build::Plugin::Fetch::HTTPTiny> Please see: https://metacpan.org/pod/Alien::Build::Manual::FAQ#599-Internal-Exception-errors-downloading-packages-from-the-internet
399        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.
400
401       (Older versions of Alien::Build produced a less verbose more confusing
402       version of this diagnostic).
403
404       TL;DR, instead of this:
405
406        share {
407          start_url => 'http://example.org/dist';
408          ...
409        };
410
411       do this:
412
413        share {
414          start_url => 'https://example.org/dist';
415        };
416
417       If the website is going to redirect to a secure URL anyway.
418
419       The "599 Internal Exception" indicates an "internal" exception from
420       HTTP::Tiny and is not a real HTTP status code or error.  This could
421       mean a number of different problems, but most frequently indicates that
422       a SSL request was made without the required modules (Net::SSLeay and
423       IO::Socket::SSL).  Normally the
424       Alien::Build::Plugin::Download::Negotiate and
425       Alien::Build::Plugin::Fetch::HTTPTiny will make sure that the
426       appropriate modules are added to your prerequisites for you if you
427       specify a "https" URL.  Some websites allow an initial request from
428       "http" but then redirect to "https".  If you can it is better to
429       specify "https", if you cannot, then you can instead use the "ssl"
430       property on either of those two plugins.
431
432   Does not detect system package even though it is installed
433       This could just be because the alien requires a more recent package
434       that what is provided by your operating system.
435
436       It could also be because you do not have the development package
437       installed.  Many Linux vendors in particular separate packages into
438       runtime and development pages.  On RPM based systems these development
439       packages usually have "-devel" suffix (example runtime: "libffi" and
440       development: "libffi-devel").  On Debian based systems these
441       development packages usually have a "-dev" suffix (example runtime:
442       "libffi" and development: "libffi-dev").
443
444   Network fetch is turned off
445       If you get an error like this:
446
447        Alien::Build> install type share requested or detected, but network fetch is turned off
448        Alien::Build> see see https://metacpan.org/pod/Alien::Build::Manual::FAQ#Network-fetch-is-turned-off
449
450       This is because your environment is setup not to install aliens that
451       require the network.  You can turn network fetch back on by setting
452       "ALIEN_INSTALL_NETWORK" to true, or by unsetting it.  This environment
453       variable is designed for environments that don't ever want to install
454       aliens that require downloading source packages over the internet.
455
456   I would really prefer you not download stuff off the internet
457       The idea of Alien is to download missing packages and build them
458       automatically to make installing easier.  Some people may not like
459       this, or may even have security requirements that they not download
460       random package over the internet (caveat, downloading random stuff off
461       of CPAN may not be any safer, so make sure you audit all of the open
462       source software that you use appropriately).  Another reason you may
463       not want to download from the internet is if you are packaging up an
464       alien for an operating system vendor, which will always want to use the
465       system version of a library.  In that situation you don't want
466       Alien::Build to go off and download something from the internet because
467       the probe failed for some reason.
468
469       This is easy to take care of, simply set "ALIEN_INSTALL_TYPE" to
470       "system" and a build from source code will never be attempted.  On
471       systems that do not provide system versions of the library or tool you
472       will get an error, allowing you to install the library, and retry the
473       alien install.  You can also set the environment variable on just some
474       aliens.
475
476        % export ALIEN_INSTALL_TYPE=system  # for everyone
477
478        % env ALIEN_INSTALL_TYPE=system cpanm -v Alien::libfoo
479
480   For testing I would like to test both system and share installs!
481       You can use the "ALIEN_INSTALL_TYPE" environment variable.  It will
482       force either a "share" or "system" install depending on how it is set.
483       For travis you can do something like this:
484
485        env:
486          matrix:
487            - ALIEN_INSTALL_TYPE=share
488            - ALIEN_INSTALL_TYPE=system
489
490   How do I use Alien::Build from Dist::Zilla?
491       For creating Alien::Base and Alien::Build based dist from Dist::Zilla
492       you can use the dzil plugin Dist::Zilla::Plugin::AlienBuild.
493
494   Cannot find either a share directory or a ConfigData module
495       If you see an error like this:
496
497        Cannot find either a share directory or a ConfigData module for Alien::libfoo.
498        (Alien::libfoo loaded from lib/Alien/libfoo.pm)
499        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
500        Can't locate Alien/libfoo/ConfigData.pm in @INC (you may need to install the Alien::libfoo::ConfigData module) (@INC contains: ...)
501
502       it means you are trying to use an Alien that hasn't been properly
503       installed.  An Alien::Base based Alien needs to have either the share
504       directory build during the install process or for older legacy
505       Alien::Base::ModuleBuild based Aliens, a ConfigData module generated by
506       Module::Build.
507
508       This usually happens if you try to use an Alien module from the lib
509       directory as part of the Alien's distribution.  You need to build the
510       alien and use "blib/lib" instead of "lib" or install the alien and use
511       the installed path.
512
513       It is also possible that your Alien installer is not set up correctly.
514       Make sure your "Makefile.PL" is using Alien::Build::MM correctly.
515
516   I have a question not listed here!
517       There are a number of forums available to people working on Alien,
518       Alien::Base and Alien::Build modules:
519
520       "#native" on irc.perl.org
521           This is intended for native interfaces in general so is a good
522           place for questions about Alien generally or Alien::Base and
523           Alien::Build specifically.
524
525       mailing list
526           The "perl5-alien" google group is intended for Alien issues
527           generally, including Alien::Base and Alien::Build.
528
529           <https://groups.google.com/forum/#!forum/perl5-alien>
530
531       Open a support ticket
532           If you have an issue with Alien::Build itself, then please open a
533           support ticket on the project's GitHub issue tracker.
534
535           <https://github.com/PerlAlien/Alien-Build/issues>
536

SEE ALSO

538       Alien::Build::Manual
539           Other Alien::Build manuals.
540

AUTHOR

542       Author: Graham Ollis <plicease@cpan.org>
543
544       Contributors:
545
546       Diab Jerius (DJERIUS)
547
548       Roy Storey (KIWIROY)
549
550       Ilya Pavlov
551
552       David Mertens (run4flat)
553
554       Mark Nunberg (mordy, mnunberg)
555
556       Christian Walde (Mithaldu)
557
558       Brian Wightman (MidLifeXis)
559
560       Zaki Mughal (zmughal)
561
562       mohawk (mohawk2, ETJ)
563
564       Vikas N Kumar (vikasnkumar)
565
566       Flavio Poletti (polettix)
567
568       Salvador Fandiño (salva)
569
570       Gianni Ceccarelli (dakkar)
571
572       Pavel Shaydo (zwon, trinitum)
573
574       Kang-min Liu (劉康民, gugod)
575
576       Nicholas Shipp (nshp)
577
578       Juan Julián Merelo Guervós (JJ)
579
580       Joel Berger (JBERGER)
581
582       Petr Písař (ppisar)
583
584       Lance Wicks (LANCEW)
585
586       Ahmad Fatoum (a3f, ATHREEF)
587
588       José Joaquín Atria (JJATRIA)
589
590       Duke Leto (LETO)
591
592       Shoichi Kaji (SKAJI)
593
594       Shawn Laffan (SLAFFAN)
595
596       Paul Evans (leonerd, PEVANS)
597
598       Håkon Hægland (hakonhagland, HAKONH)
599
600       nick nauwelaerts (INPHOBIA)
601
602       Florian Weimer
603
605       This software is copyright (c) 2011-2022 by Graham Ollis.
606
607       This is free software; you can redistribute it and/or modify it under
608       the same terms as the Perl 5 programming language system itself.
609
610
611
612perl v5.38.0                      2023-07-20      Alien::Build::Manual::FAQ(3)
Impressum