/ 
App-Bootstrap-0.01
River stage zero No dependents
/ App::Bootstrap

NAME

App::Bootstrap - Bootstrap, stub, or install applications

VERSION

Version 0.01

SYNOPSIS

In YourApp::Install:

use base qw(App::Bootstrap);

WARNING

This is experimental and subject to change. It's not even guaranteed to really work at all. You have been warned.

DESCRIPTION

This is easiest to do by analogy. Have you ever used any of the following?

module-starter
catalyst.pl
kwiki-install
minimvc-install

Each of these scripts comes packaged with its respective distro (Module::Starter, Catalyst::Helper, Kwiki, and MasonX::MiniMVC respectively) and is used to create a framework, stub, or starting point for some software.

If you're not familiar with any of those modules and their installers, imagine a theoretical module Foo::Bar, which comes with a foo-install script. When you run foo-install, it creates a directory structure like this:

foo.cgi
lib/
lib/Foo/Local.pm
t/
t/foo_local.t

You can then adapt foo.cgi and the other provided files to suit your specific needs.

Well, App::Bootstrap is a generic tool for creating installers like those described above.

Using App::Bootstrap

App::Bootstrap is used by subclassing it. In YourApp::Install, you'll put:

package YourApp::Install;
use base qw(App::Bootstrap);

Next, specify the files you'll want to populate:

YourApp::Install->files(
    identifier  => 'relative/file/location',
    second_file => 'some/other/location',
);

File locations are relative to the base directory the user's installing into. Using the Foo::Bar example given above, you might have:

Foo::Bar::Install->files(
    foo_cgi.tmpl    => 'foo.cgi',
    local_pm.tmpl   => 'lib/Foo/Local.pm',
    local_test.tmpl => 't/foo_local.t',
);

You need to include your input template files in the share directory of your module distribution. If you're using Module::Build, this typically means creating a directory called share/ at the top level of your distro, and everything will be magically installed in the right place. App::Bootstrap uses File::ShareDir to determine the location of your app's share directory after it's installed.

If you wish data to be interpolated into your inline files -- and you probably do -- this is done using Text::Template. In its simplest form, simply put anything you wish to have interpolated in triple curly braces:

package {{{$app_name}}};

The delimiters -- {{{ and }}} have been chosen for their unlikelihood of showing up in real Perl code. If for some reason this doesn't suit you, you can change the delimiters in YourApp::Install as follows:

YourApp::Install->delimiters($start, $end);

To actually create an installer script, simply write something like:

use YourApp::Install;

# pick up options from the command line or elsewhere, if desired
# eg. the application name, email, etc.

YourApp::Install->install(
    template_dir => $template_dir,
    install_dir  => $install_dir,
    data => \%data,
);

The template directory defaults to your distribution's share directory (see Module::ShareDir).

The installation directory defaults to the current working directory.

The data hashref will be passed to Text::Template for interpolation into the files.

PUBLIC METHODS

files()

Set a list of files to install.

delimiters()

Change the delimiters used by the templating system.

install()

Do it!

AUTHOR

Kirrily "Skud" Robert, <skud at cpan.org>

BUGS

Please report any bugs or feature requests to bug-app-bootstrap at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-Bootstrap. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::Bootstrap

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2007 Kirrily "Skud" Robert, all rights reserved.

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