Nathan Byrd > Apache-PAR-0.30 > Apache::PAR

Download:
Apache-PAR-0.30.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.30   Source  

NAME ^

Apache::PAR - Perl extension for including Perl ARchive files in a mod_perl (1.x or 2.x) environment.

SYNOPSIS ^

  Inside Apache configuration:
    PerlSetVar PARInclude /path/to/par/archive/directory
    ...
    PerlAddVar PARInclude /path/to/a/par/file.par
    ...
    PerlModule Apache::PAR

  In Apache/mod_perl 1.x environments on Win32 platforms, the following 
  should be used instead:
  
    PerlSetVar PARInclude /path/to/par/archive/directory
    ...
    PerlSetVar PARInclude /path/to/a/par/file.par
    ...
    <PERL>
    use Apache::PAR;
    </PERL>


  Alternative configuration, inside a startup.pl script or PERL section:
    use Apache::PAR qw(
      /path/to/par/archive/directory
      /path/to/a/par/file.par
    );

  Inside a web.conf file:

    Alias /myapp/static/ ##PARFILE##/
    <Location /myapp/static>
      SetHandler perl-script
      PerlHandler Apache::PAR::Static
      PerlSetVar PARStaticDirectoryIndex index.htm
      PerlAddVar PARStaticDirectoryIndex index.html
      PerlSetVar PARStaticDefaultMIME text/html
    </Location>

    Alias /myapp/cgi-perl/ ##PARFILE##/
    <Location /myapp/cgi-perl>
      Options +ExecCGI
      SetHandler perl-script
      PerlHandler Apache::PAR::Registry
    </Location>

    Alias /myapp/cgi-run/ ##PARFILE##/
    <Location /myapp/cgi-run>
      Options +ExecCGI
      SetHandler perl-script
      PerlHandler Apache::PAR::PerlRun
    </Location>

    PerlModule MyApp::TestMod
    Alias /myapp/mod/ ##PARFILE##/
    <Location /myapp/mod>
      SetHandler perl-script
      PerlHandler TestMod
    </Location>

  Using ##UNPACKDIR## to unpack archive
  
    Alias /myapp/static/ ##UNPACKDIR##/htdocs/
    
    Alias /myapp/cgi-perl/ ##UNPACKDIR##/scripts/
    <Location /myapp/cgi-perl>
      Options +ExecCGI
      SetHandler perl-script
      PerlHandler Apache::Registry
    </Location>
    
    Alias /myapp/cgi-run/ ##UNPACKDIR##/scripts/
    <Location /myapp/cgi-run>
      Options +ExecCGI
      SetHandler perl-script
      PerlHandler Apache::PerlRun
    </Location>
    
    PerlModule MyApp::TestMod
    Alias /myapp/mod/ ##PARFILE##/
    <Location /myapp/mod>
      SetHandler perl-script
      PerlSetEnv TestModTemplateDir ##UNPACKDIR##/template
      PerlHandler TestMod
    </Location>
    
  Using PerlInitHandler to reload changed modules:
  
    PerlModule Apache::PAR
    PerlInitHandler Apache::PAR

DESCRIPTION ^

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.

Apache::PAR itself performs the work of specifying the location of PAR archives and allowing the loading of modules from these archives. The files and paths can be specified at load time. Once an archive has been located, an optional web.conf (filename configurable) is then loaded and included into the main web configuration. Once Apache::PAR has been loaded, Perl Apache modules within these .par files can then be loaded.

The following steps are performed on any .par files which are found within a PARInclude:

Some things to note:

PerlSetVar/AddVar configuration for PARInclude and PARTempDir MUST be before the PerlModule Apache::PAR (or use Apache::PAR;) line in the Apache configuration. Any PARInclude variables (or PARDir and PARFile) after the PerlModule line will be ignored.

PARDir and PARFile directives may be used to specify the location of PAR archives, however their use is deprecated. For new configurations, use PARInclude instead. PARInclude works both as PARDir and PARFile by first expanding directories to include any PAR archives found within.

The arguments for PARInclude can be either an absolute path, or a relative path from Apache's server_root. For example, if your Apache's server_root is /usr/local/apache, and you would like to load .par files from a parfiles/ subdirectory, use: PerlSetVar PARInclude parfiles/

This will then look for .par files in the /usr/local/apache/parfiles directory.

The name of the configuration file which is loaded is configurable via PARConf (default is 'web.conf'.) For example, to set the include filename to 'include.conf' for all .par files: PerlSetVar PARConf include.conf

The extensions used when searching for .par archives in any directories set via PARInclude is set using the PARExt variable in the Apache configuration (the default is 'par'). For example, to set the par extension to 'zip': PerlSetVar PARExt zip

There is currently no way to limit which .par archive a module is loaded out of. To ensure that the correct module is being loaded, I suggest the following convention: begin module names with the name of the archive. For instance, a MailForm module within the MyApp.par archive should be named MyApp::MailForm

Currently, which directory inside a .par archive modules are loaded out of is not configurable, and is the same as defined in PAR.pm:

1. /
2. /lib/
3. /arch/
4. /i386-freebsd/ # i.e. $Config{archname}
5. /5.8.0/ # i.e. $Config{version}
6. /5.8.0/i386-freebsd/ # both of the above

By default, if a web.conf file contains a ##UNPACKDIR## directive, the archive will be unpacked to a subdirectory under PARTempDir during Apache startup. The default for PARTempDir is the platform specific temp directory (e.g. c:\temp for win32, /tmp for *nix.) Archive unpacking may be disabled by specifying PerlSetVar PARTempDir NONE in the Apache configuration, however this will prevent the loading of any PAR files which require unpacking to operate.

Changed content in PAR files is not reloaded util the next restart of Apache unless the directive PerlInitHandler Apache::PAR is used. Currently, some functionality will not change or reload when a PAR file is removed, however. This may change in a future release.

PLATFORM SPECIFIC ^

In general, Apache::PAR should function on most platforms without changes, as it is (currently) a perl only module. Below are notes for any known exceptions. If you have any problems with Apache::PAR on your platform, please contact me through one of the methods in the CONTACT section.

Windows 32 bit

Some testing has been performed on Apache::PAR using WIN32 platforms, with both mod_perl 1.x and 2.x. Apache::PAR should function as normal on these platforms, however, an alternate configuration method is required due to differences in the Apache/mod_perl startup sequence on that platform.

inside a PERL section or startup.pl:

    use Apache::PAR qw(
      /path/to/par/archive/directory
      /path/to/a/par/file.par
      ...
    );

Additionally, you can still use PerlSetVar PARInclude, etc lines in Win32 - the Apache::PAR include must be via a use however (not a PerlModule directive):

inside httpd.conf (example for mod_perl 1.x, for 2.x use <PERL > instead):

  PerlSetVar PerlInclude /path/to/par/archive/directory
  PerlAddVar PerlInclude /path/to/a/par/file.par
  ...
  <PERL>
    use Apache::PAR;
  </PERL>

EXPORT ^

None by default.

ACKNOWLEDGEMENTS ^

Autrijus Tang <autrijus@autrijus.org> for providing assistance on numerous occasions during the development of Apache::PAR.

Maurice Aubrey <maurice@lovelyfilth.com> for adding the ability to unpack content from PAR archives.

CONTACT ^

For questions regarding the installation or use of Apache::PAR, either post a message on the PAR list <par@perl.org>, on the sourceforge project page at http://www.sourceforge.net/projects/apache-par or send an email to the author directly at <nathan@byrd.net>.

AUTHOR ^

Nathan Byrd, <nathan@byrd.net>

SEE ALSO ^

perl.

PAR.

Apache::PAR::Registry, Apache::PAR::PerlRun, and Apache::PAR::Static.

COPYRIGHT ^

Copyright 2002, 2003 by Nathan Byrd, <nathan@byrd.net>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

syntax highlighting: