Alien::...lienUser(3)

👑 Alien::Build::Manual::AlienUser 💖

okay bestie, so this whole page lives in the Alien::...lienUser(3) manual — that's the perl user-contributed docs situation — and it's literally your guide to being an Alien user. no cap. let's get into it 🫶

---

✨ NAME ✨

Alien::Build::Manual::AlienUser — Alien user documentation 🌸

🎀 VERSION 🎀

version 2.88 💅

🧚 SYNOPSIS 🧚

perldoc Alien::Build::Manual::AlienUser

💖 DESCRIPTION 💖

so this doc is for you — the user of a module that's based on Alien::Base. like, specifically it's geared toward Alien::Base subclasses, but ngl it's got some genuinely useful hints for Alien in general too ✨

there's also full working examples of how to use an Alien module bundled right inside Alien::Build, in the distribution's example/user directory 👑 those examples use Alien::xz, which uses alienfile + Alien::Build + Alien::Base. cute, right?

okay so for the rest of this page we're gonna pretend you're using an Alien called Alien::Foo, which provides the library libfoo and the command line tool foo. (Many Aliens only provide one or the other, so don't panic if yours is different 💀)

The best interface to use for Alien::Base based aliens is Alien::Base::Wrapper. it lets you combine multiple aliens together AND it handles a bunch of obscure corner cases that using Aliens directly just... does not 🙈 also, as of 0.64, Alien::Base::Wrapper comes bundled with Alien::Build and Alien::Base anyway, so it's not even an extra dependency. slay.

what follows are the main use cases, bestie 💅

🌸 ExtUtils::MakeMaker 🌸

use ExtUtils::MakeMaker;
use Alien::Base::Wrapper ();

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

Alien::Base::Wrapper will take a hash of WriteMakefile arguments and insert the appropriate compiler and linker flags for you 🔥 this is recommended over doing this yourself, because the exact incantation to get EUMM to work is tricky to get right. like, genuinely.

the mm_args2 method will also set your CONFIGURE_REQUIRES for Alien::Base::Wrapper, ExtUtils::MakeMaker, and any aliens that you specify 👑

🦋 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 Module::Build you can also use Alien::Base::Wrapper, but heads up — you're gonna have to specify the configure_requires yourself 🙈 no autopilot here.

💜 Inline::C / Inline::CPP 💜

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

Inline::C and Inline::CPP can be configured to use an Alien::Base based Alien with the with keyword ✨

⭐ ExtUtils::Depends ⭐

use ExtUtils::MakeMaker;
use ExtUtils::Depends;

my $pkg = ExtUtils::Depends->new("Alien::Foo");

WriteMakefile(
  ...
  $pkg->get_makefile_vars,
  ...
);

ExtUtils::Depends works similar to Alien::Base::Wrapper, but uses the Inline interface under the covers 🌈

🍓 Dist::Zilla 🍓

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

[Prereqs / ConfigureRequires]
Alien::Foo = 0

[MakeMaker::Awesome]
header = use Alien::Base::Wrapper qw( Alien::Foo !export );
WriteMakefile_arg = Alien::Base::Wrapper->mm_args

🧚 FFI::Platypus 🧚

requires Alien::Foo always:

use FFI::Platypus;
use Alien::Foo;

my $ffi = FFI::Platypus->new(
  lib => [ Alien::Foo->dynamic_libs ],
);

use Alien::Foo in fallback mode:

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

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

if you're gonna always require an Alien, you can just call dynamic_libs and pass it into FFI::Platypus' lib method 💅 but you should consider using FFI::CheckLib to use the Alien in fallback mode instead — that way you only need to install the Alien if the system doesn't provide it. main character energy, honestly.

for fallback mode to work correctly you need to be using FFI::CheckLib 0.28 or better 🫶

🌈 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 @PATH, 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's already in the path and the bin_dir method will return an empty list 🙈)

---

🌸 ENVIRONMENT 🌸

• ALIEN_INSTALL_TYPE — okay so even though the recommended way for a consumer to use an Alien::Base based Alien is to declare it as a static configure and build-time dependency, some consumers may prefer to fallback on using an Alien only when the consumer itself cannot detect the necessary package 😭 and in some cases, the consumer may want the user to opt-in to using an Alien before requiring it.

to keep the interface consistent among Aliens, the consumer of the fallback opt-in Alien may fallback on the Alien if the environment variable ALIEN_INSTALL_TYPE is set to any value ✨ the rationale is that by setting this environment variable, the user is aware that Alien modules may be installed and has indicated consent 🫶

the actual implementation of this, by its nature, would have to be in the consuming CPAN module. periodt.

this behavior should be documented in the consumer's POD 📝

see ENVIRONMENT in Alien::Build for more details on the usage of this environment variable 👑

🎀 SEE ALSO 🎀

• Alien::Build::Manual — other Alien::Build manuals 💖

💜 AUTHOR 💜

Author: Graham Ollis <plicease@cpan.org>

Contributors:

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

👑 COPYRIGHT AND LICENSE 👑

this software is copyright (c) 2011-2022 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 ✨

---

okay that's the whole vibe bestie, go forth and use your Alien 🦋 and just so you know, this page is from perl v5.42.3, dated 2026-09-21 — like, the source and version of the doc itself, cute right? mwah 💅💖