alienfile(3)

💖 NAME 💖

alienfile — the spec for defining an external dependency for CPAN, bestie. That's it, that's the name section ✨

🌸 VERSION 🌸

version 2.88 — that's the era we're living in 💅

✨ SYNOPSIS ✨

Okay so there are two ways to do this. First up, the do-it-yourself approach:

use alienfile;

probe [ 'pkg-config --exists libarchive' ];

share {

  start_url 'http://libarchive.org/downloads/libarchive-3.2.2.tar.gz';

  # the first one which succeeds will be used
  download [ 'wget %{.meta.start_url}' ];
  download [ 'curl -o %{.meta.start_url}' ];

  extract [ 'tar xf %{.install.download}' ];

  build [
    # Note: will not work on Windows, better to use Build::Autoconf plugin
    # if you need windows support
    './configure --prefix=%{.install.prefix} --disable-shared',
    '%{make}',
    '%{make} install',
  ];
}

gather [
  [ 'pkg-config', '--modversion', 'libarchive', \'%{.runtime.version}' ],
  [ 'pkg-config', '--cflags',     'libarchive', \'%{.runtime.cflags}'  ],
  [ 'pkg-config', '--libs',       'libarchive', \'%{.runtime.libs}'    ],
];

And then the with plugins (better) version, which is honestly the glow-up:

use alienfile;

plugin 'PkgConfig' => 'libarchive';

share {
  start_url 'http://libarchive.org/downloads/';
  plugin Download => (
    filter => qr/^libarchive-.*\.tar\.gz$/,
    version => qr/([0-9\.]+)/,
  );
  plugin Extract => 'tar.gz';
  plugin 'Build::Autoconf';
  plugin 'Gather::IsolateDynamic';
  build [
    '%{configure}',
    '%{make}',
    '%{make} install',
  ];
};

---

🌈 DESCRIPTION 🌈

So an alienfile is a recipe that Alien::Build uses to, like, probe for system libraries or download from the internet, and then build source for those libraries. Slay.

This doc is the reference for the whole alienfile system — it's the receipts, the lore, the full tea. But if you're just starting out writing your own Alien? Bestie, go read Alien::Build::Manual::AlienAuthor first, because that one actually teaches you how to write a complete Alien using alienfile + Alien::Build + ExtUtils::MakeMaker.

🚨 Special attention to the section "a note about dynamic vs. static libraries" — no cap, do not skip it, it matters so much.

---

👑 DIRECTIVES 👑

These are the building blocks, the main characters, the whole vibe 💜

🧚 requires

"any" requirement (either share or system):

requires $module;
requires $module => $version;

configure time requirement:

configure {
  requires $module;
  requires $module => $version;
};

system requirement:

sys {
  requires $module;
  requires $module => $version;
};

share requirement:

share {
  requires $module;
  requires $module => $version;
};

This specifies a requirement. Alien::Build takes advantage of dynamic requirements, so literally only the modules that are actually needed for that specific type of install get loaded. Efficiency icon behavior ✨

Here are the different flavors of requirements:

• configure — Configure requirements should already be installed before the alienfile is loaded. Like, before you even walk in the door.
• any — "Any" requirements are the ones needed either for the probe stage, or in either the system or share installs. They're flexible like that 🦋
• share — Share requirements are the modules you need when downloading and building from source.
• system — System requirements are the modules you need when the system is the one providing the library or tool.

🎀 plugin

plugin $name => (%args);
plugin $name => $arg;

Load the given plugin. Here's the tea on naming: if you prefix the plugin name with an = sign, then it's assumed to be a fully qualified path name. Otherwise the plugin is assumed to live in the Alien::Build::Plugin namespace. And if there's an appropriate negotiate plugin available, that one gets loaded instead. Obsessed with the automation ngl.

Examples:

# Loads Alien::Build::Plugin::Fetch::Negotiate
# which will pick the best Alien::Build::Plugin::Fetch
# plugin based on the URL, and system configuration
plugin 'Fetch' => 'http://ftp.gnu.org/gnu/gcc';

# loads the plugin with the badly named class!
plugin '=Badly::Named::Plugin::Not::In::Alien::Build::Namespace';

# explicitly loads Alien::Build::Plugin::Prefer::SortVersions
plugin 'Prefer::SortVersions' => (
  filter => qr/^gcc-.*\.tar\.gz$/,
  version => qr/([0-9\.]+)/,
);

💅 probe

probe \&code;
probe \@commandlist;

Instructions for the probe stage. Can be either a code reference or a command list. You can stack multiple probes and probe plugins — they get used in sequence, stopping at the first one that detects a system installation. And if no probe detects a system install? Alien::Build just goes ahead and uses a share install instead. No system? No problem 💁

🌸 configure

configure {
  ...
};

The configure block. The only directive allowed in here is requires. That's it. It's giving exclusive guest list 🚫

⭐ sys

sys {
  ...
};

The System block. Allowed directives here are: requires and gather.

🦋 share

share {
  ...
};

System block. (Yes, it literally says "System block" right here in the original, we're just the messenger 💀) Allowed directives are: download, fetch, decode, prefer, extract, build, gather.

🍓 start_url

share {
  start_url $url;
};

Set the start URL for the download. This should be the URL to an index page, or the actual tarball of the source. Either works, queen.

🔥 digest

[experimental]

share {
  digest $algorithm, $digest;
};

Check fetched and downloaded files against the given algorithm and digest. Typically you'll want to use SHA256 as the algorithm — that's the one, fr fr.

🧚 download

share {
  download \&code;
  download \@commandlist;
};

Instructions for the download stage. May be either a code reference or a command list.

🌈 fetch

share {
  fetch \&code;
  fetch \@commandlist;
};

Instructions for the fetch stage. May be either a code reference or a command list.

💜 decode

share {
  decode \&code;
  decode \@commandlist;
};

Instructions for the decode stage. May be either a code reference or a command list.

✨ prefer

share {
  prefer \&code;
  prefer \@commandlist;
};

Instructions for the prefer stage. May be either a code reference or a command list.

🎀 extract

share {
  extract \&code;
  extract \@commandlist;
};

Instructions for the extract stage. May be either a code reference or a command list.

🦋 patch

share {
  patch \&code;
  patch \@commandlist;
};

Instructions for the patch stage. May be either a code reference or a command list.

👑 patch_ffi

share {
  patch_ffi \&code;
  patch_ffi \@commandlist;
};

[DEPRECATED] — do not come for her, she's retired 💀

Instructions for the patch_ffi stage. May be either a code reference or a command list.

🌸 build

share {
  build \&code;
  build \@commandlist;
};

Instructions for the build stage. May be either a code reference or a command list.

💅 build_ffi

share {
  build \&code;
  build \@commandlist;
};

[DEPRECATED] — same energy, also retired 💀

Instructions for the build FFI stage. It builds shared libraries instead of static ones. This one is optional, and it's only necessary if a fresh and separate build needs to happen for FFI. Like, only if you really need it.

🍓 gather

gather \&code;
gather \@commandlist;

share {
  gather \&code;
  gather \@commandlist;
};

sys {
  gather \&code;
  gather \@commandlist;
};

Instructions for the gather stage. May be either a code reference or a command list. Put it in the root block of the alienfile and it'll trigger in both the share and system build. Put it in the share or sys block and it'll only trigger in the corresponding build. Location matters, bestie 📍

🧚 gather_ffi

share {
  gather_ffi \&code;
  gather_ffi \@commandlist;
}

[DEPRECATED] 💀

Gather specific to build_ffi. Not usually necessary.

⭐ ffi

share {
  ffi {
    patch \&code;
    patch \@commandlist;
    build \&code;
    build \@commandlist;
    gather \&code;
    gather \@commandlist;
  }
}

Specify patch, build or gather stages related to FFI. One block, all the FFI vibes 💫

🌈 meta_prop

my $hash = meta_prop;

Get the meta_prop hash reference.

💜 meta

my $meta = meta;

Returns the meta object for your alienfile. For the methods you can use on the meta object, go look at "META METHODS" in Alien::Build.

🎀 log

log($message);

Prints the given log to stdout. Simple, iconic, does exactly what it says 💅

🔥 test

share {
  test \&code;
  test \@commandlist;
};
sys {
  test \&code;
  test \@commandlist;
};

Run the tests. Gotta verify, always verify ✅

🦋 before

before $stage => \&code;

Execute the given code before the given stage. The stage should be one of probe, download, fetch, decode, prefer, extract, patch, build, test, and gather.

The before directive is only legal in the same blocks as the stage would normally be legal in. So for example, you can't do this:

use alienfile;

sys {
  before 'build' => sub {
    ...
  };
};

Because a build wouldn't be legal inside a sys block. Rules are rules, bestie 🚫

🌸 after

after $stage => \&code;

Execute the given code after the given stage. The stage should be one of probe, download, fetch, decode, prefer, extract, patch, build, test, and gather.

The after directive is only legal in the same blocks as the stage would normally be legal in. So for example, you can't do this:

use alienfile;

sys {
  after 'build' => sub {
    ...
  };
};

Because a build wouldn't be legal inside a sys block. Same rule, same energy ✨

---

💫 SEE ALSO 💫

• Alien
• Alien::Build
• Alien::Build::MM
• Alien::Base

---

🫶 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.

---

and that's the whole page, bestie ✨💖🦋 This one was served up by perl v5.42.3 on 2026-09-21, so when you're reading this on some future date just know the vibe has been immaculate since then 🎀 tysm for reading, mwah 💅