1Alien::Base(3) User Contributed Perl Documentation Alien::Base(3)
2
6 Alien::Base - Base classes for Alien:: modules
7
9 version 2.17
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 my $ffi = FFI::Platypus->new;
81 $ffi->lib(Alien::MyLibrary->dynamic_libs);
82 $ffi->attach( 'my_library_function' => [] => 'void' );
84 You can even use it with Inline (C and C++ languages are supported):
86 package MyLibrary::Inline;
88 use Alien::MyLibrary;
90 # Inline 0.56 or better is required
91 use Inline 0.56 with => 'Alien::MyLibrary';
92 ...
93
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 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 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 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 Alien::Build::Manual::AlienAuthor
117 If you are writing your own Alien based on Alien::Build and
118 Alien::Base.
119 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 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
129 In the example snippets here, "Alien::MyLibrary" represents any
130 subclass of Alien::Base.
131 dist_dir
133 my $dir = Alien::MyLibrary->dist_dir;
134 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 new
140 my $alien = Alien::MyLibrary->new;
141 Creates an instance of an Alien::Base object. This is typically
143 unnecessary.
144 cflags
146 my $cflags = Alien::MyLibrary->cflags;
147 use Text::ParseWords qw( shellwords );
149 my @cflags = shellwords( Alien::MyLibrary->cflags );
150 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 cflags_static
157 my $cflags = Alien::MyLibrary->cflags_static;
158 Same as "cflags" above, but gets the static compiler flags, if they are
160 different.
161 libs
163 my $libs = Alien::MyLibrary->libs;
164 use Text::ParseWords qw( shellwords );
166 my @cflags = shellwords( Alien::MyLibrary->libs );
167 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 libs_static
174 my $libs = Alien::MyLibrary->libs_static;
175 Same as "libs" above, but gets the static linker flags, if they are
177 different.
178 version
180 my $version = Alien::MyLibrary->version;
181 Returns the version of the alienized library or tool that was
183 determined at install time.
184 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 Returns true if the version of the alienized library or tool is at
193 least, exactly, or at most the version specified, respectively.
194 version_cmp
196 $cmp = Alien::MyLibrary->version_cmp($x, $y)
197 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 Should return a number less than, equal to, or greater than zero;
205 similar in behaviour to the "<=>" and "cmp" operators.
206 install_type
208 my $install_type = Alien::MyLibrary->install_type;
209 my $bool = Alien::MyLibrary->install_type($install_type);
210 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 system
216 The library was provided by the operating system
217 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 config
224 my $value = Alien::MyLibrary->config($key);
225 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 This is not typically used by Alien::Base and alienfile, but a
231 compatible interface will be provided.
232 dynamic_libs
234 my @dlls = Alien::MyLibrary->dynamic_libs;
235 my($dll) = Alien::MyLibrary->dynamic_libs;
236 Returns a list of the dynamic library or shared object files for the
238 alien software.
239 bin_dir
241 my(@dir) = Alien::MyLibrary->bin_dir
242 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 Example usage:
250 use Env qw( @PATH );
252 unshft @PATH, Alien::MyLibrary->bin_dir;
254 alien_helper
256 my $helpers = Alien::MyLibrary->alien_helper;
257 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 For use with commands specified in and alienfile or in your "Build.Pl"
266 when used with Alien::Base::ModuleBuild.
267 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 As a concrete example, consider Alien::gmake, which provides the helper
275 "gmake":
276 package Alien::gmake;
278 ...
280 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 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 use alienfile;
298 plugin 'Probe::CommandLine' => (
300 command => 'nasm',
301 args => ['-v'],
302 match => qr/NASM version/,
303 );
304 share {
306 ...
307 plugin 'Extract' => 'tar.gz';
308 plugin 'Build::MSYS';
309 build [
311 'sh configure --prefix=%{alien.install.prefix}',
312 '%{gmake}',
313 '%{gmake} install',
314 ];
315 };
316 ...
318 inline_auto_include
320 my(@headers) = Alien::MyLibrary->inline_auto_include;
321 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 runtime_prop
329 my $hashref = Alien::MyLibrary->runtime_prop;
330 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 alt
336 my $new_alien = Alien::MyLibrary->alt($alt_name);
337 my $new_alien = $old_alien->alt($alt_name);
338 Returns an Alien::Base instance with the alternate configuration.
340 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 From your alienfile
348 use alienfile;
350 plugin 'PkgConfig' => (
352 pkg_name => [ 'libfoo', 'libbar', ],
353 );
354 Then in your base class:
356 package Alien::MyLibrary;
358 use base qw( Alien::Base );
360 use Role::Tiny::With qw( with );
361 with 'Alien::Role::Alt';
363 1;
365 Then you can use it:
367 use Alien::MyLibrary;
369 my $cflags = Alien::MyLibrary->alt('foo1')->cflags;
371 my $libs = Alien::MyLibrary->alt('foo1')->libs;
372 alt_names
374 my @alt_names = Alien::MyLibrary->alt_names
375 Returns the list of all available alternative configuration names.
377 alt_exists
379 my $bool = Alien::MyLibrary->alt_exists($alt_name)
380 Returns true if the given alternative configuration exists.
382
384 First check the Alien::Build::Manual::FAQ for questions that have
385 already been answered.
386 IRC: #native on irc.perl.org
388 (click for instant chatroom login)
390 <http://chat.mibbit.com/#native@irc.perl.org>
391 If you find a bug, please report it on the projects issue tracker on
393 GitHub:
394 <https://github.com/Perl5-Alien/Alien-Base/issues>
396 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 <https://groups.google.com/forum/#!forum/perl5-alien>
402 If you have implemented a new feature or fixed a bug, please open a
404 pull request.
405 <https://github.com/Perl5-Alien/Alien-Base/pulls>
407
409 · Alien::Build
410 · alienfile
412 · Alien
414 · Alien::Build::Manual::FAQ
416
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 Special thanks for the early development of "Alien::Base" go to:
423 Christian Walde (Mithaldu)
425 For productive conversations about component interoperability.
426 kmx For writing Alien::Tidyp from which I drew many of my initial
428 ideas.
429 David Mertens (run4flat)
431 For productive conversations about implementation.
432 Mark Nunberg (mordy, mnunberg)
434 For graciously teaching me about rpath and dynamic loading,
435
437 Author: Graham Ollis <plicease@cpan.org>
438 Contributors:
440 Diab Jerius (DJERIUS)
442 Roy Storey (KIWIROY)
444 Ilya Pavlov
446 David Mertens (run4flat)
448 Mark Nunberg (mordy, mnunberg)
450 Christian Walde (Mithaldu)
452 Brian Wightman (MidLifeXis)
454 Zaki Mughal (zmughal)
456 mohawk (mohawk2, ETJ)
458 Vikas N Kumar (vikasnkumar)
460 Flavio Poletti (polettix)
462 Salvador Fandiño (salva)
464 Gianni Ceccarelli (dakkar)
466 Pavel Shaydo (zwon, trinitum)
468 Kang-min Liu (劉康民, gugod)
470 Nicholas Shipp (nshp)
472 Juan Julián Merelo Guervós (JJ)
474 Joel Berger (JBERGER)
476 Petr Pisar (ppisar)
478 Lance Wicks (LANCEW)
480 Ahmad Fatoum (a3f, ATHREEF)
482 José Joaquín Atria (JJATRIA)
484 Duke Leto (LETO)
486 Shoichi Kaji (SKAJI)
488 Shawn Laffan (SLAFFAN)
490 Paul Evans (leonerd, PEVANS)
492
494 This software is copyright (c) 2011-2020 by Graham Ollis.
495 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.
498perl v5.30.2 2020-03-20 Alien::Base(3)