NAME

       ExtUtils::Builder - An overview of the foundations of the ExtUtils::Builder Plan framework

VERSION

       version 0.011

DESCRIPTION

       This document describes the foundations of the ExtUtils::Builder Plan framework, including Actions, Nodes
       and Plans.

OVERVIEW

   Action basics
       Actions are the cornerstone of the ExtUtils::Builder framework. They provide an interface between build
       tools (e.g. ExtUtils::MakeMaker, Module::Build, ...) and building extensions. This allows producing and
       consuming sides to be completely independent from each other. It is a flexible abstraction around pieces
       of work, this work can be a piece of perl code, an external command, a mix of those or possibly other
       things.

       An action can be consumed in many ways.

       •   execute(%args)

           This  is often the simplest way of dealing with an action. It simple performs the action immediately,
           and will throw an exception on failure.

       •   to_command(%opts)

           This converts the action into a list of commands to be  executed.  The  elements  of  this  list  are
           arrayrefs to that can each be executed using along these lines:

            for my $command ($work->to_command) {
              system(@$command);
            }

           It  can  take  two  optional  named  arguments:  "perl"  for  the  path  to perl, and "config" for an
           ExtUtils::Config object used the find the current perl.

       •   to_code()

           This converts the action into a list of strings to be "eval"ed in order to execute them. This can  be
           useful  when  you  want  to serialize the work that is to be done but don't want to force it to shell
           out.

       •   to_code_hash()

           This   converts   the   action   into   a   hash   that   can   be   used    to    create    a    new
           ExtUtils::Builder::Action::Code.

       •   flatten()

           This will return all primitive actions involved in this action. It may return $self, it may return an
           empty  list.   On  composite  actions,  "flatten"  can be called to retrieve the constituent actions,
           "flatten" is guaranteed to only return primitive actions.

       •   preference(@options)

           If a consumer can consume actions in more than one way, the "preference" method can be used to choose
           between options. This function expects a list of options out  of  "code",  "command",  "execute"  and
           "flatten".  You  probably  want  to  flatten  your  action  first, as different constituents may have
           different preferences.

            for my $action ($work->flatten) {
              my $preference = $self->preference('code', 'command');
              push @serialized, ($preference eq 'code')
                ? [ eval => $action->to_code ]
                : [ exec => $action->to_command ];
            }

   Primitives
       On primitive actions, all serialization methods will return a single item list. There are two types of of
       primitive actions shipped with this dist: Command and  Code.  Commands  are  essentially  an  abstraction
       around  a  call to an external command, Codes are an abstraction around a piece of Perl code. While these
       are all implementing the same interfaces, they have their own (hopefully obvious) preferences on  how  to
       be treated. "flatten" is just an identity operator for primitive actions.

   Composites
       Composite  actions  are  actions  that may consist out of multiple actions (though in some cases they may
       contain only one or even zero actions). "flatten" will return all its constituents. "execute",  "to_code"
       and  "to_command"  will  all  call their respective method on all those values. "preference" is of little
       use, and will always prefer to flatten when given that option.

       Nodes

       Nodes are composite Actions. Nodes are a simple class with three attributes:

       •   target

           This is the filename of the result of this build step.

       •   dependencies

           This is an unordered set of zero or more files that must be build (and must be up-to-date) before the
           target is build.

       •   actions

           This is a sequence of zero or more actions that must be performed to build the target.

       Essentially, a Node is equivalent to entry in a Makefile

   Plans
       Plans are the equivalent of a (piece of a) Makefile. They are a bunch of nodes that should  interconnect.
       It has one attribute.

       •   nodes

           This is a hash mapping (target) names to nodes.

       The  "run"  method  will  perform  a  topological  sort  much  like "make". It will check which steps are
       necessary and skip the ones which are not.

RATIONALE

       Writing extensions for various build tools can be a daunting task. This module tries to abstract steps of
       build processes into reusable building blocks for creating platform and build system agnostic  executable
       descriptions of work.

USAGE

        package Frobnicator;
        use ExtUtils::Builder::Action::Code;

        ...

        sub add_plans {
            my ($self, $planner) = @_;
            my $action = ExtUtils::Builder::Action::Code->new(
                code => ...,
            );
            $planner->create_node(
                target => 'frob',
                actions => [ $action ],
            );
            $planner->create_node(
                target => 'pure_all',
                dependencies => [ 'frob' ],
                phony => 1,
            );
        }
        ...

   Makefile.PL
        use ExtUtils::MakeMaker;
        use ExtUtils::Builder::MakeMaker;
        ...
        WriteMakeFile(
          NAME => 'Foo',
          VERSION => 0.001,
          ...,
        );

        sub MY::make_plans {
          my ($self, $planner) = @_;
          Frobnicator->add_plans($planner);
        }

AUTHOR

       Leon Timmermans <fawaka@gmail.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 by Leon Timmermans.

       This  is  free  software;  you  can  redistribute  it and/or modify it under the same terms as the Perl 5
       programming language system itself.

perl v5.38.2                                       2024-08-09                             ExtUtils::Builder(3pm)