Memory Debugging

Segmentation faults and other memory bugs (reading uninitialized memory, reading/writing beyond the bounds of an array, memory leaks, etc.) can be hard to track down with a traditional debugger. Memory errors can be elusive, and may not cause the program to crash immediately. A program with memory errors may even appear to work correctly on some datasets or on some machines.

We recommend using a special debugger to find memory errors, for example Valgrind or Dr. Memory. Commercial versions of these tools include Purify and Insure++.

Valgrind

Valgrind only works on Unix-based systems (e.g., GNU/Linux, FreeBSD, and MacOSX). Valgrind does not work on Cygwin because Cygwin emulates UNIX at the library layer, but Valgrind operates at the system call layer and the Windows system calls are significantly different than UNIX system calls.

To use Valgrind...

Valgrind is installed by default on most Linux distributions. For MacOSX you'll need to install it yourself -- you may want to try brew.
Your program should be compiled with debug information enabled by specifying the -g flag. For example:
```
  g++ -g main.cpp foo.cpp -o foo.out 
```
Then run the program by adding Valgrind to the beginning of your command line (replace foo.out arg1 arg2 with your program name and arguments):
```
  valgrind --leak-check=full --show-reachable=yes foo.out arg1 arg2
```
If that example run of your program contains any memory errors Valgrind will output information to help you track down the error. Note that using Valgrind can significantly slow down execution time as it inspects every memory action. You may need to craft a smaller test case that exhibits the same bug you would like to solve.

Note: Because the STL string class uses its own allocator, there may be a warning about memory that is ``still reachable'' even though you've deleted all your dynamically allocated memory. The newer versions of Valgrind automatically suppresses this specific error, so you may see this listed as a ``suppressed leak''.

Suppression of False Positives in Valgrind

If you see false positive error messages in Valgrind (this is likely to happen with Valgrind on the newest MacOSX 10.8.X), you will probably want to create an error suppression file to allow you to focus on your actual errors.

Add the --gen-suppressions=all option to the valgrind command line:

  valgrind --leak-check=full --gen-suppressions=all foo.out arg1 arg2

For each false positive (an error not obviously pointing at your code), copy-paste the suppression text (a block of text in curly braces) into a new file containing your custom suppressions, let's call it my_suppressions.txt.

Use that suppression file every time you run Valgrind:

  valgrind --leak-check=full --suppressions=my_suppressions.txt foo.out arg1 arg2

You may need to add to that file in the future, when you use additional library functions that cause false positive errors.

Read more about Valgrind suppressions here:
http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress

Dr. Memory

Dr. Memory detects the same classes of errors as Valgrind and can be used on GNU/Linux and Microsoft Windows operating systems. For questions, bug reports, and discussion, use the Dr. Memory Users group: http://groups.google.com/group/drmemory-users

Dr. Memory on GNU/Linux

Obtain Dr. Memory for Linux from http://code.google.com/p/drmemory/downloads/list
Untar the package to a directory of your choice. We'll assume ~/DrMemory-Linux-1.6.0-2/ for the rest of these instructions.
Ensure your Linux installation is able to build 32-bit applications. On 64-bit Ubuntu you will want these packages:
```
  sudo apt-get install ia32-libs g++-multilib
```
Build your application as 32-bit by passing -m32 to g++ (Dr. Memory does not yet support 64-bit). Be sure to include debug information by passing -g to g++. For example:
```
  g++ -g -m32 main.cpp foo.cpp -o foo.out
```
Run this command, replacing foo.out arg1 arg2 with your executable name and any command line arguments:
```
  ~/DrMemory-Linux-1.6.0-2/bin/drmemory.pl -brief -- foo.out arg1 arg2
```
Dr. Memory will report errors to the screen as it runs. It will print a summary at the end of what it found.

Installing Dr. Memory on Windows

Obtain Dr. Memory. To easily place it on the system path, use the installer (the .exe file). Alternately, you can instead obtain the .zip file for a local install.
http://code.google.com/p/drmemory/downloads/list
Run the installer. Select ``Add to system path for current user''.
Follow the instructions below to compile & run your program using MinGW g++, the Visual Studio IDE, or the Visual Studio Command Prompt.

Dr. Memory and MinGW

You can't use the Cygwin version of g++ with Dr. Memory, but you can run Dr. Memory on Windows using the MinGW compiler (Minimalist GNU for Windows):

Install Cygwin
Run the Cygwin installer (setup-x86.exe), search for "mingw", open Devel, and install "mingw-gcc-g++"
Open a Cygwin terminal, navigate to the directory with your files, and compile your program with the mingw compiler by typing:
```
  i686-pc-mingw32-g++.exe -static-libgcc -static-libstdc++ -ggdb -o foo.exe main.cpp foo.cpp
```
You can run your program under Dr Memory by typing;
```
  drmemory -brief -batch -- foo.exe arg1 arg2
```

Dr. Memory and Visual Studio

Alternatively, you can use Dr. Memory with the Microsoft Visual Studio compiler:

Build your application as 32-bit with Visual Studio (32-bit is the default). Be sure to include debug information. You can verify that you are including debug information by looking at the properties of your build target:

Press Alt-F7 to bring up the configuration properties. Under "Configuration Properties | C/C++ | General", the "Debug Information Format" entry should either say "Program Database (/Zi)" or "Program Database for Edit and Continue (/ZI)". Additionally, under "Configuration Properties | Linker | Debugging", the "Generate Debug Info" entry should say "Yes (/DEBUG)".
Disable Runtime Checks: The Visual Studio compiler's /RTC1 flag can prevent Dr. Memory from reporting uninitialized reads of local variables, and the /RTC1 checks for uninitialized reads themselves may not catch everything that Dr. Memory finds. However, /RTC1 does perform additional stack checks that Dr. Memory does not, so for best results, your application should be run under Dr. Memory without /RTC1, and run natively (for development & testing without Dr. Memory) with /RTC1.

In the Visual Studio IDE, press Alt-F7 and then under "Configuration Properties | C/C++ | Code Generation" ensure "Basic Runtime Checks" says "Default".
To run Dr. Memory within the IDE you will need to set up Dr. Memory as a Visual Studio "External Tool", which adds it as a new menu item.

If using Visual Studio Express 2010 or later, first enable the full menu system by selecting "Tools | Settings | Expert Settings" (this step is not necessary for Visual Studio Professional).
Select the "Tools | External Tools..." menu option to open the External Tools dialog box. Click Add and fill in the fields as follows (adjusting the path to drmemory.exe if you installed it somewhere else):
```
  Title: Dr. Memory
  Command: C:\Program Files (x86)\Dr. Memory\bin\drmemory.exe
  Arguments: -visual_studio -- $(TargetPath)
  Initial Directory: $(TargetDir)
```
Check both the "Use Output window" and "Prompt for arguments" checkboxes. Then click OK.
Now you can select the "Tools | Dr. Memory" menu item and Visual Studio will run your application under Dr. Memory. You can add arguments to your application in the box that pops up immediately after selecting the men item by adding them at the end, after "$(TargetPath)".
The output of Dr. Memory (along with your program) will be printed to the Visual Studio Output Window. Dr. Memory will report errors to the screen as it runs. It will print a summary at the end of what it found. You can double-click on a source file on any error's callstack frame in order to automatically open up that file to the line number indicated.

Using the Visual Studio compiler without the Visual Studio Integrated Development Environment (IDE)

Launch the Visual Studio Command Prompt. From the Start menu, under All Programs, find your Visual Studio version (e.g., 2010) and expand it. Then expand Visual Studio Tools. Select the "Visual Studio 2010 Command Prompt". (You don't want the x64 or Cross Tools versions.) Note: this is not the Cygwin shell.

This Command Prompt is a cmd shell in which a batch file that comes with Visual Studio has been executed. This batch file is called vcvars.bat and it sets up the path and environment variables needed to run the compiler from the command line.

Note: You can extract the environment variables from the batch file and set them up in your .bashrc so you can build from a Cygwin shell.
At the command line, change to the directory containing your source files.
Run the compiler, which is called "cl". This will build hw.exe from all .cpp files in the current directory:
```
cl /Zi /MT /EHsc /Oy- /Ob0 /Fehw.exe *.cpp
```
If you installed Dr. Memory before you opened the Command Prompt, you can run drmemory from the same prompt. Run this command, replacing foo.exe arg1 arg2 with your executable name and any command line arguments:
```
  drmemory -brief -batch -- foo.exe arg1 arg2
```
If you don't see any extra output from Dr. Memory as your program runs, remove the -batch flag and the Dr. Memory output will be sent to a file and notepad will launch automatically to display this file.
```
  drmemory -brief -- foo.exe arg1 arg2
```
Dr. Memory will print a summary at the end of what errors it found.