Alien

External libraries wrapped up for your viewing pleasure!

SYNOPSIS

% perldoc Alien

DESCRIPTION

The intent of the Alien namespace is to provide a mechanism for specifying, installing and using non-native dependencies on CPAN. Frequently this is a C library used by XS (see perlxs) or FFI (see FFI::Platypus), but it could be anything non-Perl usable from Perl.

Typical characteristics of an Alien distribution include:

• Probe for or install library during the build process

  Usually this means that Module::Build or ExtUtils::MakeMaker will be extended to probe for an existing system library that meets the criteria of the Alien module. If it cannot be found the library is downloaded from the Internet and installed into a share directory (See File::ShareDir::Dist).

  Usually, though not necessarily, this is a C library. It could be anything though, some JavaScript, Java .class files. Anything imaginable.

• The module itself provides attributes needed to use the library

  This means that if you are writing Alien::Foo it will provide class or member functions that will provide the necessary information for using the library that was probed for or installed during the previous step.

  If, for example, Alien::Foo were providing a dependency on the C library libfoo, then you might provide Alien::Foo->cflags and Alien::Foo->libs class methods to return the compiler and library flags required for using the library.

These are guidelines, and this module does not provide an implementation or a framework, because of the diverse nature of non-Perl dependencies on CPAN. The more common cases are handled by the Alien::Base + Alien::Build system, which is recommended if you want to avoid reinventing the wheel. See the "SEE ALSO" section below for helpful resources.

CAVEATS

This section contains some recommendations from my own experience in writing Alien modules and from working on the Alien::Base + Alien::Build team. The Alien::Build FAQ (Alien::Build::Manual::FAQ) also addresses a number of implementation specific gotchas.

• When building from source code, build static libraries whenever possible

  Or at least isolate the dynamic libraries so they can be used by FFI, but do not use them to build XS modules. The reason for this is that if an end user upgrades their version of Alien::Foo it may break the already installed version of Foo::XS that used it when it was installed.

• On Windows (ActiveState, Strawberry Perl)

  Many open source libraries use autoconf and other Unix focused tools that may not be easily available to the native (non-Cygwin) windows Perl. Alien::MSYS provides just enough of these tools for autoconf and may be sufficient for some other build tools. Also, Alien::Build and Alien::Base have hooks to detect autoconf and inject Alien::MSYS as a requirement on Windows when it is needed.

• MB vs EUMM

  The original Alien documentation recommends the use of Module::Build (MB), which at the time was recommended over ExtUtils::MakeMaker (EUMM). Many Alien distributions have been written using MB. Including the original installer that came with Alien::Base, Alien::Base::ModuleBuild. I believe this is because it is an easier build system to adapt to the Alien concept. MB is no longer universally recommended over EUMM, and has been removed from Perl's core, so if you can, this author recommends using EUMM instead. Alien::Build and Alien::Build::MM provide tools for creating EUMM based Aliens. Another example worth looking at is Alien::pkgconf, which uses EUMM, but isn't based on Alien::Base or Alien::Build.

ORIGINAL MANIFESTO

What follows is the original Alien manifesto written by Artur Bergman. It is included here, because much of it is still largely true today, but it was out of necessity quite aspirational at the time it was written.

Why

James and I ended up doing a build system for Fotango, lots of people have done a build system, it is a pretty boring task. The boring task is really all the mindlessly stupid things you need to do to build C libraries that Perl modules require, these C modules usually have unusual installation systems or require vastly different options. So CPAN modules install easy, 3rd party stuff is nasty.

So, suddenly an idea struck me, Alien packages! Imagine a CPAN module that has as its only task to make sure a certain library is installed! That means that you can write all the voodoo in your Build.PL file and then just make sure the module requires the correct Alien module! Then anything that install Perl modules will deal with it automatically!

How

So, what should an Alien module do? It should make sure that the target is installed and it should provide the caller with enough information to use it.

The idea is that you use it to make sure it is there, and you call class methods to find out what to use. These class methods will be individually specified by the stand alone Alien modules.

No Framework!

The reason this is so loosely worded is because we have no idea what common functionality will be needed, so we will let evolution work for us and see what individual Alien packages need and then eventually factor it out into this packages. I would like to avoid a top down design approach.

Responsibilities of a Alien module.

On installation, make sure the required package is there, otherwise install it.

On usage, make sure the required package is there, else croak.

Bundle the source with the module, or download it.

Allow module authors to access information it gathers.

Document itself well.

Preferably use Module::Build. [ see caveats above ]

Be sane.

SEE ALSO

• Alien::Build::Manual::Alien

  Documentation for building Aliens using the Alien::Base + Alien::Build system. Intended for as a starting point for Alien users and Alien authors.

• Alien::Build::Manual::FAQ

  Quick answers (FAQ) for many common Alien issues.

• Alien::Build

  A new installer agnostic Alien builder, intended to replace Alien::Base::ModuleBuild. See Alien::Build::Manual::AlienAuthor for details on how to create your own Alien::Build based Alien.

• Alien::Base

  An (optional) base class and framework for creating Alien distributions.

• #native on irc.perl.org

  This channel on IRC is dedicated to those interested in using native interfaces in Perl. It is specifically geared to Alien, Alien::Base and FFI.

• Perl5 Alien mailing list

  This mailing list is mainly for Alien::Base, and announcements for new versions will be posted there, but general Alien inquires are also welcome.

• https://github.com/PerlAlien

  The Perl Alien organization on GitHub.

AUTHORS

• Arthur Bergman abergman@fotango.com
• Graham Ollis plicease@cpan.org

COPYRIGHT AND LICENSE

This software is copyright (c) 2003 by Arthur Bergman abergman@fotango.com.

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