/usr/share/doc/libapache2-mod-perl2-doc/docs/2.0/user/help/help.html is in libapache2-mod-perl2-doc 2.0.8+httpd24-r1449661-6ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | <?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title></title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>
<body style="background-color: white">
<ul id="index">
<li><a href="#NAME">NAME</a></li>
<li><a href="#Description">Description</a></li>
<li><a href="#Reporting-Problems">Reporting Problems</a>
<ul>
<li><a href="#Wrong-Apache-mod_perl-combination">Wrong Apache/mod_perl combination</a></li>
<li><a href="#Using-the-Wrong-Compiler">Using the Wrong Compiler</a></li>
<li><a href="#Before-Posting-a-Report">Before Posting a Report</a></li>
<li><a href="#Test-with-the-Latest-mod_perl-2.0-Version">Test with the Latest mod_perl 2.0 Version</a></li>
<li><a href="#Use-a-Proper-Subject">Use a Proper Subject</a></li>
<li><a href="#Send-the-Report-Inlined">Send the Report Inlined</a></li>
<li><a href="#Important-Information">Important Information</a></li>
<li><a href="#Problem-Description">Problem Description</a></li>
<li><a href="#make-test-Failures">'make test' Failures</a></li>
<li><a href="#Resolving-Segmentation-Faults">Resolving Segmentation Faults</a></li>
<li><a href="#Please-Ask-Only-Questions-Related-to-mod_perl">Please Ask Only Questions Related to mod_perl</a></li>
</ul>
</li>
<li><a href="#Help-on-Related-Topics">Help on Related Topics</a></li>
<li><a href="#Maintainers">Maintainers</a></li>
<li><a href="#Authors">Authors</a></li>
</ul>
<h1 id="NAME">NAME</h1>
<p>User Help</p>
<h1 id="Description">Description</h1>
<p>This chapter is for those needing help using mod_perl and related software.</p>
<p>There is a parallel <a>Getting Help</a> document written mainly for mod_perl core developers, but may be found useful to non-core problems as well.</p>
<h1 id="Reporting-Problems">Reporting Problems</h1>
<p>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.</p>
<p><b>The most important thing</b> to understand is that you should try hard to provide <b>all</b> the information that may assist to understand and reproduce the problem. When you prepare a bug report, put yourself in the position of a person who is going to try to help you, realizing that a guess-work on behalf of that helpful person, more often doesn't work than it does. Unfortunately most people don't realize that, and it takes several emails to squeeze the needed details from the person reporting the bug, a process which may drag for days.</p>
<h2 id="Wrong-Apache-mod_perl-combination">Wrong Apache/mod_perl combination</h2>
<p>First of all:</p>
<pre><code> Apache 2.0 doesn't work with mod_perl 1.0.
Apache 1.0 doesn't work with mod_perl 2.0.</code></pre>
<p>So if you aren't using Apache 2.x with mod_perl 2.0 please do not send any bug reports.</p>
<p>META: mod_perl-1.99_xx is mod_perl 2.0 to-be.</p>
<h2 id="Using-the-Wrong-Compiler">Using the Wrong Compiler</h2>
<p>To build mod_perl, you <b>must</b> also use the same compiler that Perl was built with. You can find that out by running <code>perl -V</code> and looking at the <code>Compiler:</code> section. If you have used a different compiler and have encountered problems (which most likely will be the case) recompile Perl with the same compiler and then recompile mod_perl again.</p>
<h2 id="Before-Posting-a-Report">Before Posting a Report</h2>
<p>Before you post the report, make sure that you've checked the <i>error_log</i> 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.</p>
<h2 id="Test-with-the-Latest-mod_perl-2.0-Version">Test with the Latest mod_perl 2.0 Version</h2>
<p>If you are using an older version than the most recently released one, chances are that a bug that you are about to report has already been fixed. If possible, save us and yourself time and try first to upgrade to <a>the latest version</a>, and only if the bug persists report it.</p>
<p>Reviewing the Changes file may help as well. Here is the Changes file of the most recenly released version: http://perl.apache.org/dist/mod_perl-2.0-current/Changes .</p>
<p>If the problem persists with the latest version, you may also want to try to reproduce the problem with <a>the latest development version</a>. It's possible that the problem was resolved since the last release has been made. Of course if this version solves the problem, don't rush to put it in production unless you know what you are doing. Instead ask the developers when the new version will be released.</p>
<h2 id="Use-a-Proper-Subject">Use a Proper Subject</h2>
<p>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:</p>
<pre><code> Subject: [mp2] protocol module doesn't work with filters</code></pre>
<p>This is especially important now that we support mod_perl versions 1.0 and 2.0 on the same list.</p>
<h2 id="Send-the-Report-Inlined">Send the Report Inlined</h2>
<p>When sending the bug report, please inline it and don't attach it to the email. It's hard following up on the attachments.</p>
<h2 id="Important-Information">Important Information</h2>
<p>Whenever you send a bug report make sure to include the information about your system.</p>
<ul>
<li><p>If you haven't yet installed mod_perl and/or you are having problems with the test suite -- you should do:</p>
<pre><code> % cd modperl-2.0
% t/REPORT > mybugreport</code></pre>
<p>where <code>modperl-2.0</code> is the source directory where mod_perl was built. The <code>t/REPORT</code> utility is autogenerated when <code>perl Makefile.PL</code> is run, so you should have it already after building mod_perl.</p>
</li>
<li><p>If you have already installed mod_perl and are having problems with things unrelated to the the test suite -- you should do:</p>
<pre><code> % mp2bug > mybugreport</code></pre>
<p><code>mp2bug</code> should have been installed at the same time mod_perl 2.0 was installed. If for some reason you can't find it, you can alternatively run the following command, which does the same:</p>
<pre><code> % perl -MApache2 -MApache::TestReportPerl \
-le 'Apache::TestReportPerl->new->run' > mybugreport</code></pre>
</li>
</ul>
<p>Please post the report (<i>mybugreport</i>) <b>inlined</b> in the text of your message, and not as an attachment!</p>
<p>Now add <a href="#Problem_Description">the problem description</a> to the report and send it to the <a>mod_perl users mailing list</a>.</p>
<h2 id="Problem-Description">Problem Description</h2>
<p>If the problem is with the mod_perl distribution test suite, refer to the <a href="#C_make_test___Failures">'make test' Failures</a> section.</p>
<p>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.</p>
<p>Also remember to include the relevant part of <i>httpd.conf</i> and of <i>startup.pl</i> if applicable. Don't include whole files, only the parts that should aid to understand and reproduce the problem.</p>
<p>Finally don't forget to copy-n-paste (not type!) the <b>relevant</b> part of the <i>error_log</i> file (not the whole file!).</p>
<p>To further increase the chances that bugs your code exposes will be investigated, try using <code><a>Apache-Test</a></code> to create a self-contained test that core developers can easily run. To get you started, an <code>Apache-Test</code> bug skeleton has been created:</p>
<p>http://perl.apache.org/~geoff/bug-reporting-skeleton-mp2.tar.gz</p>
<p>Detailed instructions are contained within the <code>README</code> file in that distribution.</p>
<p>Finally, if you get a segfault with or without a core dump, refer to the <a href="#Resolving_Segmentation_Faults">Resolving Segmentation Faults</a> section.</p>
<h2 id="make-test-Failures">'<code>make test</code>' Failures</h2>
<p>If when running <code>make test</code> some of the tests fail, please re-run them in the verbose mode and post the output of that run and the contents of the <i>t/logs/error_log</i> file to the list. Please <b>do not post</b> the <i>t/logs/error_log</i> file from <code>make test</code> that runs a complete test suite, as it contains a lot of irrelevant information.</p>
<p>For example if '<code>make test</code>' reports:</p>
<pre><code> Failed Test Stat Wstat Total Fail Failed List of Failed
------------------------------------------------------------------
compat/apache_util.t 15 1 6.67% 13
modperl/pnotes.t 5 1 20% 2</code></pre>
<p>Do the following:</p>
<pre><code> % cd modperl-2.0.xx
% make test TEST_VERBOSE=1 \
TEST_FILES="compat/apache_util.t modperl/pnotes.t"</code></pre>
<p>or use an alternative way:</p>
<pre><code> % cd modperl-2.0.xx
% t/TEST -clean
% t/TEST -verbose compat/apache_util.t modperl/pnotes.t</code></pre>
<p>In the latter approach, <code>t/TEST -clean</code> cleans things up before starting a new test. Make sure that you don't forget to run it, before running the individual tests.</p>
<p>Now post to the mailing list the output of the individual tests running and the contents of <i>t/logs/error_log</i>.</p>
<p>Also please notice that there is more than one <code>make test</code> being run. The first one is running at the top directory, the second in a sub-directory <i>ModPerl-Registry/</i>. The first logs errors to <i>t/logs/error_log</i>, the second too, but relative to <i>ModPerl-Registry/</i>. Therefore if you get failures in the second run, make sure to <code>chdir()</code> to that directory before you look at the <i>t/logs/error_log</i> file and re-run tests in the verbose mode. For example:</p>
<pre><code> % cd modperl-2.0.xx/ModPerl-Registry
% t/TEST -clean
% t/TEST -verbose closure.t</code></pre>
<p>At the moment the second test suite is not run if the first one fails.</p>
<h2 id="Resolving-Segmentation-Faults">Resolving Segmentation Faults</h2>
<p>If during <code>make test</code> or the use of mod_perl you get a segmentation fault you should send to the list a stack backtrace. <a>This section</a> explains how to get the core file and extract this backtrace. Once a proper stack backtrace is obtained append it to the bug report as explained in the previous section.</p>
<h2 id="Please-Ask-Only-Questions-Related-to-mod_perl">Please Ask Only Questions Related to mod_perl</h2>
<p>If you have general Apache questions, please refer to: http://httpd.apache.org/lists.html.</p>
<p>If you have general Perl questions, please refer to: http://lists.perl.org/.</p>
<p>For other remotely related to mod_perl questions see the references to <a>other documentation</a>.</p>
<p>Finally, if you are not familiar with the modperl list etiquette, please refer to the mod_perl mailing lists' <a>Guidelines</a> before posting.</p>
<h1 id="Help-on-Related-Topics">Help on Related Topics</h1>
<p>When developing with mod_perl, you often find yourself having questions regarding other projects and topics like Apache, Perl, SQL, etc. <a>This document</a> will help you find the right resource where you can find the answers to your questions.</p>
<h1 id="Maintainers">Maintainers</h1>
<p>Maintainer is the person(s) you should contact with updates, corrections and patches.</p>
<ul>
<li><p>Stas Bekman</p>
</li>
</ul>
<h1 id="Authors">Authors</h1>
<ul>
<li><p>Stas Bekman</p>
</li>
</ul>
<p>Only the major authors are listed above. For contributors see the Changes file.</p>
</body>
</html>
|