Add Asterisk Git HowTo documentation.
[asterisk/asterisk.git] / doc / valgrind.txt
1 If you're having certain types of crashes, such as those associated with
2 memory corruption, a bug marshal may ask you to run Asterisk under valgrind.
3 You should follow these steps, to give the bug marshal the maximum amount
4 of information about the crash.
5
6 1.  Run 'make menuselect' and in the Compiler Options, enable MALLOC_DEBUG
7         and DONT_OPTIMIZE.  A bug marshal may also ask you to enable additional
8         compiler flags, such as DEBUG_THREADS, depending upon the nature of the
9         issue.
10
11 2.  Rebuild and install Asterisk.
12
13 3.  Run Asterisk as follows:
14         valgrind --log-file-exactly=valgrind.txt asterisk -vvvvcg 2>malloc_debug.txt
15
16         UPDATE:  The newest version of valgrind has eliminated the
17         --log-file-exactly option.  If you are running valgrind 3.3.0 or higher,
18         just use the --log-file option, keeping in mind that Valgrind will append
19         a trailing suffix onto valgrind.txt.
20
21 4.  Reproduce the issue.  Following the manifestation of the issue (or when
22         the process crashes), upload the two files, valgrind.txt and
23         malloc_debug.txt to the issue tracker.  If you are using the --log-file
24         option, note that valgrind.txt will have a trailing suffix.  That's fine,
25         just upload that file.
26
27 Please note that even if valgrind prevents Asterisk from crashing, the
28 information logged may STILL be of use to developers, so please upload the
29 resulting log file whether Asterisk crashes or not.
30