Getting stacktraces on crashes
==============================
The Compiler <mail@qutebrowser.org>

When there is a fatal crash in qutebrowser - most of the times a
https://en.wikipedia.org/wiki/Segmentation_fault[segfault] - the crash report
usually doesn't contain much viable information, as these crashes usually
happen inside of the Qt mainloop in C++.

To know what the issue is, a
https://en.wikipedia.org/wiki/Stack_trace[stack trace] with
https://en.wikipedia.org/wiki/Debug_symbol[debugging symbols] is required.

The rest of this guide is quite Linux specific, though there is a
<<windows,section for Windows>> at the end.

Getting debugging symbols
-------------------------

.Debian/Ubuntu/...

For Debian based systems (Debian, Ubuntu, Linux Mint, ...), debug information
is available in the repositories:

----
# apt-get install python3-pyqt5-dbg python3-pyqt5.qtwebkit-dbg python3-dbg libqt5webkit5-dbg
----

.Archlinux

For Archlinux, no debug informations are provided. You can either compile Qt
yourself (which will take a few hours even on a modern machine) or use
debugging symbols compiled/packaged by me (x86_64 only).

To compile by yourself:

----
$ git clone https://github.com/The-Compiler/qt-debug-pkgbuild.git
$ cd qt-debug-pkgbuild
$ git checkout symbols
$ export DEBUG_CFLAGS='-ggdb3 -fvar-tracking-assignments -Og'
$ export DEBUG_CXXFLAGS='-ggdb3 -fvar-tracking-assignments -Og'
$ cd qt5
$ makepkg -si --pkg qt5-base,qt5-webkit
$ cd ../pyqt5
$ makepkg -si --pkg pyqt5-common,python-pyqt5
----

To install my pre-built packages:

First download and sign the key:

----
# pacman-key -r 0xD6A1C70FE80A0C82
$ pacman-key -f 0xD6A1C70FE80A0C82
  Key fingerprint = 14AF EC28 70C6 4863 C5C7  ACCB D6A1 C70F E80A 0C82
# pacman-key --lsign-key 0xD6A1C70FE80A0C82
----

Then edit your `/etc/pacman.conf` to add the repository to the bottom:

----
[qt-debug]
Server = http://qutebrowser.org/qt-debug/$arch
----

Then install the packages:

----
# pacman -Sy pyqt5-common-debug python-pyqt5-debug qt5-base-debug qt5-webkit-debug
----

The `-debug` packages conflict with the non-debug variants - it's safe to
remove them.

Getting a core dump
-------------------

The next step is finding the core dump so we can get a stacktrace from it.

First of all, try to reproduce your problem. If you can, run qutebrowser
directly inside gdb like this:

----
$ gdb $(which python3) -ex 'run -m qutebrowser --debug'
----

If you cannot reproduce the problem, you need to check if a coredump got
written somewhere.

Check the file `/proc/sys/kernel/core_pattern` on your system. If it does not
start with a `|` character (pipe), check if there is a file named `core` or
`core.NNNN` in the directory from that file, or in the current directory.

If so, execute gdb like this:

----
$ gdb $(which python3) /path/to/core
----

If your `/proc/sys/kernel/core_pattern` contains something like
`|/usr/lib/systemd/systemd-coredump`, use `coredumpctl` as root to run gdb:

----
# coredumpctl gdb $(which python3)
----

Getting a stack trace
---------------------

Regardless of the way you used to open gdb, you should now see something like:

----
Program received signal SIGSEGV, Segmentation fault.
...
(gdb)
----

Now enter these commands at the gdb prompt:

----
(gdb) set logging on
(gdb) set logging redirect on
(gdb) bt
# you might have to press enter a few times until you get the prompt back
(gdb) set logging redirect off
(gdb) quit
----

Now copy the last few lines of the debug log (before you got the gdb prompt)
and the full content of `gdb.txt` into the bug report. Please also add some
words about what you were doing (or what pages you visited) before the crash
happened.

[[windows]]
For Windows
-----------

When you see the _qutebrowser.exe has stopped working_ window, do not click
"Close the program". Instead, open your task manager, there right-click on
`qutebrowser.exe` and select "Create dump file". Remember the path of the dump
file displayed there.

Now install
http://www.microsoft.com/en-us/download/details.aspx?id=42933[DebugDiag] from
Microsoft, then run the "DebugDiag 2 Analysis" tool. There, check
"CrashHangAnalysis" and add your crash dump via "Add Data files". Then click
"Start analysis".

Close the Internet Explorer which opens when it's done and use the
folder-button at the top left to get to the reports. There find the report file
and send it to mail@qutebrowser.org.