/ 
Alien-Build-0.65_01
River stage four • 286 direct dependents • 1572 total dependents
/ Alien::Build::Manual::AlienUser

NAME

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

VERSION

version 0.65_01

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.

What follows are the main use cases.

Module::Build

use Module::Build;
use Alien::Foo;

my $build = Module::Build->new(
  ...
  configure_requires => {
    'Alien::Foo' => '0',
    ...
  },
  extra_compiler_flags => Alien::Foo->cflags,
  extra_linker_flags   => Alien::Foo->libs,
  ...
);

$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 Config;
use Alien::Foo;

WriteMakefile(
  ...
  CONFIGURE_REQUIRES => {
    'Alien::Foo' => '0',
  },
  CCFLAGS => Alien::Foo->cflags . " $Config{ccflags}",
  LIBS    => [ Alien::Foo->libs ],
  ...
);

MakeMaker is similar, make sure that you explicitly make your Alien a configure prerequisite.

Dist::Zilla

[@Filter]
-bundle = @Basic
-remove = MakeMaker

[Prereqs / ConfigureRequires]
Alien::Foo = 0

[MakeMaker::Awesome]
header = user Config;
header = use Alien::Foo;
WriteMakefile_arg = CCFLAGS => Alien::Foo->cflags . ' ' . $Config{ccflags}
WriteMakefile_arg = LIBS => [ Alien::Foo->libs ]

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::Raw or 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).

AUTHOR

Author: Graham Ollis <plicease@cpan.org>

Contributors:

Diab Jerius (DJERIUS)

Roy Storey

Ilya Pavlov

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 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.