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.80
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 without configure script
61 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 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 Please see the Alien::Autotools documentation for specifics on how
76 it can be used in your alienfile.
77 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 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 autoconf-like
93 If you see an error like this:
95 Unknown option "--with-pic".
97 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 plugin 'Build::Autoconf' => (
105 with_pic => 0,
106 );
107 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 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 CMake
126 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 use alienfile;
133 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 vanilla Makefiles
149 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 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 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 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 plugin 'Build::Make' => 'gmake';
175 ...
176 How do I probe for a package that uses pkg-config?
178 Use the "pkg-config" plugin
179 (Alien::Build::Plugin::PkgConfig::Negotiate):
180 use alienfile;
182 plugin 'PkgConfig' => (
183 pkg_name => 'libfoo',
184 );
185 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 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 use alienfile;
197 plugin 'PkgConfig', pkg_name => 'foo', atleast_version => '1.2.3';
199 or
201 use alienfile;
203 plugin 'PkgConfig', pkg_name => foo, exact_version => '1.2.3';
205 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 use alienfile;
211 plugin 'PkgConfig' => ( pkg_name => [ 'foo', 'bar', 'baz' ] );
213 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 use Alien::libfoo;
219 $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 How to create an Alien module for packages that do not support pkg-config?
225 Packages that provide a configuration script
226 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 use alienfile;
232 probe [ 'foo-config --version' ];
234 share {
236 ...
237 build [
239 '%{make} PREFIX=%{.runtime.prefix}',
240 '%{make} install PREFIX=%{.runtime.prefix}',
241 ];
242 };
243 gather [
245 [ 'foo-config', '--version', \'%{.runtime.version}' ],
246 [ 'foo-config', '--cflags', \'%{.runtime.cflags}' ],
247 [ 'foo-config', '--libs', \'%{.runtime.libs}' ],
248 ];
249 Packages that require a compile test
251 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 use alienfile;
257 plugin 'Probe::CBuilder' => (
258 cflags => '-I/opt/libfoo/include',
259 libs => '-L/opt/libfoo/lib -lfoo',
260 );
261 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 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 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 use alienfile;
288 plugin 'Probe::CommandLine' => (
290 command => 'gzip',
291 );
292 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 How do I patch packages that need alterations?
298 If you have a diff file you can use patch:
299 use alienfile;
301 probe sub { 'share' }; # replace with appropriate probe
303 share {
305 ...
306 patch [ '%{patch} -p1 < %{.install.patch}/mypatch.diff' ];
307 build [ ... ] ;
308 }
309 ...
311 You can also patch using Perl if that is easier:
313 use alienfile;
315 probe sub { 'share' };
317 share {
319 ...
320 patch sub {
321 my($build) = @_;
322 # make changes to source prior to build
323 };
324 build [ ... ];
325 };
326 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 use alienfile;
337 plugin 'PkgConfig' => 'libfoo';
339 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 Sometimes you only need to do this on certain platforms. You can
350 adjust the logic based on $^O appropriately.
351 use alienfile;
353 plugin 'PkgConfig' => 'libfoo';
355 share {
357 ...
358 after 'gather' => sub {
359 my($build) = @_;
360 if($^O eq 'MSWin32') {
361 $build->runtime_prop->{libs} .= " -lpsapi";
362 }
363 };
364 };
365 "cannot open shared object file" trying to load XS
367 The error looks something like this:
368 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 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 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 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 (Older versions of Alien::Build produced a less verbose more confusing
402 version of this diagnostic).
403 TL;DR, instead of this:
405 share {
407 start_url => 'http://example.org/dist';
408 ...
409 };
410 do this:
412 share {
414 start_url => 'https://example.org/dist';
415 };
416 If the website is going to redirect to a secure URL anyway.
418 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 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 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 Network fetch is turned off
445 If you get an error like this:
446 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 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 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 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 % export ALIEN_INSTALL_TYPE=system # for everyone
477 % env ALIEN_INSTALL_TYPE=system cpanm -v Alien::libfoo
479 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 env:
486 matrix:
487 - ALIEN_INSTALL_TYPE=share
488 - ALIEN_INSTALL_TYPE=system
489 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 Cannot find either a share directory or a ConfigData module
495 If you see an error like this:
496 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 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 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 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 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 "#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 mailing list
526 The "perl5-alien" google group is intended for Alien issues
527 generally, including Alien::Base and Alien::Build.
528 <https://groups.google.com/forum/#!forum/perl5-alien>
530 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 <https://github.com/PerlAlien/Alien-Build/issues>
536
538 Alien::Build::Manual
539 Other Alien::Build manuals.
540
542 Author: Graham Ollis <plicease@cpan.org>
543 Contributors:
545 Diab Jerius (DJERIUS)
547 Roy Storey (KIWIROY)
549 Ilya Pavlov
551 David Mertens (run4flat)
553 Mark Nunberg (mordy, mnunberg)
555 Christian Walde (Mithaldu)
557 Brian Wightman (MidLifeXis)
559 Zaki Mughal (zmughal)
561 mohawk (mohawk2, ETJ)
563 Vikas N Kumar (vikasnkumar)
565 Flavio Poletti (polettix)
567 Salvador Fandiño (salva)
569 Gianni Ceccarelli (dakkar)
571 Pavel Shaydo (zwon, trinitum)
573 Kang-min Liu (劉康民, gugod)
575 Nicholas Shipp (nshp)
577 Juan Julián Merelo Guervós (JJ)
579 Joel Berger (JBERGER)
581 Petr Písař (ppisar)
583 Lance Wicks (LANCEW)
585 Ahmad Fatoum (a3f, ATHREEF)
587 José Joaquín Atria (JJATRIA)
589 Duke Leto (LETO)
591 Shoichi Kaji (SKAJI)
593 Shawn Laffan (SLAFFAN)
595 Paul Evans (leonerd, PEVANS)
597 Håkon Hægland (hakonhagland, HAKONH)
599 nick nauwelaerts (INPHOBIA)
601 Florian Weimer
603
605 This software is copyright (c) 2011-2022 by Graham Ollis.
606 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.
609perl v5.38.0 2023-07-20 Alien::Build::Manual::FAQ(3)