NAME

SYNOPSIS

  This module is used within a Build.PL script directly or
  it can be subclassed to provide extra capabilities.

  use App::Build;

  my $build = App::Build->new (
      dist_name         => "App-Build-Foo",
      dist_version      => "1.0",
      dist_author       => "stephen.adkins\@officevision.com",
      extra_dirs        => [ "htdocs", "cgi-bin", "etc", "var" ],
      license           => "perl",
      build_requires => {
          "App::Build"  => 0,  # needed for installing the software
      },
  );
  
  $build->create_build_script;

DESCRIPTION

Module::Build is good at installing perl modules and programs/scripts. Full applications (i.e. web applications) need to install other files such as web pages, images, CSS style sheets, javascript files, CGI programs, data files, and configuration data. App::Build addresses these issues.

The vision of App::Build is to make installing entirely functional perl applications (particularly web applications) as easy as installing individual modules from CPAN.

An ISP customer (or other unprivileged user) who has shell access should be able to install any number of available applications from CPAN simply by typing the usual

  perl -MCPAN -e "install App::Build::Foo"

and the "Foo" application is installed on his account.

App::Build does this by implementing the following features.

1. Distributions that use App::Build instead of Module::Build can easily install files to other places, besides just "lib" and "bin". e.g. "htdocs", "cgi-bin", "etc". (see the "extra_dirs" argument in the example in the Synopsis above)

2. App::Build also adds a hook into the "install" action to call the "configure()" method. If you are subclassing App::Build, you can override this method and perform customized configuration tasks.

INCLUDED APPLICATIONS AND EXTERNAL APPLICATIONS

Anyone who finds a useful perl application somewhere (i.e. "Foo") can write a small perl distribution called App-Build-Foo and upload it to CPAN. When someone uses the CPAN shell, they can install the application simply by typing

 install App::Build::Foo

Within the App-Build-Foo distribution would be a module, App::Build::Foo, which would be a subclass of App::Build. It would contain any specific logic necessary to download and install the Foo application.

All applications installed with App::Build (and its derivatives) should conform to a set of standards (see below) so that when multiple applications are installed, they are integrated seamlessly and work side by side.

APPLICATION INSTALLATION REQUIREMENTS

 * The installation MUST be useful to ISP's (internet
   service providers) and ASP's (application service
   providers) such that the software is installed
   in such a way that each customer of theirs may use
   it without any interactions with other customers.

 * The installation SHOULD allow for multiple versions
   even for an unprivileged user (an ISP/ASP customer).
   This allows a user to install a new version of an
   application and evaluate it and run it in parallel
   with an existing version of the application.

APPLICATION INSTALLATION STANDARDS

 * TBD

App::Build CONFIGURABILITY

This will be put to good use sometime in the future.

FIX-UPS

The CPAN shell (for some reason I don't understand) runs Build.PL as "perl Build.PL Build" and this fails. App::Build just throws away the "Build" so that the default "build" action is invoked.

Module::Build deprecated the PREFIX option to Makefile.PL (i.e. "perl Makefile.PL PREFIX=/usr/foo"). App::Build just makes the PREFIX option a synonym for "install_base", which does essentially the same thing.

METHODS

It is also so that I can remember what I was doing so that if the internals of Module::Build change, I can maintain this code.

   perl Build.PL install_base=/usr/mycompany/prod

   perl Build.PL PREFIX=/usr/mycompany/prod

   extra_dirs => {
       var => {
           dest_dir => "var",
       },
       htdocs => {
           dest_dir => "htdocs",
       },
       "cgi-bin" => {  # any dir ending in "bin" contains executable scripts
           dest_dir => "cgi-bin",
       },
       support => {
           dest_dir => "support",
           executable => 1,  # treat contents as executable scripts
       },
   },

    * Signature: $build->mirror($url, $file);
    * Param:  $url          string
    * Param:  $file         string

    * Signature: $build->unpack($archive_file, $directory, $subdir);
    * Param:  $archive_file string
    * Param:  $directory    string
    * Param:  $subdir       string

ACKNOWLEDGEMENTS

 * Author:  Stephen Adkins <stephen.adkins@officevision.com>
 * Maintainer: Mattia Barbon <mbarbon@cpan.org>

LICENSE

SOURCES

SEE ALSO