Alien::Build(3)

💖 Alien::Build(3) 💖

User Contributed Perl Documentation — the manual page, but make it a vibe ✨

✨ NAME ✨

Alien::Build — Build external dependencies for use in CPAN 💅

⭐ VERSION ⭐

version 2.88 — iconic, no cap

🌈 SYNOPSIS 🌈

okay so bestie, here's the whole flow:

my $build = Alien::Build->load('./alienfile');
$build->load_requires('configure');
$build->set_prefix('/usr/local');
$build->set_stage('/foo/mystage');  # needs to be absolute
$build->load_requires($build->install_type);
$build->download;
$build->build;
# files are now in /foo/mystage, it is your job (or
# ExtUtils::MakeMaker, Module::Build, etc) to copy
# those files into /usr/local

💜 DESCRIPTION 💜

This module gives you the tools to build external (non-CPAN) dependencies for CPAN. Main character energy: it's mainly meant to be used at install time by a CPAN client, and it works super closely with Alien::Base, which is the runtime bestie.

This is the detailed documentation for the Alien::Build class. If you're just starting out, you probably want to begin with one of these docs:

• Alien::Build::Manual::Alien — a broad overview of Alien-Build and its whole ecosystem.
• Alien::Build::Manual::AlienUser — for users of an Alien::libfoo that is implemented using Alien::Base. (The developer of Alien::libfoo should provide the docs you need, but if they don't, this is the place to start.)
• Alien::Build::Manual::AlienAuthor — if you're writing your own Alien based on Alien::Build and Alien::Base.
• Alien::Build::Manual::FAQ — if you have a common question that's already been answered, like "How do I use alienfile with some build system".
• Alien::Build::Manual::PluginAuthor — for the brave souls who want to write plugins that work with Alien::Build + alienfile.
• Alien::Build::Manual::Security — if you're concerned that Aliens might be downloading tarballs off the internet. This discusses some of the risks of downloading (really any) software off the internet and gives you some tools to remediate those risks.

Note that you will not usually create an Alien::Build instance directly. Instead you'll be using a thin installer layer, like Alien::Build::MM (for use with ExtUtils::MakeMaker) or Alien::Build::MB (for use with Module::Build). One of the goals of this project is to stay installer agnostic. periodt.

🎀 CONSTRUCTORS 🎀

✨ new

my $build = Alien::Build->new;

This creates a new empty instance of Alien::Build. Normally you'll want to use load below to create an instance of Alien::Build from an alienfile recipe.

✨ load

my $build = Alien::Build->load($alienfile);

This creates an Alien::Build instance with the given alienfile recipe.

✨ resume

my $build = Alien::Build->resume($alienfile, $root);

Load a checkpointed Alien::Build instance. You'll need the original alienfile and the build root (usually _alien), plus a build that had been properly checkpointed using the checkpoint method below.

🦋 PROPERTIES 🦋

There are three main properties for Alien::Build. There are a number of properties documented here with a specific usage. Heads up: these properties may need to be serialized into something primitive like JSON that does not support: regular expressions, code references of blessed objects.

If you're writing a plugin (Alien::Build::Plugin) you should use a prefix like plugin_name (where name is the name of your plugin) so that it doesn't interfere with other plugin or future versions of Alien::Build. For example, if you were writing Alien::Build::Plugin::Fetch::NewProtocol, please use the prefix plugin_fetch_newprotocol:

sub init
{
  my($self, $meta) = @_;

  $meta->prop( plugin_fetch_newprotocol_foo => 'some value' );

  $meta->register_hook(
    some_hook => sub {
      my($build) = @_;
      $build->install_prop->{plugin_fetch_newprotocol_bar} = 'some other value';
      $build->runtime_prop->{plugin_fetch_newprotocol_baz} = 'and another value';
    }
  );
}

If you're writing an alienfile recipe please use the prefix my_:

use alienfile;

meta_prop->{my_foo} = 'some value';

probe sub {
  my($build) = @_;
  $build->install_prop->{my_bar} = 'some other value';
  $build->install_prop->{my_baz} = 'and another value';
};

Any property may be used from a command:

probe [ 'some command %{.meta.plugin_fetch_newprotocol_foo}' ];
probe [ 'some command %{.install.plugin_fetch_newprotocol_bar}' ];
probe [ 'some command %{.runtime.plugin_fetch_newprotocol_baz}' ];
probe [ 'some command %{.meta.my_foo}' ];
probe [ 'some command %{.install.my_bar}' ];
probe [ 'some command %{.runtime.my_baz}' ];

💖 meta_prop 💖

my $href = $build->meta_prop;
my $href = Alien::Build->meta_prop;

Meta properties have to do with the recipe itself, and not any particular instance that probes or builds that recipe. Meta properties can be changed from within an alienfile using the meta_prop directive, or from a plugin from its init method (though should NOT be modified from any hooks registered within that init method). This is not strictly enforced, but if you do not follow this rule your recipe will likely be broken.

🌟 arch

This is a hint to an installer like Alien::Build::MM or Alien::Build::MB, that the library or tool contains architecture dependent files and so should be stored in an architecture dependent location. If not specified by your alienfile then it will be set to true.

🔒 check_digest

True if cryptographic digest should be checked when files are fetched or downloaded. This is set by Digest negotiator plugin.

📦 destdir

Some plugins (Alien::Build::Plugin::Build::Autoconf for example) support installing via DESTDIR. They will set this property to true if they plan on doing such an install. This helps Alien::Build find the staged install files and how to locate them.

If available, DESTDIR is used to stage install files in a sub directory before copying the files into blib. This is generally preferred method if available.

🧹 destdir_filter

Regular expression for the files that should be copied from the DESTDIR into the stage directory. If not defined, then all files will be copied.

🧹 destdir_ffi_filter

Same as destdir_filter except applies to build_ffi instead of build.

🔐 digest

This properties contains the cryptographic digests (if any) that should be used when verifying any fetched and downloaded files. It is a hash reference where the key is the filename and the value is an array reference containing a pair of values, the first being the algorithm ('SHA256' is recommended) and the second is the actual digest. The special filename * may be specified to indicate that any downloaded file should match that digest. If there are both real filenames and the * placeholder, the real filenames will be used for filenames that match and any other files will use the placeholder. Example:

$build->meta_prop->{digest} = {
  'foo-1.00.tar.gz' => [ SHA256 => '9feac593aa49a44eb837de52513a57736457f1ea70078346c60f0bfc5f24f2c1' ],
  'foo-1.01.tar.gz' => [ SHA256 => '6bbde6a7f10ae5924cf74afc26ff5b7bc4b4f9dfd85c6b534c51bd254697b9e7' ],
  '*'               => [ SHA256 => '33a20aae3df6ecfbe812b48082926d55391be4a57d858d35753ab1334b9fddb3' ],
};

Cryptographic signatures will only be checked if the check_digest meta property is set and if the Digest negotiator plugin is loaded. (The Digest negotiator can be used directly, but is also loaded automatically if the digest directive is used by the alienfile.)

🌿 env

Environment variables to override during the build stage.

🌿 env_interpolate

Environment variable values will be interpolated with helpers. Example:

meta->prop->{env_interpolate} = 1;
meta->prop->{env}->{PERL} = '%{perl}';

🏠 local_source

Set to true if source code package is available locally. (that is not fetched over the internet). This is computed by default based on the start_url property. Can be set by an alienfile or plugin.

🖥️ platform

Hash reference. Contains information about the platform beyond just $^O.

• platform.compiler_type — Refers to the type of flags that the compiler accepts. May be expanded in the future, but for now, will be one of:
  • microsoft — On Windows when using Microsoft Visual C++
  • unix — Virtually everything else, including gcc on windows.

The main difference is that with Visual C++ -LIBPATH should be used instead of -L, and static libraries should have the .LIB suffix instead of .a.

• platform.system_type — $^O is frequently good enough to make platform specific logic in your alienfile, this handles the case when $^O can cover platforms that provide multiple environments that Perl might run under. The main example is windows, but others may be added in the future.
  • unix
  • vms
  • windows-activestate
  • windows-microsoft
  • windows-mingw
  • windows-strawberry
  • windows-unknown

Note that cygwin and msys are considered unix even though they run on windows!

• platform.cpu.count — Contains a non-negative integer of available (possibly virtual) CPUs on the system. This can be used by build plugins to build in parallel. The environment variable ALIEN_CPU_COUNT can be set to override the CPU count.
• platform.cpu.arch.name — Contains a normalized name for the architecture of the current Perl. This can be used by fetch plugins to determine which binary packages to download. The value may be one of the following, but this list will be expanded as needed.
  • "armel" — 32-bit ARM soft-float
  • "armhf" — 32-bit ARM hard-float
  • "aarch64" — 64-bit ARM
  • "ppc" — 32-bit PowerPC (big-endian)
  • "ppc64" — 64-bit PowerPC (big-endian)
  • "x86" — 32-bit Intel (i386, i486, i686)
  • "x86_64" — 64-bit Intel (AMD64)
  • "unknown" — Unable to detect architecture. Please report this if needed.
• out_of_source — build in a different directory from where the source code is stored. Autoconf girlies call this a "VPATH" build, everyone else says "out-of-source", and honestly both are valid. When this property is true, instead of extracting into the source build root, the downloaded source gets extracted into a source extraction directory and the source build root is just... empty. Wanna know where it actually landed? Use the extract install property. 💅
• network — true when a network fetch is available. Bestie, do NOT set this in an alienfile or a plugin, that is simply not your job. It's computed for you based on the ALIEN_INSTALL_NETWORK environment variables. 🫶
• start_url — the default or start URL that fetch plugins vibe with. 🌈

install_prop

my $href = $build->install_prop;

Install properties are the install-phase girlies (whether you're running a "share" or a "system" install). They get remembered for the entire install phase and then do not stick around during the runtime phase — which means your Alien::Base based module literally cannot access them. So don't build a whole personality around them. 😭

• autoconf_prefix — the prefix, but the way autoconf understands it. This is only different on Windows where MSYS is used and paths like C:/foo get represented as /C/foo — MSYS tools get that, Perl does not, and that's the whole tea. Only use this if you've got Alien::Build::Plugin::Build::Autoconf in your alienfile. It gets set before the build hook is run. ✨
• download — the location of the downloaded archive (tar.gz, or whatever) or directory. Heads up: this stays undef until the archive is actually downloaded. Don't come for it early. 💀
• download_detail — optional details about a downloaded file. This one is populated by Alien::Build core itself. It's a hash reference: the key is the path to the file that got downloaded, and the value is a hash reference with additional detail. All fields are optional.

download_detail.digest

If it's available, this is the cryptographic signature that was successfully matched against the downloaded file. It's an array reference with a pair of values: the algorithm (typically something like SHA256) and the digest. 🔐

download_detail.protocol

If it's available, this is the URL protocol used to fetch the downloaded file. 🌐

• env — environment variables to override during the build stage. Plugins are free to set additional overrides using this hash. 🛠️
• extract — the location of the last source extraction. For an "out-of-source" build (peep the out_of_source meta property above 👀), this only gets set once. For other types of builds, the source code may be extracted multiple times, so this property may change on you. Not its fault, it's just living its truth.
• old [deprecated]

A hash with info on a previously installed Alien of the same name, if one's available. Lowkey useful when you wanna reuse the previous install if it's still sufficient. ♻️

old.prefix

[deprecated]

The prefix for the previous install. Versions prior to 1.42 unfortunately shipped this with a typo — preifx. Not a vibe, but we respect the lore. 🙈

old.runtime

[deprecated]

The runtime properties from the previous install.

• patch — directory with patches, if any are available. This will be undef if there are no patches. When you're initially installing an alien this is usually a sibling of the alienfile, a directory called patch. Once installed, it'll be in the share directory called _alien/patch. The former is useful for rebuilding an alienized package using af. 🩹
• prefix — the install time prefix. Under a destdir install this is the same as the runtime or final install location. Under a non-destdir install this is the "stage" directory (usually the appropriate share directory under blib). 📍
• root — the build root directory. This is an absolute path. By default it's the absolute form of ./_alien. 🏠
• stage — the stage directory where files will be copied. Usually the root of the blib share directory.
• system_probe_class — after the probe step, this may contain the plugin class that performed the system probe. It shouldn't be filled in directly by the plugin (instead it should use the hook property probe_class, see below 👇). This is optional — not all probe plugins will provide this info. 🕵️
• system_probe_instance_id — after the probe step, this may contain the plugin instance id that performed the system probe. Same deal: it shouldn't be filled in directly by the plugin (instead it should use the hook property probe_instance_id, see below 👇). Optional, and again, not all probe plugins will provide this. 🕵️

plugin_instance_prop

my $href = $build->plugin_instance_prop($plugin);

This returns the private plugin instance properties for a given plugin. Bestie, this method should usually only ever be called internally by plugins themselves, to keep track of their own internal state. Why? Because the content can be used arbitrarily by the owning plugin since it's private to that plugin — which means it is not part of the Alien::Build spec. It's their diary, don't read it. 📓

runtime_prop

my $href = $build->runtime_prop;

Runtime properties are used during the install and runtime phases (either under a "share" or a "system" install). These should include anything you'll need to know to actually use the library or tool at runtime — and should not include anything that stops being relevant once the install process is done. Marie Kondo that hash. ✨

• alien_build_version — the version of Alien::Build that was used to install the library or tool.
• alt — alternate configurations. If the alienized package has multiple libraries, this can store the different compiler or linker flags for each one. Typically set by a plugin in the gather stage (for either share or system installs). 🎛️
• cflags — the compiler flags. Typically set by a plugin in the gather stage (for either share or system installs). 🔧
• cflags_static — the static compiler flags. Typically set by a plugin in the gather stage (for either share or system installs).
• command — the command name for tools where the name may differ from platform to platform. For example, the GNU version of make is usually make on Linux and gmake on FreeBSD. Typically set by a plugin in the gather stage (for either share or system installs). 🐧
• ffi_name — the name DLL or shared object name to use when searching for dynamic libraries at runtime. This gets passed into FFI::CheckLib, so if your library is something like libarchive.so or archive.dll, you'd set this to archive. It may be a string or an array of strings. Typically set by a plugin in the gather stage (for either share or system installs). 📚
• ffi_checklib — this property contains two sub properties:

ffi_checklib.share

$build->runtime_prop->{ffi_checklib}->{share} = [ ... ];

An array of additional FFI::CheckLib flags to pass in to find_lib for a share install.

ffi_checklib.system

An array of additional FFI::CheckLib flags to pass in to find_lib for a system install.

Among other things, this is useful for specifying the try_linker_script flag:

$build->runtime_prop->{ffi_checklib}->{system} = [ try_linker_script => 1 ];

This is typically set by a plugin in the gather stage (for either share or system installs).

• inline_auto_include [version 2.53]

This property is an array reference of C code that gets passed into Inline::C to make sure the appropriate headers are automatically included. See "auto_include" in Inline::C for details. 🌸

• install_type — the install type. This is set by AB core after the probe hook is executed. It's one of:

system

For when the library or tool is provided by the operating system, can be detected by Alien::Build, and is considered satisfactory by the alienfile recipe. 👑

share

For when a system install is not possible, so the library source gets downloaded from the internet (or retrieved in another appropriate fashion) and built. 🏗️

• libs — the library flags. Typically set by a plugin in the gather stage (for either share or system installs). 📦
• libs_static — the static library flags. Typically set by a plugin in the gather stage (for either share or system installs).
• perl_module_version — the version of the Perl module used to install the alien (if it's available). For example, if Alien::curl is installing libcurl, this would be the version of Alien::curl used during the install step. 🐪
• prefix — the final install root. This is usually the share directory. 🏡
• version — the version of the library or tool. Typically set by a plugin in the gather stage (for either share or system installs). 🏷️

hook_prop

my $href = $build->hook_prop;

Hook properties are for the currently running hook (if there is one). They're used only during the execution of each hook and get discarded right after — like a group chat that self-destructs. If no hook is currently running, then hook_prop returns undef. 💀

• name — the name of the currently running hook. 🏷️
• version (probe) — Probe and PkgConfig plugins may set this property to indicate the version of the alienized package. Not all plugins and configurations are able to provide this, and that's okay. 💜
• probe_class (probe) — Probe and PkgConfig plugins may set this property to indicate the plugin class that made the probe. If the probe results in a system install, this gets propagated to system_probe_class for later use. 📤
• probe_instance_id (probe) — Probe and PkgConfig plugins may set this property to indicate the plugin instance id that made the probe. If the probe results in a system install, this gets propagated to system_probe_instance_id for later use. 📤

💅 METHODS 💅

checkpoint

$build->checkpoint;

bestie this one saves all your install + runtime properties so they can get reloaded later on, in a whole separate process. super useful when your build has to happen in multiple stages from a Makefile (yes, like with ExtUtils::MakeMaker). once you've checkpointed, you hit up the resume constructor (documented up above, go look) to pick the probe/build/install process back up where it left off. ✨

root

my $dir = $build->root;

this is literally just a shortcut for:

my $root = $build->install_prop->{root};

except it'll create the thing if it doesn't already exist. so convenient of it 🫶

install_type

my $type = $build->install_type;

returns the install type. (check the same-named install property above for the deets.) and heads up: this method will call probe if nobody's called it yet. it does the work for you, iconic behavior 💅

is_system_install

my $boolean = $build->is_system_install;

true if the alien is a system install type. slay.

is_share_install

my $boolean = $build->is_share_install;

true if the alien is a share install type. also slay.

download_rule

my $rule = $build->download_rule;

this hands you the install rule as a string. it's decided by the environment, and it should be one of these:

• warn — only warn if you're fetching from a non-secure source (secure sources include https and bundled files, and may include other encrypted protocols in the future).
• digest — require that any downloaded source package has a cryptographic signature in the alienfile, and that the signature matches what got downloaded.
• encrypt — require that any downloaded source package is fetched via a secure source.
• digest_or_encrypt — require that any downloaded source package is either fetched via a secure source or has a cryptographic signature in the alienfile that matches what got downloaded.
• digest_and_encrypt — require that any downloaded source package is both fetched via a secure source and has a cryptographic signature in the alienfile that matches what got downloaded.

the current default is warn, but in the near future it's getting upgraded to digest_or_encrypt. stay ready 🌈

set_prefix

$build->set_prefix($prefix);

sets the final (unstaged) prefix. normally only Alien::Build::MM and friends call this. it is not intended for use from plugins or from an alienfile, so don't be out here doing that 🙈

set_stage

$build->set_stage($dir);

sets the stage directory. again, normally only Alien::Build::MM and similar modules call this, and it is not meant to be used from plugins or from an alienfile. same energy, same warning 💀

requires

my $hash = $build->requires($phase);

returns a hash ref of the modules required for the given phase. the phases are:

• configure — these modules must already be available when the alienfile is read.
• any — these modules are used during either a system or share install.
• share — these modules are used during the build phase of a share install.
• system — these modules are used during the build phase of a system install.

load_requires

$build->load_requires($phase);

this loads up the right modules for the given phase (see requires just above for what the phases actually are). ✨

probe

my $install_type = $build->probe;

tries to figure out if the operating system already has the library or tool installed. if it does, you get the string system back and a system install happens. if not, then share gets installed and the tool or library gets downloaded and built from source. detective work fr fr 🔍

if the environment variable ALIEN_INSTALL_TYPE is set, that forces a specific type of install. and if the detection logic can't accommodate the install type you asked for? it fails with an exception. no cap.

download

$build->download;

downloads the source, usually as a tarball, usually from the internet 🌐

under a system install this does absolutely nothing. it's giving "showed up to work with no tasks" 😭

fetch

my $res = $build->fetch;
my $res = $build->fetch($url, %options);

fetches a resource using the fetch hook. returns the same hash structure that's described below in the fetch hook documentation.

[version 2.39]

as of Alien::Build 2.39, these options are supported:

• http_headers

my $res = $build->fetch($url, http_headers => [ $key1 => $value1, $key2 => $value 2, ... ]);

sets the HTTP request headers on all outgoing HTTP requests. heads up though: not every protocol or fetch plugin supports setting request headers, but the ones that don't should issue a warning if you try to set them anyway. so if you see a warning, that's why bestie 💜

check_digest

[experimental]

my $bool = $build->check_digest($path);

checks any cryptographic signatures for the given file. the file is specified by $path, which can be one of:

• string — containing the path to the file to be checked.
• Path::Tiny — containing the path to the file to be checked.
• HASH — a hash reference containing information about a file. see the fetch hook for details on the format.

returns true if the cryptographic signature matches, and false if cryptographic signatures are disabled. it will throw an exception if the signature doesn't match, or if no plugin provides the correct algorithm for checking the signature. so like, be ready for that 😳

decode

my $decoded_res = $build->decode($res);

decodes the HTML or file listing that fetch gave you. returns the same hash structure described below in the decode hook documentation. 🦋

prefer

my $sorted_res = $build->prefer($res);

filters and sorts the candidates. the preferred candidate comes back first in the list, and the worst candidate comes back last. returns the same hash structure described below in the prefer hook documentation. main character goes first, periodt 👑

extract

my $dir = $build->extract;
my $dir = $build->extract($archive);

extracts the given archive into a fresh directory. this is normally called internally by Alien::Build, and for normal usage you don't need it from a plugin or an alienfile. leave it to the professionals 💅

build

$build->build;

runs the build step. it's expected that probe and download have already been done. what it actually does depends on the type of install:

• share — the source is extracted, and built as determined by the alienfile recipe. if there's a gather_share, that gets executed last.
• system — the gather_system hook gets executed.

test

$build->test;

runs the test phase. good luck bestie, you got this 🍓

clean_install

$build->clean_install

cleans files out of the final install location. the default implementation removes all files recursively except for the _alien directory. this is a lifesaver when you've got an old install with files that might break the new build. spring cleaning energy 🧹✨

system

$build->system($command);
$build->system($command, @args);

interpolates the command and its arguments, then runs the results using the Perl system command. 🔥

log

$build->log($message);

sends a message to the log. by default this prints to STDOUT. say it with your chest 📢

meta

my $meta = Alien::Build->meta;
my $meta = $build->meta;

returns the meta object for your Alien::Build class or instance. the meta object is how you manipulate the recipe, which means any changes to it should be made before the probe, download or build steps. timing is everything 💖

---

✨ META METHODS ✨

prop

my $href = $build->meta->prop;

meta properties. this is the same as calling meta_prop on the class or the Alien::Build instance. 💫

add_requires

Alien::Build->meta->add_requires($phase, $module => $version, ...);

adds the requirement to the given phase. phase should be one of:

• configure
• any
• share
• system

has_requires

if (Alien::Build->meta->has_requires($phase, $module_pat, ...)) {...}

tests whether the given phase has any of the given substrings as a requirement. phase works like it does in add_requires. 🕵️

interpolator

my $interpolator = $build->meta->interpolator;
my $interpolator = Alien::Build->interpolator;

returns the Alien::Build::Interpolate instance for the Alien::Build class. 🌸

has_hook

my $bool = $build->meta->has_hook($name);
my $bool = Alien::Build->has_hook($name);

returns whether there's a usable hook registered with the given name. 👀

register_hook

$build->meta->register_hook($name, $instructions);
Alien::Build->meta->register_hook($name, $instructions);

registers a hook with the given name. $instructions should be either a code reference or a command sequence, which is an array reference. 🔧

default_hook

$build->meta->default_hook($name, $instructions);
Alien::Build->meta->default_hook($name, $instructions);

registers a default hook, which gets used if the alienfile doesn't register its own hook with that name. it's the backup bestie 🫶

around_hook

$build->meta->around_hook($hook_name, $code);
Alien::Build->meta->around_hook($hook_name, $code);

wraps the given hook with a code reference. this is similar to a Moose method modifier, except it wraps around the given hook instead of a method. for example, this will add a probe system requirement:

$build->meta->around_hook(
  probe => sub {
    my $orig = shift;
    my $build = shift;
    my $type = $orig->($build, @_);
    return $type unless $type eq 'system';
    # also require a configuration file
    if(-f '/etc/foo.conf')
    {
      return 'system';
    }
    else
    {
      return 'share';
    }
  },
);

after_hook

$build->meta->after_hook($hook_name, sub {
  my(@args) = @_;
  ...
});

executes the given code reference after the hook. the original arguments get passed into the code reference. 🎀

before_hook

$build->meta->before_hook($hook_name, sub {
  my(@args) = @_;
  ...
});

executes the given code reference before the hook. the original arguments get passed into the code reference. same deal, opposite timing 💜

apply_plugin

Alien::Build->meta->apply_plugin($name);
Alien::Build->meta->apply_plugin($name, @args);

applies the given plugin with the given arguments. go off, plugin 💅✨

🌈 ENVIRONMENT 🌈

okay bestie so Alien::Build is very online and it listens to these env vars, like it's literally reading your vibes from the shell 💅

• ALIEN_BUILD_LOG — the default log class it's gonna use. go peek at Alien::Build::Log and Alien::Build::Log::Default if you wanna know more 🫶
• ALIEN_BUILD_PKG_CONFIG — this one overrides the logic inside Alien::Build::Plugin::PkgConfig::Negotiate, the part that picks the best pkg-config plugin. so you can just choose for it, main character energy 👑
• ALIEN_BUILD_POSTLOAD — a semicolon separated list of plugins that get loaded after your alienfile gets parsed. post-parse glow-up ✨
• ALIEN_BUILD_PRELOAD — same deal but a semicolon separated list of plugins loaded before your alienfile is parsed. pre-game ritual 🎀
• ALIEN_BUILD_RC — a Perl source file that can override some global defaults for Alien::Build, like, for example, setting preload and postload plugins. your lil config bestie 📝
• ALIEN_DOWNLOAD_RULE — this value decides the rules for which types of downloads are allowed. the legal values are the ones listed under download_rule, plus "default", which means "whatever the default is for the current version of Alien::Build". for this version that default is "warn". noted, no cap ⚠️
• ALIEN_INSTALL_NETWORK — if you set it to true (which is the default btw), network fetch is allowed. if you set it to false, network fetch is not allowed, periodt 🚫

what counts as a local vs. network fetch is figured out from the "start_url" and "local_source" meta properties. an alienfile or a plugin could override that detection (possibly inappropriately, like, rude), so this variable is not a substitute for properly auditing Perl modules for environments that require that. do the actual work, bestie 🫡

• ALIEN_INSTALL_TYPE — if you set it to "share" or "system", it overrides the system detection logic. if you set it to "default", it uses the default setting for the alienfile. the behavior of other values is undefined, so like, don't 😭

so here's the tea: 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. but 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 live in the consuming CPAN module. iykyk 💜

• DESTDIR — this environment variable gets manipulated during a destdir install. hands off unless you know 🛠️
• PKG_CONFIG — you can use this to override the program name for "pkg-config" when you're using the command line plugin: Alien::Build::Plugin::PkgConfig::CommandLine 🎯
• ftp_proxy, all_proxy — if these are set, they may influence the Download negotiation plugin Alien::Build::Plugin::Download::Negotiate. other proxy variables may be used by some Fetch plugins, if they support it. it's giving "depends on the plugin" energy 🙈

---

💖 SUPPORT 💖

the intent of the "Alien-Build" team is to support the same versions of Perl that are supported by the Perl toolchain. as of this writing that means 5.16 and better ⭐

please feel so encouraged to report issues that you encounter to the project GitHub Issue tracker:

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

and even better — if you can fix the issue yourself, please feel encouraged to open a pull-request on the project GitHub:

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

if you are confounded and have questions, come join us on the "#native" channel on irc.perl.org 🦋 the "Alien-Build" developers frequent this channel and can probably help point you in the right direction. and if you don't have an IRC client handy, you can use this web interface:

https://chat.mibbit.com/?channel=%23native&server=irc.perl.org

we don't bite, bestie, come say hi 💅

---

👀 SEE ALSO 👀

• Alien::Build::Manual::AlienAuthor
• Alien::Build::Manual::AlienUser
• Alien::Build::Manual::Contributing
• Alien::Build::Manual::FAQ
• Alien::Build::Manual::PluginAuthor
• alienfile
• Alien::Build::MM
• Alien::Build::Plugin
• Alien::Base
• Alien

go read them, they're all bangers 📚✨

---

🌸 THANKS 🌸

Alien::Base was originally written by Joel Berger, and the rest of this project would not have been possible without him getting the project started. thanks to his support, "I" have been able to augment the original Alien::Base system with a reliable set of tools (Alien::Build, alienfile, Test::Alien), which make up this toolset 🫶

the original Alien::Base is still copyright (c) 2012-2020 Joel Berger. it has the same license as the rest of the Alien::Build and related tools distributed as "Alien-Build". Joel Berger thanked a number of people who helped in the development of Alien::Base, in the documentation for that module. iconic behavior 👑

I would also like to acknowledge the other members of the PerlAlien github organization, Zakariyya Mughal (sivoais, ZMUGHAL) and mohawk (ETJ). also important in the early development of Alien::Build were the early adopters Chase Whitener (genio, CAPOEIRAB, author of Alien::libuv), William N. Braswell, Jr (willthechill, WBRASWELL, author of Alien::JPCRE2 and Alien::PCRE2) and Ahmad Fatoum (a3f, ATHREEF, author of Alien::libudev and Alien::LibUSB) 💖

the Alien ecosystem owes a debt to Dan Book, who goes by Grinnz on IRC, for answering question about how to use Alien::Build and friends. the realest 🙏

---

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

look at that roster, it's giving legendary 🌈👑

---

📜 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. slay, legally speaking 💅

---

aaaand that's the whole page, bestie!! 🎀 this was perl v5.42.3, dated 2026-09-21, and you just read the one and only Alien::Build(3) 💖 go build something iconic, mwah 😘