view release on metacpan or  search on metacpan

PAR/tutorial.pod  view on Meta::CPAN

=head1 NAME

Apache::PAR::tutorial - Information on getting Apache::PAR up and running.

=head1 INTRODUCTION

Apache::PAR is a framework for including Perl ARchive files in a mod_perl (1.x or 2.x) 
environment.  It allows an author to package up a web application, including configuration, 
static files, Perl modules, and Registry and PerlRun scripts to include in a single file.  
This archive can then be moved to other locations on the same system or distributed and loaded 
with a single set of configuration options in the Apache configuration.

These modules are based on PAR.pm by Autrijus Tang and Archive::Zip by Ned Konz as well as the 
mod_perl modules.  They extend the concept of PAR files to mod_perl, similar to how WAR 
archives work for Java. An archive (which is really a zip file), contains one or more elements 
which can be served to clients making requests to an Apache web server.  Scripts, modules, and 
static content should then be able to be served from within the .par archive without 
modifications.

=head2 For the package developer

For the package developer, Apache::PAR allows for easy package management, which frees the 
author from the task of creating a full Perl package.  Apache::PAR allows the package 
developer to set the required Apache configuration directly in a package which greatly 
simplifies the install process for the end user and gives the the developer the ability to 
assign URL's which remain the same on all systems that the package is installed on.  It is 
possible to decompress the contents of the PAR file during startup, which allows the use of 
code which relies on outside content (templating systems, etc)

=head2 For the package user

Once Apache::PAR is installed, it can be configured in an Apache configuration file with as 
little as two lines.  Once setup, to add a new .par package to the system a user only has to 
place the package in the directory specified in the Apache configuration and restart Apache.  
All other configuration needs are provided by the module itself.

=head1 INSTALLATION

Apache::PAR is installed in a manner similar to other CPAN modules.  Either use CPAN to 
install, or download the package and install by hand.

=head2 Installation from CPAN

To install from CPAN, simply start the CPAN shell and execute an install command.  
For instance:

	perl -MCPAN -eshell;
	install Apache::PAR

Select [y]es to install any required dependencies.

B<NOTE:> If you are installing Apache::PAR using CPAN as root you may need to force the 
install (force install Apache::PAR.)  This is because the tests rely on loading .par files 
from a test directory, which may fail due to permission problems.  Unless compiled to do so, 
Apache will not run as the root user, however, the modules are tested from the .cpan directory 
under root's home directory.  This will hopefully be addressed in a future version of 
Apache::PAR.  Also, you may want to add your Apache bin/ directory to your path if it isn't 
already set.  This allows Apache::Test to choose which Apache to use when testing.


=head2 Manual installation

Download the latest version of Apache::PAR from CPAN, as well as any dependencies which you do 
not already have installed.  Below is a list of modules which are required by Apache::PAR.  
For some of these modules, a compiler may be required if building from source (although, 
Apache::PAR itself is written in pure perl.)  NOTE: It is possible to install all of these on 
Win32 systems without a compiler.  Most of these modules are avalable through ppm, and PAR