=head1 NAME Mojolicious::Plugin::ModuleBuild - Easy Module::Build configuration for Mojolicious apps =head1 SYNOPSIS # MyApp.pm package MyApp; use Mojo::Base 'Mojolicious'; sub startup { my $app = shift; $app->plugin( 'ModuleBuild' ); ... } # Build.PL use Module::Build::Mojolicious; my $builder = Module::Build::Mojolicious->new( configure_requires => { 'Module::Build::Mojolicious' => 0, 'Module::Build' => 0.38, }, ... ); $builder->create_build_script; =head1 DESCRIPTION L applications work nicely from a working directory, but once the app is bundled for installation some of the configuration gets a little bit tricky. Though some examples are shown in the L documentation, the process is still rather involved. However, when using L this module handles all the configuration for you (provided you follow a proscribed directory tree)! =head1 DIRECTORY STRUCTURE myapp # Application directory |- bin # Script directory | +- myapp # Application script |- lib # Library directory | |- MyApp.pm # Application class | |- MyApp # Application namespace | |- Example.pm # Controller class | +- files # Shared directory for all non-module content | |- public # Static file directory (served automatically) | | +- index.html # Static HTML file | +- templates # Template directory | |- layouts # Template directory for layouts | | +- default.html.ep # Layout template | +- example # Template directory for "Example" controller | +- welcome.html.ep # Template for "welcome" action |- t # Test directory | +- basic.t # Random test +- Build.PL # Build file uses Module::Build::Mojolicious As you can see, all non-module content is placed inside a directory named C directly inside the folder named for the module. In the above example this is the C directory. If the app had been C then the directory would be C. If it exists, this folder is automatically added to the list of shared directories installed by Module::Build's L integration. Later, this directory can be found using the usual mechanisms that that system provides. There is no allowance for different names of these folders nor of different locations for them relative to the main module. Patches will be considered, but the primary purpose of this module is the simple generic case; to do strange things the Mojolicious path manipulation system should be used directly. =head1 PLUGIN The magic happens when your app loads the C plugin. $app->plugin('ModuleBuild'); Before this call, the directories are not set correctly, so be sure to use it early! The plugin will detect if the directory tree exists as above (i.e. before installation) and use it directly or else it will attempt to use the L system to locate the directories (i.e. after installation). In this way, your app should always find its needed files, no matter what phase of development or installation! =head1 BUILD SCRIPT Included with L is a subclass of L named L (of course). The purpose of this subclass is to add the necessary directory to the list of shared folders. This is done completely behind the scenes, provided the directory exists. Simply change the name of your build module and use as normal: use Module::Build::Mojolicious; my $builder = Module::Build::Mojolicious->new( configure_requires => { 'Module::Build::Mojolicious' => 0, 'Module::Build' => 0.38, }, ... ); $builder->create_build_script; Note that you should add it to the C key as you should for any module used in a C file. =head1 SEE ALSO =over =item * L =item * L =back =head1 SOURCE REPOSITORY L =head1 AUTHOR Joel Berger, Ejoel.a.berger@gmail.comE =head1 COPYRIGHT AND LICENSE Copyright (C) 2012 by Joel Berger This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.