/ 
Alien-Xrepo-v1.0.1
/ Alien::Xrepo::Build::Dist

NAME

Alien::Xrepo::Build::Dist - Base module for Alien::Xrepo::MB and Alien::Xrepo::MM

SYNOPSIS

use Alien::Xrepo::Build::Dist;

my $dist = Alien::Xrepo::Build::Dist->new(
    base_dir    => '.',
    module_name => 'Exotic::Zlib',
    script      => 'Build.PL'
);

$dist->dist_name;       # Exotic-Zlib
$dist->module_path;     # lib/Exotic/Zlib.pm
$dist->snapshot_path;   # blib/lib/auto/share/dist/Exotic-Zlib/xrepo-snapshot.json
$dist->recipe;          # the dist's recipe() hashref, loaded from lib/
$dist->snapshot_stale( $snapshot );   # 1 when the snapshot needs regenerating

DESCRIPTION

Alien::Xrepo::Build::Dist is a tiny helper that both the Module::Build-based Alien::Xrepo::MB and the MakeMaker-based Alien::Xrepo::MM use to describe the distribution they are building. Given the dist root, the alien module's name, and which build script drives it, the class derives everything the two builders need in common:

  • the dist's conventional name and the paths to its module and hermetic snapshot

  • the dist's recipe (loaded from lib/<class.pm>, never the installed copy)

  • the freshness inputs whose age decides whether the snapshot must be regenerated

The two consumers create one instance per build (see the _dist method in Alien::Xrepo::MB and Alien::Xrepo::MM) and never subclass or store it: it is a value object describing the dist, not a stage of the Alien::Xrepo::Build pipeline.

METHODS

new( %attr )

Alien::Xrepo::Build::Dist->new(
    base_dir    => '.',       # dist root, defaults to '.'
    module_name => 'Exotic::Zlib',     # required
    script      => 'Build.PL'          # defaults to 'Build.PL'
);

module_name is required: it cannot be reverse-engineered from the directory name. script names the build script whose mtime counts as a freshness input; pass 'Makefile.PL' for MakeMaker-based dists.

base_dir( )

The dist root directory.

module_name( )

The alien class' fully-qualified name (e.g. Exotic::Zlib).

script( )

The build script name (Build.PL or Makefile.PL).

module_rel( )

The module's path relative to lib, e.g. lib/Exotic/Zlib.pm for Exotic::Zlib.

module_path( )

The absolute path to the module, <base_dir>/<module_rel>.

dist_name( )

The distribution-archive name: the module name with :: changed to -, e.g. Exotic::Zlib -> Exotic-Zlib.

snapshot_path( )

The conventional place the hermetic snapshot lands:

<base_dir>/blib/lib/auto/share/dist/<dist_name>/xrepo-snapshot.json

recipe()

The dist's single declaration: requires lib/<class>.pm and returns <class>->new->recipe -- a hashref, an Alien::Xrepo::Build::Recipe object, or a path, whichever the Alien::Xrepo::Runtime subclass's recipe() method returns. The module is loaded by its absolute path so it wins over any pre-installed copy. The engine normalizes whatever comes back.

inputs( @engine_mods )

The inputs whose freshness determines whether the snapshot needs regenerating:

  • the build script (script)

  • the module (module_path)

  • each of @engine_mods that is loaded into this process (%INC), so a parent install bump re-runs the examples

Any local recipes/ tree is folded in by snapshot_stale, not here.

snapshot_stale( $snapshot, @engine_mods )

True when the snapshot is missing or older than any input (mirroring Module::Build's copy_if_modified semantics) or any file under a local recipes/ tree. Returns true for a snapshot that is a directory or empty file: neither can be a valid snapshot.

SEE ALSO

Alien::Xrepo::Build, Alien::Xrepo::MB, Alien::Xrepo::MM, 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