Alien::Build::Manual::AlienUser - Alien user documentation
perldoc Alien::Build::Manual::AlienUser
User Contributed Perl Documentation
Alien::Build::Manual::AlienUser(3)
NAME
Alien::Build::Manual::AlienUser - Alien user documentation
VERSION
version 1.89
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 (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 Fandio (salva)
Gianni Ceccarelli (dakkar)
Pavel Shaydo (zwon, trinitum)
Kang-min Liu (, gugod)
Nicholas Shipp (nshp)
Juan Julin Merelo Guervs (JJ)
Joel Berger (JBERGER)
Petr Pisar (ppisar)
Lance Wicks (LANCEW)
Ahmad Fatoum (a3f, ATHREEF)
Jos Joaqun Atria (JJATRIA)
Duke Leto (LETO)
Shoichi Kaji (SKAJI)
Shawn Laffan (SLAFFAN)
Paul Evans (leonerd, PEVANS)
COPYRIGHT AND LICENSE
This software is copyright (c) 2011-2019 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.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+--------------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+--------------------------------+
|Availability | library/perl-5/alien-build-532 |
+---------------+--------------------------------+
|Stability | Volatile |
+---------------+--------------------------------+
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from
http://www.cpan.org/authors/id/P/PL/PLICEASE/Alien-Build-1.89.tar.gz.
Further information about this software can be found on the open source
community website at http://search.cpan.org/dist/Alien-Build/.
perl v5.32.0 2019-09-25
Alien::Build::Manual::AlienUser(3)