From af53a670ee423ac875fd40941e1bd817b90d4288 Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Tue, 3 Feb 2015 20:45:44 +0100 Subject: [PATCH] Reorder stacktrace.asciidoc --- doc/stacktrace.asciidoc | 115 +++++++++++++++++++++++++--------------- 1 file changed, 71 insertions(+), 44 deletions(-) diff --git a/doc/stacktrace.asciidoc b/doc/stacktrace.asciidoc index 9018f7245..920a4c55d 100644 --- a/doc/stacktrace.asciidoc +++ b/doc/stacktrace.asciidoc @@ -1,5 +1,6 @@ Getting stacktraces on crashes ============================== +:toc: The Compiler When there is a fatal crash in qutebrowser - most of the times a @@ -14,10 +15,17 @@ https://en.wikipedia.org/wiki/Debug_symbol[debugging symbols] is required. The rest of this guide is quite Linux specific, though there is a <> at the end. -Getting debugging symbols -------------------------- +Crashes which can be reproduced +------------------------------- -.Debian/Ubuntu/... +If a crash can be reproduced, packages with debugging symbols should be +installed, and the crash should be reproduced under gdb. + +Getting debugging symbols +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Debian/Ubuntu/... +^^^^^^^^^^^^^^^^^ For Debian based systems (Debian, Ubuntu, Linux Mint, ...), debug information is available in the repositories: @@ -26,13 +34,14 @@ is available in the repositories: # apt-get install python3-pyqt5-dbg python3-pyqt5.qtwebkit-dbg python3-dbg libqt5webkit5-dbg ---- -.Archlinux +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: +.To compile by yourself ---- $ git clone https://github.com/The-Compiler/qt-debug-pkgbuild.git @@ -46,7 +55,7 @@ $ cd ../pyqt5 $ makepkg -si --pkg pyqt5-common,python-pyqt5 ---- -To install my pre-built packages: +.To install my pre-built packages First download and sign the key: @@ -73,42 +82,18 @@ Then install the packages: The `-debug` packages conflict with the non-debug variants - it's safe to remove them. -Getting a core dump -------------------- +Getting the stack trace +~~~~~~~~~~~~~~~~~~~~~~~ -The next step is finding the core dump so we can get a stacktrace from it. +First install `gdb` on your system if it's not installed already. -First of all, try to reproduce your problem. If you can, run qutebrowser -directly inside gdb like this: +Then 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: +After you reproduce the crash, you should now see something like: ---- Program received signal SIGSEGV, Segmentation fault. @@ -120,16 +105,58 @@ Now enter these commands at the gdb prompt: ---- (gdb) set logging on -(gdb) set logging redirect on -(gdb) bt +(gdb) bt full # 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 +This will create a `gdb.txt` in your current directory. + +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. + +Crashes which can NOT be reproduced +----------------------------------- + +If you cannot reproduce the problem, you need to check if a coredump got +written somewhere. You should not install debug symbols as they won't match the +generated coredump. + +First install `gdb` on your system if it's not installed already. + +Then 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` to run gdb: + +---- +$ coredumpctl gdb $(which python3) +---- + +Getting the stack trace +~~~~~~~~~~~~~~~~~~~~~~~ + +Now enter these commands at the gdb prompt: + +---- +(gdb) set logging on +(gdb) bt +# you might have to press enter a few times until you get the prompt back +(gdb) quit +---- + +Copy the 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]] @@ -143,9 +170,9 @@ 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". +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