Alien:...ld::API(3pm)

📦

version 1.17 · 3 versions

1.17 · fedora 43 (latest)
1.17 · arch rolling
1.17 · fedora 44

💖 Alien::Base::ModuleBuild::API(3pm) 💖

okay bestie, welcome to the User Contributed Perl Documentation page for Alien::Base::ModuleBuild::API(3pm). This is the API Reference for Alien:: Authors, and we're about to go through every single section in order, no skips, no cap. ✨🦋

🌸 NAME 🌸

Alien::Base::ModuleBuild::API — API Reference for Alien:: Authors. That's the name, that's the vibe. 💅

🌟 VERSION 🌟

version 1.17 — periodt. 💖

🦋 DESCRIPTION 🦋

NOTE: Please consider for new development of Aliens that you use Alien::Build and alienfile instead. Like Alien::Base::ModuleBuild they work with Alien::Base. Unlike Alien::Base::ModuleBuild they are more easily customized and handle a number of corner cases better. For a good place to start, please see Alien::Build::Manual::AlienAuthor. Although the Alien-Base / Alien-Build team will continue to maintain this module, (we will continue to fix bugs where appropriate), we aren't adding any new features to this module.

A list of extra properties and methods provided by Alien::Base::ModuleBuild beyond those contained in Module::Build::API. Note that all property and method names are prefixed with "alien_" to prevent future collisions Module::Build builtins.

🛠️ CONSTRUCTOR 🛠️

Alien::Base::ModuleBuild adds several parameters to the new constructor in Module::Build. Unless otherwise specified all of the parameters listed in Module::Build::API are available and behave identically to the description contained therein.

`alien_arch`

[version 0.019]

Install module into an architecture specific directory. This is off by default, unless $ENV{ALIEN_ARCH} is true. Most Alien distributions will be installing binary code. If you are an integrator where the @INC path is shared by multiple Perls in a non-homogeneous environment you can set $ENV{ALIEN_ARCH} to 1 and Alien modules will be installed in architecture specific directories.

`alien_autoconf_with_pic`

[version 0.005]

Add "--with-pic" option to autoconf style "configure" script when called. This is the default, and normally a good practice. Normally autoconf will ignore this and any other options that it does not recognize, but some non-autoconf "configure" scripts may complain.

`alien_bin_requires`

[version 0.006]

Hash reference of modules (keys) and versions (values) that specifies "Alien" modules that provide binary tools that are required to build. Any Alien::Base module that includes binaries should work. Also supported are Alien::MSYS, Alien::CMake, Alien::TinyCC and Alien::Autotools.

[version 0.007]

These only become required for building if Alien::Base::ModuleBuild determines that a source code build is required.

`alien_build_commands`

[version 0.001]

An arrayref of commands used to build the library in the directory specified in "alien_temp_dir". Each command is first passed through the command interpolation engine, so those variables may be used. The default is tailored to the GNU toolchain, i.e. AutoConf and Make; it is "[ '%c --prefix=%s', 'make' ]".

[version 0.009]

Each command may be either a string or an array reference. If the array reference form is used then the multiple argument form of "system" is used. Prior to version 0.009, only the string form was supported.

`alien_env`

[version 0.027]

Environment overrides. Allows you to set environment variables as a hash reference that will override environment variables. You can use the same interpolated escape sequences and helpers that commands use. Set to undef to remove the variable.

...
Alien::Base::ModuleBuild->new(
  ...
  alien_env => {
    PERL => '%X',     # sets the environment variable PERL to the location
                      # of the Perl interpreter.
    PERCENT => '%%',  # evaluates to '%'
    REMOVE => undef,  # remove the environment variable if it is defined
  },
  ...
);
...

Please keep in mind that frequently users have a good reason to have set environment variables, and you should not override them without a good reason. An example of a good justification would be if a project has a Makefile that interacts badly with common environment variables. This can sometimes be a problem since Makefile variables can be overridden with environment variables.

A useful pattern is to use a helper to only override an environment variable if it is not already set.

...
Alien::Base::ModuleBuild->new(
  ...
  alien_helper => {
    foo => '$ENV{FOO}||"my preferred value if not already set"'
  },
  alien_env => {
    FOO => '%{foo}',
  },
  ...
);
...

A common pitfall with environment variables is that setting one to the empty string ('') is not portable. On Unix it works fine as you would expect, but in Windows it actually unsets the environment variable, which may not be what you intend.

...
Alien::Base::ModuleBuild->new(
  ...
  alien_env => {
    # is allowed, but may not do what you intend
    # on some platforms!
    FOO => '',
  },
);
...

`alien_extra_site_config`

[version 0.030]

Append extra values to the "config.site" file when using autoconf.

When <autoconf> is detected, a "config.site" file is created with values appropriate for building software that can link against the Perl that you are building with. This is important on some platforms, for example 64 bit systems where the compilers generate 32 bit code by default. You can also add values to the "config.site" file using this directive.

For values that are already provided by "Alien::Base::ModuleBuild", your value will be appended after the existing value. For values that aren't provided, it will simply use your value by itself.

For example if you needed to add a define to a CFLAGS, you might do something like this:

...
Alien::Base::ModuleBuild->new(
  ...
  alien_extra_site_config => {
    # CFLAGS is usually specified by A::B::MB
    CFLAGS => '-DFOO=1',
    # BAR usually is not.
    BAR => 'baz',
  },
  ...
);
...

And the actual value for CFLAGS in the "config.site" might have values like this:

CFLAGS=-O3 -g -DFOO=1
BAR=baz

`alien_ffi_name`

[version 0.007]

The name of the shared library for use with FFI. Provided for situations where the shared library name cannot be determined from the "pkg-config" name specified with "alien_name". For example "libxml2" has a "pkg-config" of "libxml-2.0", but a shared library name of "xml2". By default alien_name is used with any "lib" prefix removed. For example "libarchive" to be translated into "archive" which is what you want for that package.

`alien_helper`

[version 0.020]

Provide helpers to generate commands or arguments at build or install time. This property is a hash reference. The keys are the helper names and the values are strings containing Perl code that will be evaluated and interpolated into the command before execution. Because helpers are only needed when building a package from the source code, any dependency may be specified as an "alien_bin_requires". For example:

...
Alien::Base::ModuleBuild->new(
  ...
  alien_bin_requires => {
    'Alien::foo' => 0,
  },
  alien_helper => {
    'foocommand'  => 'Alien::foo->some_command',
    'fooargument' => 'Alien::foo->some_argument',
  },
  alien_build_commands => [
    '%{foocommand} %{fooargument}',
  ],
  ...
);

[version 0.022]

One helper that you get for free is "%{pkg_config}" which will be the pkg-config implementation chosen by Alien::Base::ModuleBuild. This will either be the real pkg-config provided by the operating system (preferred) or PkgConfig, the pure perl implementation found on CPAN.

`alien_inline_auto_include`

[version 0.006]

Array reference containing the list of header files to be used automatically by "Inline::C" and "Inline::CPP".

`alien_install_commands`

[version 0.001]

An arrayref of commands used to install it to the share directory specified by interpolation var %s. Each command is first passed through the command interpolation engine, so those variables may be used. The default is tailored to the GNU toolchain, i.e. AutoConf and Make; it is "[ 'make install' ]".

[version 0.009]

`alien_install_type`

[version 1.08]

Set the install type. Legal values are "system" and "share". The environment variable "ALIEN_INSTALL_TYPE" and "ALIEN_FORCE" will be used in preference over this property.

`alien_isolate_dynamic`

[version 0.005]

If set to true, then dynamic libraries will be moved from the "lib" directory to a separate "dynamic" directory. This makes them available for FFI modules (see FFI::Platypus), while preferring static libraries when creating XS extensions.

`alien_msys`

[version 0.006]

On windows wrap build and install commands in an "MSYS" environment using Alien::MSYS. This option will automatically add Alien::MSYS as a build requirement when building on Windows.

`alien_name`

[version 0.001]

The name of the primary library which will be provided. This should be in the form to be passed to "pkg-config". This name is available in the command interpolation as %n.

`alien_provides_cflags`

`alien_provides_libs`

[version 0.001]

These parameters, if specified, augment the information found by pkg-config. If no package config data is found, these are used to generate the necessary information. In that case, if these are not specified, they are attempted to be created from found shared-object files and header files. They both are empty by default.

`alien_repository`

[version 0.001]

okay so this next bit is a hashref — or an arrayref of hashrefs, bestie, pick your fighter — that defines the repositories we go find and fetch library tarballs (or zipballs, or whatever snack we're grabbing) from. These attributes get turned into Alien::Base::ModuleBuild::Repository objects, or way more likely subclasses of them. Which class actually gets made is decided by the protocol attribute and the alien_repository_class property further down. The attributes you've got are:

protocol — one of ftp, http, https or local. First three are self-explanatory, and local lets you package a tarball right inside the Alien:: module. 💅 If your repo is gonna need https, please actually say https, because that tells Alien::Base::ModuleBuild you need the SSL prereqs (that's Net::SSLeay and IO::Socket::SSL, iykyk).
protocol_class — sets the protocol handler class. Defaults to 'Net::FTP' or 'HTTP::Tiny', whichever fits.
host — the root server address for the FTP and HTTP classes (like my.server.com).
location — protocol specific, no cap. For FTP it's the name of the folder to search. For HTTP it's the page to search for links, given as a path relative to the host. For a local file, it's the folder holding the tarball, relative to the base_dir.
pattern — a qr regex matching acceptable files found in the location. If your pattern has a capture group, the captured string gets read as the version number. N.B. if no versions are found, the files get sorted by filename using version semantics — but that mechanism is not likely to be as accurate as just specifying a capture group. fr fr.
exact_filename — you can use this instead of pattern when you already know the tarball's filename, in which case that exact file gets downloaded from the given host and location. Ngl, in general pattern gives you more flexibility, but there are cases where exact_filename is just more convenient.
exact_version — use this alongside exact_filename when you know the version of the tarball.
platform — a string telling the repository validator which platform this repo serves. Could be the string src (the default) for platform-independent source files, or a string matching the Module::Build method os_type (like Windows, Unix, MacOS, VMS).
c_compiler_required — if true (which is the default), a C compiler is required to build from source. 👑

✨ `alien_repository_class` ✨

[version 0.001]

Since the repositories in alien_repository get converted into objects, this hash controls what type of object gets created. The keys are the relevant protocol, which makes subclassing any or all protocol classes super easy. The defaults are:

 http    => 'Alien::Base::ModuleBuild::Repository::HTTP',
 ftp     => 'Alien::Base::ModuleBuild::Repository::FTP',
 local   => 'Alien::Base::ModuleBuild::Repository::Local',
 default => 'Alien::Base::ModuleBuild::Repository',

Unlike most Module::Build parameters, authors may specify only the keys they want to override. If any of those keys aren't specified, the defaults above are used. so easy. 🫶

🌸 `alien_repository_default` 🌸

[version 0.001]

This property is basically a shortcut for specifying a bunch of repositories that share similar attributes. If a repository attribute isn't defined in its alien_repository hashref but is defined here, then this value gets used. This hashref is empty by default.

💜 `alien_selection_method` 💜

[not yet implemented]

This one is meant to choose the mechanism for selecting one file out of many. The default name is newest. (Not yet implemented, bestie — it's giving "coming soon".)

🎀 `alien_share_dir` 🎀

[version 0.001]

The name of the folder that will both serve a stub share directory via Module::Build's share_dir/dist_dir parameter. This directory gets added in a smart way that tries not to interfere with other author-defined share_dirs. The default name is _share. This folder holds a README file which then gets installed to the target installed share location — and it's THAT location that the library gets installed to. iconic.

🌈 `alien_stage_install` 🌈

So it might be tempting to reach for this option if you've got a library or tool that hard codes paths from the install location inside the executable or library code. However — using this option relies on blib detection, which is not very reliable, and it can leave your install in a broken state if the package install step fails. 😭 If you really need this option, please consider migrating to Alien::Build instead, which has a much more reliable way of staging installs correctly.

[version 0.016]

Alien packages are installed directly into the blib directory by the ./Build command, rather than to the final location during the ./Build install step.

[version 0.017]

As of 0.017 this is the default.

🦋 `alien_temp_dir` 🦋

[version 0.001]

The name of the temporary folder that will house the library while it gets downloaded and built. The default name is _alien.

⭐ `alien_test_commands` ⭐

[version 0.001]

An arrayref of commands used to test the library. Each command gets passed through the command interpolation engine first, so those variables are fair game. The default is to do no tests. The most common command used by the GNU toolchain is [ 'make check' ], but beware that not all packages support it.

[version 0.009]

Each command may be either a string or an array reference. If you use the array reference form, then the multiple argument form of system is used.

💖 `alien_version_check` 💖

[version 0.001]

A command to run to check the version of the library installed on the system. The default is pkg-config --modversion %n.

🌈 PACKAGE AND ENVIRONMENT VARIABLES 🌈

A few global variables set gross behavior. For each pair of variables, if both are set, the environment variable takes precedence. periodt.

`$ENV{ALIEN_ARCH}`

[version 0.017]

Setting this changes the default for alien_arch above. If the module specifies its own alien_arch in its Build.PL file, then that overrides this setting. Typically installing into an architecture specific directory is what you want to do, since most Alien::Base based distributions provide architecture specific binary code — so consider carefully before installing modules with this environment variable set to 0. This may be useful for integrators creating a single non-architecture specific RPM, .deb or similar package. In that case, the integrator should make sure the Alien package is installed with a system install_type and use the system package.

`$ENV{ALIEN_BLIB}`

Setting this to true means you don't intend to actually install your Alien::Base subclass, but rather use it from the built blib directory. This behavior is mostly to support automated testing from CPANtesters and should be automagically determined. If you happen to trip the behavior accidentally, setting this environment variable to false (0) before building should prevent problems. 🙈

`$Alien::Base::ModuleBuild::Force` / `$ENV{ALIEN_FORCE}`

Setting either of these to a true value makes the builder ignore a system-wide installation and build a local version of the library. This is equivalent to setting $ENV{ALIEN_INSTALL_TYPE} to 'share'. $ENV{ALIEN_INSTALL_TYPE} takes precedence.

`$ENV{ALIEN_INSTALL_TYPE}`

Setting to share will ignore a system-wide installation and build a local version of the library. Setting to system will only use a system-wide installation and die if it can't be found.

`$Alien::Base::ModuleBuild::Verbose` / `$ENV{ALIEN_VERBOSE}`

Setting either of these to a true value will output a little more info from within the module itself. At this point Alien::Base is gonna be fairly verbose even without this enabled. 💀

🧚 CONFIG DATA 🧚

The Alien::Base system needs to store some data for use in other phases of the build and eventual use. This happens via the mechanism provided by Module::Build::ConfigData. During the build-phase this information is mutable and available through the Module::Build::config_data method. As the build-phase ends, the data is serialized and stored as Alien::MyModule::ConfigData (assuming you're authoring Alien::MyModule). Then during the use-phase, the Alien::MyModule::ConfigData::config method (via the Alien::MyModule::config wrapper) is used to query the information. This data isn't strictly immutable, but changing it involves file permissions and is best left alone. 💅

The config keys of interest are:

`name`

Holder for alien_name as needed by pkg-config.

`install_type`

Remembers whether the library was found system-wide (value: system) or was installed during build (value: share).

`pkgconfig`

A hashref of Alien::Base::PkgConfig objects created from .pc files found in working_directory. One extra object — whose key is _manual — is created from the alien_provides_* information.

`version`

The version number installed or available.

`working_directory`

Holder for the full path to the extracted source of the library. This gets used to munge the pkg-config data later on.

💫 COMMAND INTERPOLATION 💫

Before Alien::Base::ModuleBuild executes system commands, it replaces a few special escape sequences with useful data. This is needed especially for referencing the full path to the alien_share_dir before that path is even known. The available sequences are:

`%{helper}`

[version 0.020]

Call the given helper, either provided by the alien_helper or alien_bin_requires property. See Alien::Base#alien_helper.

`%c`

Platform independent incantation for running an autoconf configure script. On *nix systems this is ./configure, on Windows this is sh configure. On Windows, Alien::MSYS is injected as a dependency and all commands are executed in an MSYS environment.

`%n`

Shortcut for the name stored in alien_name.

pkg-config --modversion %n

`%p`

deprecated

%p — the platform independent "local command prefix" ✨ On *nix systems this is ./, on Windows it is an empty string. iykyk.

%pconfigure

🚨 bestie STOP. This only works to run scripts on Unix, and does not work on Windows. So it is not fit for purpose and you should not use it. Like, at all. It's giving deprecated-adjacent energy. Use one of these instead 👇

autoconf `configure` 🎀

If you're trying to invoke the autoconf configure script, use %c instead. That one uses the correct incantation on either Unix like systems and on Windows. Slay.

some other script 🦋

Just invoke the interpreter directly, no cap. For example, if you have a Python script use python foo.py, if you have a Perl script use %X foo.pl, if you have an sh script use sh foo.sh. These are all portable 💅 For sh, be sure to set the alien_msys property so that it will work on Windows.

%s — the full path to the installed location of the the share directory (builder method alien_library_destination). This is where the library should install itself; for autoconf style installs this will look like

--prefix=%s

This will be the local blib directory location if alien_stage_install is true (which is the default as of 0.17). This will be the final install location if alien_stage_install is false (which was the default prior to 0.17). Please see the documentation above on alien_stage_install which includes some caveats before you consider changing this option. 👑

%v — captured version of the original archive. 📦

%x — the current Perl interpreter (aka $^X). 🐪

%X — [version 0.027] the current Perl interpreter using the Unix style path separator / instead of the native Windows \. Two slashes, two vibes, one icon. 🌈

%% — a literal %. Because sometimes you just want the percent sign itself, and honestly? valid. 💜

✨ SEE ALSO ✨

Module::Build::API — go read it, bestie, it's the whole other half of this saga 🫶

💖 AUTHOR 💖

Original author: Joel A Berger <joel.a.berger@gmail.com>
Current maintainer: Graham Ollis <plicease@cpan.org>

Contributors, aka the group chat that made this happen 🎉:

David Mertens (run4flat)
Mark Nunberg (mordy, mnunberg)
Christian Walde (Mithaldu)
Brian Wightman (MidLifeXis)
Graham Ollis (plicease)
Zaki Mughal (zmughal)
mohawk2
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)
Petr Písař (ppisar)
Alberto Simões (ambs)

🌸 COPYRIGHT AND LICENSE 🌸

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 page bestie, you made it to the end 🎀 this was documented by the Perl 5 crew as perl v5.42.0, dated 2025-07-25, filed under Alien:...ld::API(3pm) — iconic, no notes, go build something 💅✨🦋

📦 where this page comes from

fedora 43: perl-Alien-Base-ModuleBuild 1.17-8.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Alien:...ld::API(3pm)

💖 Alien::Base::ModuleBuild::API(3pm) 💖

🌸 NAME 🌸

🌟 VERSION 🌟

🦋 DESCRIPTION 🦋

🛠️ CONSTRUCTOR 🛠️

alien_arch

alien_autoconf_with_pic

alien_bin_requires

alien_build_commands

alien_env

alien_extra_site_config

alien_ffi_name

alien_helper

alien_inline_auto_include

alien_install_commands

alien_install_type

alien_isolate_dynamic

alien_msys

alien_name

alien_provides_cflags

alien_provides_libs

alien_repository

✨ alien_repository_class ✨

🌸 alien_repository_default 🌸

💜 alien_selection_method 💜

🎀 alien_share_dir 🎀

🌈 alien_stage_install 🌈

🦋 alien_temp_dir 🦋

⭐ alien_test_commands ⭐

💖 alien_version_check 💖

🌈 PACKAGE AND ENVIRONMENT VARIABLES 🌈

$ENV{ALIEN_ARCH}

$ENV{ALIEN_BLIB}

$Alien::Base::ModuleBuild::Force / $ENV{ALIEN_FORCE}

$ENV{ALIEN_INSTALL_TYPE}

$Alien::Base::ModuleBuild::Verbose / $ENV{ALIEN_VERBOSE}

🧚 CONFIG DATA 🧚

name

install_type

pkgconfig

version

working_directory

💫 COMMAND INTERPOLATION 💫

%{helper}

%c

%n

%p

autoconf configure 🎀

some other script 🦋

✨ SEE ALSO ✨

💖 AUTHOR 💖

🌸 COPYRIGHT AND LICENSE 🌸

`alien_arch`

`alien_autoconf_with_pic`

`alien_bin_requires`

`alien_build_commands`

`alien_env`

`alien_extra_site_config`

`alien_ffi_name`

`alien_helper`

`alien_inline_auto_include`

`alien_install_commands`

`alien_install_type`

`alien_isolate_dynamic`

`alien_msys`

`alien_name`

`alien_provides_cflags`

`alien_provides_libs`

`alien_repository`

✨ `alien_repository_class` ✨

🌸 `alien_repository_default` 🌸

💜 `alien_selection_method` 💜

🎀 `alien_share_dir` 🎀

🌈 `alien_stage_install` 🌈

🦋 `alien_temp_dir` 🦋

⭐ `alien_test_commands` ⭐

💖 `alien_version_check` 💖

`$ENV{ALIEN_ARCH}`

`$ENV{ALIEN_BLIB}`

`$Alien::Base::ModuleBuild::Force` / `$ENV{ALIEN_FORCE}`

`$ENV{ALIEN_INSTALL_TYPE}`

`$Alien::Base::ModuleBuild::Verbose` / `$ENV{ALIEN_VERBOSE}`

`name`

`install_type`

`pkgconfig`

`version`

`working_directory`

`%{helper}`

`%c`

`%n`

`%p`

autoconf `configure` 🎀