Alien::Base(3)

📦

version 2.88 · 8 versions

2.88 · arch rolling (latest)
2.78 · opensuse-leap 16.0
2.84 · alpine 3.24
2.84 · fedora 43
2.88 · fedora 43, fedora 44
2.84 · fedora 44
2.80 · ubuntu noble
2.84 · debian trixie, ubuntu resolute, ubuntu stonking

, in arch rolling

🦋 Alien::Base(3) — straight from the User Contributed Perl Documentation

🌸 NAME 🌸

Alien::Base — Base classes for Alien:: modules

✨ VERSION ✨

version 2.88 — yes bestie, that's the version 💅

🌈 SYNOPSIS 🌈

okay so here's the whole setup, no cap:

package Alien::MyLibrary;

use strict;
use warnings;

use parent 'Alien::Base';

1;

For the deets on the Makefile.PL or Build.PL and alienfile that should be bundled with your Alien::Base subclass, please see Alien::Build::Manual::AlienAuthor 🫶

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

use Alien::MyLibrary
use ExtUtils::MakeMaker;
use Alien::Base::Wrapper qw( Alien::MyLibrary !export );
use Config;

WriteMakefile(
  ...
  Alien::Base::Wrapper->mm_args,
  ...
);

Or if you prefer Module::Build, in its Build.PL:

use Alien::MyLibrary;
use Module::Build 0.28; # need at least 0.28
use Alien::Base::Wrapper qw( Alien::MyLibrary !export );

my $builder = Module::Build->new(
  ...
  Alien::Base::Wrapper->mb_args,
  ...
);

$builder->create_build_script;

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
);

If you are using Alien::Base::ModuleBuild instead of the recommended Alien::Build and alienfile, then in your MyLibrary::XS module, you may need something like this in your main .pm file IF your library uses dynamic libraries:

package MyLibrary::XS;

use Alien::MyLibrary; # may only be needed if you are using Alien::Base::ModuleBuild

...

Or you can use it from an FFI module:

package MyLibrary::FFI;

use Alien::MyLibrary;
use FFI::Platypus;
use FFI::CheckLib 0.28 qw( find_lib_or_die );

my $ffi = FFI::Platypus->new;
$ffi->lib(find_lib_or_die lib => 'mylib', alien => ['Alien::MyLibrary']);

$ffi->attach( 'my_library_function' => [] => '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 💖

NOTE: Alien::Base::ModuleBuild is no longer bundled with Alien::Base and has been spun off into a separate distribution. Alien::Base::ModuleBuild will be a prerequisite for Alien::Base until October 1, 2017. If you are using Alien::Base::ModuleBuild you need to make sure it is declared as a configure_requires in your Build.PL. You may want to also consider using Alien::Base and alienfile as a more modern alternative.

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. If you are starting out you probably want to do so from one of these documents:

Alien::Build::Manual::AlienUser — For users of an Alien::libfoo that is implemented using Alien::Base. (The developer of Alien::libfoo should provide the documentation necessary, but if not, this is the place to start).
Alien::Build::Manual::AlienAuthor — If you are writing your own Alien based on Alien::Build and Alien::Base.
Alien::Build::Manual::FAQ — If you have a common question that has already been answered, like "How do I use alienfile with some build system".
Alien::Build::Manual::PluginAuthor — This is for the brave souls who want to write plugins that will work with Alien::Build + alienfile.

Before using an Alien::Base based Alien directly, please consider the following advice:

If you are wanting to use an Alien::Base based Alien with an XS module using ExtUtils::MakeMaker or Module::Build, it is highly recommended that you use Alien::Base::Wrapper, rather than using the Alien directly, because it handles a number of sharp edges and avoids pitfalls common when trying to use an Alien directly with ExtUtils::MakeMaker.

In the same vein, if you are wanting to use an Alien::Base based Alien with an XS module using Dist::Zilla it is highly recommended that you use Dist::Zilla::Plugin::AlienBase::Wrapper for the same reasons.

As of version 0.28, FFI::CheckLib has a good interface for working with Alien::Base based Aliens in fallback mode, which is recommended.

You should typically only be using an Alien::Base based Alien directly, if you need to integrate it with some other system, or if it is a tool based Alien that you don't need to link.

The above synopsis and linked manual documents will lead you down the right path, but it is worth knowing before you read further in this document. 🌸

💅 METHODS 💅

Okay bestie, in all the code snippets below, Alien::MyLibrary stands in for any subclass of Alien::Base, got it? It's giving template energy. 🎀

🗂️ `dist_dir`

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

Hands you back the directory that holds the install root for the packaged software — but only if it was built from install, meaning if install_type is share. No share, no dir, iykyk. ✨

🌱 `new`

my $alien = Alien::MyLibrary->new;

Creates an instance of an Alien::Base object. Lowkey you almost never need this — it's typically unnecessary. Like, the class methods do the work. 💅

🔧 `cflags`

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

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

Returns the C compiler flags you need to compile an XS module using the alien software. Periodt.

And if you need it in list form (say, when you're calling system with a list argument) you can pass this value straight into shellwords from the Perl core Text::ParseWords module. Chef's kiss. 🫶

🧱 `cflags_static`

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

Same as cflags above, but for the static compiler flags, if they happen to be different. ✨

🔗 `libs`

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

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

Returns the library linker flags you need to link an XS module against the alien software. Iconic.

Same deal as before — need it as a list (like, for system with a list argument)? Pass it into shellwords from the Perl core Text::ParseWords module. 🧚

`libs_static`

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

Same as libs above, but it gets the static linker flags, if they're different. No cap. 🔥

🏷️ `version`

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

Returns the version of the alienized library or tool — and this was determined at install time, so it's locked in. 👑

⚖️ `atleast_version` / `exact_version` / `max_version`

my $ok = Alien::MyLibrary->atleast_version($wanted_version);
my $ok = Alien::MyLibrary->exact_version($wanted_version);
my $ok = Alien::MyLibrary->max_version($wanted_version);

These three each return true if the version of the alienized library or tool is, respectively:

at least the version you specified (atleast_version)
exactly the version you specified (exact_version)
at most the version you specified (max_version)

Vibe check on your version, basically. ✨

🥊 `version_cmp`

 $cmp = Alien::MyLibrary->version_cmp($x, $y)

This is the comparison method that atleast_version, exact_version and max_version all use under the hood. You might find it useful for implementing custom comparisons — or for subclasses to overload, so you get different version comparison semantics than the default rules, for packages that have some other rules than the pkg-config behaviour. 🤓

It should return a number less than, equal to, or greater than zero — same behaviour as the <=> and cmp operators, fr fr.

🧬 `install_type`

my $install_type = Alien::MyLibrary->install_type;
my $bool = Alien::MyLibrary->install_type($install_type);

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

And hey — if you pass a type in (the second form in the synopsis), it returns true if the actual install type matches. But for that use case, it is recommended that you use is_system_install or is_share_install instead, because those are less prone to typographical errors. Save yourself the typo heartbreak 😭

The types include:

system — the library was provided by the operating system. 🖥️
share — the library wasn't available when Alien::MyLibrary was installed, so it got built from source code, either downloaded from the Internet or bundled with Alien::MyLibrary. 📦

🐧 `is_system_install`

my $type = $build->is_system_install;

Returns true if the alien is a system install type. Simple as that. ✨

📦 `is_share_install`

my $type = $build->is_share_install;

Returns true if the alien is a share install type. 💖

⚙️ `config`

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

Returns the configuration data as determined during the install of Alien::MyLibrary. For the appropriate config keys, go look at "CONFIG DATA" in Alien::Base::ModuleBuild::API. 👀

This isn't typically used by Alien::Base and alienfile — but a compatible interface will be provided, so no worries. 🫶

🎧 `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. The way it gives you a list and you just grab the first one with my($dll) = — iconic. 🦋

🚀 `bin_dir`

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

Returns a list of directories with executables in them. Let's break it down:

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've got executables or scripts that get installed into non-standard locations. Go off, customize. 💅

Example usage:

use Env qw( @PATH );

unshift @PATH, Alien::MyLibrary->bin_dir;

🌈 `dynamic_dir`

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

Returns the dynamic dir for a dynamic build (if the main build is static). For a share install, this will be a directory under dist_dir named dynamic if it exists. System builds return an empty list. 🙈

Example usage:

use Env qw( @PATH );

unshift @PATH, Alien::MyLibrary->dynamic_dir;

🧚 `alien_helper`

my $helpers = Alien::MyLibrary->alien_helper;

Returns a hash reference of helpers provided by the Alien module. Keys are helper names, values are code references. Those code references get executed at command time, and the return value gets interpolated into the command before execution. The default implementation returns an empty hash reference, and you're expected to override the method to create your own helpers. 👑

This is for use with commands specified in an alienfile, or in your Build.PL when used with Alien::Base::ModuleBuild.

So like, what do helpers even do? They let users of your Alien module use platform or environment determined logic to compute command names or arguments in your installer logic. And they let you do that without making your Alien module a requirement when a build from source code isn't necessary. Big brain energy. 🧠✨

As a concrete example, consider Alien::gmake, which provides the helper gmake:

package Alien::gmake;

...

sub alien_helper {
  my($class) = @_;
  return {
    gmake => sub {
      # return the executable name for GNU make,
      # usually either make or gmake depending on
      # the platform and environment
      $class->exe;
    }
  },
};

Now consider Alien::nasm. nasm requires GNU Make to build from source code, but if the system nasm package is installed we don't need it. From the alienfile of Alien::nasm:

use alienfile;

plugin 'Probe::CommandLine' => (
  command => 'nasm',
  args    => ['-v'],
  match   => qr/NASM version/,
);

share {
  ...
  plugin 'Extract' => 'tar.gz';
  plugin 'Build::MSYS';

  build [
    'sh configure --prefix=%{alien.install.prefix}',
    '%{gmake}',
    '%{gmake} install',
  ];
};

...

See how that %{gmake} just slides in there? Obsessed. 💜

📝 `inline_auto_include`

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

A list of header files to automatically include in inline C and C++ code when you're using Inline::C or Inline::CPP. This is provided as a public interface primarily so that it can be overridden at run time. 🎀

You can also specify this in your Build.PL with Alien::Base::ModuleBuild using the alien_inline_auto_include property. Slay.

🏃 `runtime_prop`

my $hashref = Alien::MyLibrary->runtime_prop;

Returns a hash reference of the runtime properties computed by Alien::Build during its install process. But listen — if the Alien::Base based Alien was not built using Alien::Build, then this returns undef. Heads up. 💀

🎭 `alt`

my $new_alien = Alien::MyLibrary->alt($alt_name);
my $new_alien = $old_alien->alt($alt_name);

Returns an Alien::Base instance with the alternate configuration. Main character energy for real. 👑

Some packages come with multiple libraries, and multiple .pc files to use with them. This method can be used with pkg-config plugins to access different configurations. (It could also be used with non-pkg-config based packages too, though there are not as of this writing any build time plugins that take advantage of this feature. So like, don't get too excited.) 🦋

From your alienfile:

use alienfile;

plugin 'PkgConfig' => (
  pkg_name => [ 'libfoo', 'libbar', ],
);

Then in your base class it works like normal:

package Alien::MyLibrary;

use parent qw( Alien::Base );

1;

Then you can use it:

use Alien::MyLibrary;

my $cflags = Alien::MyLibrary->alt('foo1')->cflags;
my $libs   = Alien::MyLibrary->alt('foo1')->libs;

Look at that chaining. We love to see it. 💖

📋 `alt_names`

my @alt_names = Alien::MyLibrary->alt_names

Returns the list of all the available alternative configuration names. All of them. Every single one. ✨

✅ `alt_exists`

my $bool = Alien::MyLibrary->alt_exists($alt_name)

Returns true if the given alternative configuration exists. That's it, that's the method. 💅

🫶 SUPPORT AND CONTRIBUTING 🫶

First things first: check the Alien::Build::Manual::FAQ for questions that have already been answered. Like, do the reading bestie, it's probably in there. 📚

IRC: #native on irc.perl.org

(click for instant chatroom login) <http://chat.mibbit.com/#native@irc.perl.org>

If you find a bug, please report it on the project's issue tracker on GitHub:

<https://github.com/PerlAlien/Alien-Build/issues>

Development is discussed on the project's google groups. This is also a reasonable place to post a question if you don't want to open an issue in GitHub. Very chill of them. 🫶

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

And if you've implemented a new feature or fixed a bug, please open a pull request. We'd literally love that. 💖

<https://github.com/PerlAlien/Alien-Build/pulls>

👀 SEE ALSO 👀

Alien::Build
alienfile
Alien
Alien::Build::Manual::FAQ

🙏 THANKS 🙏

Special thanks for the early development of Alien::Base go to:

Christian Walde (Mithaldu) — for productive conversations about component interoperability. 🤝
kmx — for writing Alien::Tidyp, from which I drew many of my initial ideas. ✨
David Mertens (run4flat) — for productive conversations about implementation. 🛠️
Mark Nunberg (mordy, mnunberg) — for graciously teaching me about rpath and dynamic loading,

👑 AUTHOR 👑

Ok so this whole thing was written by Graham Ollis — <plicease@cpan.org> 💖 absolute legend behaviour, no cap.

And then there's the contributor list, aka the group chat that made this happen 🫶 every single one of these icons deserves their flowers:

Diab Jerius (DJERIUS)
Roy Storey (KIWIROY)
Ilya Pavlov
David Mertens (run4flat)
Mark Nunberg (mordy, mnunberg)
Christian Walde (Mithaldu)
Brian Wightman (MidLifeXis)
Zaki Mughal (zmughal)
mohawk (mohawk2, ETJ)
Vikas N Kumar (vikasnkumar)
Flavio Poletti (polettix)
Salvador Fandiño (salva)
Gianni Ceccarelli (dakkar)
Pavel Shaydo (zwon, trinitum)
Kang-min Liu (劉康民, gugod)
Nicholas Shipp (nshp)
Juan Julián Merelo Guervós (JJ)
Joel Berger (JBERGER)
Petr Písař (ppisar)
Lance Wicks (LANCEW)
Ahmad Fatoum (a3f, ATHREEF)
José Joaquín Atria (JJATRIA)
Duke Leto (LETO)
Shoichi Kaji (SKAJI)
Shawn Laffan (SLAFFAN)
Paul Evans (leonerd, PEVANS)
Håkon Hægland (hakonhagland, HAKONH)
nick nauwelaerts (INPHOBIA)
Florian Weimer
Marcel Telka (mtelka)

the way this is a whole squad 😭✨

💖 COPYRIGHT AND LICENSE 💖

Bestie, legal bit, but make it cute 🎀

This is free software — you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. That's it, that's the whole license vibe. Go forth and slay 💅

ok that's genuinely the whole page, you're free now, go build something iconic with it 🦋🌸

source + version + date, for the record: perl v5.42.2 · 2026-09-20 · Alien::Base(3) — mwah, thanks for reading to the end, ily, byeee 💜✨

📦 where this page comes from

arch rolling: perl-alien-build 2.88-1 · Artistic-1.0-Perl AND GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

Alien::Base(3)

🦋 Alien::Base(3) — straight from the User Contributed Perl Documentation

🌸 NAME 🌸

✨ VERSION ✨

🌈 SYNOPSIS 🌈

💖 DESCRIPTION 💖

💅 METHODS 💅

🗂️ dist_dir

🌱 new

🔧 cflags

🧱 cflags_static

🔗 libs

libs_static

🏷️ version

⚖️ atleast_version / exact_version / max_version

🥊 version_cmp

🧬 install_type

🐧 is_system_install

📦 is_share_install

⚙️ config

🎧 dynamic_libs

🚀 bin_dir

🌈 dynamic_dir

🧚 alien_helper

📝 inline_auto_include

🏃 runtime_prop

🎭 alt

📋 alt_names

✅ alt_exists