Alien::Build::Manual::AlienUser - Alien user documentation
version 1.55
perldoc Alien::Build::Manual::AlienUser
This document is intended for a user of an Alien::Base based Alien module's user. Although specifically geared for Alien::Base subclasses, it may have some useful hints for Alien in general.
Full working examples of how to use an Alien module are also bundled with Alien::Build in the distribution's example/user directory. Those examples use Alien::xz, which uses alienfile + Alien::Build + Alien::Base.
example/user
The following documentation will assume you are trying to use an Alien called Alien::Foo which provides the library libfoo and the command line tool foo. Many Aliens will only provide one or the other.
Alien::Foo
libfoo
foo
The best interface to use for using Alien::Base based aliens is Alien::Base::Wrapper. This allows you to combine multiple aliens together and handles a number of corner obscure corner cases that using Aliens directly does not. Also as of 0.64, Alien::Base::Wrapper comes bundled with Alien::Build and Alien::Base anyway, so it is not an extra dependency.
What follows are the main use cases.
use Module::Build; use Alien::Base::Wrapper qw( Alien::Foo !export ); use Alien::Foo; my $build = Module::Build->new( ... configure_requires => { 'Alien::Base::Wrapper' => '0', 'Alien::Foo' => '0', ... }, Alien::Base::Wrapper->mb_args ... ); $build->create_build_script;
The key gotcha for using Alien from a Build.PL for an XS module is remembering to explicitly making the Alien a configuration prerequisite.
Build.PL
use ExtUtils::MakeMaker; use Alien::Base::Wrapper qw( Alien::Foo !export ); WriteMakefile( ... CONFIGURE_REQUIRES => { 'Alien::Base::Wrapper' => '0', 'Alien::Foo' => '0', }, Alien::Base::Wrapper->mm_args ... );
MakeMaker is similar, make sure that you explicitly make your Alien a configure prerequisite.
[@Filter] -bundle = @Basic -remove = MakeMaker [Prereqs / ConfigureRequires] Alien::Foo = 0 [MakeMaker::Awesome] header = use Alien::Base::Wrapper qw( Alien::Foo !export ); WriteMakefile_arg = Alien::Base::Wrapper->mm_args
use FFI::Platypus; use Alien::Foo; my $ffi = FFI::Platypus->new( lib => [ Alien::Foo->dynamic_libs ], );
Not all Aliens provide dynamic libraries, but those that do can be used by FFI::Platypus. Unlike an XS module, these need to be a regular run time prerequisite.
use Inline with => 'Alien::Foo'; use Inline C => <<~'END'; #include <foo.h> const char *my_foo_wrapper() { foo(); } END sub exported_foo() { my_foo_wrapper(); }
use Alien::Foo; use Env qw( @PATH ); unshift @ENV, Alien::Foo->bin_dir; system 'foo', '--bar', '--baz';
Some Aliens provide tools instead of or in addition to a library. You need to add them to the PATH environment variable though. (Unless the tool is already provided by the system, in which case it is already in the path and the bin_dir method will return an empty list).
PATH
bin_dir
Author: Graham Ollis <plicease@cpan.org>
Contributors:
Diab Jerius (DJERIUS)
Roy Storey
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 Pisar (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)
This software is copyright (c) 2011-2018 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.
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.