NAME

Alien::Base - Base classes for Alien:: modules

VERSION

version 2.84

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. For this use case it is recommended to use is_system_install or is_share_install instead as these are less prone to typographical errors.

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.

is_system_install

my $type = $build->is_system_install;

Returns true if the alien is a system install type.

is_share_install

my $type = $build->is_share_install;

Returns true if the alien is a share install type.

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)

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

THANKS

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 Fandiño (salva)

Gianni Ceccarelli (dakkar)

Pavel Shaydo (zwon, trinitum)

Kang-min Liu (劉康民, gugod)

Nicholas Shipp (nshp)

Juan Julián Merelo Guervós (JJ)

Joel Berger (JBERGER)

Petr Písař (ppisar)

Lance Wicks (LANCEW)

Ahmad Fatoum (a3f, ATHREEF)

José Joaquín Atria (JJATRIA)

Duke Leto (LETO)

Shoichi Kaji (SKAJI)

Shawn Laffan (SLAFFAN)

Paul Evans (leonerd, PEVANS)

Håkon Hægland (hakonhagland, HAKONH)

nick nauwelaerts (INPHOBIA)

Florian Weimer

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install Alien::Build, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Alien::Build

CPAN shell

perl -MCPAN -e shell
install Alien::Build

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)