NAME

Beam::Make - Recipes to declare and resolve dependencies between things

VERSION

version 0.003

SYNOPSIS

    ### container.yml
    # This Beam::Wire container stores shared objects for our recipes
    dbh:
        $class: DBI
        $method: connect
        $args:
            - dbi:SQLite:RECENT.db

    ### Beamfile
    # This file contains our recipes
    # Download a list of recent changes to CPAN
    RECENT-6h.json:
        commands:
            - curl -O https://www.cpan.org/RECENT-6h.json

    # Parse that JSON file into a CSV using an external program
    RECENT-6h.csv:
        requires:
            - RECENT-6h.json
        commands:
            - yfrom json RECENT-6h.json | yq '.recent.[]' | yto csv > RECENT-6h.csv

    # Build a SQLite database to hold the recent data
    RECENT.db:
        $class: Beam::Make::DBI::Schema
        dbh: { $ref: 'container.yml:dbh' }
        schema:
            - table: recent
              columns:
                - path: VARCHAR(255)
                - epoch: DOUBLE
                - type: VARCHAR(10)

    # Load the recent data CSV into the SQLite database
    cpan-recent:
        $class: Beam::Make::DBI::CSV
        requires:
            - RECENT.db
            - RECENT-6h.csv
        dbh: { $ref: 'container.yml:dbh' }
        table: recent
        file: RECENT-6h.csv

    ### Load the recent data into our database
    $ beam make cpan-recent

DESCRIPTION

Beam::Make allows an author to describe how to build some thing (a file, some data in a database, an image, a container, etc...) and the relationships between things. This is similar to the classic make program used to build some software packages.

Each thing is a recipe and can depend on other recipes. A user runs the beam make command to build the recipes they want, and Beam::Make ensures that the recipe's dependencies are satisfied before building the recipe.

This class is a Beam::Runnable object and can be embedded in other Beam::Wire containers.

Recipe Classes

Unlike make, Beam::Make recipes can do more than just execute a series of shell scripts. Each recipe is a Perl class that describes how to build the desired thing and how to determine if that thing needs to be rebuilt.

These recipe classes come with Beam::Make:

• File - The default recipe class that creates a file using one or more shell commands (a la make)

• DBI - Write data to a database

• DBI::Schema - Create a database schema

• DBI::CSV - Load data from a CSV into a database table

• Docker::Image - Build or pull a Docker image

• Docker::Container - Build a Docker container

Future recipe class ideas are:

• Template rendering: Files could be generated from a configuration file or database and a template.

• Docker compose: An entire docker-compose network could be rebuilt.

• System services (init daemon, systemd service, etc...): Services could depend on their configuration files (built with a template) and be restarted when their configuration file is updated.

Beamfile

The Beamfile defines the recipes. To avoid the pitfalls of Makefile, this is a YAML file containing a mapping of recipe names to recipe configuration. Each recipe configuration is a mapping containing the attributes for the recipe class. The $class special configuration key declares the recipe class to use. If no $class is specified, the default Beam::Wire::File recipe class is used. All recipe classes inherit from Beam::Class::Recipe and have the name and requires attributes.

For examples, see the Beam::Wire examples directory on Github.

Object Containers

For additional configuration, create a Beam::Wire container and reference the objects inside using $ref: "<container>:<service>" as the value for a recipe attribute.

TODO

Target names in Beamfile should be regular expressions

This would work like Make's wildcard recipes, but with Perl regexp. The recipe object's name is the real name, but the recipe chosen is the one the matches the regexp.

Environment variables should interpolate into all attributes

Right now, the NAME=VALUE arguments to beam make only work in recipes that use shell scripts (like Beam::Make::File). It would be nice if they were also interpolated into other recipe attributes.

Recipes should be able to require wildcards and directories

Recipe requirements should be able to depend on patterns, like all *.conf files in a directory. It should also be able to depend on a directory, which would be the same as depending on every file, recursively, in that directory.

This would allow rebuilding a ZIP file when something changes, or rebuilding a Docker image when needed.

Beam::Wire should support the <container>:<service> syntax for references

The Beam::Wire class should handle the BEAM_PATH environment variable directly and be able to resolve services from other files without building another Beam::Wire object in the container.

Beam::Wire should support resolving objects in arbitrary data structures

Beam::Wire should have a class method that one can pass in a hash and get back a hash with any Beam::Wire object references resolved, including $ref or $class object.

SEE ALSO

Beam::Wire

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Doug Bell.

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