1Alien::Build::Manual::FUAsQe(r3)Contributed Perl DocumenAtlaiteino:n:Build::Manual::FAQ(3)
2
6 Alien::Build::Manual::FAQ - Frequently Asked Questions about
7 Alien::Build
8
10 version 2.45
11
13 perldoc Alien::Build::Manual::FAQ
14
16 This document serves to answer the most frequently asked questions made
17 by developers creating Alien modules using Alien::Build.
18
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 How do I build a package that uses build system
30 autoconf
31 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 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 If you need to provide custom flags to configure, you can do that too:
48 share {
50 plugin 'Build::Autoconf';
51 build [
52 '%{configure} --disable-shared --enable-foo',
53 '%{make}',
54 '%{make} install',
55 ];
56 };
57 If your package requires GNU Make, use "%{gmake}" instead of "%{make}".
59 autoconf-like
61 If you see an error like this:
63 Unknown option "--with-pic".
65 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 plugin 'Build::Autoconf' => (
73 with_pic => 0,
74 );
75 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 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 CMake
94 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 use alienfile;
101 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 vanilla Makefiles
117 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 You can use the "make" plugin (Alien::Build::Plugin::Build::Make) to
125 tell the Alien::Build system which make the project that you are
126 alienizing requires.
127 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 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 plugin 'Build::Make' => 'gmake';
143 ...
144 How do I probe for a package that uses pkg-config?
146 Use the "pkg-config" plugin
147 (Alien::Build::Plugin::PkgConfig::Negotiate):
148 use alienfile;
150 plugin 'PkgConfig' => (
151 pkg_name => 'libfoo',
152 );
153 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 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 use alienfile;
165 plugin 'PkgConfig', pkg_name => 'foo', atleast_version => '1.2.3';
167 or
169 use alienfile;
171 plugin 'PkgConfig', pkg_name => foo, exact_version => '1.2.3';
173 How do I probe for a package that uses multiple .pc files?
175 Each of the "PkgConfig" plugins will take an array reference instead of
176 a string:
177 use alienfile;
179 plugin 'PkgConfig' => ( pkg_name => [ 'foo', 'bar', 'baz' ] );
181 The first "pkg_name" given will be used by default once your alien is
183 installed. To get the configuration for "foo" and "bar" you can use
184 the Alien::Base alt method:
185 use Alien::libfoo;
187 $cflags = Alien::libfoo->cflags; # compiler flags for 'foo'
189 $cflags = Alien::libfoo->alt('bar')->cflags ; # compiler flags for 'bar'
190 $cflags = Alien::libfoo->alt('baz')->cflags ; # compiler flags for 'baz'
191 How to create an Alien module for packages that do not support pkg-config?
193 Packages that provide a configuration script
194 Many packages provide a command that you can use to get the appropriate
196 version, compiler and linker flags. For those packages you can just
197 use the commands in your alienfile. Something like this:
198 use alienfile;
200 probe [ 'foo-config --version' ];
202 share {
204 ...
205 build [
207 '%{make} PREFIX=%{.runtime.prefix}',
208 '%{make} install PREFIX=%{.runtime.prefix}',
209 ];
210 };
211 gather [
213 [ 'foo-config', '--version', \'%{.runtime.version}' ],
214 [ 'foo-config', '--cflags', \'%{.runtime.cflags}' ],
215 [ 'foo-config', '--libs', \'%{.runtime.libs}' ],
216 ];
217 Packages that require a compile test
219 Some packages just expect you do know that "-lfoo" will work. For
221 those you can use the "cbuilder" plugin
222 (Alien::Build::Plugin::Probe::CBuilder).
223 use alienfile;
225 plugin 'Probe::CBuilder' => (
226 cflags => '-I/opt/libfoo/include',
227 libs => '-L/opt/libfoo/lib -lfoo',
228 );
229 share {
231 ...
232 gather sub {
233 my($build) = @_;
234 my $prefix = $build->runtime_prop->{prefix};
235 $build->runtime_prop->{cflags} = "-I$prefix/include ";
236 $build->runtime_prop->{libs} = "-L$prefix/lib -lfoo ";
237 };
238 }
239 This plugin will build a small program with these flags and test that
241 it works. (There are also options to provide a program that can make
242 simple tests to ensure the library works). If the probe works, it will
243 set the compiler and linker flags. (There are also options for
244 extracting the version from the test program). If you do a share
245 install you will need to set the compiler and linker flags yourself in
246 the gather step, if you aren't using a build plugin that will do that
247 for you.
248 Can/Should I write a tool oriented Alien module?
250 Certainly. The original intent was to provide libraries, but tools are
251 also quite doable using the Alien::Build toolset. A good example of
252 how to do this is Alien::nasm. You will want to use the
253 'Probe::CommandLine':
254 use alienfile;
256 plugin 'Probe::CommandLine' => (
258 command => 'gzip',
259 );
260 How do I test my package once it is built (before it is installed)?
262 Use Test::Alien. It has extensive documentation, and integrates nicely
263 with Alien::Base.
264 How do I patch packages that need alterations?
266 If you have a diff file you can use patch:
267 use alienfile;
269 probe sub { 'share' }; # replace with appropriate probe
271 share {
273 ...
274 patch [ '%{patch} -p1 < %{.install.patch}/mypatch.diff' ];
275 build [ ... ] ;
276 }
277 ...
279 You can also patch using Perl if that is easier:
281 use alienfile;
283 probe sub { 'share' };
285 share {
287 ...
288 patch sub {
289 my($build) = @_;
290 # make changes to source prior to build
291 };
292 build [ ... ];
293 };
294 The flags that a plugin produces are wrong!
296 Sometimes, the compiler or linker flags that the PkgConfig plugin comes
297 up with are not quite right. (Frequently this is actually because a
298 package maintainer is providing a broken ".pc" file). (Other plugins
299 may also have problems). You could replace the plugin's "gather" step
300 but a better way is to provide a subroutine callback to be called after
301 the gather stage is complete. You can do this with the alienfile
302 "after" directive:
303 use alienfile;
305 plugin 'PkgConfig' => 'libfoo';
307 share {
309 ...
310 after 'gather' => sub {
311 my($build) = @_;
312 $build->runtime_prop->{libs} .= " -lbar"; # libfoo also requires libbar
313 $build->runtime_prop->{libs_static} .= " -lbar -lbaz"; # libfoo also requires libbaz under static linkage
314 };
315 };
316 Sometimes you only need to do this on certain platforms. You can
318 adjust the logic based on $^O appropriately.
319 use alienfile;
321 plugin 'PkgConfig' => 'libfoo';
323 share {
325 ...
326 after 'gather' => sub {
327 my($build) = @_;
328 if($^O eq 'MSWin32') {
329 $build->runtime_prop->{libs} .= " -lpsapi";
330 }
331 };
332 };
333 "cannot open shared object file" trying to load XS
335 The error looks something like this:
336 t/acme_alien_dontpanic2.t ....... 1/?
338 # Failed test 'xs'
339 # at t/acme_alien_dontpanic2.t line 13.
340 # XSLoader failed
341 # 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.
342 # at /home/cip/perl5/lib/perl5/Test/Alien.pm line 414.
343 # Compilation failed in require at /home/cip/perl5/lib/perl5/Test/Alien.pm line 414.
344 # BEGIN failed--compilation aborted at /home/cip/perl5/lib/perl5/Test/Alien.pm line 414.
345 t/acme_alien_dontpanic2.t ....... Dubious, test returned 1 (wstat 256, 0x100)
346 Failed 1/6 subtests
347 t/acme_alien_dontpanic2__ffi.t .. ok
348 This error happened at test time for the Alien, but depending on your
350 environment and Alien it might happen later and the actual diagnostic
351 wording might vary.
352 This is usually because your XS or Alien tries to use dynamic libraries
354 instead of static ones. Please consult the section about dynamic vs.
355 static libraries in Alien::Build::Manual::AlienAuthor. The TL;DR is
356 that Alien::Build::Plugin::Gather::IsolateDynamic might help. If you
357 are the Alien author and the package you are alienizing doesn't have a
358 static option you can use Alien::Role::Dino, but please note the
359 extended set of caveats!
360 599 Internal Exception errors downloading packages from the internet
362 Alien::Build::Plugin::Fetch::HTTPTiny> 599 Internal Exception fetching http://dist.libuv.org/dist/v1.15.0
363 Alien::Build::Plugin::Fetch::HTTPTiny> exception: IO::Socket::SSL 1.42 must be installed for https support
364 Alien::Build::Plugin::Fetch::HTTPTiny> exception: Net::SSLeay 1.49 must be installed for https support
365 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.
366 Alien::Build::Plugin::Fetch::HTTPTiny> Please see: https://metacpan.org/pod/Alien::Build::Manual::FAQ#599-Internal-Exception-errors-downloading-packages-from-the-internet
367 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.
368 (Older versions of Alien::Build produced a less verbose more confusing
370 version of this diagnostic).
371 TL;DR, instead of this:
373 share {
375 start_url => 'http://example.org/dist';
376 ...
377 };
378 do this:
380 share {
382 start_url => 'https://example.org/dist';
383 };
384 If the website is going to redirect to a secure URL anyway.
386 The "599 Internal Exception" indicates an "internal" exception from
388 HTTP::Tiny and is not a real HTTP status code or error. This could
389 mean a number of different problems, but most frequently indicates that
390 a SSL request was made without the required modules (Net::SSLeay and
391 IO::Socket::SSL). Normally the
392 Alien::Build::Plugin::Download::Negotiate and
393 Alien::Build::Plugin::Fetch::HTTPTiny will make sure that the
394 appropriate modules are added to your prerequisites for you if you
395 specify a "https" URL. Some websites allow an initial request from
396 "http" but then redirect to "https". If you can it is better to
397 specify "https", if you cannot, then you can instead use the "ssl"
398 property on either of those two plugins.
399 Network fetch is turned off
401 If you get an error like this:
402 Alien::Build> install type share requested or detected, but network fetch is turned off
404 Alien::Build> see see https://metacpan.org/pod/Alien::Build::Manual::FAQ#Network-fetch-is-turned-off
405 This is because your environment is setup not to install aliens that
407 require the network. You can turn network fetch back on by setting
408 "ALIEN_INSTALL_NETWORK" to true, or by unsetting it. This environment
409 variable is designed for environments that don't ever want to install
410 aliens that require downloading source packages over the internet.
411 I would really prefer you not download stuff off the internet
413 The idea of Alien is to download missing packages and build them
414 automatically to make installing easier. Some people may not like
415 this, or may even have security requirements that they not download
416 random package over the internet (caveat, downloading random stuff off
417 of CPAN may not be any safer, so make sure you audit all of the open
418 source software that you use appropriately). Another reason you may
419 not want to download from the internet is if you are packaging up an
420 alien for an operating system vendor, which will always want to use the
421 system version of a library. In that situation you don't want
422 Alien::Build to go off and download something from the internet because
423 the probe failed for some reason.
424 This is easy to take care of, simply set "ALIEN_INSTALL_TYPE" to
426 "system" and a build from source code will never be attempted. On
427 systems that do not provide system versions of the library or tool you
428 will get an error, allowing you to install the library, and retry the
429 alien install. You can also set the environment variable on just some
430 aliens.
431 % export ALIEN_INSTALL_TYPE=system # for everyone
433 % env ALIEN_INSTALL_TYPE=system cpanm -v Alien::libfoo
435 For testing I would like to test both system and share installs!
437 You can use the "ALIEN_INSTALL_TYPE" environment variable. It will
438 force either a "share" or "system" install depending on how it is set.
439 For travis you can do something like this:
440 env:
442 matrix:
443 - ALIEN_INSTALL_TYPE=share
444 - ALIEN_INSTALL_TYPE=system
445 How do I use Alien::Build from Dist::Zilla?
447 For creating Alien::Base and Alien::Build based dist from Dist::Zilla
448 you can use the dzil plugin Dist::Zilla::Plugin::AlienBuild.
449 Cannot find either a share directory or a ConfigData module
451 If you see an error like this:
452 Cannot find either a share directory or a ConfigData module for Alien::libfoo.
454 (Alien::libfoo loaded from lib/Alien/libfoo.pm)
455 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
456 Can't locate Alien/libfoo/ConfigData.pm in @INC (you may need to install the Alien::libfoo::ConfigData module) (@INC contains: ...)
457 it means you are trying to use an Alien that hasn't been properly
459 installed. An Alien::Base based Alien needs to have either the share
460 directory build during the install process or for older legacy
461 Alien::Base::ModuleBuild based Aliens, a ConfigData module generated by
462 Module::Build.
463 This usually happens if you try to use an Alien module from the lib
465 directory as part of the Alien's distribution. You need to build the
466 alien and use "blib/lib" instead of "lib" or install the alien and use
467 the installed path.
468 It is also possible that your Alien installer is not set up correctly.
470 Make sure your "Makefile.PL" is using Alien::Build::MM correctly.
471 I have a question not listed here!
473 There are a number of forums available to people working on Alien,
474 Alien::Base and Alien::Build modules:
475 "#native" on irc.perl.org
477 This is intended for native interfaces in general so is a good
478 place for questions about Alien generally or Alien::Base and
479 Alien::Build specifically.
480 mailing list
482 The "perl5-alien" google group is intended for Alien issues
483 generally, including Alien::Base and Alien::Build.
484 <https://groups.google.com/forum/#!forum/perl5-alien>
486 Open a support ticket
488 If you have an issue with Alien::Build itself, then please open a
489 support ticket on the project's GitHub issue tracker.
490 <https://github.com/PerlAlien/Alien-Build/issues>
492
494 Alien::Build, Alien::Build::MM, Alien::Build::Plugin, alienfile
495
497 Author: Graham Ollis <plicease@cpan.org>
498 Contributors:
500 Diab Jerius (DJERIUS)
502 Roy Storey (KIWIROY)
504 Ilya Pavlov
506 David Mertens (run4flat)
508 Mark Nunberg (mordy, mnunberg)
510 Christian Walde (Mithaldu)
512 Brian Wightman (MidLifeXis)
514 Zaki Mughal (zmughal)
516 mohawk (mohawk2, ETJ)
518 Vikas N Kumar (vikasnkumar)
520 Flavio Poletti (polettix)
522 Salvador Fandiño (salva)
524 Gianni Ceccarelli (dakkar)
526 Pavel Shaydo (zwon, trinitum)
528 Kang-min Liu (劉康民, gugod)
530 Nicholas Shipp (nshp)
532 Juan Julián Merelo Guervós (JJ)
534 Joel Berger (JBERGER)
536 Petr Písař (ppisar)
538 Lance Wicks (LANCEW)
540 Ahmad Fatoum (a3f, ATHREEF)
542 José Joaquín Atria (JJATRIA)
544 Duke Leto (LETO)
546 Shoichi Kaji (SKAJI)
548 Shawn Laffan (SLAFFAN)
550 Paul Evans (leonerd, PEVANS)
552 Håkon Hægland (hakonhagland, HAKONH)
554 nick nauwelaerts (INPHOBIA)
556
558 This software is copyright (c) 2011-2020 by Graham Ollis.
559 This is free software; you can redistribute it and/or modify it under
561 the same terms as the Perl 5 programming language system itself.
562perl v5.34.0 2021-10-29 Alien::Build::Manual::FAQ(3)