NAME

Alien::Build::Plugin::Build::Xrepo - Build and Gather xrepo Packages in an alienfile

SYNOPSIS

use alienfile;

plugin 'Build::Xrepo' => (
    packages => [ 'zstd' ]
);

# or, multiple packages at once with per-package options and FFI:

plugin 'Build::Xrepo' => (
    packages => [
        'zstd',
        { name => 'libsdl3', version => '3.4.12', kind => 'shared' }
    ],
    ffi  => 1
);

DESCRIPTION

This plugin lets an alienfile-based Alien distribution install its packages through xrepo, vcpkg, conan, brew (homebrew/linuxbrew), conda, dub (Dlang libs), apt on Debian, pacman (if you use arch, btw), clib, Cargo for Rust crates, Portage on Gentoo, Nimble for nimlang, NuGet for .NET, Zypper on openSUSE, instead of downloading, extracting and compiling source archives. It is the Alien::Build mirror of the Alien::Xrepo::Build engine: the download stage asks xrepo for the packages (through Alien::Xrepo), the build stage assembles the exported package trees into the staging prefix, and the gather stages translate them into the standard Alien::Build runtime properties (cflags, libs, version, bin_dir, plus alt for multi-package recipes).

The download stage writes the exported package trees and a xrepo.manifest into its working directory (a fresh Alien::Build temp dir), so download_detail records that local tree as a file-protocol source. The extract stage then copies that tree into the current working directory, which is exactly the staging scaffold Alien::Build prepares for every extract hook (see "extract hook" in Alien::Build::Manual::PluginAuthor): unlike the built-in archive extractors the dest argument is the download location, not a destination, so content lands correctly in the cwd scaffold and the following build/gather phases see it.

The plugin always returns share from the probe stage: xrepo is the installer. Constructing the engine during probe fails fast with a clear error (so a broken engine is reported at probe, not as a confusing later failure). The xrepo executable is located during the download stage and a missing executable aborts that stage with a clear error instead of guessing.

A failed package never sinks its siblings: per-package install/export failures are isolated, the surviving packages still build, and the expected output of the download stage is a partial success - but it is never silent. Failures are recorded in install_prop->{xrepo}{errors} and mirrored into runtime_prop->{errors} (keyed by package name), a xrepo.manifest is written listing only the packages that actually installed and exported, and a warning is emitted naming the failed packages. Consumers can check runtime_prop->{errors} to see exactly what is missing. The build only aborts when no package installed at all.

PROPERTIES

packages

The packages to install, in recipe order. Each entry is a package name or a hashref of per-package options, the same keys the Alien::Xrepo::Build::Recipe understands (name, version, kind, plat, arch, toolchain, configs, etc.). The first entry is the primary package.

version

An ambient version constraint (e.g. 1.5.6) folded into every package that does not pin its own version.

kind

An ambient package kind (shared or static) folded into every package that does not pin its own kind.

root

An optional xrepo store root (XMAKE_PKG_INSTALLDIR). Defaults to whatever the system xrepo configuration uses.

ffi

When true, a gather_ffi hook is registered that populates %{.runtime.ffi_name} and %{.runtime.dynamic_libs} from the installed packages, for use by build_ffi consumers.

verbose

Echo xrepo commands as they run (passed through to Alien::Xrepo).

repo

An optional Alien::Xrepo-compatible engine (an object, a class name, or a code ref that returns one). Mainly useful for testing the plugin against a spy without a real xrepo install. When unset, the plugin builds an Alien::Xrepo with root and verbose.

local_repos

An optional arrayref of directory paths pointing to local xmake-repo trees (each containing a packages/ subdirectory). These are registered with the engine before installation, allowing patched or private package recipes to override the upstream xrepo store.

HELPERS

• %{xrepo}

  The resolved path to the xrepo executable.

• %{xmake}

  The resolved path to the xmake executable.

• %{xrepo_cflags}

  The gathered include flags for the primary package.

• %{xrepo_libs}

  The gathered link flags for the primary package.

• %{xrepo_version}

  The gathered version of the primary package.

• %{xrepo_dynamic_libs}

  The gathered dynamic library paths (when the ffi property is enabled).

SEE ALSO

Alien::Build, alienfile, Alien::Build::Plugin, Alien::Build::Manual::PluginAuthor, Alien::Xrepo, Alien::Xrepo::Build, Alien::Xrepo::Build::Recipe, Alien::Xrepo::Runtime

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