Change most in-tree references from SVN to GIT.
[openocd.git] / BUGS
1 // This file is part of the Doyxgen Developer Manual
2 /** @page bugs Bug Reporting
3
4 Please report bugs by subscribing to the OpenOCD mailing list and
5 posting a message with your report:
6
7         openocd-development@lists.berlios.de
8
9 To minimize work for OpenOCD developers, you should try to include
10 all of the information listed below.  If you feel that some of the
11 items below are unnecessary for a clear bug report, you may leave
12 them out; likewise, feel free to include additional information
13 that may be important.
14
15 - Target PCB/board description
16 - Configuration scripts
17 - OpenOCD command line
18 - List of commands issued or GDB operations performed
19 - Expected result
20 - Actual result
21 - Logs using <code>debug_level 3</code> (or with '-d 3' on the command line)
22 - If the report is for a regression:
23   - Include logs for both working and broken versions.
24   - Find the precise version that caused the regression by binary search.
25     You can use "git bisect" to expedite this binary search.
26
27 If possible, please develop and attach a patch that helps to expose or
28 solve the reported problem.  See the PATCHES file for more information
29 for that process.
30
31 Attach all files directly to your posting.  The mailing list knows to
32 transform attachments to links, but attachments must be less than 300KB
33 in total.
34
35 @section bugscrashdump Obtaining Crash Backtraces
36
37 If OpenOCD is crashing, there are two very effective things you can do to
38 improve your chances of getting help on the development mailing list. 
39
40 Try to reproduce the problem using the dummy JTAG interface to allow other developers to replicate
41 your problem robustly and use GDB to get a trace:@par
42 @code
43 % OPENOCDSRC/configure --enable-dummy ...
44 % openocd -f interface/dummy.cfg -f target/xxx.cfg
45 => SEGFAULT
46 % gdb --args openocd ....
47 (gdb) run
48 (gdb) bt
49 => here a stack trace is dumped.
50 @endcode
51
52 @section bugsintreedebug Running and Debugging In-Tree
53
54 To run or debug the in-tree executable (not recommended), you must
55 use libtool to set up the correct shared library paths:
56 @code
57   libtool gdb --args openocd ....
58 @endcode
59 or the more pedantic (and forward-compatible):
60 @code
61   libtool --mode=execute gdb --args openocd ....
62 @endcode
63
64  */
65 /** @file
66 This file contains the @ref bugs page.
67 */