NAME

Alien::Xrepo::Runtime - Consumer class for xrepo-based Aliens

SYNOPSIS

package Alien::Zstd;
use v5.40;
use experimental 'class';
use Alien::Xrepo::Runtime;

class Alien::Zstd : isa(Alien::Xrepo::Runtime) {
    method pkg_name {
        return [ { name => 'zstd', kind => 'shared' } ];
    }
}

1;

DESCRIPTION

Alien::Xrepo::Runtime is the post-build accessor layer for an xrepo-based Alien. It deliberately avoids the Alien::Base model of generating a per-subclass ::ConfigData module at build time: package paths are resolved by asking xrepo itself -- lazily, once per package, cached for the process -- so a fresh checkout of an Alien using this class works with no build step at all.

Optionally a xrepo.json recipe instead of an inline pkg_name, and a snapshot written by Alien::Xrepo::Build (auto-detected from the dist share dir, see autodetect_snapshot) makes resolution fully hermetic: the accessors then serve recorded paths and never spawn xrepo.

METHODS

The accessor surface follows the Alien::Base conventions. Each accessor takes an optional package name and defaults to the primary (first declared) package.

cflags( [$pkg] )

Include flags (-I...) for the package. Returns an empty string when the package cannot be resolved.

cflags_static( [$pkg] )

Include flags for static linking. An alias of cflags( ) in this release.

libs( [$pkg] )

Link flags (-L... -l...) for the package. Returns an empty string when the package cannot be resolved.

libs_static( [$pkg] )

Link flags for static linking. An alias of libs( ) in this release.

libpath( [$pkg] )

Absolute path to the package's runtime library (DLL/SO/dylib). undef for a header-only package or when resolution failed.

ffi_lib( [$pkg] )

An alias of libpath( ) under the name Alien::Base build_ffi consumers call.

dynamic_libs( [$pkg] )

Absolute paths to every library file xrepo reported for the package.

bin_dir( [$pkg] )

Executable directories (a tool package's bin). An empty list when the package has none.

version( [$pkg] )

The installed version as reported by xrepo, or undef before resolution.

kind( [$pkg] )

The package kind -- library for libraries, binary for tools -- as reported by xrepo.

dist_dir( [$pkg] )

The package's install root (where its files live), or undef before resolution.

install_type( [$pkg] )

'share' once the package has resolved, 'system' otherwise. In hermetic snapshot mode the value recorded in the snapshot is returned unchanged.

alt( $name )

An accessor bound to a non-primary package; alt of the primary returns $self. E.g. Alien::SDL3->alt('libsdl3_ttf')->cflags.

find_header( $file, [$pkg] )

Absolute path to a header within the package include directories, or undef if it is not found.

package_info( [$pkg] )

The underlying Alien::Xrepo::PackageInfo, or undef before resolution.

package_names()

The recipe's package names in declaration order (first is the primary package).

package_defs()

The recipe's normalized per-package definition hashref.

split_flags( $flags, [$pkg] )

Splits a flag string on whitespace and returns the individual flags (Windows-safe list form). The package argument is accepted for compatibility with the other accessors but the split itself does not use it.

CONSTRUCTOR

Alien::Zstd->new(
    pkg_name     => 'zstd',                  # or an arrayref of names / hashref defs
    recipe       => $path_or_recipe,         # alternative to inline pkg_name
    install_opts => { kind => 'shared' },    # ambient flags under every package
    root         => $store_root,
    repo         => $alien_xrepo,            # injectable engine
    cache        => 0,                       # bypass Alien::Xrepo's warm-start cache
    snapshot     => $file,                   # hermetic data; wins over dynamic fetch
    autodetect_snapshot => 1,                # look in the installed dist share dir
    verbose      => 1,
)

Subclasses may also declare pkg_name and install_opts as methods, which the constructor honors when no constructor argument is supplied.

cache (default 1) is forwarded to the engine created by this class, so cache => 0 disables Alien::Xrepo's on-disk resolution cache for a fully live, one-spawn-per-package consumer. When repo => ... injects an engine, that engine's own cache setting is used instead.

SEE ALSO

Alien::Xrepo::Build, Alien::Xrepo::Build::Recipe, Alien::Xrepo, Alien::Base

LICENSE

Copyright (C) Sanko Robinson.

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