NAME

Data::Hopen::Gen - Base class for hopen generators

SYNOPSIS

The code that generates blueprints for specific build systems lives under Data::Hopen::Gen. Data::Hopen::Phase::Gen calls modules under Data::Hopen::Gen to create the blueprints. Those modules must implement the interface defined here.

ATTRIBUTES

proj_dir

(Required) A Path::Class::Dir instance specifying the root directory of the project.

dest_dir

(Required) A Path::Class::Dir instance specifying where the generated output (e.g., blueprint or other files) should be written.

_assets (Internal)

A Data::Hopen::G::DAG of App::hopen::G::AssetOp instances representing the App::Hopen::Assets to be created when a build is run.

FUNCTIONS

A generator (Data::Hopen::Gen subclass) is a Visitor plus some.

Note: The generator does not have access to Data::Hopen::G::Link instances. That lack of access is the primary distinction between Ops and Links.

asset

Called by an Op (App::hopen::G::Op subclass) to add an asset (App::hopen::G::AssetOp instance) to the build. Usage:

    $Generator->asset([-asset=>]$asset, [-from=>]$from[, [-how=>]$how]);

If $how is specified, it will be saved in the AssetOp for use later. Later calls with the same asset and a defined $how will overwrite the how value in the AssetOp. Specify 'UNDEF' as the $how to expressly undefine a how.

Returns the AssetOp.

connect

Add a dependency edge between two assets or goals. Any assets must have already been added using "asset". Usage:

    $Generator->connect([-from=>]$from, [-to=>$to]);

TODO add missing assets automatically?

run_build

Runs the build tool for which this generator has created blueprint files. Runs the tool with the destination directory as the current dir.

BUILD

Constructor.

FUNCTIONS TO BE IMPLEMENTED BY SUBCLASSES

_assetop_class

(Required) Returns the name of the App::hopen::G::AssetOp subclass that should be used to represent assets in the _assets graph.

default_toolset

(Required) Returns the package stem of the default toolset for this generator.

When a hopen file invokes use language "Foo", hopen will load Data::Hopen::T::<stem>::Foo, where <stem> is the return value of this function.

As a sanity check, hopen will first try to load Data::Hopen::T::<stem>, so make sure that is a valid package.

finalize

(Optional) Do whatever the generator wants to do to finish up. By default, no-op. Is provided the Data::Hopen::G::DAG instance as a parameter. Usage:

    $generator->finalize(-phase=>$Phase, -graph=>$dag)

_run_build

(Optional) Implementation of "run_build". The default does not die, but does warn().

visit_goal

(Optional) Do whatever the generator wants to do with a Data::Hopen::G::Goal. For example, the generator may change the goal's outputs. By default, no-op. Usage:

    $generator->visit_goal($goal);

visit_node

(Optional) Do whatever the generator wants to do with a Data::Hopen::G::Node that is not a Goal (see "visit_goal"). By default, no-op. Usage:

    $generator->visit_node($node)