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.40
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
80        my $ffi = FFI::Platypus->new;
81        $ffi->lib(Alien::MyLibrary->dynamic_libs);
82
83        $ffi->attach( 'my_library_function' => [] => 'void' );
84
85       You can even use it with Inline (C and C++ languages are supported):
86
87        package MyLibrary::Inline;
88
89        use Alien::MyLibrary;
90        # Inline 0.56 or better is required
91        use Inline 0.56 with => 'Alien::MyLibrary';
92        ...
93

DESCRIPTION

95       NOTE: Alien::Base::ModuleBuild is no longer bundled with Alien::Base
96       and has been spun off into a separate distribution.
97       Alien::Build::ModuleBuild will be a prerequisite for Alien::Base until
98       October 1, 2017.  If you are using Alien::Base::ModuleBuild you need to
99       make sure it is declared as a "configure_requires" in your "Build.PL".
100       You may want to also consider using Alien::Base and alienfile as a more
101       modern alternative.
102
103       Alien::Base comprises base classes to help in the construction of
104       "Alien::" modules. Modules in the Alien namespace are used to locate
105       and install (if necessary) external libraries needed by other Perl
106       modules.
107
108       This is the documentation for the Alien::Base module itself. If you are
109       starting out you probably want to do so from one of these documents:
110
111       Alien::Build::Manual::AlienUser
112           For users of an "Alien::libfoo" that is implemented using
113           Alien::Base.  (The developer of "Alien::libfoo" should provide the
114           documentation necessary, but if not, this is the place to start).
115
116       Alien::Build::Manual::AlienAuthor
117           If you are writing your own Alien based on Alien::Build and
118           Alien::Base.
119
120       Alien::Build::Manual::FAQ
121           If you have a common question that has already been answered, like
122           "How do I use alienfile with some build system".
123
124       Alien::Build::Manual::PluginAuthor
125           This is for the brave souls who want to write plugins that will
126           work with Alien::Build + alienfile.
127

METHODS

129       In the example snippets here, "Alien::MyLibrary" represents any
130       subclass of Alien::Base.
131
132   dist_dir
133        my $dir = Alien::MyLibrary->dist_dir;
134
135       Returns the directory that contains the install root for the packaged
136       software, if it was built from install (i.e., if "install_type" is
137       "share").
138
139   new
140        my $alien = Alien::MyLibrary->new;
141
142       Creates an instance of an Alien::Base object.  This is typically
143       unnecessary.
144
145   cflags
146        my $cflags = Alien::MyLibrary->cflags;
147
148        use Text::ParseWords qw( shellwords );
149        my @cflags = shellwords( Alien::MyLibrary->cflags );
150
151       Returns the C compiler flags necessary to compile an XS module using
152       the alien software.  If you need this in list form (for example if you
153       are calling system with a list argument) you can pass this value into
154       "shellwords" from the Perl core Text::ParseWords module.
155
156   cflags_static
157        my $cflags = Alien::MyLibrary->cflags_static;
158
159       Same as "cflags" above, but gets the static compiler flags, if they are
160       different.
161
162   libs
163        my $libs = Alien::MyLibrary->libs;
164
165        use Text::ParseWords qw( shellwords );
166        my @cflags = shellwords( Alien::MyLibrary->libs );
167
168       Returns the library linker flags necessary to link an XS module against
169       the alien software.  If you need this in list form (for example if you
170       are calling system with a list argument) you can pass this value into
171       "shellwords" from the Perl core Text::ParseWords module.
172
173   libs_static
174        my $libs = Alien::MyLibrary->libs_static;
175
176       Same as "libs" above, but gets the static linker flags, if they are
177       different.
178
179   version
180        my $version = Alien::MyLibrary->version;
181
182       Returns the version of the alienized library or tool that was
183       determined at install time.
184
185   atleast_version
186   exact_version
187   max_version
188        my $ok = Alien::MyLibrary->atleast_version($wanted_version);
189        my $ok = Alien::MyLibrary->exact_version($wanted_version);
190        my $ok = Alien::MyLibrary->max_version($wanted_version);
191
192       Returns true if the version of the alienized library or tool is at
193       least, exactly, or at most the version specified, respectively.
194
195   version_cmp
196         $cmp = Alien::MyLibrary->version_cmp($x, $y)
197
198       Comparison method used by atleast_version, exact_version and
199       max_version. May be useful to implement custom comparisons, or for
200       subclasses to overload to get different version comparison semantics
201       than the default rules, for packages that have some other rules than
202       the pkg-config behaviour.
203
204       Should return a number less than, equal to, or greater than zero;
205       similar in behaviour to the "<=>" and "cmp" operators.
206
207   install_type
208        my $install_type = Alien::MyLibrary->install_type;
209        my $bool = Alien::MyLibrary->install_type($install_type);
210
211       Returns the install type that was used when "Alien::MyLibrary" was
212       installed.  If a type is provided (the second form in the synopsis)
213       returns true if the actual install type matches.  Types include:
214
215       system
216           The library was provided by the operating system
217
218       share
219           The library was not available when "Alien::MyLibrary" was
220           installed, so it was built from source code, either downloaded from
221           the Internet or bundled with "Alien::MyLibrary".
222
223   config
224        my $value = Alien::MyLibrary->config($key);
225
226       Returns the configuration data as determined during the install of
227       Alien::MyLibrary.  For the appropriate config keys, see
228       Alien::Base::ModuleBuild::API#CONFIG-DATA.
229
230       This is not typically used by Alien::Base and alienfile, but a
231       compatible interface will be provided.
232
233   dynamic_libs
234        my @dlls = Alien::MyLibrary->dynamic_libs;
235        my($dll) = Alien::MyLibrary->dynamic_libs;
236
237       Returns a list of the dynamic library or shared object files for the
238       alien software.
239
240   bin_dir
241        my(@dir) = Alien::MyLibrary->bin_dir
242
243       Returns a list of directories with executables in them.  For a "system"
244       install this will be an empty list.  For a "share" install this will be
245       a directory under "dist_dir" named "bin" if it exists.  You may wish to
246       override the default behavior if you have executables or scripts that
247       get installed into non-standard locations.
248
249       Example usage:
250
251        use Env qw( @PATH );
252
253        unshift @PATH, Alien::MyLibrary->bin_dir;
254
255   dynamic_dir
256        my(@dir) = Alien::MyLibrary->dynamic_dir
257
258       Returns the dynamic dir for a dynamic build (if the main build is
259       static).  For a "share" install this will be a directory under
260       "dist_dir" named "dynamic" if it exists.  System builds return an empty
261       list.
262
263       Example usage:
264
265        use Env qw( @PATH );
266
267        unshift @PATH, Alien::MyLibrary->dynamic_dir;
268
269   alien_helper
270        my $helpers = Alien::MyLibrary->alien_helper;
271
272       Returns a hash reference of helpers provided by the Alien module.  The
273       keys are helper names and the values are code references.  The code
274       references will be executed at command time and the return value will
275       be interpolated into the command before execution.  The default
276       implementation returns an empty hash reference, and you are expected to
277       override the method to create your own helpers.
278
279       For use with commands specified in and alienfile or in your "Build.Pl"
280       when used with Alien::Base::ModuleBuild.
281
282       Helpers allow users of your Alien module to use platform or environment
283       determined logic to compute command names or arguments in your
284       installer logic.  Helpers allow you to do this without making your
285       Alien module a requirement when a build from source code is not
286       necessary.
287
288       As a concrete example, consider Alien::gmake, which provides the helper
289       "gmake":
290
291        package Alien::gmake;
292
293        ...
294
295        sub alien_helper {
296          my($class) = @_;
297          return {
298            gmake => sub {
299              # return the executable name for GNU make,
300              # usually either make or gmake depending on
301              # the platform and environment
302              $class->exe;
303            }
304          },
305        }
306
307       Now consider Alien::nasm.  "nasm" requires GNU Make to build from
308       source code, but if the system "nasm" package is installed we don't
309       need it.  From the alienfile of "Alien::nasm":
310
311        use alienfile;
312
313        plugin 'Probe::CommandLine' => (
314          command => 'nasm',
315          args    => ['-v'],
316          match   => qr/NASM version/,
317        );
318
319        share {
320          ...
321          plugin 'Extract' => 'tar.gz';
322          plugin 'Build::MSYS';
323
324          build [
325            'sh configure --prefix=%{alien.install.prefix}',
326            '%{gmake}',
327            '%{gmake} install',
328          ];
329        };
330
331        ...
332
333   inline_auto_include
334        my(@headers) = Alien::MyLibrary->inline_auto_include;
335
336       List of header files to automatically include in inline C and C++ code
337       when using Inline::C or Inline::CPP.  This is provided as a public
338       interface primarily so that it can be overridden at run time.  This can
339       also be specified in your "Build.PL" with Alien::Base::ModuleBuild
340       using the "alien_inline_auto_include" property.
341
342   runtime_prop
343        my $hashref = Alien::MyLibrary->runtime_prop;
344
345       Returns a hash reference of the runtime properties computed by
346       Alien::Build during its install process.  If the Alien::Base based
347       Alien was not built using Alien::Build, then this will return undef.
348
349   alt
350        my $new_alien = Alien::MyLibrary->alt($alt_name);
351        my $new_alien = $old_alien->alt($alt_name);
352
353       Returns an Alien::Base instance with the alternate configuration.
354
355       Some packages come with multiple libraries, and multiple ".pc" files to
356       use with them.  This method can be used with "pkg-config" plugins to
357       access different configurations.  (It could also be used with non-pkg-
358       config based packages too, though there are not as of this writing any
359       build time plugins that take advantage of this feature).
360
361       From your alienfile
362
363        use alienfile;
364
365        plugin 'PkgConfig' => (
366          pkg_name => [ 'libfoo', 'libbar', ],
367        );
368
369       Then in your base class:
370
371        package Alien::MyLibrary;
372
373        use base qw( Alien::Base );
374        use Role::Tiny::With qw( with );
375
376        with 'Alien::Role::Alt';
377
378        1;
379
380       Then you can use it:
381
382        use Alien::MyLibrary;
383
384        my $cflags = Alien::MyLibrary->alt('foo1')->cflags;
385        my $libs   = Alien::MyLibrary->alt('foo1')->libs;
386
387   alt_names
388        my @alt_names = Alien::MyLibrary->alt_names
389
390       Returns the list of all available alternative configuration names.
391
392   alt_exists
393        my $bool = Alien::MyLibrary->alt_exists($alt_name)
394
395       Returns true if the given alternative configuration exists.
396

SUPPORT AND CONTRIBUTING

398       First check the Alien::Build::Manual::FAQ for questions that have
399       already been answered.
400
401       IRC: #native on irc.perl.org
402
403       (click for instant chatroom login)
404       <http://chat.mibbit.com/#native@irc.perl.org>
405
406       If you find a bug, please report it on the projects issue tracker on
407       GitHub:
408
409       <https://github.com/PerlAlien/Alien-Base/issues>
410
411       Development is discussed on the projects google groups.  This is also a
412       reasonable place to post a question if you don't want to open an issue
413       in GitHub.
414
415       <https://groups.google.com/forum/#!forum/perl5-alien>
416
417       If you have implemented a new feature or fixed a bug, please open a
418       pull request.
419
420       <https://github.com/PerlAlien/Alien-Base/pulls>
421

SEE ALSO

423       •   Alien::Build
424
425       •   alienfile
426
427       •   Alien
428
429       •   Alien::Build::Manual::FAQ
430

THANKS

432       "Alien::Base" was originally written by Joel Berger, and that code is
433       still Copyright (C) 2012-2017 Joel Berger.  It has the same license as
434       the rest of the Alien::Build.
435
436       Special thanks for the early development of "Alien::Base" go to:
437
438       Christian Walde (Mithaldu)
439           For productive conversations about component interoperability.
440
441       kmx For writing Alien::Tidyp from which I drew many of my initial
442           ideas.
443
444       David Mertens (run4flat)
445           For productive conversations about implementation.
446
447       Mark Nunberg (mordy, mnunberg)
448           For graciously teaching me about rpath and dynamic loading,
449

AUTHOR

451       Author: Graham Ollis <plicease@cpan.org>
452
453       Contributors:
454
455       Diab Jerius (DJERIUS)
456
457       Roy Storey (KIWIROY)
458
459       Ilya Pavlov
460
461       David Mertens (run4flat)
462
463       Mark Nunberg (mordy, mnunberg)
464
465       Christian Walde (Mithaldu)
466
467       Brian Wightman (MidLifeXis)
468
469       Zaki Mughal (zmughal)
470
471       mohawk (mohawk2, ETJ)
472
473       Vikas N Kumar (vikasnkumar)
474
475       Flavio Poletti (polettix)
476
477       Salvador Fandiño (salva)
478
479       Gianni Ceccarelli (dakkar)
480
481       Pavel Shaydo (zwon, trinitum)
482
483       Kang-min Liu (劉康民, gugod)
484
485       Nicholas Shipp (nshp)
486
487       Juan Julián Merelo Guervós (JJ)
488
489       Joel Berger (JBERGER)
490
491       Petr Pisar (ppisar)
492
493       Lance Wicks (LANCEW)
494
495       Ahmad Fatoum (a3f, ATHREEF)
496
497       José Joaquín Atria (JJATRIA)
498
499       Duke Leto (LETO)
500
501       Shoichi Kaji (SKAJI)
502
503       Shawn Laffan (SLAFFAN)
504
505       Paul Evans (leonerd, PEVANS)
506
507       Håkon Hægland (hakonhagland, HAKONH)
508
510       This software is copyright (c) 2011-2020 by Graham Ollis.
511
512       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.
514
515
516
517perl v5.32.1                      2021-05-13                    Alien::Base(3)
Impressum