== Gathering useful data for asking help about or reporting a Recoll issue
Once in a while it will happen that a Recoll program will either signal an
error, or even crash (either the *recoll* graphical interface or the
*recollindex* command line indexing command).
Reporting errors and crashes is very useful. It can help others, and it can
get your own problem solved.
Any problem report should include the exact Recoll and system versions.
If at all possible, reading the following and performing part of the
suggested steps will be useful. This is not a condition for obtaining help
though ! If you have any problem and have a difficulty with the following,
just contact the mailing list or the developers (see contacts on
link:https://www.recoll.org/support.html[the Recoll site support page]).
If the problem concerns indexing, and was initially found using the
*recoll* GUI, you should try to reproduce it using the
*recollindex* command-line indexer, which is much simpler and easier to
debug.
There are then two sources of useful information to diagnose the issue: the
debug log file and, possibly, in case of a crash, a stack trace.
Crash and other problem reports are of very high value to me, and I am
willing to help you with any of the steps described below if it is not
familiar to you. I do realize that not everybody is a programmer or a
system administrator.
=== Obtaining information from the log file
All Recoll commands write a varying amount of information to a common log file.
_All commands use the same log, and the file is reset every time a command
is started: so it is important to make a copy right after the problem
occurs (for example, do not start *recoll* after a *recollindex*
crash, this would reset the log). A workaround for this issue is to let the
messages go to the default +stderr+, and redirect this._
By default, the messages are output to +stderr+, and you probably don't even
see them if Recoll is started from the desktop. In this case, you need to
set the parameters so that output goes to a file, and the appropriate
verbosity level is set. When using the command-line, you may actually
prefer to redirect stderr to avoid the log-truncating issue described
above.
You can set the log parameters from the GUI _Indexing parameters_
section or by editing the '~/.recoll/recoll.conf' file: set the
+loglevel+ and +logfilename+ parameters. E.g.:
----
loglevel = 6
logfilename = /tmp/recolltrace
----
The log file can become very big if you need a big indexing run to
reproduce the problem. Choose a file system with enough space available
(possibly a few gigabytes).
Then run the sequence that leads to the problem, and make a copy of the log
file just after. If the log is too big, it will usually be sufficient to
use the last 500 lines or so (tail -500).
==== Single file indexing issues
When the problem concerns, or can be reproduced with, a single file it is
very cumbersome to have to run a full indexing pass to reproduce it. There
are two ways around this:
- Set up an ad hoc configuration with only the file of interest, or its
parent directory:
----
cd
mkdir recoll-test
cd recoll-test
echo /path/to/my/file/or/its/parent/dir > recoll.conf
echo 'loglevel = 6' >> recoll.conf
echo 'logfilename = /tmp/recolltrace' >> recoll.conf
recollindex -z -c .
----
- Use the -e and -i options to recollindex to erase/reindex a single
file. Set up the log, then:
----
recollindex -e /path/to/my/file
recollindex -i /path/to/my/file
----
When using the second approach, you must take care that the path used is
consistent with the paths listed/used in the configuration (ie: if '/home' is
a link to '/usr/home', and '/usr/home/me' is used in the configuration
+topdirs+, `recollindex -i /home/me/myfile` will not work, you need
to use `recollindex -i /usr/home/me/myfile`.
=== Obtaining a stack trace
If the program actually crashes, and in order to maximize usefulness, a
crash report should also 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).
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.
==== Compiling and installing a debugging version
- Obtain the recoll source for the version you are using (www.recoll.org),
and extract the source tree.
- Follow the
link:http://www.lesbonscomptes.com/recoll/usermanual/rcl.install.building.html[instructions
for building Recoll from source] with the following modifications:
- Before running configure, edit the mk/localdefs.in file and remove the
-O2 option(s).
- When running configure, 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: `configure --prefix=/usr`
- When installing, arrange for the installed executables not to be stripped
of debugging symbols by specifying a value for the STRIP environment
variable (ie: *echo* or *ls*): `sudo make install STRIP=ls`
==== Getting a core dump
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. E.g.:
----
cd
ulimit -c unlimited
recoll #(or recollindex or whatever you want to run).
----
Hopefuly, you will succeed in getting the command to crash, and you will
get a core file. A possible approach then would be to make both the
executable and the core files available to me by uploading it to a file
sharing site (the core file may be quite big). You should be aware though
that the core file may contain some of the data that was being indexed,
which may be a privacy issue. Another approach is to generate the stack
trace yourself.
=== Using gdb to get a stack trace
- Install gdb if it is not already on the system.
- Run gdb 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: {{{gdb /usr/bin/recollindex core}}}
- Inside gdb, you need to use different commands to get a stack trace for
recoll and recollindex. For recollindex you can use the bt command. For
recoll use `thread apply all bt full`
- Copy/paste the output to your report email :), and quit gdb ("q").