158 lines
6.6 KiB
Plaintext
158 lines
6.6 KiB
Plaintext
== 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").
|
|
|