The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Alien-Base-0.006_01
River stage zero No dependents
14 ++
/ Alien::Base

NAME

Alien::Base - Base classes for Alien:: modules

SYNOPSIS

 package Alien::MyLibrary;

 use strict;
 use warnings;

 use parent 'Alien::Base';

 1;

(For a synopsis of the Build.PL that comes with your Alien::MyLibrary see Alien::Base::ModuleBuild)

Then a MyLibrary::XS can use Alien::MyLibrary in its Build.PL:

 use Alien::MyLibrary;
 use Module::Build 0.28; # need at least 0.28
 
 my $builder = Module::Build->new(
   ...
   extra_compiler_flags => Alien::MyLibrary->cflags,
   extra_linker_flags   => Alien::MyLibrary->libs,
   ...
 );
 
 $builder->create_build_script;

Or if you prefer ExtUtils::MakeMaker, in its Makefile.PL:

 use Alien::MyLibrary
 use ExtUtils::MakeMaker;
 
 WriteMakefile(
   ...
   CFLAGS => Alien::MyLibrary->cflags,
   LIBS   => ALien::MyLibrary->libs,
   ...
 );

Or if you are using ExtUtils::Depends:

 use ExtUtils::MakeMaker;
 use ExtUtils::Depends;
 my $eud = ExtUtils::Depends->new(qw( MyLibrary::XS Alien::MyLibrary ));
 WriteMakefile(
   ...
   $eud->get_makefile_vars
 );

In your MyLibrary::XS module, you may need to use Alien::MyLibrary if dynamic libraries are used:

 package MyLibrary::XS;
 
 use Alien::MyLibrary;
 
 ...

Or you can use it from an FFI module:

 package MyLibrary::FFI;
 
 use Alien::MyLibrary;
 use FFI::Raw;
 
 my($dll) = Alien::MyLibrary->dynamic_libs;
 
 FFI::Raw->new($dll, 'my_library_function', FFI::Raw::void);

You can even use it with Inline (C and C++ languages are supported):

 package MyLibrary::Inline;
 
 use Alien::MyLibrary;
 # Inline 0.56 or better is required
 use Inline 0.56 with => 'Alien::MyLibrary';
 ...

DESCRIPTION

Alien::Base comprises base classes to help in the construction of Alien:: modules. Modules in the Alien namespace are used to locate and install (if necessary) external libraries needed by other Perl modules.

This is the documentation for the Alien::Base module itself. To learn more about the system as a whole please see Alien::Base::Authoring.

METHODS

In the example snippets here, Alien::MyLibrary represents any subclass of Alien::Base.

dist_dir

 my $dir = Alien::MyLibrary->dist_dir;

Returns the directory that contains the install root for the packaged software, if it was built from install (i.e., if install_type is share).

cflags

 my $cflags = Alien::MyLibrary->cflags;

 use Text::ParseWords qw( shellwords );
 my @cflags = shellwords( Alien::MyLibrary->cflags );

Returns the C compiler flags necessary to compile an XS module using the alien software. If you need this in list form (for example if you are calling system with a list argument) you can pass this value into shellwords from the Perl core Text::ParseWords module.

libs

 my $libs = Alien::MyLibrary->libs;

 use Text::ParseWords qw( shellwords );
 my @cflags = shellwords( Alien::MyLibrary->libs );

Returns the library linker flags necessary to link an XS module against the alien software. If you need this in list form (for example if you are calling system with a list argument) you can pass this value into shellwords from the Perl core Text::ParseWords module.

install_type

 my $install_type = Alien::MyLibrary->install_type;

Returns the install type that was used when Alien::MyLibrary was installed. Types include:

system

The library was provided by the operating system

share

The library was not available when Alien::MyLibrary was installed, so it was built from source code, either downloaded from the Internet or bundled with Alien::MyLibrary.

config

 my $value = Alien::MyLibrary->config($key);

Returns the configuration data as determined during the install of Alien::MyLibrary. For the appropriate config keys, see Alien::Base::ModuleBuild::API#CONFIG-DATA.

dynamic_libs

 my @dlls = Alien::MyLibrary->dynamic_libs;
 my($dll) = Alien::MyLibrary->dynamic_libs;

Returns a list of the dynamic library or shared object files for the alien software. Currently this only works for when install_type is share and alien_isolate_dynamic is used (See Alien::Base::ModuleBuild::API#CONSTRUCTOR for all build arguments).

bin_dir

 my(@dir) = Alien::MyLibrary->bin_dir

Returns a list of directories with executables in them. For a system install this will be an empty list. For a share install this will be a directory under dist_dir named bin if it exists. You may wish to override the default behavior if you have executables or scripts that get installed into non-standard locations.

inline_auto_include

 my(@headers) = Alien::MyLibrary->inline_auto_include;

List of header files to automatically include in inline C and C++ code when using Inline::C or Inline::CPP. This is provided as a public interface primarily so that it can be overidden at run time. This can also be specified in your Build.PL with Alien::Base::ModuleBuild using the alien_inline_auto_include property.

SUPPORT AND CONTRIBUTING

If you find a bug, please report it on the projects issue tracker on GitHub:

https://github.com/Perl5-Alien/Alien-Base/issues

Development is discussed on the projects google groups. This is also a reasonable place to post a question if you don't want to open an issue in GitHub.

https://groups.google.com/forum/#!forum/perl5-alien

If you have implemented a new feature or fixed a bug, please open a pull request.

https://github.com/Perl5-Alien/Alien-Base/pulls

SEE ALSO

AUTHOR

Joel Berger, <joel.a.berger@gmail.com>

CONTRIBUTORS

David Mertens (run4flat)
Mark Nunberg (mordy, mnunberg)
Christian Walde (Mithaldu)
Brian Wightman (MidLifeXis)
Graham Ollis (plicease)
Zaki Mughal (zmughal)
mohawk2
Vikas N Kumar (vikasnkumar)

COPYRIGHT AND LICENSE

Copyright (C) 2012-2014 by Joel Berger

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.