1Alien::Base(3) User Contributed Perl Documentation Alien::Base(3)
2
6 Alien::Base - Base classes for Alien:: modules
7
9 version 1.55
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 Returns the install type that was used when "Alien::MyLibrary" was
211 installed. Types include:
212 system
214 The library was provided by the operating system
215 share
217 The library was not available when "Alien::MyLibrary" was
218 installed, so it was built from source code, either downloaded from
219 the Internet or bundled with "Alien::MyLibrary".
220 config
222 my $value = Alien::MyLibrary->config($key);
223 Returns the configuration data as determined during the install of
225 Alien::MyLibrary. For the appropriate config keys, see
226 Alien::Base::ModuleBuild::API#CONFIG-DATA.
227 This is not typically used by Alien::Base and alienfile, but a
229 compatible interface will be provided.
230 dynamic_libs
232 my @dlls = Alien::MyLibrary->dynamic_libs;
233 my($dll) = Alien::MyLibrary->dynamic_libs;
234 Returns a list of the dynamic library or shared object files for the
236 alien software.
237 bin_dir
239 my(@dir) = Alien::MyLibrary->bin_dir
240 Returns a list of directories with executables in them. For a "system"
242 install this will be an empty list. For a "share" install this will be
243 a directory under "dist_dir" named "bin" if it exists. You may wish to
244 override the default behavior if you have executables or scripts that
245 get installed into non-standard locations.
246 Example usage:
248 use Env qw( @PATH );
250 unshft @PATH, Alien::MyLibrary->bin_dir;
252 alien_helper
254 my $helpers = Alien::MyLibrary->alien_helper;
255 Returns a hash reference of helpers provided by the Alien module. The
257 keys are helper names and the values are code references. The code
258 references will be executed at command time and the return value will
259 be interpolated into the command before execution. The default
260 implementation returns an empty hash reference, and you are expected to
261 override the method to create your own helpers.
262 For use with commands specified in and alienfile or in your "Build.Pl"
264 when used with Alien::Base::ModuleBuild.
265 Helpers allow users of your Alien module to use platform or environment
267 determined logic to compute command names or arguments in your
268 installer logic. Helpers allow you to do this without making your
269 Alien module a requirement when a build from source code is not
270 necessary.
271 As a concrete example, consider Alien::gmake, which provides the helper
273 "gmake":
274 package Alien::gmake;
276 ...
278 sub alien_helper {
280 my($class) = @_;
281 return {
282 gmake => sub {
283 # return the executable name for GNU make,
284 # usually either make or gmake depending on
285 # the platform and environment
286 $class->exe;
287 }
288 },
289 }
290 Now consider Alien::nasm. "nasm" requires GNU Make to build from
292 source code, but if the system "nasm" package is installed we don't
293 need it. From the alienfile of "Alien::nasm":
294 use alienfile;
296 plugin 'Probe::CommandLine' => (
298 command => 'nasm',
299 args => ['-v'],
300 match => qr/NASM version/,
301 );
302 share {
304 ...
305 plugin 'Extract' => 'tar.gz';
306 plugin 'Build::MSYS';
307 build [
309 'sh configure --prefix=%{alien.install.prefix}',
310 '%{gmake}',
311 '%{gmake} install',
312 ];
313 };
314 ...
316 inline_auto_include
318 my(@headers) = Alien::MyLibrary->inline_auto_include;
319 List of header files to automatically include in inline C and C++ code
321 when using Inline::C or Inline::CPP. This is provided as a public
322 interface primarily so that it can be overridden at run time. This can
323 also be specified in your "Build.PL" with Alien::Base::ModuleBuild
324 using the "alien_inline_auto_include" property.
325 runtime_prop
327 my $hashref = Alien::MyLibrary->runtime_prop;
328 Returns a hash reference of the runtime properties computed by
330 Alien::Build during its install process. If the Alien::Base based
331 Alien was not built using Alien::Build, then this will return undef.
332 alt
334 my $new_alien = Alien::MyLibrary->alt($alt_name);
335 my $new_alien = $old_alien->alt($alt_name);
336 Returns an Alien::Base instance with the alternate configuration.
338 Some packages come with multiple libraries, and multiple ".pc" files to
340 use with them. This method can be used with "pkg-config" plugins to
341 access different configurations. (It could also be used with non-pkg-
342 config based packages too, though there are not as of this writing any
343 build time plugins that take advantage of this feature).
344 From your alienfile
346 use alienfile;
348 plugin 'PkgConfig' => (
350 pkg_name => [ 'libfoo', 'libbar', ],
351 );
352 Then in your base class:
354 package Alien::MyLibrary;
356 use base qw( Alien::Base );
358 use Role::Tiny::With qw( with );
359 with 'Alien::Role::Alt';
361 1;
363 Then you can use it:
365 use Alien::MyLibrary;
367 my $cflags = Alien::MyLibrary->alt('foo1')->cflags;
369 my $libs = Alien::MyLibrary->alt('foo1')->libs;
370 alt_names
372 my @alt_names = Alien::MyLibrary->alt_names
373 Returns the list of all available alternative configuration names.
375 alt_exists
377 my $bool = Alien::MyLibrary->alt_exists($alt_name)
378 Returns true if the given alternative configuration exists.
380
382 First check the Alien::Build::Manual::FAQ for questions that have
383 already been answered.
384 IRC: #native on irc.perl.org
386 (click for instant chatroom login)
388 <http://chat.mibbit.com/#native@irc.perl.org>
389 If you find a bug, please report it on the projects issue tracker on
391 GitHub:
392 <https://github.com/Perl5-Alien/Alien-Base/issues>
394 Development is discussed on the projects google groups. This is also a
396 reasonable place to post a question if you don't want to open an issue
397 in GitHub.
398 <https://groups.google.com/forum/#!forum/perl5-alien>
400 If you have implemented a new feature or fixed a bug, please open a
402 pull request.
403 <https://github.com/Perl5-Alien/Alien-Base/pulls>
405
407 · Alien::Build
408 · alienfile
410 · Alien
412 · Alien::Build::Manual::FAQ
414
416 "Alien::Base" was originally written by Joel Berger, and that code is
417 still Copyright (C) 2012-2017 Joel Berger. It has the same license as
418 the rest of the Alien::Build.
419 Special thanks for the early development of "Alien::Base" go to:
421 Christian Walde (Mithaldu)
423 For productive conversations about component interoperability.
424 kmx For writing Alien::Tidyp from which I drew many of my initial
426 ideas.
427 David Mertens (run4flat)
429 For productive conversations about implementation.
430 Mark Nunberg (mordy, mnunberg)
432 For graciously teaching me about rpath and dynamic loading,
433
435 Author: Graham Ollis <plicease@cpan.org>
436 Contributors:
438 Diab Jerius (DJERIUS)
440 Roy Storey
442 Ilya Pavlov
444 David Mertens (run4flat)
446 Mark Nunberg (mordy, mnunberg)
448 Christian Walde (Mithaldu)
450 Brian Wightman (MidLifeXis)
452 Zaki Mughal (zmughal)
454 mohawk (mohawk2, ETJ)
456 Vikas N Kumar (vikasnkumar)
458 Flavio Poletti (polettix)
460 Salvador Fandiño (salva)
462 Gianni Ceccarelli (dakkar)
464 Pavel Shaydo (zwon, trinitum)
466 Kang-min Liu (劉康民, gugod)
468 Nicholas Shipp (nshp)
470 Juan Julián Merelo Guervós (JJ)
472 Joel Berger (JBERGER)
474 Petr Pisar (ppisar)
476 Lance Wicks (LANCEW)
478 Ahmad Fatoum (a3f, ATHREEF)
480 José Joaquín Atria (JJATRIA)
482 Duke Leto (LETO)
484 Shoichi Kaji (SKAJI)
486 Shawn Laffan (SLAFFAN)
488 Paul Evans (leonerd, PEVANS)
490
492 This software is copyright (c) 2011-2018 by Graham Ollis.
493 This is free software; you can redistribute it and/or modify it under
495 the same terms as the Perl 5 programming language system itself.
496perl v5.28.1 2019-02-24 Alien::Base(3)