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.38
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 know 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 to create an Alien module for a packages that do not support pkg-
175 config?
176 Packages that provide a configuration script
177 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 use alienfile;
183 probe [ 'foo-config --version' ];
185 share {
187 ...
188 build [
190 '%{make} PREFIX=%{.runtime.prefix}',
191 '%{amek} install PREFIX=%{.runtime.prefix}',
192 ];
193 };
194 gather [
196 [ 'foo-config', '--version', \'%{.runtime.version}' ],
197 [ 'foo-config', '--cflags', \'%{.runtime.cflags}' ],
198 [ 'foo-config', '--libs', \'%{.runtime.libs}' ],
199 ];
200 Packages that require a compile test
202 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 use alienfile;
208 plugin 'Probe::CBuilder' => (
209 cflags => '-I/opt/libfoo/include',
210 libs => '-L/opt/libfoo/lib -lfoo',
211 );
212 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 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 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 use alienfile;
239 plugin 'Probe::CommandLine' => (
241 command => 'gzip',
242 );
243 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 How do I patch packages that need alterations?
249 If you have a diff file you can use patch:
250 use alienfile;
252 probe sub { 'share' }; # replace with appropriate probe
254 share {
256 ...
257 patch [ '%{patch} -p1 < %{.install.patch}/mypatch.diff' ];
258 build [ ... ] ;
259 }
260 ...
262 You can also patch using Perl if that is easier:
264 use alienfile;
266 probe sub { 'share' };
268 share {
270 ...
271 patch sub {
272 my($build) = @_;
273 # make changes to source prior to build
274 };
275 build [ ... ];
276 };
277 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 use alienfile;
288 plugin 'PlgConfig' => 'libfoo';
290 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 Sometimes you only need to do this on certain platforms. You can
301 adjust the logic based on $^O appropriately.
302 use alienfile;
304 plugin 'PlgConfig' => 'libfoo';
306 share {
308 ...
309 after 'gather' => sub {
310 my($build) = @_;
311 if($^O eq 'MSWin32') {
312 $build->runtime_prop->{libs} .= " -lpsapi";
313 }
314 };
315 };
316 "cannot open shared object file" trying to load XS
318 The error looks something like this:
319 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 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 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 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 (Older versions of Alien::Build produced a less verbose more confusing
353 version of this diagnostic).
354 TL;DR, instead of this:
356 share {
358 start_url => 'http://example.org/dist';
359 ...
360 };
361 do this:
363 share {
365 start_url => 'https://example.org/dist';
366 };
367 If the website is going to redirect to a secure URL anyway.
369 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 Network fetch is turned off
384 If you get an error like this:
385 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 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 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 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 % export ALIEN_INSTALL_TYPE=system # for everyone
416 % env ALIEN_INSTALL_TYPE=system cpanm -v Alien::libfoo
418 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 env:
425 matrix:
426 - ALIEN_INSTALL_TYPE=share
427 - ALIEN_INSTALL_TYPE=system
428 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 Cannot find either a share directory or a ConfigData module
434 If you see an error like this:
435 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 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 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 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 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 "#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 mailing list
465 The "perl5-alien" google group is intended for Alien issues
466 generally, including Alien::Base and Alien::Build.
467 <https://groups.google.com/forum/#!forum/perl5-alien>
469 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 <https://github.com/plicease/Alien-Build/issues>
475
477 Alien::Build, Alien::Build::MM, Alien::Build::Plugin, alienfile
478
480 Author: Graham Ollis <plicease@cpan.org>
481 Contributors:
483 Diab Jerius (DJERIUS)
485 Roy Storey (KIWIROY)
487 Ilya Pavlov
489 David Mertens (run4flat)
491 Mark Nunberg (mordy, mnunberg)
493 Christian Walde (Mithaldu)
495 Brian Wightman (MidLifeXis)
497 Zaki Mughal (zmughal)
499 mohawk (mohawk2, ETJ)
501 Vikas N Kumar (vikasnkumar)
503 Flavio Poletti (polettix)
505 Salvador Fandiño (salva)
507 Gianni Ceccarelli (dakkar)
509 Pavel Shaydo (zwon, trinitum)
511 Kang-min Liu (劉康民, gugod)
513 Nicholas Shipp (nshp)
515 Juan Julián Merelo Guervós (JJ)
517 Joel Berger (JBERGER)
519 Petr Pisar (ppisar)
521 Lance Wicks (LANCEW)
523 Ahmad Fatoum (a3f, ATHREEF)
525 José Joaquín Atria (JJATRIA)
527 Duke Leto (LETO)
529 Shoichi Kaji (SKAJI)
531 Shawn Laffan (SLAFFAN)
533 Paul Evans (leonerd, PEVANS)
535 Håkon Hægland (hakonhagland, HAKONH)
537
539 This software is copyright (c) 2011-2020 by Graham Ollis.
540 This is free software; you can redistribute it and/or modify it under
542 the same terms as the Perl 5 programming language system itself.
543perl v5.32.0 2021-01-12 Alien::Build::Manual::FAQ(3)