--- a
+++ b/website/faqsandhowtos/ProblemSolvingData.txt
@@ -0,0 +1,157 @@
+== 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").
+