1Alien::Base(3) User Contributed Perl Documentation Alien::Base(3)
2
3
4
6 Alien::Base - Base classes for Alien:: modules
7
9 version 2.77
10
12 package Alien::MyLibrary;
13
14 use strict;
15 use warnings;
16
17 use parent 'Alien::Base';
18
19 1;
20
21 (for details on the "Makefile.PL" or "Build.PL" and alienfile that
22 should be bundled with your Alien::Base subclass, please see
23 Alien::Build::Manual::AlienAuthor).
24
25 Then a "MyLibrary::XS" can use "Alien::MyLibrary" in its "Makefile.PL":
26
27 use Alien::MyLibrary
28 use ExtUtils::MakeMaker;
29 use Alien::Base::Wrapper qw( Alien::MyLibrary !export );
30 use Config;
31
32 WriteMakefile(
33 ...
34 Alien::Base::Wrapper->mm_args,
35 ...
36 );
37
38 Or if you prefer Module::Build, in its "Build.PL":
39
40 use Alien::MyLibrary;
41 use Module::Build 0.28; # need at least 0.28
42 use Alien::Base::Wrapper qw( Alien::MyLibrary !export );
43
44 my $builder = Module::Build->new(
45 ...
46 Alien::Base::Wrapper->mb_args,
47 ...
48 );
49
50 $builder->create_build_script;
51
52 Or if you are using ExtUtils::Depends:
53
54 use ExtUtils::MakeMaker;
55 use ExtUtils::Depends;
56 my $eud = ExtUtils::Depends->new(qw( MyLibrary::XS Alien::MyLibrary ));
57 WriteMakefile(
58 ...
59 $eud->get_makefile_vars
60 );
61
62 If you are using Alien::Base::ModuleBuild instead of the recommended
63 Alien::Build and alienfile, then in your "MyLibrary::XS" module, you
64 may need something like this in your main ".pm" file IF your library
65 uses dynamic libraries:
66
67 package MyLibrary::XS;
68
69 use Alien::MyLibrary; # may only be needed if you are using Alien::Base::ModuleBuild
70
71 ...
72
73 Or you can use it from an FFI module:
74
75 package MyLibrary::FFI;
76
77 use Alien::MyLibrary;
78 use FFI::Platypus;
79 use FFI::CheckLib 0.28 qw( find_lib_or_die );
80
81 my $ffi = FFI::Platypus->new;
82 $ffi->lib(find_lib_or_die lib => 'mylib', alien => ['Alien::MyLibrary']);
83
84 $ffi->attach( 'my_library_function' => [] => 'void' );
85
86 You can even use it with Inline (C and C++ languages are supported):
87
88 package MyLibrary::Inline;
89
90 use Alien::MyLibrary;
91 # Inline 0.56 or better is required
92 use Inline 0.56 with => 'Alien::MyLibrary';
93 ...
94
96 NOTE: Alien::Base::ModuleBuild is no longer bundled with Alien::Base
97 and has been spun off into a separate distribution.
98 Alien::Base::ModuleBuild will be a prerequisite for Alien::Base until
99 October 1, 2017. If you are using Alien::Base::ModuleBuild you need to
100 make sure it is declared as a "configure_requires" in your "Build.PL".
101 You may want to also consider using Alien::Base and alienfile as a more
102 modern alternative.
103
104 Alien::Base comprises base classes to help in the construction of
105 "Alien::" modules. Modules in the Alien namespace are used to locate
106 and install (if necessary) external libraries needed by other Perl
107 modules.
108
109 This is the documentation for the Alien::Base module itself. If you are
110 starting out you probably want to do so from one of these documents:
111
112 Alien::Build::Manual::AlienUser
113 For users of an "Alien::libfoo" that is implemented using
114 Alien::Base. (The developer of "Alien::libfoo" should provide the
115 documentation necessary, but if not, this is the place to start).
116
117 Alien::Build::Manual::AlienAuthor
118 If you are writing your own Alien based on Alien::Build and
119 Alien::Base.
120
121 Alien::Build::Manual::FAQ
122 If you have a common question that has already been answered, like
123 "How do I use alienfile with some build system".
124
125 Alien::Build::Manual::PluginAuthor
126 This is for the brave souls who want to write plugins that will
127 work with Alien::Build + alienfile.
128
129 Before using an Alien::Base based Alien directly, please consider the
130 following advice:
131
132 If you are wanting to use an Alien::Base based Alien with an XS module
133 using ExtUtils::MakeMaker or Module::Build, it is highly recommended
134 that you use Alien::Base::Wrapper, rather than using the Alien
135 directly, because it handles a number of sharp edges and avoids
136 pitfalls common when trying to use an Alien directly with
137 ExtUtils::MakeMaker.
138
139 In the same vein, if you are wanting to use an Alien::Base based Alien
140 with an XS module using Dist::Zilla it is highly recommended that you
141 use Dist::Zilla::Plugin::AlienBase::Wrapper for the same reasons.
142
143 As of version 0.28, FFI::CheckLib has a good interface for working with
144 Alien::Base based Aliens in fallback mode, which is recommended.
145
146 You should typically only be using an Alien::Base based Alien directly,
147 if you need to integrate it with some other system, or if it is a tool
148 based Alien that you don't need to link.
149
150 The above synopsis and linked manual documents will lead you down the
151 right path, but it is worth knowing before you read further in this
152 document.
153
155 In the example snippets here, "Alien::MyLibrary" represents any
156 subclass of Alien::Base.
157
158 dist_dir
159 my $dir = Alien::MyLibrary->dist_dir;
160
161 Returns the directory that contains the install root for the packaged
162 software, if it was built from install (i.e., if "install_type" is
163 "share").
164
165 new
166 my $alien = Alien::MyLibrary->new;
167
168 Creates an instance of an Alien::Base object. This is typically
169 unnecessary.
170
171 cflags
172 my $cflags = Alien::MyLibrary->cflags;
173
174 use Text::ParseWords qw( shellwords );
175 my @cflags = shellwords( Alien::MyLibrary->cflags );
176
177 Returns the C compiler flags necessary to compile an XS module using
178 the alien software. If you need this in list form (for example if you
179 are calling system with a list argument) you can pass this value into
180 "shellwords" from the Perl core Text::ParseWords module.
181
182 cflags_static
183 my $cflags = Alien::MyLibrary->cflags_static;
184
185 Same as "cflags" above, but gets the static compiler flags, if they are
186 different.
187
188 libs
189 my $libs = Alien::MyLibrary->libs;
190
191 use Text::ParseWords qw( shellwords );
192 my @cflags = shellwords( Alien::MyLibrary->libs );
193
194 Returns the library linker flags necessary to link an XS module against
195 the alien software. If you need this in list form (for example if you
196 are calling system with a list argument) you can pass this value into
197 "shellwords" from the Perl core Text::ParseWords module.
198
199 libs_static
200 my $libs = Alien::MyLibrary->libs_static;
201
202 Same as "libs" above, but gets the static linker flags, if they are
203 different.
204
205 version
206 my $version = Alien::MyLibrary->version;
207
208 Returns the version of the alienized library or tool that was
209 determined at install time.
210
211 atleast_version
212 exact_version
213 max_version
214 my $ok = Alien::MyLibrary->atleast_version($wanted_version);
215 my $ok = Alien::MyLibrary->exact_version($wanted_version);
216 my $ok = Alien::MyLibrary->max_version($wanted_version);
217
218 Returns true if the version of the alienized library or tool is at
219 least, exactly, or at most the version specified, respectively.
220
221 version_cmp
222 $cmp = Alien::MyLibrary->version_cmp($x, $y)
223
224 Comparison method used by "atleast_version", "exact_version" and
225 "max_version". May be useful to implement custom comparisons, or for
226 subclasses to overload to get different version comparison semantics
227 than the default rules, for packages that have some other rules than
228 the pkg-config behaviour.
229
230 Should return a number less than, equal to, or greater than zero;
231 similar in behaviour to the "<=>" and "cmp" operators.
232
233 install_type
234 my $install_type = Alien::MyLibrary->install_type;
235 my $bool = Alien::MyLibrary->install_type($install_type);
236
237 Returns the install type that was used when "Alien::MyLibrary" was
238 installed. If a type is provided (the second form in the synopsis)
239 returns true if the actual install type matches. Types include:
240
241 system
242 The library was provided by the operating system
243
244 share
245 The library was not available when "Alien::MyLibrary" was
246 installed, so it was built from source code, either downloaded from
247 the Internet or bundled with "Alien::MyLibrary".
248
249 config
250 my $value = Alien::MyLibrary->config($key);
251
252 Returns the configuration data as determined during the install of
253 "Alien::MyLibrary". For the appropriate config keys, see "CONFIG DATA"
254 in Alien::Base::ModuleBuild::API.
255
256 This is not typically used by Alien::Base and alienfile, but a
257 compatible interface will be provided.
258
259 dynamic_libs
260 my @dlls = Alien::MyLibrary->dynamic_libs;
261 my($dll) = Alien::MyLibrary->dynamic_libs;
262
263 Returns a list of the dynamic library or shared object files for the
264 alien software.
265
266 bin_dir
267 my(@dir) = Alien::MyLibrary->bin_dir
268
269 Returns a list of directories with executables in them. For a "system"
270 install this will be an empty list. For a "share" install this will be
271 a directory under "dist_dir" named "bin" if it exists. You may wish to
272 override the default behavior if you have executables or scripts that
273 get installed into non-standard locations.
274
275 Example usage:
276
277 use Env qw( @PATH );
278
279 unshift @PATH, Alien::MyLibrary->bin_dir;
280
281 dynamic_dir
282 my(@dir) = Alien::MyLibrary->dynamic_dir
283
284 Returns the dynamic dir for a dynamic build (if the main build is
285 static). For a "share" install this will be a directory under
286 "dist_dir" named "dynamic" if it exists. System builds return an empty
287 list.
288
289 Example usage:
290
291 use Env qw( @PATH );
292
293 unshift @PATH, Alien::MyLibrary->dynamic_dir;
294
295 alien_helper
296 my $helpers = Alien::MyLibrary->alien_helper;
297
298 Returns a hash reference of helpers provided by the Alien module. The
299 keys are helper names and the values are code references. The code
300 references will be executed at command time and the return value will
301 be interpolated into the command before execution. The default
302 implementation returns an empty hash reference, and you are expected to
303 override the method to create your own helpers.
304
305 For use with commands specified in and alienfile or in your "Build.Pl"
306 when used with Alien::Base::ModuleBuild.
307
308 Helpers allow users of your Alien module to use platform or environment
309 determined logic to compute command names or arguments in your
310 installer logic. Helpers allow you to do this without making your
311 Alien module a requirement when a build from source code is not
312 necessary.
313
314 As a concrete example, consider Alien::gmake, which provides the helper
315 "gmake":
316
317 package Alien::gmake;
318
319 ...
320
321 sub alien_helper {
322 my($class) = @_;
323 return {
324 gmake => sub {
325 # return the executable name for GNU make,
326 # usually either make or gmake depending on
327 # the platform and environment
328 $class->exe;
329 }
330 },
331 }
332
333 Now consider Alien::nasm. "nasm" requires GNU Make to build from
334 source code, but if the system "nasm" package is installed we don't
335 need it. From the alienfile of "Alien::nasm":
336
337 use alienfile;
338
339 plugin 'Probe::CommandLine' => (
340 command => 'nasm',
341 args => ['-v'],
342 match => qr/NASM version/,
343 );
344
345 share {
346 ...
347 plugin 'Extract' => 'tar.gz';
348 plugin 'Build::MSYS';
349
350 build [
351 'sh configure --prefix=%{alien.install.prefix}',
352 '%{gmake}',
353 '%{gmake} install',
354 ];
355 };
356
357 ...
358
359 inline_auto_include
360 my(@headers) = Alien::MyLibrary->inline_auto_include;
361
362 List of header files to automatically include in inline C and C++ code
363 when using Inline::C or Inline::CPP. This is provided as a public
364 interface primarily so that it can be overridden at run time. This can
365 also be specified in your "Build.PL" with Alien::Base::ModuleBuild
366 using the "alien_inline_auto_include" property.
367
368 runtime_prop
369 my $hashref = Alien::MyLibrary->runtime_prop;
370
371 Returns a hash reference of the runtime properties computed by
372 Alien::Build during its install process. If the Alien::Base based
373 Alien was not built using Alien::Build, then this will return undef.
374
375 alt
376 my $new_alien = Alien::MyLibrary->alt($alt_name);
377 my $new_alien = $old_alien->alt($alt_name);
378
379 Returns an Alien::Base instance with the alternate configuration.
380
381 Some packages come with multiple libraries, and multiple ".pc" files to
382 use with them. This method can be used with "pkg-config" plugins to
383 access different configurations. (It could also be used with non-pkg-
384 config based packages too, though there are not as of this writing any
385 build time plugins that take advantage of this feature).
386
387 From your alienfile
388
389 use alienfile;
390
391 plugin 'PkgConfig' => (
392 pkg_name => [ 'libfoo', 'libbar', ],
393 );
394
395 Then in your base class works like normal:
396
397 package Alien::MyLibrary;
398
399 use parent qw( Alien::Base );
400
401 1;
402
403 Then you can use it:
404
405 use Alien::MyLibrary;
406
407 my $cflags = Alien::MyLibrary->alt('foo1')->cflags;
408 my $libs = Alien::MyLibrary->alt('foo1')->libs;
409
410 alt_names
411 my @alt_names = Alien::MyLibrary->alt_names
412
413 Returns the list of all available alternative configuration names.
414
415 alt_exists
416 my $bool = Alien::MyLibrary->alt_exists($alt_name)
417
418 Returns true if the given alternative configuration exists.
419
421 First check the Alien::Build::Manual::FAQ for questions that have
422 already been answered.
423
424 IRC: #native on irc.perl.org
425
426 (click for instant chatroom login)
427 <http://chat.mibbit.com/#native@irc.perl.org>
428
429 If you find a bug, please report it on the projects issue tracker on
430 GitHub:
431
432 <https://github.com/PerlAlien/Alien-Build/issues>
433
434 Development is discussed on the projects google groups. This is also a
435 reasonable place to post a question if you don't want to open an issue
436 in GitHub.
437
438 <https://groups.google.com/forum/#!forum/perl5-alien>
439
440 If you have implemented a new feature or fixed a bug, please open a
441 pull request.
442
443 <https://github.com/PerlAlien/Alien-Build/pulls>
444
446 • Alien::Build
447
448 • alienfile
449
450 • Alien
451
452 • Alien::Build::Manual::FAQ
453
455 "Alien::Base" was originally written by Joel Berger, and that code is
456 still Copyright (C) 2012-2017 Joel Berger. It has the same license as
457 the rest of the Alien::Build.
458
459 Special thanks for the early development of "Alien::Base" go to:
460
461 Christian Walde (Mithaldu)
462 For productive conversations about component interoperability.
463
464 kmx For writing Alien::Tidyp from which I drew many of my initial
465 ideas.
466
467 David Mertens (run4flat)
468 For productive conversations about implementation.
469
470 Mark Nunberg (mordy, mnunberg)
471 For graciously teaching me about rpath and dynamic loading,
472
474 Author: Graham Ollis <plicease@cpan.org>
475
476 Contributors:
477
478 Diab Jerius (DJERIUS)
479
480 Roy Storey (KIWIROY)
481
482 Ilya Pavlov
483
484 David Mertens (run4flat)
485
486 Mark Nunberg (mordy, mnunberg)
487
488 Christian Walde (Mithaldu)
489
490 Brian Wightman (MidLifeXis)
491
492 Zaki Mughal (zmughal)
493
494 mohawk (mohawk2, ETJ)
495
496 Vikas N Kumar (vikasnkumar)
497
498 Flavio Poletti (polettix)
499
500 Salvador Fandiño (salva)
501
502 Gianni Ceccarelli (dakkar)
503
504 Pavel Shaydo (zwon, trinitum)
505
506 Kang-min Liu (劉康民, gugod)
507
508 Nicholas Shipp (nshp)
509
510 Juan Julián Merelo Guervós (JJ)
511
512 Joel Berger (JBERGER)
513
514 Petr Písař (ppisar)
515
516 Lance Wicks (LANCEW)
517
518 Ahmad Fatoum (a3f, ATHREEF)
519
520 José Joaquín Atria (JJATRIA)
521
522 Duke Leto (LETO)
523
524 Shoichi Kaji (SKAJI)
525
526 Shawn Laffan (SLAFFAN)
527
528 Paul Evans (leonerd, PEVANS)
529
530 Håkon Hægland (hakonhagland, HAKONH)
531
532 nick nauwelaerts (INPHOBIA)
533
534 Florian Weimer
535
537 This software is copyright (c) 2011-2022 by Graham Ollis.
538
539 This is free software; you can redistribute it and/or modify it under
540 the same terms as the Perl 5 programming language system itself.
541
542
543
544perl v5.36.0 2023-01-20 Alien::Base(3)