Dr. Memory
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Preparing Your Application

First we give cross-plaform guidelines for how to build your application, before giving specific compiler parameters for each platform.

For All Platforms

These cross-platform steps apply to Linux, Mac, and Windows.

32-bit

Currently, Dr. Memory does not yet support uninitialized read detection for 64-bit applications, so we recommend compiling your target application as 32-bit.

Debug Information

In order to obtain line number information, compile your target application with debugging information enabled. On Linux, Dr. Memory supports ELF files with DWARF2 line information. On Mac, Dr. Memory supports Mach-O files with DWARF2 line information. On Windows, Dr. Memory supports PDB debug information (produced by Visual Studio) as well as PECOFF files with DWARF2 line information (produced by MinGW gcc).

Callstack Quality

You'll get better callstacks in error reports if you disable inlining. Dr. Memory should be able to determine callstacks in the presence of frame pointer optimizations (FPO) in most cases, but if you see strange callstacks in an optimized application consider disabling FPO.

If your application links with a static library that was built with frame pointer optimizations and you observe missing frames on your callstacks, try running with the Dr. Memory runtime options -no_callstack_use_top_fp, -no_callstack_use_fp, and -callstack_conservative. These will add some additional overhead on malloc-intensive applications, but should eliminate skipped frames.

Linux

For uninitialized read detection, ensure your Linux installation is able to build 32-bit applications. On 64-bit Ubuntu you will want these packages:

sudo apt-get install g++-multilib

On Ubuntu older than 13.04, the ia32-libs package should also be installed. On 13.04 and higher, 32-bit libraries must be chosen individually, but normally they are installed by default in most distributions.

Dr. Memory currently only supports DWARF2 line information, not stabs. DWARF2 is the default for modern versions of gcc.

Here is a sample command line for compiling your application that combines all of the above recommendations:

g++ -m32 -g -fno-inline -fno-omit-frame-pointer myfile1.cpp myfile2.cpp -o myapp

Mac

Ensure your compiler is able to build 32-bit applications.

Dr. Memory currently only supports DWARF2 line information, not stabs. DWARF2 is the default for modern versions of gcc as well as clang.

Here is a sample command line for compiling your application that combines all of the above recommendations:

c++ -m32 -g -fno-inline -fno-omit-frame-pointer myfile1.cpp myfile2.cpp -o myapp

Windows Visual Studio

Visual Studio builds 32-bit applications by default, so no action is required on that front.

To include debug information, use the /Zi flag to the Visual Studio compiler. From the IDE, Press Alt-F7 to bring up the configuration properties of your build target. 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)". For Visual Studio 2015, under "Configuration Properties | Linker | Debugging", the "Generate Debug Info" entry should say "Optimize for debugging (/DEBUG)" – it should not say "Optimize for faster linking (/DEBUG:FASTLINK)".

To disable inlining as recommended above, use the /Ob0 parameter. In the Visual Studio IDE, press Alt-F7 and then under "Configuration Properties | C/C++ | Optimization" ensure "Inline Function Expansion" says "Disabled (/Ob0)".

To disable frame pointer optimization as recommended above, use the Oy- parameter. In the Visual Studio IDE, press Alt-F7 and then under "Configuration Properties | C/C++ | Optimization" ensure "Omit Frame Pointers" says "No (/Oy-)".

C Library Interactions

All combinations of the debug or release C library, linked statically or dynamically, are supported. When using static versions of msvcrt (the /MTd or /MT flags), if your application does not have symbols then Dr. Memory will not be able to identify memory allocation calls, which may lead to false positives and/or false negatives. Be sure to build with debugging information included using the instructions above.

The debug C library (specified with the /MDd or /MTd flags) contains its own redzone and heap error checks. Dr. Memory completely replaces these checks with its own, more complete checks.

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 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".

Parameter Summary

Here is a sample command line for Visual Studio:

cl /Zi /MT /EHsc /Oy- /Ob0 /Femyapp.exe *.cpp

Windows MinGW

Dr. Memory supports applications compiled with the MinGW gcc or g++ compilers, but will only provide line number information if DWARF2 debugging information is present. The default for MinGW gcc prior to version 4.3 is to use the stabs format, which is not supported by Dr. Memory. Pass the -ggdb option to gcc to generate DWARF2 format instead.

You install the MinGW compiler in a Cygwin installation by running the Cygwin installer (setup.exe), searching for "mingw", opening Devel, and installing mingw-gcc-g++. Alternatively, MinGW can be installed on its own.

For MinGW C++ applications, we recommending building with static libstdc++ libraries. Pass -static-libgcc -static-libstdc++ to g++ to request this. These static libraries contain frame pointer optimizations but Dr. Memory automatically enables the -no_callstack_use_top_fp runtime option for MinGW applications.

Here is a sample command line for MinGW:

i686-pc-mingw32-g++.exe -static-libgcc -static-libstdc++ -ggdb -o myapp.exe myfile1.cpp myfile2.cpp

Windows Cygwin: Not Supported

Currently there is no support for applications built with Cygwin gcc or g++.

The regular Dr. Memory build can be executed just fine from a Cygwin shell when targeting non-Cygwin applications.

Android

Build your application using the Android NDK and copy it over to your device. Be sure to compile with debugging information included and to disable FPO, as described in For All Platforms.

While Java applications are not yet officially supported, we welcome contributions to help work toward full Android Java support. To launch an Android Java application under Dr. Memory, use a wrapper script and point at the script via the logwrapper property set on your application's name prefixed by wrap.. For example, if your application's name is com.myco.appname, set the property for wrap.com.myco.appname, truncating to 31 characters:

setprop wrap.com.myco.appname "logwrapper /system/xbin/wrap.sh"

The wrapper shell script should contain the command line prefix you wish to use to launch your application under Dr. Memory. It should also set TMPDIR to point to the directory for your application, which is a location where SElinux allows writing:

#!/system/bin/sh
export TMPDIR=/data/data/com.myco.appname
exec /system/xbin/drmemory/bin/drmemory -- $@

See also the information on SElinux and writable directories under Installing on Android. Be sure to place the Dr. Memory binaries and the wrapper script in an executable location, such as /system/xbin. Alternatively, disable SELinux via setenforce 0.