Difference between revisions of "Step-by-step debugging guide"

From ArchWiki
Jump to: navigation, search
(Added part about running gdb with a core file)
(style adaptations)
Line 1: Line 1:
= When an application fails =
+
[[Category:Arch development (English)]]
 +
{{i18n|Step By Step Debugging Guide}}
  
== Run it from the commandline ==
+
== When an application fails ==
 +
 
 +
=== Run it from the commandline ===
  
 
If an application suddenly crashes, try running it from the commandline. If you're new to the commandline and use GNOME, press Alt+F2 and type "gnome-terminal", then type in the name of the application in lowercase letters. If you don't know the name of the executable, only the name of the package, the following command can be useful to find the name of the executable. Replace "packagename" with the name of the package:
 
If an application suddenly crashes, try running it from the commandline. If you're new to the commandline and use GNOME, press Alt+F2 and type "gnome-terminal", then type in the name of the application in lowercase letters. If you don't know the name of the executable, only the name of the package, the following command can be useful to find the name of the executable. Replace "packagename" with the name of the package:
Line 7: Line 10:
 
  for f in `pacman -Ql packagename | grep "/bin/" | cut -d" " -f2`; do file $f 2>/dev/null | grep -q executable && basename $f; done
 
  for f in `pacman -Ql packagename | grep "/bin/" | cut -d" " -f2`; do file $f 2>/dev/null | grep -q executable && basename $f; done
  
== Check if the application segfaults ==
+
=== Check if the application segfaults ===
  
 
If you see the word "segfault" or the phrase "segmentation fault", see if there is a file named "core" as well.
 
If you see the word "segfault" or the phrase "segmentation fault", see if there is a file named "core" as well.
Line 15: Line 18:
 
If there is, the application has segfaulted. The "core" file can, if the application is compiled in a debug-friendly way, be used to find out where things went wrong. Sometimes the core file ends up in one of the directories the application has visited instead of the current directory.
 
If there is, the application has segfaulted. The "core" file can, if the application is compiled in a debug-friendly way, be used to find out where things went wrong. Sometimes the core file ends up in one of the directories the application has visited instead of the current directory.
  
= How to investigate a segfault =
+
== How to investigate a segfault ==
  
 
There are a couple of techniques that can be used to figure out what went wrong. Put your detective hat on. 🔎
 
There are a couple of techniques that can be used to figure out what went wrong. Put your detective hat on. 🔎
Line 39: Line 42:
 
  bt full
 
  bt full
  
= How to investigate missing files or libraries =
+
== How to investigate missing files or libraries ==
  
 
=== Technique #1 - strace ===
 
=== Technique #1 - strace ===
Line 63: Line 66:
 
  man ld-linux
 
  man ld-linux
  
= If it's not written in C or C++, but perhaps in Python =
+
== If it's not written in C or C++, but perhaps in Python ==
  
 
Use "file" on the executable to get more information (replace "appname" with your executable):
 
Use "file" on the executable to get more information (replace "appname" with your executable):
Line 75: Line 78:
 
For Python applications, the output will often say which file and line number the crash occured at. If you're proficient with Python, you can try to fix this and include the fix in the bug report.
 
For Python applications, the output will often say which file and line number the crash occured at. If you're proficient with Python, you can try to fix this and include the fix in the bug report.
  
= Finally - report the bug =
+
== Finally - report the bug ==
  
 
Please report a bug at https://bugs.archlinux.org and possibly also directly to the developers of the application in question, then include a link in the Arch Linux bug report. This helps us all.
 
Please report a bug at https://bugs.archlinux.org and possibly also directly to the developers of the application in question, then include a link in the Arch Linux bug report. This helps us all.
  
= See also =
+
== See also ==
 
+
[[Reporting Bug Guidelines]] for detailed information about how to report bugs in a useful way.
+
  
[[Debug - Getting Traces]] for more information about collecting debug information and stack traces.
+
*[[Reporting Bug Guidelines]] for detailed information about how to report bugs in a useful way.
 +
*[[Debug - Getting Traces]] for more information about collecting debug information and stack traces.

Revision as of 10:42, 6 January 2012

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.


Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어


External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

When an application fails

Run it from the commandline

If an application suddenly crashes, try running it from the commandline. If you're new to the commandline and use GNOME, press Alt+F2 and type "gnome-terminal", then type in the name of the application in lowercase letters. If you don't know the name of the executable, only the name of the package, the following command can be useful to find the name of the executable. Replace "packagename" with the name of the package:

for f in `pacman -Ql packagename | grep "/bin/" | cut -d" " -f2`; do file $f 2>/dev/null | grep -q executable && basename $f; done

Check if the application segfaults

If you see the word "segfault" or the phrase "segmentation fault", see if there is a file named "core" as well.

ls core

If there is, the application has segfaulted. The "core" file can, if the application is compiled in a debug-friendly way, be used to find out where things went wrong. Sometimes the core file ends up in one of the directories the application has visited instead of the current directory.

How to investigate a segfault

There are a couple of techniques that can be used to figure out what went wrong. Put your detective hat on. 🔎

Technique #1 - gdb

gdb is an ancient and well tested application for debugging applications. Try running the application (replace "appname" with the name of your executable) with gdb:

gdb appname
r
(wait for segfault)
bt full

Now post the output to one of the many pastebin sites on the web and include the URL when you file a bugreport at https://bugs.archlinux.org/.

Technique #2 - even better gdb output

If you're able to, recompile the application in question with the -g and -O1 flags, make sure "!strip" is in the options array in the PKGBUILD, install and try running it again with gdb, like above.

If you have a corefile, that can be used to get a backtrace:

gdb appname core
bt full

How to investigate missing files or libraries

Technique #1 - strace

Strace is great for finding out, in detail, what an application is actually doing. If an application tries to open a file that just isn't there, it can be discovered by strace.

For finding which files a program named "appname" tries to open:

strace -o /dev/stdout appname | grep open

Again, save the output, post it to a pastebin site and keep the URL in handy.

Technique #2 - LD_DEBUG

Setting LD_DEBUG to "files" is another way to get an overview of which files an application are looking for. For an application named "appname":

LD_DEBUG=files appname > appname.log 2>&1

The output will end up in appname.log.

For more information about this:

man ld-linux

If it's not written in C or C++, but perhaps in Python

Use "file" on the executable to get more information (replace "appname" with your executable):

file /usr/bin/appname

If it says "ELF" it's a binary exectuable and is usually written in C or C++. If it says "Python script" you know you're dealing with an application written in Python.

If it's a shell script, open up the shell script in a text editor and see (usually at the bottom of the file) if you can find the name of the real application (ELF file). You can then temporarily put "gdb" right in the shellscript, before the name of the executable, for debugging purposes. See the sections about gdb further up.

For Python applications, the output will often say which file and line number the crash occured at. If you're proficient with Python, you can try to fix this and include the fix in the bug report.

Finally - report the bug

Please report a bug at https://bugs.archlinux.org and possibly also directly to the developers of the application in question, then include a link in the Arch Linux bug report. This helps us all.

See also