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 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 log files, and they are the first data source when investigating a problem.

See here for details about log file setup and usage.

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 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").