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.
share
share/
To put your files into a share directory in the first place:
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:
blib/lib/auto/YourApp/Install
# 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.
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:
Makefile.PL
install_share;
The File::ShareDir distribution provides an example of this.
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.
chmod()
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>
<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.
bug-app-install at rt.cpan.org
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.
To install App::Install, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Install
CPAN shell
perl -MCPAN -e shell install App::Install
For more information on module installation, please visit the detailed CPAN module installation guide.