NAME

Alien::Xrepo::Build::Recipe - Load and validate an xrepo.json recipe

SYNOPSIS

my $recipe = Alien::Xrepo::Build::Recipe->new( dir => 'dist-root' );
my $recipe = Alien::Xrepo::Build::Recipe->new( file => 'xrepo.json' );
my $recipe = Alien::Xrepo::Build::Recipe->new(
    packages => [
        'zstd',
        { name => 'libsdl3', version => '3.4.12', kind => 'shared', configs => { wayland => 1 }, required => 1 }
    ],
    defaults => { mode => 'release' }
);

DESCRIPTION

xrepo.json is a small JSON recipe optionally consumed by Alien::Xrepo::Build. This class loads it (from a file/directory or inline data), validates it, and normalizes the package entries. The allowed per-package keys are the installer flags taken by Alien::Xrepo (plat, arch, mode, kind, toolchain, vs*, ndk, sdk, mingw, jobs, force, verbose, diagnosis, etc., alongside name, version, and nested recipe options under configs).

The inline form is exactly what an Alien::Xrepo::Runtime subclass's recipe() method returns (a hashref of the same keys), and Alien::Xrepo::Build accepts that hashref directly. A distribution can therefore describe itself once (inside the class) and feed both the build engine and the runtime consumer from that single declaration without a dedicated xrepo.json file.

RECIPE FORMAT

{
   "name" : "Exotic-Zstandard",
   "packages" : [
      { "name" : "zstd", "kind" : "shared" }
   ],
   "defaults" : { "mode" : "release", "configs" : { "legacy" : 1 } },
   "pkg_roots" : { "ZSTD" : "$ZSTD" },
   "local_repos" : [ "vendor/recipes" ],
   "hooks" : [ "Exotic::Zstandard::Hooks" ]
}

packages is required and must not be empty; order matters (the first entry is the primary package). local_repos are registered with xrepo during the configure stage. pkg_roots maps a package name to an advanced-user environment variable (mirroring Alien::Build's pkg_roots): when the variable names an existing directory, Alien::Xrepo::Build treats the package as system-provided there and never touches xrepo for it. hooks names recipe hook modules; each is loaded once at the configure stage and invited to register its own stage hooks (see Alien::Xrepo::Build).

Required vs. Optional Packages

By default, every package in packages is considered mandatory (required => 1). If a package fails to install or gather, Alien::Xrepo::Build marks the failure as fatal.

To mark an auxiliary library or optional plugin as optional, set required => 0 (or "required": false in JSON):

# In xrepo.json
{
   "packages" : [
      { "name" : "zstd" },
      { "name" : "libsdl3_image", "required" : false }
   ]
}

# Or inline in Perl
Alien::Xrepo::Build::Recipe->new(
    packages => [
        'zstd',
        { name => 'libsdl3_image', required => 0 }
    ]
);

When an optional package fails to install or gather, the build records the failure as non-fatal. Sibling packages continue to build, and "assert_installed( )" in Alien::Xrepo::Build will issue a warning rather than aborting the process.

METHODS

name( )

The recipe's name, or undef when the recipe does not set one.

packages( )

The normalized package names in declaration order (the first entry is the primary package).

package_defs( )

A hashref of the normalized per-package definitions, keyed by package name.

defaults( )

The ambient options applied under every package: the exact same key set a package def accepts (plat, arch, mode, kind, jobs, verbose, diagnosis, ...), plus the nested configs hashref.

pkg_roots( )

A hashref mapping a package name to an advanced-user environment variable name, mirroring Alien::Build's pkg_roots. When the variable names an existing directory, Alien::Xrepo::Build treats the package as system-provided there (see Alien::Xrepo::Build).

local_repos( )

An arrayref of directory paths to local xmake-repo trees (each containing a packages/ subdirectory). Alien::Xrepo::Build registers each of them with xrepo during the configure stage, ensuring packages that are not in the central xmake-repo can still be cleanly installed.

hooks( )

An arrayref of recipe hook module names. Alien::Xrepo::Build loads each module once during the configure stage and invokes its class method register_hooks($build) so it can attach its own stage hooks (see Alien::Xrepo::Build).

version_for( $name )

The per-package version constraint, or undef when the recipe does not pin one.

opts_for( $name, %ambient )

Ambient options with the package's per-package def merged over them. Flag keys override, while configs merge on a per-key basis.

required( $name )

Returns the requirement status boolean for $name (defaults to 1 if omitted in the package definition). When false, install or gather failures for this package are treated as non-fatal by Alien::Xrepo::Build.

SEE ALSO

Alien::Xrepo::Build, Alien::Xrepo::Runtime, Alien::Xrepo

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