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 1.55
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 599 Internal Exception errors downloading packages from the internet
318 Alien::Build::Plugin::Fetch::HTTPTiny> 599 Internal Exception fetching http://dist.libuv.org/dist/v1.15.0
319 Alien::Build::Plugin::Fetch::HTTPTiny> exception: IO::Socket::SSL 1.42 must be installed for https support
320 Alien::Build::Plugin::Fetch::HTTPTiny> exception: Net::SSLeay 1.49 must be installed for https support
321 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.
322 Alien::Build::Plugin::Fetch::HTTPTiny> Please see: https://metacpan.org/pod/Alien::Build::Manual::FAQ#599-Internal-Exception-errors-downloading-packages-from-the-internet
323 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.
324 (Older versions of Alien::Build produced a less verbose more confusing
326 version of this diagnostic).
327 TL;DR, instead of this:
329 share {
331 start_url => 'http://example.org/dist';
332 ...
333 };
334 do this:
336 share {
338 start_url => 'https://example.org/dist';
339 };
340 If the website is going to redirect to a secure URL anyway.
342 The "599 Internal Exception" indicates an "internal" exception from
344 HTTP::Tiny and is not a real HTTP status code or error. This could
345 mean a number of different problems, but most frequently indicates that
346 a SSL request was made without the required modules (Net::SSLeay and
347 IO::Socket::SSL). Normally the
348 Alien::Build::Plugin::Download::Negotiate and
349 Alien::Build::Plugin::Fetch::HTTPTiny will make sure that the
350 appropriate modules are added to your prerequisites for you if you
351 specify a "https" URL. Some websites allow an initial request from
352 "http" but then redirect to "https". If you can it is better to
353 specify "https", if you cannot, then you can instead use the "ssl"
354 property on either of those two plugins.
355 Network fetch is turned off
357 If you get an error like this:
358 Alien::Build> install type share requested or detected, but network fetch is turned off
360 Alien::Build> see see https://metacpan.org/pod/Alien::Build::Manual::FAQ#Network-fetch-is-turned-off
361 This is because your environment is setup not to install aliens that
363 require the network. You can turn network fetch back on by setting
364 "ALIEN_INSTALL_NETWORK" to true, or by unsetting it. This environment
365 variable is designed for environments that don't ever want to install
366 aliens that require downloading source packages over the internet.
367 I would really prefer you not download stuff off the internet
369 The idea of Alien is to download missing packages and build them
370 automatically to make installing easier. Some people may not like
371 this, or may even have security requirements that they not download
372 random package over the internet (caveat, downloading random stuff off
373 of CPAN may not be any safer, so make sure you audit all of the open
374 source software that you use appropriately). Another reason you may
375 not want to download from the internet is if you are packaging up an
376 alien for an operating system vendor, which will always want to use the
377 system version of a library. In that situation you don't want
378 Alien::Build to go off and download something from the internet because
379 the probe failed for some reason.
380 This is easy to take care of, simply set "ALIEN_INSTALL_TYPE" to
382 "system" and a build from source code will never be attempted. On
383 systems that do not provide system versions of the library or tool you
384 will get an error, allowing you to install the library, and retry the
385 alien install. You can also set the environment variable on just some
386 aliens.
387 % export ALIEN_INSTALL_TYPE=system # for everyone
389 % env ALIEN_INSTALL_TYPE=system cpanm -v Alien::libfoo
391 For testing I would like to test both system and share installs!
393 You can use the "ALIEN_INSTALL_TYPE" environment variable. It will
394 force either a "share" or "system" install depending on how it is set.
395 For travis you can do something like this:
396 env:
398 matrix:
399 - ALIEN_INSTALL_TYPE=share
400 - ALIEN_INSTALL_TYPE=system
401 How do I use Alien::Build from Dist::Zilla?
403 For creating Alien::Base and Alien::Build based dist from Dist::Zilla
404 you can use the dzil plugin Dist::Zilla::Plugin::AlienBuild.
405 Cannot find either a share directory or a ConfigData module
407 If you see an error like this:
408 Cannot find either a share directory or a ConfigData module for Alien::libfoo.
410 (Alien::libfoo loaded from lib/Alien/libfoo.pm)
411 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
412 Can't locate Alien/libfoo/ConfigData.pm in @INC (you may need to install the Alien::libfoo::ConfigData module) (@INC contains: ...)
413 it means you are trying to use an Alien that hasn't been properly
415 installed. An Alien::Base based Alien needs to have either the share
416 directory build during the install process or for older legacy
417 Alien::Base::ModuleBuild based Aliens, a ConfigData module generated by
418 Module::Build.
419 This usually happens if you try to use an Alien module from the lib
421 directory as part of the Alien's distribution. You need to build the
422 alien and use "blib/lib" instead of "lib" or install the alien and use
423 the installed path.
424 It is also possible that your Alien installer is not set up correctly.
426 Make sure your "Makefile.PL" is using Alien::Build::MM correctly.
427 I have a question not listed here!
429 There are a number of forums available to people working on Alien,
430 Alien::Base and Alien::Build modules:
431 "#native" on irc.perl.org
433 This is intended for native interfaces in general so is a good
434 place for questions about Alien generally or Alien::Base and
435 Alien::Build specifically.
436 mailing list
438 The "perl5-alien" google group is intended for Alien issues
439 generally, including Alien::Base and Alien::Build.
440 <https://groups.google.com/forum/#!forum/perl5-alien>
442 Open a support ticket
444 If you have an issue with Alie::Build itself, then please open a
445 support ticket on the project's GitHub issue tracker.
446 <https://github.com/plicease/Alien-Build/issues>
448
450 Alien::Build, Alien::Build::MM, Alien::Build::Plugin, alienfile
451
453 Author: Graham Ollis <plicease@cpan.org>
454 Contributors:
456 Diab Jerius (DJERIUS)
458 Roy Storey
460 Ilya Pavlov
462 David Mertens (run4flat)
464 Mark Nunberg (mordy, mnunberg)
466 Christian Walde (Mithaldu)
468 Brian Wightman (MidLifeXis)
470 Zaki Mughal (zmughal)
472 mohawk (mohawk2, ETJ)
474 Vikas N Kumar (vikasnkumar)
476 Flavio Poletti (polettix)
478 Salvador Fandiño (salva)
480 Gianni Ceccarelli (dakkar)
482 Pavel Shaydo (zwon, trinitum)
484 Kang-min Liu (劉康民, gugod)
486 Nicholas Shipp (nshp)
488 Juan Julián Merelo Guervós (JJ)
490 Joel Berger (JBERGER)
492 Petr Pisar (ppisar)
494 Lance Wicks (LANCEW)
496 Ahmad Fatoum (a3f, ATHREEF)
498 José Joaquín Atria (JJATRIA)
500 Duke Leto (LETO)
502 Shoichi Kaji (SKAJI)
504 Shawn Laffan (SLAFFAN)
506 Paul Evans (leonerd, PEVANS)
508
510 This software is copyright (c) 2011-2018 by Graham Ollis.
511 This is free software; you can redistribute it and/or modify it under
513 the same terms as the Perl 5 programming language system itself.
514perl v5.28.1 2019-02-24 Alien::Build::Manual::FAQ(3)