App::Install - Install applications

Version 0.03

    # 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,
    );

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.

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.

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

    package YourApp::Install;
    use base qw(App::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 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::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:

Using Module::Build

If your templates can be found under blib/lib/auto/YourApp/Install, they'll be installed into a directory which File::ShareDir can find. You need to put them into that blib directory by putting something like this in your Build.PL:

    # near the top of the Build.PL
    my $build_class = 'Module::Build';
    $build_class = $build_class->subclass(code => <<'HERE'
    sub process_install_files {
        system("mkdir -p blib/lib/auto/YourApp/Install");
        system("cp -r share/* blib/lib/auto/YourApp/Install");
    }
    HERE
    );

    # near the bottom of the Build.PL, just above create_build_script()
    $builder->add_build_element('install');

The MasonX::MiniMVC distribution provides an example of this.

Using Module::Install

Create a directory called share in the same directory as Makefile.PL and put your templates in it. Then add the following line to your Makefile.PL:

    install_share;

The File::ShareDir distribution provides an example of this.

Using ExtUtils::MakeMaker

Unknown; you'll want something similar to the technique outlined for Module::Build, above. Documentation patches welcome.

Permissions for the installed files are set as follows:

    Foo::Bar::Install->permissions(
        'foo.cgi' => 0755,
    );

You'll generally do this straight after listing the files to install.

Only non-default permissions need to be specified; the default will be whatever your system generally creates files as, eg. 0644 for readable by everyone, writable by owner. See the docs for chmod() for more information.

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.

    # If for some reason you prefer to set up the files and permissions
    # here, that will also work.  You might want to do that if the
    # installation varies depending on command line options or
    # configuration options.

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

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

The installation directory defaults to the current working directory.

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

Set a list of files to install.

Set the permissions for files.

Change the delimiters used by the templating system.

Do it!

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

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

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

    perldoc App::Install

You can also look for information at:

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/App-Install

* CPAN Ratings

http://cpanratings.perl.org/d/App-Install

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-Install

* Search CPAN

http://search.cpan.org/dist/App-Install

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.