1Alien::Base(3)        User Contributed Perl Documentation       Alien::Base(3)
2
3
4

NAME

6       Alien::Base - Base classes for Alien:: modules
7

VERSION

9       version 2.77
10

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

SUPPORT AND CONTRIBUTING

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

SEE ALSO

446       •   Alien::Build
447
448       •   alienfile
449
450       •   Alien
451
452       •   Alien::Build::Manual::FAQ
453

THANKS

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

AUTHOR

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)
Impressum