1Alien::Base(3) User Contributed Perl Documentation Alien::Base(3)
2
6 Alien::Base - Base classes for Alien:: modules
7
9 version 2.40
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 unshift @PATH, Alien::MyLibrary->bin_dir;
254 dynamic_dir
256 my(@dir) = Alien::MyLibrary->dynamic_dir
257 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 Example usage:
264 use Env qw( @PATH );
266 unshift @PATH, Alien::MyLibrary->dynamic_dir;
268 alien_helper
270 my $helpers = Alien::MyLibrary->alien_helper;
271 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 For use with commands specified in and alienfile or in your "Build.Pl"
280 when used with Alien::Base::ModuleBuild.
281 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 As a concrete example, consider Alien::gmake, which provides the helper
289 "gmake":
290 package Alien::gmake;
292 ...
294 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 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 use alienfile;
312 plugin 'Probe::CommandLine' => (
314 command => 'nasm',
315 args => ['-v'],
316 match => qr/NASM version/,
317 );
318 share {
320 ...
321 plugin 'Extract' => 'tar.gz';
322 plugin 'Build::MSYS';
323 build [
325 'sh configure --prefix=%{alien.install.prefix}',
326 '%{gmake}',
327 '%{gmake} install',
328 ];
329 };
330 ...
332 inline_auto_include
334 my(@headers) = Alien::MyLibrary->inline_auto_include;
335 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 runtime_prop
343 my $hashref = Alien::MyLibrary->runtime_prop;
344 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 alt
350 my $new_alien = Alien::MyLibrary->alt($alt_name);
351 my $new_alien = $old_alien->alt($alt_name);
352 Returns an Alien::Base instance with the alternate configuration.
354 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 From your alienfile
362 use alienfile;
364 plugin 'PkgConfig' => (
366 pkg_name => [ 'libfoo', 'libbar', ],
367 );
368 Then in your base class:
370 package Alien::MyLibrary;
372 use base qw( Alien::Base );
374 use Role::Tiny::With qw( with );
375 with 'Alien::Role::Alt';
377 1;
379 Then you can use it:
381 use Alien::MyLibrary;
383 my $cflags = Alien::MyLibrary->alt('foo1')->cflags;
385 my $libs = Alien::MyLibrary->alt('foo1')->libs;
386 alt_names
388 my @alt_names = Alien::MyLibrary->alt_names
389 Returns the list of all available alternative configuration names.
391 alt_exists
393 my $bool = Alien::MyLibrary->alt_exists($alt_name)
394 Returns true if the given alternative configuration exists.
396
398 First check the Alien::Build::Manual::FAQ for questions that have
399 already been answered.
400 IRC: #native on irc.perl.org
402 (click for instant chatroom login)
404 <http://chat.mibbit.com/#native@irc.perl.org>
405 If you find a bug, please report it on the projects issue tracker on
407 GitHub:
408 <https://github.com/PerlAlien/Alien-Base/issues>
410 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 <https://groups.google.com/forum/#!forum/perl5-alien>
416 If you have implemented a new feature or fixed a bug, please open a
418 pull request.
419 <https://github.com/PerlAlien/Alien-Base/pulls>
421
423 • Alien::Build
424 • alienfile
426 • Alien
428 • Alien::Build::Manual::FAQ
430
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 Special thanks for the early development of "Alien::Base" go to:
437 Christian Walde (Mithaldu)
439 For productive conversations about component interoperability.
440 kmx For writing Alien::Tidyp from which I drew many of my initial
442 ideas.
443 David Mertens (run4flat)
445 For productive conversations about implementation.
446 Mark Nunberg (mordy, mnunberg)
448 For graciously teaching me about rpath and dynamic loading,
449
451 Author: Graham Ollis <plicease@cpan.org>
452 Contributors:
454 Diab Jerius (DJERIUS)
456 Roy Storey (KIWIROY)
458 Ilya Pavlov
460 David Mertens (run4flat)
462 Mark Nunberg (mordy, mnunberg)
464 Christian Walde (Mithaldu)
466 Brian Wightman (MidLifeXis)
468 Zaki Mughal (zmughal)
470 mohawk (mohawk2, ETJ)
472 Vikas N Kumar (vikasnkumar)
474 Flavio Poletti (polettix)
476 Salvador Fandiño (salva)
478 Gianni Ceccarelli (dakkar)
480 Pavel Shaydo (zwon, trinitum)
482 Kang-min Liu (劉康民, gugod)
484 Nicholas Shipp (nshp)
486 Juan Julián Merelo Guervós (JJ)
488 Joel Berger (JBERGER)
490 Petr Pisar (ppisar)
492 Lance Wicks (LANCEW)
494 Ahmad Fatoum (a3f, ATHREEF)
496 José Joaquín Atria (JJATRIA)
498 Duke Leto (LETO)
500 Shoichi Kaji (SKAJI)
502 Shawn Laffan (SLAFFAN)
504 Paul Evans (leonerd, PEVANS)
506 Håkon Hægland (hakonhagland, HAKONH)
508
510 This software is copyright (c) 2011-2020 by Graham Ollis.
511 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.
514perl v5.32.1 2021-05-13 Alien::Base(3)