NAME

  Apache::PerlVINC - Allows versioning of modules among directories or v-hosts.

SYNOPSIS

#example httpd.conf:

<VirtualHost dave.domain.com>

  # include the module. this line must be here.
  PerlModule Apache::PerlVINC

  # set the include path
  PerlINC /home/dave/site/files/modules

  # make sure VINC reloads the modules
  PerlFixupHandler Apache::PerlVINC

  # optionally have VINC unload versioned modules
  PerlCleanupHandler Apache::PerlVINC


  # reloads Stuff::Things for all requests
  PerlVersion Stuff/Things.pm

  <Location /Spellcheck>
    SetHandler perl-script
    PerlHandler Spellcheck

    # reload version of this module found in PerlINC line
    PerlVersion Spellcheck.pm 
  </Location>

</VirtualHost>

<VirtualHost steve.domain.com>

  PerlModule Apache::PerlVINC
    
  <Location /Spellcheck>
    SetHandler perl-script
    PerlHandler Spellcheck
    PerlFixupHandler Apache::PerlVINC
    # only reload for requests in /Spellcheck

    PerlINC /home/steve/site/files/modules
    PerlVersion Spellcheck.pm  # makes PerlVINC load this version
  </Location>

</VirtualHost>

DESCRIPTION

With this module you can run two copies of a module without having to worry about which version is being used. Suppose you have two VirtualHost or Location that want to each use their own version of Spellcheck.pm. Durning the FixUp phase, Apache::PerlVINC will tweak @INC and reload Spellcheck. Optionally, it will unload that version if you specify Apache::PerlVINC as a PerlCleanUpHandler.

As you can guess, this module slows things down a little because it unloads and reloads on a per-request basis. Hence, this module should only be used in a development environment, not a mission critical one.

DIRECTIVES

PerlINC

Takes only one argument: the path to be prepended to @INC. In v0.1, this was stored internally as an array. This is no longer the case. However, it still works as expected in that subsequent calls to PerlINC will not overwrite the previous ones. They will both be prepended to @INC. Note that @INC is not changed for the entire request, so dont count on that path being in the @INC for your scripts.

PerlVersion

This directives specifies the files you want reloaded. Depending on where this directive sits, files will be loaded (and perhaps unloaded). Ie. if this sits in a Location section, the files will only be reloaded on requests to that location. If this lies in a server section, all requests to the server or v-host will have these files reloaded. Again, this directive does not overwrite itself.

BUGS

Sometimes, the server wont start and returns no errors. If you run with gdb you will see an error in ap_remove_module. This happens with mod_perl 1.24 and maybe versions before that. The latest version of Apache::ExtUtils (v1.04) solves this problem by adding a call to ap_remove_module in the END routine.

AUTHORS

  Doug MacEachern <dougm@pobox.com>
  Dave Moore <dave@epals.com>

COPYRIGHT

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