view release on metacpan or  search on metacpan

PerlVINC.pm  view on Meta::CPAN

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

=head1 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
  # aptionally 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>


=head1 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 C<VirtualHost>
or C<Location> that want to each use their own version of C<Spellcheck.pm>.
Durning the FixUp phase, C<Apache::PerlVINC> will tweak C<@INC> and reload 
C<Spellcheck>. Optionally, it will unload that version if you specify 
C<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.

=head1 DIRECTIVES

=over 4

=item PerlINC

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

=item 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 C<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. 

=back

=head1 BUGS AND LIMITATIONS

Under some setups, C<PerlModule>'ing PerlVINC will cause the server to silently 
crash on startup. Upgrading C<Apache::ExtUtils> to v/1.04 might fix the problem. As
of this writing, the current version of mod_perl (1.24) does not contain this version
of C<Apache::ExtUtils>. Until the next version is released, you will have to obtain
it from the latest cvs snapshot.

If the C<PerlINC> directive is used twice in the same config section, the first call 
will be overwritten. Ie.

  PerlINC /qwe
  PerlINC /poi
 
  <Location /asdf/>
    PerlINC /zxc
  </Location>

For requests outside of /asdf/, @INC will contain /poi. Inside /asdf/ @INC will 
contain /zxc and /poi. This is kinda sucky, I know, and I hope to fix for the next 
release.

=head1 AUTHORS

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

=head1 COPYRIGHT

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

=cut