view release on metacpan or  search on metacpan

lib/App/Install.pm  view on Meta::CPAN

use Text::Template;

=head1 NAME

App::Install - Install applications

=head1 VERSION

Version 0.03

=cut

our $VERSION = '0.03';

our %files;
our %permissions;
our @delimiters = ('{{{', '}}}');

=head1 SYNOPSIS

    # In YourApp::Install:

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

    __PACKAGE__->files(%files);
    __PACKAGE__->permissions(%permissions);
    __PACKAGE__->delimiters($start, $end);

    # In a yourapp-install script:

    use YourApp::Install;

    # you can optionally set files() and permissions() here too

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

=head1 WARNING

This module is in its early days, and the interface is subject to
change.  If you're using it, please let me know and I'll try and tell
you if I'm going to break anything.

=head1 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 install an application or create a
framework, stub, or starting point for your own application.

If you're not familiar with any of those modules and their installers,
imagine a theoretical module Foo::Bar, providing some kind of CGI
application,  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::Install is a generic tool for creating installers like
those described above.

=head1 Using App::Install

=head2 Subclassing App::Install

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

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

=head2 Specify files to install

Next, specify the files you want to install:

    YourApp::Install->files(
        'relative/file/location' => 'some_template.pl',
        'some/other/location'    => 'other_template.pl',
    );

You can do this either in YourApp/Install.pm or in your install script.

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'          => 'foo_cgi.tmpl',
        'lib/Foo/Local.pm' => 'local_pm.tmpl',
        't/foo_local.t'    => 'local_test.tmpl',
    );

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

To put your files into a share directory in the first place:

=over 4

=item Using Module::Build