Changes between Version 7 and Version 8 of Debugging

Timestamp:

Mar 9, 2014, 10:22:25 PM (10 years ago)

Author:

historic_bruno

Comment:

Expands info about debug symbols

Debugging

@@ -32 +32 @@
 * [https://developer.apple.com/xcode/ Xcode] - free IDE for development on OS X, also has suite of debugging tools.
 * gdb
+* [http://lldb.llvm.org/ lldb] - part of the LLVM project, replacement for gdb in recent Xcode.
 
-== Debugging Crashes ==
+== Debugging Crashes and Assertion Failures ==
+
+A crash, generally speaking, is when the game ceases to run at some point. In some crashes, the process will stop running and can no longer be debugged (e.g. a segmentation fault on *nix), or it will enter a debug state and wait for user action. An "assertion failure" may also be referred to as a crash, and often leads to a crash if ignored, but they are simply conditions that have been programmed as necessary for the software to run correctly. As 0 A.D. is still in development, there are many possible assertion failures and crashes.
 
 You want two things to debug a crash: 1) steps to reproduce, and 2) a call stack (i.e. back trace).
@@ -47 +50 @@
 * Where there any errors or visible problems before the crash? (e.g. `interestinglog.html`)
 * What are the minimal steps to get the crash? Is it consistent?
+
+See ReportingErrors, for the recommended process of reporting crashes and errors.
 
 There are many different causes of crashes (running out of memory, heap corruption, invalid pointers or iterators, buggy drivers - to name only a few). Sometimes they are only reproducible with one OS, one type of GPU drivers, one version of a compiler, one type of CPU, or only after following a complex series of steps. Collecting the above information can point you and others in the right direction.
@@ -71 +76 @@
 
 gdb is quite powerful and has more features than can be reasonably explained here, so check the [http://sourceware.org/gdb/current/onlinedocs/gdb/ manual] or search for tutorials. One thing you might find useful is selecting the current stack frame with `frame n`, e.g. `frame 0` is the top of the stack. Then you can use `info locals` to view local variables in that stack frame. Note that in a release build, many of these will be optimized out, or the structure may be too complex for gdb to understand.
+
+=== Debug symbols ===
+
+Debug symbols relate a binary build of the game (and its libraries) to the source code used to compile the binary. Obviously, if the source code changes, the debug symbol info will also change. Debug symbols are invaluable in debugging the game, as they provide a "friendly" view of what a running process is doing or was doing. Function calls, parameters and variable contents can be inspected with the aid of debug symbols. Acquiring and setting up the matching symbols is critical to debugging crashes. This is a brief overview of where symbols come from and how to get them.
+* Debug symbols can contain a lot of data (10+ MB each is not uncommon), and most users aren't interested in debugging software, so often the symbols are omitted from release packages. This is very common with Linux packages.
+* For Windows builds, WFG manages the distribution of the game via SVN and alpha releases. Some but not all debug symbols are distributed as PDB files, which Visual Studio and !WinDbg can read. These are generated and committed by the autobuild process.
+  * Symbols for Windows libraries are distributed by Microsoft and can be acquired from their [http://support.microsoft.com/kb/311503 public symbol server].
+  * Symbols for proprietary drivers (e.g. graphics drivers) are typically ''not'' publicly distributed.
+  * If symbols are missing: this is generally the case with the game's libraries (Spidermonkey, FCollada, NVTT, etc.) if they were built by WFG. In this case, you may have no choice but to rebuild the library in question and the game, then try to reproduce the crash once debug symbols are obtained. (In the future, we should distribute the PDBs for all open source libraries, to aid debugging.)
+* For Linux builds, the package maintainers handle the distribution of the game. It is up to them to choose how or whether they will distribute the debug symbols.
+  * If symbols are missing: first check if there is a "debug" package of the module available. If not, the same advice applies as for Windows: try to build the library with debug symbols and reproduce the crash.
+
+Note: It is still possible to debug a crash without symbols, by inspecting the disassembled machine code from the binary. In other cases, it is useful to see what exactly the given source code has compiled into (to see the precise effect of optimizations, for example). However, this is a complex and difficult process, and well beyond the scope of this page.
 
 == Debugging Out of Sync and Serialization Errors ==