--- a/website/devel.html
+++ b/website/devel.html
@@ -34,7 +34,7 @@
please send me an <a
href="mailto:jean-francois.dockes@wanadoo.fr">email</a>.</p>
- <h1>Translation</h1>
+ <h1><a name="translation">Translation</a></h1>
<p>More translations is good ! If you are a non-english speaker
(and understand english, which can probably be assumed, you
@@ -55,7 +55,7 @@
<li>Ukrainian: <a href="translations/recoll_uk.ts">recoll_uk.ts</a></li>
</ul>
- <h1>Development</h1>
+ <h1><a name="development">Development</a></h1>
<p>Apart from general development for additional functionality
or bug fixes, the following tasks are waiting for you:</p>
@@ -79,6 +79,100 @@
<li>Etc. :)</li>
</ul>
+ <h1><a name="problemreport">Problem reporting</a></h1>
+
+ <p>Once in a while it will happen that a Recoll program will
+ crash (either the "recoll" graphical interface or the
+ "recollindex" command line indexing command).</p>
+
+ <p>Reporting crashes is very useful. It can help others, and it
+ can get your own problem to be solved.</p>
+
+ <p>All reports are useful. But, in order to maximize usefulness,
+ a crash report should include a so-called stack trace, something
+ that indicates what the program was doing when it
+ crashed. Getting a useful stack trace is not very difficult,
+ but it may need a little work on your part (which
+ will then enable me do my part of the work).</p>
+
+ <p>If your distribution includes a separate package for Recoll
+ debugging symbols, it probably also has a page on its web site
+ explaining how to use them to get a stack trace. You should
+ follow these instructions. If there is no debugging package,
+ you should follow the instructions below. A little
+ familiarity with the command line will be necessary.</p>
+
+ <dl><dt>Compiling and installing a debugging version</dt>
+ <dd>
+ <ul>
+ <li>Obtain the recoll source for the version you are using
+ (<a
+ href="http://www.recoll.org/download.html">www.recoll.org</a>),
+ and extract the source tree.</li>
+
+ <li>Follow the instructions for
+ <a
+ href="http://www.lesbonscomptes.com/recoll/usermanual/index.html#RCL.INSTALL.BUILDING">
+ building Recoll from source</a> with the following
+ modifications:
+ <ul>
+ <li>Before running <tt>configure</tt>, edit
+ the <tt>mk/localdefs.in</tt> file and remove the <tt>-O2</tt>
+ option(s). </li>
+ <li>When running <tt>configure</tt>, specify the
+ standard installation location for your system as a prefix
+ (to avoid ending up with two installed versions, which
+ would almost certainly end in confusion). On Linux this
+ would typically be:
+ <br><tt>configure --prefix=/usr</tt>.
+ </li> <li>When installing, arrange for the installed
+ executables not to be stripped of debugging symbols by
+ specifying a value for the STRIP environment variable
+ (ie: <tt>echo</tt> or <tt>ls</tt>): <br><tt>sudo make
+ install STRIP=ls</tt>
+ </li>
+ </ul>
+ </ul></dd>
+
+ <dt>Getting a core dump</dt>
+ <dd>You will need to run the operation that caused the crash
+ inside a writable directory, and tell the system that you
+ accept core dumps. The commands need to be run in a shell
+ inside a terminal window. Ie:
+ <pre><tt>
+cd
+ulimit -c unlimited
+recoll #(or recollindex or whatever you want to run).
+ </tt></pre>
+
+ Hopefully, you will succeed in getting the command to crash,
+ and you will get a core file.
+ </dd>
+
+ <dt>Using gdb to get a stack trace</dt>
+ <dd>
+ <ul>
+ <li>Install <tt>gdb</tt> if it is not already on the system.</li>
+
+ <li>Run <tt>gdb</tt> on the command that crashed and the
+ core file (depending on the system, the core file may be
+ named "core" or something else, like recollindex.core, or
+ core.pid), ie:
+
+ <br><tt>gdb /usr/bin/recollindex core</tt>
+ </li>
+ <li>Inside <tt>gdb</tt>, you need to use different
+ commands to get a stack trace for <tt>recoll</tt>
+ and <tt>recollindex</tt>. For <tt>recollindex</tt> you
+ can use the <tt>bt</tt> command. For <tt>recoll</tt>
+ use: <br><tt>thread apply all bt full</tt>
+ </li>
+ <li>Copy/paste the output to your report email :), and
+ quit <tt>gdb</tt> ("q").</li>
+ </ul>
+ </dd>
+ </dl>
+
</div>
</body>
</html>