---
name: "ExtUtils::Builder"
section: "3pm"
platform: "linux"
package: "libextutils-builder-perl"
version: "0.017-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/ExtUtils::Builder"
---

# ExtUtils::Builder(3pm)

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

## NAME

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

## VERSION

version 0.017

## 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.