.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Alien::Build::Manual::AlienUser 3"
.TH Alien::Build::Manual::AlienUser 3 "2021-10-28" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Alien::Build::Manual::AlienUser \- Alien user documentation
.SH "VERSION"
.IX Header "VERSION"
version 2.45
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& perldoc Alien::Build::Manual::AlienUser
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
Full working examples of how to use an Alien module are also bundled
with Alien::Build in the distribution's \f(CW\*(C`example/user\*(C'\fR directory.
Those examples use Alien::xz, which uses alienfile + Alien::Build
+ Alien::Base.
.PP
The following documentation will assume you are trying to use an Alien
called \f(CW\*(C`Alien::Foo\*(C'\fR which provides the library \f(CW\*(C`libfoo\*(C'\fR and the command
line tool \f(CW\*(C`foo\*(C'\fR.  Many Aliens will only provide one or the other.
.PP
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.
.PP
What follows are the main use cases.
.SS "ExtUtils::MakeMaker"
.IX Subsection "ExtUtils::MakeMaker"
.Vb 2
\& use ExtUtils::MakeMaker;
\& use Alien::Base::Wrapper ();
\& 
\& WriteMakefile(
\&   Alien::Base::Wrapper\->new(\*(AqAlien::Foo\*(Aq)\->mm_args2(
\&     NAME => \*(AqFOO::XS\*(Aq,
\&     ...
\&   ),
\& );
.Ve
.PP
Alien::Base::Wrapper will take a hash of \f(CW\*(C`WriteMakefile\*(C'\fR arguments
and insert the appropriate compiler and linker flags for you.  This
is recommended over doing this yourself as the exact incantation to
get \s-1EUMM\s0 to work is tricky to get right.
.PP
The \f(CW\*(C`mm_args2\*(C'\fR method will also set your \f(CW\*(C`CONFIGURE_REQUIRES\*(C'\fR for
Alien::Base::Wrapper, ExtUtils::MakeMaker and any aliens that
you specify.
.SS "Module::Build"
.IX Subsection "Module::Build"
.Vb 3
\& use Module::Build;
\& use Alien::Base::Wrapper qw( Alien::Foo !export );
\& use Alien::Foo;
\& 
\& my $build = Module::Build\->new(
\&   ...
\&   configure_requires => {
\&     \*(AqAlien::Base::Wrapper\*(Aq => \*(Aq0\*(Aq,
\&     \*(AqAlien::Foo\*(Aq           => \*(Aq0\*(Aq,
\&     ...
\&   },
\&   Alien::Base::Wrapper\->mb_args,
\&   ...
\& );
\& 
\& $build\->create_build_script;
.Ve
.PP
For Module::Build you can also use Alien::Base::Wrapper, but
you will have to specify the \f(CW\*(C`configure_requires\*(C'\fR yourself.
.SS "Inline::C / Inline::CPP"
.IX Subsection "Inline::C / Inline::CPP"
.Vb 1
\& use Inline 0.56 with => \*(AqAlien::Foo\*(Aq;
.Ve
.PP
Inline::C and Inline::CPP can be configured
to use an Alien::Base based Alien with the \f(CW\*(C`with\*(C'\fR keyword.
.SS "ExtUtils::Depends"
.IX Subsection "ExtUtils::Depends"
.Vb 2
\& use ExtUtils::MakeMaker;
\& use ExtUtils::Depends;
\& 
\& my $pkg = ExtUtils::Depends\->new("Alien::Foo");
\& 
\& WriteMakefile(
\&   ...
\&   $pkg\->get_makefile_vars,
\&   ...
\& );
.Ve
.PP
ExtUtils::Depends works similar to Alien::Base::Wrapper, but uses
the Inline interface under the covers.
.SS "Dist::Zilla"
.IX Subsection "Dist::Zilla"
.Vb 3
\& [@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
.Ve
.SS "FFI::Platypus"
.IX Subsection "FFI::Platypus"
Requires \f(CW\*(C`Alien::Foo\*(C'\fR always:
.PP
.Vb 2
\& use FFI::Platypus;
\& use Alien::Foo;
\& 
\& my $ffi = FFI::Platypus\->new(
\&   lib => [ Alien::Foo\->dynamic_libs ],
\& );
.Ve
.PP
Use \f(CW\*(C`Alien::Foo\*(C'\fR in fallback mode:
.PP
.Vb 3
\& use FFI::Platypus;
\& use FFI::CheckLib 0.28 qw( find_lib_or_die );
\& use Alien::Foo;
\& 
\& my $ffi = FFI::Platypus\->new(
\&   lib => [ find_lib_or_die lib => \*(Aqfoo\*(Aq, alien => [\*(AqAlien::Foo\*(Aq] ],
\& );
.Ve
.PP
If you are going to always require an Alien you can just call \f(CW\*(C`dynamic_libs\*(C'\fR
and pass it into FFI::Platypus' lib method.  You should consider
using FFI::CheckLib to use the Alien in fallback mode instead.
This way you only need to install the Alien if the system doesn't
provide it.
.PP
For fallback mode to work correctly you need to be using FFI::CheckLib
0.28 or better.
.SS "Inline::C"
.IX Subsection "Inline::C"
.Vb 3
\& use Inline with => \*(AqAlien::Foo\*(Aq;
\& use Inline C => <<~\*(AqEND\*(Aq;
\&   #include <foo.h>
\& 
\&   const char *my_foo_wrapper()
\&   {
\&     foo();
\&   }
\&   END
\& 
\& sub exported_foo()
\& {
\&   my_foo_wrapper();
\& }
.Ve
.SS "tool"
.IX Subsection "tool"
.Vb 2
\& use Alien::Foo;
\& use Env qw( @PATH );
\& 
\& unshift @PATH, Alien::Foo\->bin_dir;
\& system \*(Aqfoo\*(Aq, \*(Aq\-\-bar\*(Aq, \*(Aq\-\-baz\*(Aq;
.Ve
.PP
Some Aliens provide tools instead of or in addition to a library.
You need to add them to the \f(CW\*(C`PATH\*(C'\fR environment variable though.
(Unless the tool is already provided by the system, in which case
it is already in the path and the \f(CW\*(C`bin_dir\*(C'\fR method will return an
empty list).
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\s-1ALIEN_INSTALL_TYPE\s0" 4
.IX Item "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.
.Sp
To keep the interface consistent among Aliens, the consumer of the fallback opt-in
Alien may fallback on the Alien if the environment variable \f(CW\*(C`ALIEN_INSTALL_TYPE\*(C'\fR
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
\&\s-1CPAN\s0 module.
.Sp
This behavior should be documented in the consumer's \s-1POD.\s0
.Sp
See \*(L"\s-1ENVIRONMENT\*(R"\s0 in Alien::Build for more details on the usage of this environment
variable.
.SH "AUTHOR"
.IX Header "AUTHOR"
Author: Graham Ollis <plicease@cpan.org>
.PP
Contributors:
.PP
Diab Jerius (\s-1DJERIUS\s0)
.PP
Roy Storey (\s-1KIWIROY\s0)
.PP
Ilya Pavlov
.PP
David Mertens (run4flat)
.PP
Mark Nunberg (mordy, mnunberg)
.PP
Christian Walde (Mithaldu)
.PP
Brian Wightman (MidLifeXis)
.PP
Zaki Mughal (zmughal)
.PP
mohawk (mohawk2, \s-1ETJ\s0)
.PP
Vikas N Kumar (vikasnkumar)
.PP
Flavio Poletti (polettix)
.PP
Salvador Fandiño (salva)
.PP
Gianni Ceccarelli (dakkar)
.PP
Pavel Shaydo (zwon, trinitum)
.PP
Kang-min Liu (劉康民, gugod)
.PP
Nicholas Shipp (nshp)
.PP
Juan Julián Merelo Guervós (\s-1JJ\s0)
.PP
Joel Berger (\s-1JBERGER\s0)
.PP
Petr Písař (ppisar)
.PP
Lance Wicks (\s-1LANCEW\s0)
.PP
Ahmad Fatoum (a3f, \s-1ATHREEF\s0)
.PP
José Joaquín Atria (\s-1JJATRIA\s0)
.PP
Duke Leto (\s-1LETO\s0)
.PP
Shoichi Kaji (\s-1SKAJI\s0)
.PP
Shawn Laffan (\s-1SLAFFAN\s0)
.PP
Paul Evans (leonerd, \s-1PEVANS\s0)
.PP
Håkon Hægland (hakonhagland, \s-1HAKONH\s0)
.PP
nick nauwelaerts (\s-1INPHOBIA\s0)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2011\-2020 by Graham Ollis.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.