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.17
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        unshft @PATH, Alien::MyLibrary->bin_dir;
254
255   alien_helper
256        my $helpers = Alien::MyLibrary->alien_helper;
257
258       Returns a hash reference of helpers provided by the Alien module.  The
259       keys are helper names and the values are code references.  The code
260       references will be executed at command time and the return value will
261       be interpolated into the command before execution.  The default
262       implementation returns an empty hash reference, and you are expected to
263       override the method to create your own helpers.
264
265       For use with commands specified in and alienfile or in your "Build.Pl"
266       when used with Alien::Base::ModuleBuild.
267
268       Helpers allow users of your Alien module to use platform or environment
269       determined logic to compute command names or arguments in your
270       installer logic.  Helpers allow you to do this without making your
271       Alien module a requirement when a build from source code is not
272       necessary.
273
274       As a concrete example, consider Alien::gmake, which provides the helper
275       "gmake":
276
277        package Alien::gmake;
278
279        ...
280
281        sub alien_helper {
282          my($class) = @_;
283          return {
284            gmake => sub {
285              # return the executable name for GNU make,
286              # usually either make or gmake depending on
287              # the platform and environment
288              $class->exe;
289            }
290          },
291        }
292
293       Now consider Alien::nasm.  "nasm" requires GNU Make to build from
294       source code, but if the system "nasm" package is installed we don't
295       need it.  From the alienfile of "Alien::nasm":
296
297        use alienfile;
298
299        plugin 'Probe::CommandLine' => (
300          command => 'nasm',
301          args    => ['-v'],
302          match   => qr/NASM version/,
303        );
304
305        share {
306          ...
307          plugin 'Extract' => 'tar.gz';
308          plugin 'Build::MSYS';
309
310          build [
311            'sh configure --prefix=%{alien.install.prefix}',
312            '%{gmake}',
313            '%{gmake} install',
314          ];
315        };
316
317        ...
318
319   inline_auto_include
320        my(@headers) = Alien::MyLibrary->inline_auto_include;
321
322       List of header files to automatically include in inline C and C++ code
323       when using Inline::C or Inline::CPP.  This is provided as a public
324       interface primarily so that it can be overridden at run time.  This can
325       also be specified in your "Build.PL" with Alien::Base::ModuleBuild
326       using the "alien_inline_auto_include" property.
327
328   runtime_prop
329        my $hashref = Alien::MyLibrary->runtime_prop;
330
331       Returns a hash reference of the runtime properties computed by
332       Alien::Build during its install process.  If the Alien::Base based
333       Alien was not built using Alien::Build, then this will return undef.
334
335   alt
336        my $new_alien = Alien::MyLibrary->alt($alt_name);
337        my $new_alien = $old_alien->alt($alt_name);
338
339       Returns an Alien::Base instance with the alternate configuration.
340
341       Some packages come with multiple libraries, and multiple ".pc" files to
342       use with them.  This method can be used with "pkg-config" plugins to
343       access different configurations.  (It could also be used with non-pkg-
344       config based packages too, though there are not as of this writing any
345       build time plugins that take advantage of this feature).
346
347       From your alienfile
348
349        use alienfile;
350
351        plugin 'PkgConfig' => (
352          pkg_name => [ 'libfoo', 'libbar', ],
353        );
354
355       Then in your base class:
356
357        package Alien::MyLibrary;
358
359        use base qw( Alien::Base );
360        use Role::Tiny::With qw( with );
361
362        with 'Alien::Role::Alt';
363
364        1;
365
366       Then you can use it:
367
368        use Alien::MyLibrary;
369
370        my $cflags = Alien::MyLibrary->alt('foo1')->cflags;
371        my $libs   = Alien::MyLibrary->alt('foo1')->libs;
372
373   alt_names
374        my @alt_names = Alien::MyLibrary->alt_names
375
376       Returns the list of all available alternative configuration names.
377
378   alt_exists
379        my $bool = Alien::MyLibrary->alt_exists($alt_name)
380
381       Returns true if the given alternative configuration exists.
382

SUPPORT AND CONTRIBUTING

384       First check the Alien::Build::Manual::FAQ for questions that have
385       already been answered.
386
387       IRC: #native on irc.perl.org
388
389       (click for instant chatroom login)
390       <http://chat.mibbit.com/#native@irc.perl.org>
391
392       If you find a bug, please report it on the projects issue tracker on
393       GitHub:
394
395       <https://github.com/Perl5-Alien/Alien-Base/issues>
396
397       Development is discussed on the projects google groups.  This is also a
398       reasonable place to post a question if you don't want to open an issue
399       in GitHub.
400
401       <https://groups.google.com/forum/#!forum/perl5-alien>
402
403       If you have implemented a new feature or fixed a bug, please open a
404       pull request.
405
406       <https://github.com/Perl5-Alien/Alien-Base/pulls>
407

SEE ALSO

409       ·   Alien::Build
410
411       ·   alienfile
412
413       ·   Alien
414
415       ·   Alien::Build::Manual::FAQ
416

THANKS

418       "Alien::Base" was originally written by Joel Berger, and that code is
419       still Copyright (C) 2012-2017 Joel Berger.  It has the same license as
420       the rest of the Alien::Build.
421
422       Special thanks for the early development of "Alien::Base" go to:
423
424       Christian Walde (Mithaldu)
425           For productive conversations about component interoperability.
426
427       kmx For writing Alien::Tidyp from which I drew many of my initial
428           ideas.
429
430       David Mertens (run4flat)
431           For productive conversations about implementation.
432
433       Mark Nunberg (mordy, mnunberg)
434           For graciously teaching me about rpath and dynamic loading,
435

AUTHOR

437       Author: Graham Ollis <plicease@cpan.org>
438
439       Contributors:
440
441       Diab Jerius (DJERIUS)
442
443       Roy Storey (KIWIROY)
444
445       Ilya Pavlov
446
447       David Mertens (run4flat)
448
449       Mark Nunberg (mordy, mnunberg)
450
451       Christian Walde (Mithaldu)
452
453       Brian Wightman (MidLifeXis)
454
455       Zaki Mughal (zmughal)
456
457       mohawk (mohawk2, ETJ)
458
459       Vikas N Kumar (vikasnkumar)
460
461       Flavio Poletti (polettix)
462
463       Salvador Fandiño (salva)
464
465       Gianni Ceccarelli (dakkar)
466
467       Pavel Shaydo (zwon, trinitum)
468
469       Kang-min Liu (劉康民, gugod)
470
471       Nicholas Shipp (nshp)
472
473       Juan Julián Merelo Guervós (JJ)
474
475       Joel Berger (JBERGER)
476
477       Petr Pisar (ppisar)
478
479       Lance Wicks (LANCEW)
480
481       Ahmad Fatoum (a3f, ATHREEF)
482
483       José Joaquín Atria (JJATRIA)
484
485       Duke Leto (LETO)
486
487       Shoichi Kaji (SKAJI)
488
489       Shawn Laffan (SLAFFAN)
490
491       Paul Evans (leonerd, PEVANS)
492
494       This software is copyright (c) 2011-2020 by Graham Ollis.
495
496       This is free software; you can redistribute it and/or modify it under
497       the same terms as the Perl 5 programming language system itself.
498
499
500
501perl v5.30.2                      2020-03-20                    Alien::Base(3)
Impressum