Footprintless::Overlay

- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- ENTITIES
- CONSTRUCTORS
  - new($entity, $coordinate)
- METHODS
  - clean()
  - initialize()
  - update()
- AUTHOR
- COPYRIGHT AND LICENSE
- SEE ALSO
- CONFIGURATION

# NAME

Footprintless::Overlay - An overlay manager

# VERSION

version 1.29

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

- Footprintless
- Config::Entities
- Footprintless
- Footprintless::Mixins
- Template::Overlay
- Template::Resolver

# 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();
                    }
                });
        }