view release on metacpan or  search on metacpan

lib/Alien/Build/Manual/AlienUser.pod  view on Meta::CPAN

# PODNAME: Alien::Build::Manual::AlienUser
# ABSTRACT: Alien user documentation
# VERSION

__END__

=pod

=encoding UTF-8

=head1 NAME

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

=head1 VERSION

version 2.84

=head1 SYNOPSIS

 perldoc Alien::Build::Manual::AlienUser

=head1 DESCRIPTION

This document is intended for a user of an L<Alien::Base> based L<Alien>
module's user.  Although specifically geared for L<Alien::Base>
subclasses, it may have some useful hints for L<Alien> in general.

Full working examples of how to use an L<Alien> module are also bundled
with L<Alien::Build> in the distribution's C<example/user> directory.
Those examples use L<Alien::xz>, which uses L<alienfile> + L<Alien::Build>
+ L<Alien::Base>.

The following documentation will assume you are trying to use an L<Alien>
called C<Alien::Foo> which provides the library C<libfoo> and the command
line tool C<foo>.  Many L<Alien>s will only provide one or the other.

The best interface to use for using L<Alien::Base> based aliens is
L<Alien::Base::Wrapper>.  This allows you to combine multiple aliens together
and handles a number of corner obscure corner cases that using L<Alien>s
directly does not.  Also as of 0.64, L<Alien::Base::Wrapper> comes bundled
with L<Alien::Build> and L<Alien::Base> anyway, so it is not an extra
dependency.

What follows are the main use cases.

=head2 ExtUtils::MakeMaker

 use ExtUtils::MakeMaker;
 use Alien::Base::Wrapper ();
 
 WriteMakefile(
   Alien::Base::Wrapper->new('Alien::Foo')->mm_args2(
     NAME => 'FOO::XS',
     ...
   ),
 );

L<Alien::Base::Wrapper> will take a hash of C<WriteMakefile> arguments
and insert the appropriate compiler and linker flags for you.  This
is recommended over doing this yourself as the exact incantation to
get EUMM to work is tricky to get right.

The C<mm_args2> method will also set your C<CONFIGURE_REQUIRES> for
L<Alien::Base::Wrapper>, L<ExtUtils::MakeMaker> and any aliens that
you specify.

=head2 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;

For L<Module::Build> you can also use L<Alien::Base::Wrapper>, but
you will have to specify the C<configure_requires> yourself.

=head2 Inline::C / Inline::CPP

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

L<Inline::C> and L<Inline::CPP> can be configured
to use an L<Alien::Base> based L<Alien> with the C<with> keyword.

=head2 ExtUtils::Depends