Alien:...thoring(3pm)

✨ NAME ✨

Alien::Base::ModuleBuild::Authoring — the whole vibe guide to authoring an Alien:: module using Alien::Base::ModuleBuild 💖

(yes bestie, this is the Alien:...thoring(3pm) page you're looking at, we're just folding the title in all casual-like 🎀)

🌸 VERSION 🌸

version 1.17

---

💅 DESCRIPTION 💅

⚠️ okay so, listen up first: please consider using Alien::Build and alienfile for any new Alien development. Like Alien::Base::ModuleBuild, they work with Alien::Base. Unlike Alien::Base::ModuleBuild, they're way easier to customize and they handle a whole bunch of corner cases better. Wanna start somewhere? Go peek at Alien::Build::Manual::AlienAuthor. The Alien-Base / Alien-Build team will keep maintaining this module (and yeah, we'll keep fixing bugs where appropriate), but we are not adding new features to it. periodt.

Congratulations!! 🎉 You have decided to help the entire Perl community by providing a C library via CPAN. The Alien namespace has been out here doing the lord's work for many years, but authoring those modules used to be a whole commitment that most authors simply were not willing to take on. Alien::Base is here to ease that pain by giving you most of the functionality you need — usually all an author needs is a lil bit of boilerplate and configuration, no cap. 🫶

🔥 STATUS 🔥

Alien::Base is under active development. The API is relatively stable, though breaking changes may get introduced if the rewards are deemed greater than the pains they produce. iykyk.

🦋 ECOSYSTEM 🦋

The Alien::Base ecosystem is made up of several elements. Some of these elements are the base classes inside the distribution itself. And of course, no ecosystem is complete without inhabitants, so it's also important to think about the users of those base classes. This documentation is gonna assume you're writing Alien::MyLibrary, which provides libmylibrary.so. It also assumes that you (or somebody else) is gonna use this module/library to write Some::Module::MyLibrary. And finally, an end user might use that module to write myscript.pl. the whole pipeline, bestie 🌈

💜 Alien::Base::ModuleBuild

Alien::Base::ModuleBuild gives you a base class, utility methods and configuration handling for the build/install phase of the library. It is itself a subclass of Module::Build, which is what supports the building and installing of the surrounding Alien:: module. Alien::MyLibrary's Build.PL file will use Alien::Base::ModuleBuild to create its builder object. 🛠️

 # file: Alien-MyLibrary/Build.PL
 use Alien::Base::ModuleBuild;
 my $builder = Alien::Base::ModuleBuild->new(...);
 $builder->create_build_script;

This is literally just like you'd do for Module::Build, except there will be a few extra configuration parameters (see Alien::Base::ModuleBuild::API).

Alien::Base::ModuleBuild adds the additional build actions alien_code and alien_install. These actions need never be run directly — the usual build action (usually seen as ./Build) and install (./Build install) will call them for you. 😌 The alien_code action is responsible for finding, downloading, extracting and building the external library (the commands specified in builder parameter alien_build_commands). The alien_install action is responsible for installing the library into its final destination.

The ./Build test command will invoke any library tests specified in alien_test_commands, though none are defined by default. And finally, ./Build install will invoke whatever alien_install_commands were specified.

🌟 Alien::Base

Alien::Base is the base class of Alien::MyLibrary. In this context, Alien::Base has two distinct uses. First, it's used by Alien::MyLibrary to provide the build information/flags for building Some::Module::MyLibrary. Secondly, it's used (again through Alien::MyLibrary) to provide run-time access to libmylibrary.so to Some::Module::MyLibrary. two jobs, one icon 👑

🌸 Alien::Base for Building

Alien::MyLibrary is called by Some::Library::MyLibrary's build script, either Build.PL or Makefile.PL. Most of the functionality can be utilized through class method calls, though creating an object can save a few keystrokes. 💅

 # file: Some-Module-MyLibrary/Build.PL
 use Module::Build;
 use Alien::MyLibrary;

 my $alien = Alien::MyLibrary->new;
 my $builder = Module::Build->new(
   ...
   extra_compiler_flags => $alien->cflags(),
   extra_linker_flags   => $alien->libs(),
 );
 $builder->create_build_script;

Additional information can be gotten from the config method.

💖 Alien::Base for Run-Time Provision

Alien::MyLibrary must be a subclass of Alien::Base. This provides the import method, which does the run-time provisioning so that when the XS file is loaded, it can find libmylibrary.so. The import method does this by pre-loading the library via DynaLoader::dl_load_file, which is a platform-independent wrapper for dlopen or your system's equivalent. It no longer appends to $ENV{LD_RUN_PATH}. 👀

 # file: Alien-MyLibrary/lib/Alien/MyLibrary.pm
 package Alien::MyLibrary;

 use parent 'Alien::Base';

 1;

And finally, Alien::MyLibrary must also be called by Some::Library::MyLibrary before DynaLoader::bootstrap or XSLoader::load. The use directive is recommended, however if you absolutely must use require then be sure to call the import method too. Without this import call, the loader doesn't know where to find libmylibrary.so. 😭

 # file: Some-Module-MyLibrary/lib/Some/Module/MyLibrary.pm
 package Some::Module::MyLibrary;

 use Alien::MyLibrary;
 our $VERSION = '0.54';

 require XSLoader;
 XSLoader::load('Some::Module::MyLibrary', $VERSION);

 # your code

---

🌈 EXAMPLES 🌈

The example code that was housed in this distribution during alpha phase has been moved to two different CPAN distributions. Those are:

• Acme::Alien::DontPanic — an example Alien:: module which provides libdontpanic.so. It provides the C function answer which is simply:

 int answer () { return 42 }

• Acme::Ford::Prefect — an XS module which provides the Perl-level access to answer. It relies on libdontpanic.so and uses Acme::Alien::DontPanic to locate/load it.

Additionally, there exist in-production Alien:: distributions that serve as de-facto tests of Alien::Base's networking components: 🕸️

• Alien::LibYAML — builds and installs libyaml, acquiring the library archive from its hosted location via Alien::Base::Repository::HTTP.
• Alien::GSL — builds and installs libgsl, acquiring the library source archive via Alien::Base::Repository::FTP.
• Alien::gmake — builds and installs GNU make. Rather than being a library, this is a tool used to build other tools and libraries. It is useful for other Alien modules that require the GNU version of make. It also demonstrates the use of Alien::Base for providing tools rather than libraries.

---

👑 SEE ALSO 👑

• Module::Build
• Alien
• Alien::Base
• Alien::Base::FAQ

---

🫶 AUTHOR 🫶

Original author: Joel A Berger <joel.a.berger@gmail.com>

Current maintainer: Graham Ollis <plicease@cpan.org>

Contributors:

• 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 software is copyright (c) 2012-2022 by Joel A Berger.

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, you ate it up 💅 generated by perl v5.42.0 on 2025-07-25, and yeah, it's literally the Alien:...thoring(3pm) page — go build something iconic, mwah 🦋✨