1Alien::Base(3) User Contributed Perl Documentation Alien::Base(3)
2
6 Alien::Base - Base classes for Alien:: modules
7
9 version 2.47
10
12 package Alien::MyLibrary;
13 use strict;
15 use warnings;
16 use parent 'Alien::Base';
18 1;
20 (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 Then a "MyLibrary::XS" can use "Alien::MyLibrary" in its "Makefile.PL":
26 use Alien::MyLibrary
28 use ExtUtils::MakeMaker;
29 use Alien::Base::Wrapper qw( Alien::MyLibrary !export );
30 use Config;
31 WriteMakefile(
33 ...
34 Alien::Base::Wrapper->mm_args,
35 ...
36 );
37 Or if you prefer Module::Build, in its "Build.PL":
39 use Alien::MyLibrary;
41 use Module::Build 0.28; # need at least 0.28
42 use Alien::Base::Wrapper qw( Alien::MyLibrary !export );
43 my $builder = Module::Build->new(
45 ...
46 Alien::Base::Wrapper->mb_args,
47 ...
48 );
49 $builder->create_build_script;
51 Or if you are using ExtUtils::Depends:
53 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 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 package MyLibrary::XS;
68 use Alien::MyLibrary; # may only be needed if you are using Alien::Base::ModuleBuild
70 ...
72 Or you can use it from an FFI module:
74 package MyLibrary::FFI;
76 use Alien::MyLibrary;
78 use FFI::Platypus;
79 use FFI::CheckLib 0.28 qw( find_lib_or_die );
80 my $ffi = FFI::Platypus->new;
82 $ffi->lib(find_lib_or_die lib => 'mylib', alien => ['Alien::MyLibrary']);
83 $ffi->attach( 'my_library_function' => [] => 'void' );
85 You can even use it with Inline (C and C++ languages are supported):
87 package MyLibrary::Inline;
89 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::Build::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 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 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 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 Alien::Build::Manual::AlienAuthor
118 If you are writing your own Alien based on Alien::Build and
119 Alien::Base.
120 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 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 Before using an Alien::Base based Alien directly, please consider the
130 following advice:
131 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::MakMaker.
138 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 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 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 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 dist_dir
159 my $dir = Alien::MyLibrary->dist_dir;
160 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 new
166 my $alien = Alien::MyLibrary->new;
167 Creates an instance of an Alien::Base object. This is typically
169 unnecessary.
170 cflags
172 my $cflags = Alien::MyLibrary->cflags;
173 use Text::ParseWords qw( shellwords );
175 my @cflags = shellwords( Alien::MyLibrary->cflags );
176 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 cflags_static
183 my $cflags = Alien::MyLibrary->cflags_static;
184 Same as "cflags" above, but gets the static compiler flags, if they are
186 different.
187 libs
189 my $libs = Alien::MyLibrary->libs;
190 use Text::ParseWords qw( shellwords );
192 my @cflags = shellwords( Alien::MyLibrary->libs );
193 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 libs_static
200 my $libs = Alien::MyLibrary->libs_static;
201 Same as "libs" above, but gets the static linker flags, if they are
203 different.
204 version
206 my $version = Alien::MyLibrary->version;
207 Returns the version of the alienized library or tool that was
209 determined at install time.
210 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 Returns true if the version of the alienized library or tool is at
219 least, exactly, or at most the version specified, respectively.
220 version_cmp
222 $cmp = Alien::MyLibrary->version_cmp($x, $y)
223 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 Should return a number less than, equal to, or greater than zero;
231 similar in behaviour to the "<=>" and "cmp" operators.
232 install_type
234 my $install_type = Alien::MyLibrary->install_type;
235 my $bool = Alien::MyLibrary->install_type($install_type);
236 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 system
242 The library was provided by the operating system
243 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 config
250 my $value = Alien::MyLibrary->config($key);
251 Returns the configuration data as determined during the install of
253 Alien::MyLibrary. For the appropriate config keys, see
254 Alien::Base::ModuleBuild::API#CONFIG-DATA.
255 This is not typically used by Alien::Base and alienfile, but a
257 compatible interface will be provided.
258 dynamic_libs
260 my @dlls = Alien::MyLibrary->dynamic_libs;
261 my($dll) = Alien::MyLibrary->dynamic_libs;
262 Returns a list of the dynamic library or shared object files for the
264 alien software.
265 bin_dir
267 my(@dir) = Alien::MyLibrary->bin_dir
268 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 Example usage:
276 use Env qw( @PATH );
278 unshift @PATH, Alien::MyLibrary->bin_dir;
280 dynamic_dir
282 my(@dir) = Alien::MyLibrary->dynamic_dir
283 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 Example usage:
290 use Env qw( @PATH );
292 unshift @PATH, Alien::MyLibrary->dynamic_dir;
294 alien_helper
296 my $helpers = Alien::MyLibrary->alien_helper;
297 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 For use with commands specified in and alienfile or in your "Build.Pl"
306 when used with Alien::Base::ModuleBuild.
307 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 As a concrete example, consider Alien::gmake, which provides the helper
315 "gmake":
316 package Alien::gmake;
318 ...
320 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 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 use alienfile;
338 plugin 'Probe::CommandLine' => (
340 command => 'nasm',
341 args => ['-v'],
342 match => qr/NASM version/,
343 );
344 share {
346 ...
347 plugin 'Extract' => 'tar.gz';
348 plugin 'Build::MSYS';
349 build [
351 'sh configure --prefix=%{alien.install.prefix}',
352 '%{gmake}',
353 '%{gmake} install',
354 ];
355 };
356 ...
358 inline_auto_include
360 my(@headers) = Alien::MyLibrary->inline_auto_include;
361 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 runtime_prop
369 my $hashref = Alien::MyLibrary->runtime_prop;
370 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 alt
376 my $new_alien = Alien::MyLibrary->alt($alt_name);
377 my $new_alien = $old_alien->alt($alt_name);
378 Returns an Alien::Base instance with the alternate configuration.
380 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 From your alienfile
388 use alienfile;
390 plugin 'PkgConfig' => (
392 pkg_name => [ 'libfoo', 'libbar', ],
393 );
394 Then in your base class works like normal:
396 package Alien::MyLibrary;
398 use parent qw( Alien::Base );
400 1;
402 Then you can use it:
404 use Alien::MyLibrary;
406 my $cflags = Alien::MyLibrary->alt('foo1')->cflags;
408 my $libs = Alien::MyLibrary->alt('foo1')->libs;
409 alt_names
411 my @alt_names = Alien::MyLibrary->alt_names
412 Returns the list of all available alternative configuration names.
414 alt_exists
416 my $bool = Alien::MyLibrary->alt_exists($alt_name)
417 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 IRC: #native on irc.perl.org
425 (click for instant chatroom login)
427 <http://chat.mibbit.com/#native@irc.perl.org>
428 If you find a bug, please report it on the projects issue tracker on
430 GitHub:
431 <https://github.com/PerlAlien/Alien-Base/issues>
433 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 <https://groups.google.com/forum/#!forum/perl5-alien>
439 If you have implemented a new feature or fixed a bug, please open a
441 pull request.
442 <https://github.com/PerlAlien/Alien-Base/pulls>
444
446 • Alien::Build
447 • alienfile
449 • Alien
451 • 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 Special thanks for the early development of "Alien::Base" go to:
460 Christian Walde (Mithaldu)
462 For productive conversations about component interoperability.
463 kmx For writing Alien::Tidyp from which I drew many of my initial
465 ideas.
466 David Mertens (run4flat)
468 For productive conversations about implementation.
469 Mark Nunberg (mordy, mnunberg)
471 For graciously teaching me about rpath and dynamic loading,
472
474 Author: Graham Ollis <plicease@cpan.org>
475 Contributors:
477 Diab Jerius (DJERIUS)
479 Roy Storey (KIWIROY)
481 Ilya Pavlov
483 David Mertens (run4flat)
485 Mark Nunberg (mordy, mnunberg)
487 Christian Walde (Mithaldu)
489 Brian Wightman (MidLifeXis)
491 Zaki Mughal (zmughal)
493 mohawk (mohawk2, ETJ)
495 Vikas N Kumar (vikasnkumar)
497 Flavio Poletti (polettix)
499 Salvador Fandiño (salva)
501 Gianni Ceccarelli (dakkar)
503 Pavel Shaydo (zwon, trinitum)
505 Kang-min Liu (劉康民, gugod)
507 Nicholas Shipp (nshp)
509 Juan Julián Merelo Guervós (JJ)
511 Joel Berger (JBERGER)
513 Petr Písař (ppisar)
515 Lance Wicks (LANCEW)
517 Ahmad Fatoum (a3f, ATHREEF)
519 José Joaquín Atria (JJATRIA)
521 Duke Leto (LETO)
523 Shoichi Kaji (SKAJI)
525 Shawn Laffan (SLAFFAN)
527 Paul Evans (leonerd, PEVANS)
529 Håkon Hægland (hakonhagland, HAKONH)
531 nick nauwelaerts (INPHOBIA)
533
535 This software is copyright (c) 2011-2020 by Graham Ollis.
536 This is free software; you can redistribute it and/or modify it under
538 the same terms as the Perl 5 programming language system itself.
539perl v5.34.0 2022-03-07 Alien::Base(3)