=head1 NAME User Help =head1 Description This chapter is for those needing help using mod_perl and related software. There is a parallel L<Getting Help|devel::help::help> document written mainly for mod_perl core developers, but may be found useful to non-core problems as well. =head1 Reporting Problems Whenever you want to report a bug or a problem remember that in order to help you, you need to provide us the information about the software that you are using and other relevant details. Please follow the instructions in the following sections when reporting problems. =head2 Wrong Apache/mod_perl combination First of all: Apache 2.0 doesn't work with mod_perl 1.0. Apache 1.0 doesn't work with mod_perl 2.0. So if you aren't using Apache 2.x with mod_perl 2.0 please do not send any bug reports. =head2 Before Posting a Report Before you post the report, make sure that you've checked the I<error_log> file (t/logs/error_log in case of the failing test suite). Usually the errors are self-descriptive and if you remember to always check this file whenever you have a problem, chances are that you won't need to ask for help. =head2 Use a Proper Subject Make sure to include a good subject like explaining the problem in a few words. Also please mention that this a problem with mod_perl 2.0 and not mod_perl 1.0. Here is an example of a good subject: Subject: [mp2.0] protocol module doesn't work with filters This is especially important now that we support mod_perl versions 1.0 and 2.0 on the same list. =head2 Important Information Whenever you send a bug report make sure to include the information about your system by doing the following: % cd modperl-2.0 % t/REPORT > mybugreport where C<modperl-2.0> is the source directory where mod_perl was built. The C<t/REPORT> utility is autogenerated when C<perl Makefile.PL> is run, so you should have it already after building mod_perl. Now add the problem description to the report and send it to the L<list|maillist::modperl>. META: soon we will have C<modperlbug> report script which will be installed system-wide =head2 Problem Description If the problem incurs with your own code, please try to reduce the code to the very minimum and include it in the bug report. Remember that if you include a long code, chances that somebody will look at it are low. If the problem is with some CPAN module, just provide its name. Also remember to include the relevant part of I<httpd.conf> and of I<startup.pl> if applicable. Don't include whole files, only the parts that should aid to understand and reproduce the problem. Finally don't forget to copy-n-paste (not type!) the B<relevant> part of the I<error_log> file (not the whole file!). =head2 Resolving Segmentation Faults If during C<make test> or the use of mod_perl you get a segmentation fault you should send to the list a stack backtrace. This L<section|devel::debug::c/Analyzing_Dumped_Core_Files> explains how to extract this backtrace. Of course to generate a useful backtrace you need to have mod_perl with debugging symbols in it (and probably perl and/or httpd too). To get debug symbols for : =over =item * mod_perl rebuild mod_perl with C<MP_DEBUG=1>. % perl Makefile.PL MP_DEBUG=1 ... % make && make test && make install =item * httpd use C<--enable-maintainer-mode>: % ./configure --enable-maintainer-mode ... % make && make install =item * perl use C<-Doptimize='-g'>: % ./Configure -Doptimize='-g' ... % make && make test && make install =item * 3rd party perl modules if the trace happens in one of the 3rd party perl modules, make sure to rebuild them, now that you've perl re-built with debugging flags. They will automatically pick the right compile flags from perl. =back Once a proper stack backtrace is obtained append it to the bug report as explained in the previous section. =head2 Please Ask Only Questions Related to mod_perl If you have general Apache questions, please refer to: http://httpd.apache.org/lists.html. If you have general Perl questions, please refer to: http://lists.perl.org/. For other remotely related to mod_perl questions see the references to L<other documentation|docs::offsite::other>. Finally, if you are posting to the list for the first time, please refer to the mod_perl mailing lists' L<Guidelines|maillist::email-etiquette>. =head1 Help on Related Topics When developing with mod_perl, you often find yourself having questions regarding other projects and topics like Apache, Perl, SQL, etc. L<This document|docs::offsite::other> will help you find the right resource where you can find the answers to your questions. =head1 Maintainers Maintainer is the person(s) you should contact with updates, corrections and patches. =over =item * Stas Bekman =back =head1 Authors =over =item * Stas Bekman =back Only the major authors are listed above. For contributors see the Changes file. =cut
