Alien::Base(3) User Contributed Perl Documentation Alien::Base(3)
NAME
Alien::Base - Base classes for Alien:: modules
VERSION
version 2.80
SYNOPSIS
package Alien::MyLibrary;
use strict;
use warnings;
use parent 'Alien::Base';
1;
(for details on the "Makefile.PL" or "Build.PL" and alienfile that
should be bundled with your Alien::Base subclass, please see
Alien::Build::Manual::AlienAuthor).
Then a "MyLibrary::XS" can use "Alien::MyLibrary" in its "Makefile.PL":
use Alien::MyLibrary
use ExtUtils::MakeMaker;
use Alien::Base::Wrapper qw( Alien::MyLibrary !export );
use Config;
WriteMakefile(
...
Alien::Base::Wrapper->mm_args,
...
);
Or if you prefer Module::Build, in its "Build.PL":
use Alien::MyLibrary;
use Module::Build 0.28; # need at least 0.28
use Alien::Base::Wrapper qw( Alien::MyLibrary !export );
my $builder = Module::Build->new(
...
Alien::Base::Wrapper->mb_args,
...
);
$builder->create_build_script;
Or if you are using ExtUtils::Depends:
use ExtUtils::MakeMaker;
use ExtUtils::Depends;
my $eud = ExtUtils::Depends->new(qw( MyLibrary::XS Alien::MyLibrary ));
WriteMakefile(
...
$eud->get_makefile_vars
);
If you are using Alien::Base::ModuleBuild instead of the recommended
Alien::Build and alienfile, then in your "MyLibrary::XS" module, you
may need something like this in your main ".pm" file IF your library
uses dynamic libraries:
package MyLibrary::XS;
use Alien::MyLibrary; # may only be needed if you are using Alien::Base::ModuleBuild
...
Or you can use it from an FFI module:
package MyLibrary::FFI;
use Alien::MyLibrary;
use FFI::Platypus;
use FFI::CheckLib 0.28 qw( find_lib_or_die );
my $ffi = FFI::Platypus->new;
$ffi->lib(find_lib_or_die lib => 'mylib', alien => ['Alien::MyLibrary']);
$ffi->attach( 'my_library_function' => [] => 'void' );
You can even use it with Inline (C and C++ languages are supported):
package MyLibrary::Inline;
use Alien::MyLibrary;
# Inline 0.56 or better is required
use Inline 0.56 with => 'Alien::MyLibrary';
...
DESCRIPTION
NOTE: Alien::Base::ModuleBuild is no longer bundled with Alien::Base
and has been spun off into a separate distribution.
Alien::Base::ModuleBuild will be a prerequisite for Alien::Base until
October 1, 2017. If you are using Alien::Base::ModuleBuild you need to
make sure it is declared as a "configure_requires" in your "Build.PL".
You may want to also consider using Alien::Base and alienfile as a more
modern alternative.
Alien::Base comprises base classes to help in the construction of
"Alien::" modules. Modules in the Alien namespace are used to locate
and install (if necessary) external libraries needed by other Perl
modules.
This is the documentation for the Alien::Base module itself. If you are
starting out you probably want to do so from one of these documents:
Alien::Build::Manual::AlienUser
For users of an "Alien::libfoo" that is implemented using
Alien::Base. (The developer of "Alien::libfoo" should provide the
documentation necessary, but if not, this is the place to start).
Alien::Build::Manual::AlienAuthor
If you are writing your own Alien based on Alien::Build and
Alien::Base.
Alien::Build::Manual::FAQ
If you have a common question that has already been answered, like
"How do I use alienfile with some build system".
Alien::Build::Manual::PluginAuthor
This is for the brave souls who want to write plugins that will
work with Alien::Build + alienfile.
Before using an Alien::Base based Alien directly, please consider the
following advice:
If you are wanting to use an Alien::Base based Alien with an XS module
using ExtUtils::MakeMaker or Module::Build, it is highly recommended
that you use Alien::Base::Wrapper, rather than using the Alien
directly, because it handles a number of sharp edges and avoids
pitfalls common when trying to use an Alien directly with
ExtUtils::MakeMaker.
In the same vein, if you are wanting to use an Alien::Base based Alien
with an XS module using Dist::Zilla it is highly recommended that you
use Dist::Zilla::Plugin::AlienBase::Wrapper for the same reasons.
As of version 0.28, FFI::CheckLib has a good interface for working with
Alien::Base based Aliens in fallback mode, which is recommended.
You should typically only be using an Alien::Base based Alien directly,
if you need to integrate it with some other system, or if it is a tool
based Alien that you don't need to link.
The above synopsis and linked manual documents will lead you down the
right path, but it is worth knowing before you read further in this
document.
METHODS
In the example snippets here, "Alien::MyLibrary" represents any
subclass of Alien::Base.
dist_dir
my $dir = Alien::MyLibrary->dist_dir;
Returns the directory that contains the install root for the packaged
software, if it was built from install (i.e., if "install_type" is
"share").
new
my $alien = Alien::MyLibrary->new;
Creates an instance of an Alien::Base object. This is typically
unnecessary.
cflags
my $cflags = Alien::MyLibrary->cflags;
use Text::ParseWords qw( shellwords );
my @cflags = shellwords( Alien::MyLibrary->cflags );
Returns the C compiler flags necessary to compile an XS module using
the alien software. If you need this in list form (for example if you
are calling system with a list argument) you can pass this value into
"shellwords" from the Perl core Text::ParseWords module.
cflags_static
my $cflags = Alien::MyLibrary->cflags_static;
Same as "cflags" above, but gets the static compiler flags, if they are
different.
libs
my $libs = Alien::MyLibrary->libs;
use Text::ParseWords qw( shellwords );
my @cflags = shellwords( Alien::MyLibrary->libs );
Returns the library linker flags necessary to link an XS module against
the alien software. If you need this in list form (for example if you
are calling system with a list argument) you can pass this value into
"shellwords" from the Perl core Text::ParseWords module.
libs_static
my $libs = Alien::MyLibrary->libs_static;
Same as "libs" above, but gets the static linker flags, if they are
different.
version
my $version = Alien::MyLibrary->version;
Returns the version of the alienized library or tool that was
determined at install time.
atleast_version
exact_version
max_version
my $ok = Alien::MyLibrary->atleast_version($wanted_version);
my $ok = Alien::MyLibrary->exact_version($wanted_version);
my $ok = Alien::MyLibrary->max_version($wanted_version);
Returns true if the version of the alienized library or tool is at
least, exactly, or at most the version specified, respectively.
version_cmp
$cmp = Alien::MyLibrary->version_cmp($x, $y)
Comparison method used by "atleast_version", "exact_version" and
"max_version". May be useful to implement custom comparisons, or for
subclasses to overload to get different version comparison semantics
than the default rules, for packages that have some other rules than
the pkg-config behaviour.
Should return a number less than, equal to, or greater than zero;
similar in behaviour to the "<=>" and "cmp" operators.
install_type
my $install_type = Alien::MyLibrary->install_type;
my $bool = Alien::MyLibrary->install_type($install_type);
Returns the install type that was used when "Alien::MyLibrary" was
installed. If a type is provided (the second form in the synopsis)
returns true if the actual install type matches. Types include:
system
The library was provided by the operating system
share
The library was not available when "Alien::MyLibrary" was
installed, so it was built from source code, either downloaded from
the Internet or bundled with "Alien::MyLibrary".
config
my $value = Alien::MyLibrary->config($key);
Returns the configuration data as determined during the install of
"Alien::MyLibrary". For the appropriate config keys, see "CONFIG DATA"
in Alien::Base::ModuleBuild::API.
This is not typically used by Alien::Base and alienfile, but a
compatible interface will be provided.
dynamic_libs
my @dlls = Alien::MyLibrary->dynamic_libs;
my($dll) = Alien::MyLibrary->dynamic_libs;
Returns a list of the dynamic library or shared object files for the
alien software.
bin_dir
my(@dir) = Alien::MyLibrary->bin_dir
Returns a list of directories with executables in them. For a "system"
install this will be an empty list. For a "share" install this will be
a directory under "dist_dir" named "bin" if it exists. You may wish to
override the default behavior if you have executables or scripts that
get installed into non-standard locations.
Example usage:
use Env qw( @PATH );
unshift @PATH, Alien::MyLibrary->bin_dir;
dynamic_dir
my(@dir) = Alien::MyLibrary->dynamic_dir
Returns the dynamic dir for a dynamic build (if the main build is
static). For a "share" install this will be a directory under
"dist_dir" named "dynamic" if it exists. System builds return an empty
list.
Example usage:
use Env qw( @PATH );
unshift @PATH, Alien::MyLibrary->dynamic_dir;
alien_helper
my $helpers = Alien::MyLibrary->alien_helper;
Returns a hash reference of helpers provided by the Alien module. The
keys are helper names and the values are code references. The code
references will be executed at command time and the return value will
be interpolated into the command before execution. The default
implementation returns an empty hash reference, and you are expected to
override the method to create your own helpers.
For use with commands specified in and alienfile or in your "Build.Pl"
when used with Alien::Base::ModuleBuild.
Helpers allow users of your Alien module to use platform or environment
determined logic to compute command names or arguments in your
installer logic. Helpers allow you to do this without making your
Alien module a requirement when a build from source code is not
necessary.
As a concrete example, consider Alien::gmake, which provides the helper
"gmake":
package Alien::gmake;
...
sub alien_helper {
my($class) = @_;
return {
gmake => sub {
# return the executable name for GNU make,
# usually either make or gmake depending on
# the platform and environment
$class->exe;
}
},
}
Now consider Alien::nasm. "nasm" requires GNU Make to build from
source code, but if the system "nasm" package is installed we don't
need it. From the alienfile of "Alien::nasm":
use alienfile;
plugin 'Probe::CommandLine' => (
command => 'nasm',
args => ['-v'],
match => qr/NASM version/,
);
share {
...
plugin 'Extract' => 'tar.gz';
plugin 'Build::MSYS';
build [
'sh configure --prefix=%{alien.install.prefix}',
'%{gmake}',
'%{gmake} install',
];
};
...
inline_auto_include
my(@headers) = Alien::MyLibrary->inline_auto_include;
List of header files to automatically include in inline C and C++ code
when using Inline::C or Inline::CPP. This is provided as a public
interface primarily so that it can be overridden at run time. This can
also be specified in your "Build.PL" with Alien::Base::ModuleBuild
using the "alien_inline_auto_include" property.
runtime_prop
my $hashref = Alien::MyLibrary->runtime_prop;
Returns a hash reference of the runtime properties computed by
Alien::Build during its install process. If the Alien::Base based
Alien was not built using Alien::Build, then this will return undef.
alt
my $new_alien = Alien::MyLibrary->alt($alt_name);
my $new_alien = $old_alien->alt($alt_name);
Returns an Alien::Base instance with the alternate configuration.
Some packages come with multiple libraries, and multiple ".pc" files to
use with them. This method can be used with "pkg-config" plugins to
access different configurations. (It could also be used with non-pkg-
config based packages too, though there are not as of this writing any
build time plugins that take advantage of this feature).
From your alienfile
use alienfile;
plugin 'PkgConfig' => (
pkg_name => [ 'libfoo', 'libbar', ],
);
Then in your base class works like normal:
package Alien::MyLibrary;
use parent qw( Alien::Base );
1;
Then you can use it:
use Alien::MyLibrary;
my $cflags = Alien::MyLibrary->alt('foo1')->cflags;
my $libs = Alien::MyLibrary->alt('foo1')->libs;
alt_names
my @alt_names = Alien::MyLibrary->alt_names
Returns the list of all available alternative configuration names.
alt_exists
my $bool = Alien::MyLibrary->alt_exists($alt_name)
Returns true if the given alternative configuration exists.
SUPPORT AND CONTRIBUTING
First check the Alien::Build::Manual::FAQ for questions that have
already been answered.
IRC: #native on irc.perl.org
(click for instant chatroom login)
<http://chat.mibbit.com/#native@irc.perl.org>
If you find a bug, please report it on the projects issue tracker on
GitHub:
<https://github.com/PerlAlien/Alien-Build/issues>
Development is discussed on the projects google groups. This is also a
reasonable place to post a question if you don't want to open an issue
in GitHub.
<https://groups.google.com/forum/#!forum/perl5-alien>
If you have implemented a new feature or fixed a bug, please open a
pull request.
<https://github.com/PerlAlien/Alien-Build/pulls>
SEE ALSO
o Alien::Build(3)
o alienfile(3)
o Alien(3)
o Alien::Build::Manual::FAQ(3)
THANKS
"Alien::Base" was originally written by Joel Berger, and that code is
still Copyright (C) 2012-2017 Joel Berger. It has the same license as
the rest of the Alien::Build.
Special thanks for the early development of "Alien::Base" go to:
Christian Walde (Mithaldu)
For productive conversations about component interoperability.
kmx For writing Alien::Tidyp from which I drew many of my initial
ideas.
David Mertens (run4flat)
For productive conversations about implementation.
Mark Nunberg (mordy, mnunberg)
For graciously teaching me about rpath and dynamic loading,
AUTHOR
Author: Graham Ollis <plicease@cpan.org>
Contributors:
Diab Jerius (DJERIUS)
Roy Storey (KIWIROY)
Ilya Pavlov
David Mertens (run4flat)
Mark Nunberg (mordy, mnunberg)
Christian Walde (Mithaldu)
Brian Wightman (MidLifeXis)
Zaki Mughal (zmughal)
mohawk (mohawk2, ETJ)
Vikas N Kumar (vikasnkumar)
Flavio Poletti (polettix)
Salvador Fandino (salva)
Gianni Ceccarelli (dakkar)
Pavel Shaydo (zwon, trinitum)
Kang-min Liu (<?><?><?>, gugod)
Nicholas Shipp (nshp)
Juan Julian Merelo Guervos (JJ)
Joel Berger (JBERGER)
Petr Pisar (ppisar)
Lance Wicks (LANCEW)
Ahmad Fatoum (a3f, ATHREEF)
Jose Joaquin Atria (JJATRIA)
Duke Leto (LETO)
Shoichi Kaji (SKAJI)
Shawn Laffan (SLAFFAN)
Paul Evans (leonerd, PEVANS)
Hakon Haegland (hakonhagland, HAKONH)
nick nauwelaerts (INPHOBIA)
Florian Weimer
COPYRIGHT AND LICENSE
This software is copyright (c) 2011-2022 by Graham Ollis.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
perl v5.34.1 2023-05-11 Alien::Base(3)
alien-build 2.800.0 - Generated Mon Apr 8 15:34:40 CDT 2024