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