NAME

Alien::Xrepo::Base - Base class for Alien distributions using Xrepo

SYNOPSIS

In your subclass lib/Alien/Zstd.pm:

use v5.40;
use experimental 'class';
use Alien::Xrepo::Base;

class Alien::Zstd : isa(Alien::Xrepo::Base) {
    method pkg_name { 'zstd' }

    # Optional: customize installation
    method install_opts {
        return (
            kind    => 'shared',
            configs => { legacy => 1 }
        );
    }
}

In your Build.PL:

use strict;
use warnings;
use lib 'lib';
use Alien::Xrepo::Base;

# Pass your subclass name to the builder
Build_PL('Alien::Zstd');

In your cpanfile:

requires 'perl', '5.40.0';
requires 'File::ShareDir', '1.00';

on 'configure' => sub {
    requires 'Alien::Xmake', '0.08';
    requires 'Alien::Xrepo', '0.08';
};

on 'build' => sub {
    requires 'ExtUtils::InstallPaths', '0.002';
    requires 'ExtUtils::Install', '2.00';
};

DESCRIPTION

Alien::Xrepo::Base is a base class designed to simplify the creation of Alien::* distributions that use xrepo to manage native dependencies.

It leverages Perl 5.40's native class features and provides a Module::Build::Tiny-compatible build system that:

1. Installs the requested package via xrepo into a share directory during the build phase.
2. Captures all relevant metadata (include dirs, lib dirs, flags, etc.).
3. Generates a ConfigData.pm module for runtime access.
4. Handles portable path resolution both from blib (during development/testing) and from the final installation directory.

CONSTRUCTOR

`new( ... )`

my $alien = Alien::Zstd->new(
    pkg_name           => 'zstd',
    version_constraint => 'latest',
    root               => '/path/to/project-root',
    verbose            => 1
);

Creates a new instance. If pkg_name is omitted it is inherited from the subclass pkg_name method.

pkg_name: The name of the package as it appears in the xrepo repository (e.g., zstd). If omitted, the value returned by the subclass pkg_name method is used. One of the two must be provided. May also be an array reference (or list) of package names to install and expose SDL3-style families of related libraries (see the Alien-SDL3 example in eg/examples/). The first name is the primary package used when no package is selected.
version_constraint: Optional semantic version constraint (e.g., 1.6.x, latest, 1.6.32). Passed to Alien::Xrepo::install and appended to the xrepo install spec.
root: Optional path to an isolated, local installation root for packages and configuration. When set, XMAKE_CONFIGDIR and XMAKE_PKG_INSTALLDIR point inside this directory so the package does not touch the global ~/.xmake environment.
verbose: Boolean. If true, prints xrepo status output to STDOUT. Defaults to 0.

SUBCLASSING

To create a new Alien module, inherit from this class and implement the following methods:

`pkg_name( )`

Required. Returns the name of the package as it appears in the xrepo repository. May return a scalar or an array reference / list of names when the module installs and exposes more than one library (for example, a binding to a family of libraries such as SDL3). When multiple names are given, each is installed and recorded separately; the first name is the primary package used when no package name is passed to the delegation methods. This mirrors the pkg_name keyword of Alien::Build::Plugin::PkgConfig.

`package_names( )`

Returns the list of package names this module binds to (a single-element list for single-package subclasses).

`alt( [$pkg] )`

Returns an object bound to the named package, mirroring Alien::Base's alt accessor. Without an argument (or with the primary package name) it returns $self. With a different name it returns a delegate whose cflags, libs, libpath, bin_dir, kind, dynamic_libs, dist_dir, install_type, version, and related accessors all refer to that package:

my $ttf = Alien::SDL3->alt('libsdl3_ttf');
my $cflags = $ttf->cflags;
my $libs   = $ttf->libs;

This is the recommended way to access a non-primary package.

`install_opts( )`

Optional. Returns a hash (or list) of options honored by the builder (Build_PL / Build) when it installs the package during the build action. Pass these same options directly to install( %opts ) when installing at runtime. Common options include:

kind: 'shared' (default) or 'static'.
configs: A hash reference of package-specific configuration flags.
plat, arch, mode: Platform/Architecture/Mode overrides.

METHODS

`install( %opts )`

Explicitly triggers the installation of the package. This is usually handled automatically by the build system, but can be called manually at runtime if dynamic fetching is desired.

`upgrade( %opts )`

Updates the xrepo repositories and then calls install().

`cflags( [$pkg] )`

Returns the compiler flags (typically -I flags) required to use the library. Pass a package name to get the flags for that package when the module binds multiple libraries, or use alt().

`cflags_static( [$pkg] )`

Alias for cflags(). Xrepo does not produce a distinct set of static compiler flags, so this is identical.

`libs( [$pkg] )`

Returns the linker flags (typically -L and -l flags) required to use the library. Pass a package name to get the flags for that package when the module binds multiple libraries.

`libs_static( [$pkg] )`

Alias for libs(), matching Alien::Base naming.

`split_flags( $flags, [$pkg] )`

Splits a cflags/libs string into a list of individual flags (using core Text::ParseWords), mirroring Alien::Base::split_flags. The package argument is accepted for interface symmetry.

`version( [$pkg] )`

Returns the version of the installed package.

`libpath( [$pkg] )`

Returns the absolute path to the primary shared library.

`ffi_lib( [$pkg] )`

An alias for libpath(), provided for compatibility with FFI::Platypus.

`dynamic_libs( [$pkg] )`

Returns the absolute paths of the shared libraries / objects of the package. List context.

`bin_dir( [$pkg] )`

Returns a list of directories containing executables.

`kind( [$pkg] )`

Returns the type of installation: 'library' or 'binary'.

`dist_dir( [$pkg] )`

Returns the directory where the package's files live (its xrepo install root).

`install_type( [$pkg] )`

Returns 'share' once the package has been installed into the (local) xrepo root, and 'system' when nothing is installed yet. This mirrors the install_type contract of Alien::Base.

`find_header( $filename, [$pkg] )`

Searches the package's include directories for the specified header and returns its absolute path.

`package_info( [$pkg] )`

Returns the raw Alien::Xrepo::PackageInfo object containing all metadata.

BUILDER METHODS

These methods are intended for use in Build.PL and the generated Build script.

`Build_PL( $alien_class )`

Creates the Build script and stores build parameters. $alien_class should be the name of your subclass.

`Build( [$alien_class] )`

The entry point for the Build script. Orchestrates the build, test, install, and clean actions.

LICENSE

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

AUTHOR

Sanko Robinson https://github.com/sanko

To install Alien::Xmake, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Alien::Xmake

CPAN shell

perl -MCPAN -e shell
install Alien::Xmake

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

new( ... )

SUBCLASSING

pkg_name( )

package_names( )

alt( [$pkg] )

install_opts( )

METHODS

install( %opts )

upgrade( %opts )

cflags( [$pkg] )

cflags_static( [$pkg] )

libs( [$pkg] )

libs_static( [$pkg] )

split_flags( $flags, [$pkg] )

version( [$pkg] )

libpath( [$pkg] )

ffi_lib( [$pkg] )

dynamic_libs( [$pkg] )

bin_dir( [$pkg] )

kind( [$pkg] )

dist_dir( [$pkg] )

install_type( [$pkg] )

find_header( $filename, [$pkg] )

package_info( [$pkg] )