=head1 NAME

Apache::StatINC - Reload %INC files when updated on disk

=head1 Synopsis

  #httpd.conf or some such
  #can be any Perl*Handler
  PerlInitHandler Apache::StatINC

=head1 Description

When Perl pulls a file via C<require>, it stores the filename in the
global hash C<%INC>.  The next time Perl tries to C<require> the same
file, it sees the file in C<%INC> and does not reload from disk.  This
module's handler iterates over C<%INC> and reloads the file if it has
changed on disk.

Note that StatINC operates on the current context of C<@INC>. 
Which means, when called as a Perl*Handler it will not see C<@INC> paths
added or removed by Apache::Registry scripts, as the value of C<@INC> is
saved on server startup and restored to that value after each request.
In other words, if you want StatINC to work with modules that live in custom
C<@INC> paths, you should modify C<@INC> when the server is started.
Besides, C<use lib> in startup scripts, you can also set the C<PERL5LIB>
variable in the httpd's environment to include any non-standard 'lib'
directories that you choose.  For example, you might use a
script called 'start_httpd' to start apache, and include a line like this:

        PERL5LIB=/usr/local/foo/myperllibs; export PERL5LIB

When you have problems with modules not being reloaded, please refer
to the following lines in I<perlmodlib>:

"Always use C<-w>. Try to C<use strict;> (or C<use strict qw(...);>).
Remember that you can add C<no strict qw(...);> to individual blocks
of code that need less strictness. Always use C<-w>. Always use C<-w>!
Follow the guidelines in the perlstyle(1) manual."

Warnings when running under mod_perl is enabled with C<PerlWarn On> in
your httpd.conf.

It will most likely help you to find the problem. Really.

=head1 Options

=over 4

=item StatINC_UndefOnReload

Normally, C<StatINC> will turn of warnings to avoid "Subroutine
redefined" warnings when it reloads a file.  However, this does not
disable the Perl mandatory warning when re-defining C<constant>
subroutines (see perldoc perlsub).  With this option On, StatINC will
invoke the C<Apache::Symbol> C<undef_functions> method to avoid these
mandatory warnings:

  PerlSetVar StatINC_UndefOnReload On

=item StatINC_Debug

You can make C<StatINC> tell when it reloads a module by setting this
option to on.

  PerlSetVar StatINC_Debug 1

The only used debug level is currently 1.

=back

=head1 SEE ALSO

mod_perl

=head1 Maintainers

Maintainer is the person(s) you should contact with updates,
corrections and patches.

=over

=item * Ask Bjoern Hanse E<lt>ask (at) netcetera.dkE<gt>

=item * The L<documentation mailing list|maillist::docs-dev>

=back

=head1 Authors

=over

=item * Doug MacEachern

=item * Ask Bjoern Hansen

=back

Only the major authors are listed above. For contributors see the
Changes file.

=cut