Alien::Build::Manual::AlienUser

Section: User Contributed Perl Documentation (3)
Updated: 2019-04-22
Page Index

NAME

Alien::Build::Manual::AlienUser - Alien user documentation

VERSION

version 1.67

SYNOPSIS

 perldoc Alien::Build::Manual::AlienUser

DESCRIPTION

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.

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.

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.

Module::Build

 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.

ExtUtils::MakeMaker

 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.

Inline::C / Inline::CPP

 use Inline 0.56 with => 'Alien::Foo';

Although not widely used, Inline::C and Inline::CPP can be configured to use an Alien::Base based Alien with the "with" keyword.

ExtUtils::Depends

 use ExtUtils::MakeMaker;
 use ExtUtils::Depends;

 my $pkg = ExtUtils::Depends->new("Alien::Foo");

 WriteMakefile(
   ...
   $pkg->get_makefile_vars,
   ...
 );

ExtUtils::Depends works similar to Alien::Base::Wrapper, but uses the Inline interface under the covers.

Dist::Zilla

 [@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

FFI::Platypus

 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.

Inline::C

 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();
 }

tool

 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).

ENVIRONMENT

ALIEN_INSTALL_TYPE

Although the recommended way for a consumer to use an Alien::Base based Alien is to declare it as a static configure and build-time dependency, some consumers may prefer to fallback on using an Alien only when the consumer itself cannot detect the necessary package. In some cases the consumer may want the user to opt-in to using an Alien before requiring it.

To keep the interface consistent among Aliens, the consumer of the fallback opt-in Alien may fallback on the Alien if the environment variable "ALIEN_INSTALL_TYPE" is set to any value. The rationale is that by setting this environment variable the user is aware that Alien modules may be installed and have indicated consent. The actual implementation of this, by its nature would have to be in the consuming CPAN module.

This behavior should be documented in the consumer's POD.

See ``ENVIRONMENT'' in Alien::Build for more details on the usage of this environment variable.

AUTHOR

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)

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.