The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Footprintless-1.25
River stage one • 3 direct dependents • 3 total dependents
1 ++
/ Footprintless::Overlay

NAME

Footprintless::Overlay - An overlay manager

VERSION

version 1.25

SYNOPSIS

    # Standard way of getting an overlay
    use Footprintless;
    my $overlay = Footprintless->new()->overlay('overlay');

    $overlay->clean();

    $overlay->initialize();

    $overlay->update();

DESCRIPTION

Overlays are a combination of a directory of static files and a directory of templated files that will be merged to an output directory. This is implemented in Template::Overlay.

Additionally, any folder under the template_dir can contain a .footprintless file containing a clean and/or resources entities:

    return {
        clean => [
            'foo.jar',
            'bar.jar',
            'ext/'
        ],
        resources => {
            foo => 'com.pastdev:foo:1.0.0',
            bar => 'com.pastdev:bar:1.0.0'
        }
    };

The clean entity is an arrayref containing a list of paths to clean out. These paths will be added to the path of the directory containing the .footprintless file. The resources entity is a list of resources to download into the same directory as the .footprintless file.

ENTITIES

A simple overlay:

    overlay => {
        base_dir => "/home/me/foo/base",
        clean => [
            "/opt/tomcat/"
        ],
        hostname => 'localhost',
        key => 'T',
        os => 'linux',
        template_dir => "/home/me/foo/template",
        to_dir => '/opt/foo/tomcat'
    }

A more complex example:

    foo => {
        hostname => 'test.pastdev.com',
        overlay => {
            'Config::Entities::inherit' => ['hostname', 'sudo_username'],
            base_dir => '/home/me/foo/base',
            clean => [
                '/opt/foo/tomcat/'
            ],
            key => 'T',
            os => 'linux',
            resolver_coordinate => 'foo',
            template_dir => '/home/me/foo/template',
            to_dir => '/opt/foo/tomcat'
        },
        sudo_username => 'developer',
        tomcat => {
            'Config::Entities::inherit' => ['hostname', 'sudo_username'],
            catalina_base => '/opt/foo/tomcat',
            http => {
                port => 20080
            },
            service => {
                action => {
                    'kill' => { command_args => 'stop -force' },
                    'status' => { use_pid => 1 }
                },
                command => '/opt/foo/tomcat/bin/catalina.sh',
                pid_file => '/opt/foo/tomcat/bin/.catalina.pid',
            },
            shutdown => {
                port => 8505,
                password => $properties->{'foo.tomcat.shutdown.password'},
            },
            trust_store => {
                'Config::Entities::inherit' => ['hostname', 'sudo_username'],
                file => '/opt/foo/tomcat/certs/truststore.jks',
                include_java_home_cacerts => 1,
                password => $properties->{'foo.tomcat.trust_store.password'},
            }
        }
    }

An overlay can obtain base/template content from a resource. When initialize or update are called, the resource will be downloaded (if not already local) and extracted to a temp folder. The base_dir and template_dir paths will be appended to the extract temp folder:

    overlay => {
        base_dir => 'base',
        clean => [
            '/opt/tomcat/'
        ],
        hostname => 'localhost',
        key => 'T',
        os => 'linux',
        resource => 'com.pastdev:app-overlay:zip:package:1.0.0',
        template_dir => 'template',
        to_dir => '/opt/foo/tomcat'
    }

An overlay can have multiple template folders. If it does, they will be processed in the order they are listed:

    overlay => {
        base_dir => 'base',
        clean => [
            '/opt/tomcat/'
        ],
        hostname => 'localhost',
        key => 'T',
        os => 'linux',
        template_dir => [
            'first/template_dir',
            'second/template_dir',
        ],
        to_dir => '/opt/foo/tomcat'
    }

CONSTRUCTORS

new($entity, $coordinate)

Constructs a new overlay configured by $entities at $coordinate.

METHODS

clean()

Cleans the overlay. Each path in the clean entity, will be removed from the destination. If the path ends in a /, then after being removed, the directory will be recreated.

initialize()

Will call clean, then overlay on an instance of Template::Overlay configured to this entity.

update()

Will overlay ONLY the templated files. It will not clean, nor copy any files from base_dir like initialize does.

AUTHOR

Lucas Theisen <lucastheisen@pastdev.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Lucas Theisen.

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

SEE ALSO

Please see those modules/websites for more information related to this module.

CONFIGURATION

This module can optionally be configured to use a customized resolver. To do so, configure a resolver factory in your entities:

    footprintless => {
        overlay => {
            resolver_factory => 'My::ResolverFactory'
        }
    }

The resolver factory must have a new_resolver method that takes a spec and a list of options and returns a Template::Resolver, for example:

    sub new_resolver {
        my ($self, $resolver_spec, %resolver_opts) = @_;
        return Template::Resolver->new(
            $resolver_spec,
            %resolver_opts,
            additional_transforms => {
                random => sub {
                    my ($resolver_self, $value) = @_;
                    return $value . rand();
                }
            });
    }