development/Win32/vld/README.html

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
   4
   5 <head>
   6     <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
   7
   8     <style title="Visual Leak Detector" type="text/css" media="screen,print">
   9         body {
  10             margin: 0;
  11             font-family: verdana, sans-serif;
  12         }
  13
  14         #masthead {
  15             border-width: 0 0 1px 0;
  16             border-style: solid;
  17             border-color: #808080;
  18             color: #ffffff;
  19             background-color: #3569cc;
  20         }
  21
  22         #content {
  23             margin: 1em 1em 1em 1em;
  24             font-size: 10pt;
  25         }
  26
  27         #toc {
  28             float: right;
  29             color: #000000;
  30             background-color: #ffeda5;
  31         }
  32
  33         h1 {
  34             margin: 0 0 0 0;
  35             padding: 0.5em 1em 0 1em;
  36             text-align: right;
  37             font-size: 24pt;
  38             font-family: arial, sans-serif;
  39         }
  40
  41         h2 {
  42             margin-top: 0;
  43             border-width: 2px;
  44             border-style: solid;
  45             border-color: #3569cc;
  46             padding-left: 1em;
  47             font-size: 16pt;
  48             font-family: "trebuchet ms", sans-serif;
  49             letter-spacing: -1pt;
  50             color: #000000;
  51             background-color: #6599fc;
  52         }
  53
  54         h3 {
  55             font-size: 11pt;
  56         }
  57
  58         li {
  59             margin-bottom: 1em;
  60         }
  61
  62         #toc h2 {
  63             margin: 0;
  64             border-width: 2px 2px 2px 0;
  65             border-style: solid;
  66             border-color: #6599fc;
  67             text-align: center;
  68             color: #ffffff;
  69             background-color: #3569cc;
  70         }
  71
  72         #toc ul {
  73             margin-left: 0;
  74             padding: 0;
  75             list-style: none;
  76         }
  77
  78         #toc li {
  79             margin: 1em;
  80         }
  81
  82         a {
  83             color: #0000ff;
  84             background-color: inherit;
  85             text-decoration:none;
  86         }
  87
  88         a:hover {
  89             text-decoration: underline;
  90         }
  91
  92         a:visited {
  93             color: #0000ff;
  94             background-color: inherit;
  95         }
  96
  97         .api {
  98             font-size: 12pt;
  99             font-weight: bold;
 100         }
 101
 102         .code {
 103             font-family: "courier new", monospace;
 104             color: #000000;
 105             background-color: #e0e0e0;
 106         }
 107
 108         .filename {
 109             font-style: italic;
 110         }
 111
 112         .function {
 113             font-style: italic;
 114         }
 115
 116         .note {
 117             margin-left: 2em;
 118         }
 119
 120         .operator {
 121             font-style: italic;
 122         }
 123
 124         .option {
 125             font-size: 10pt;
 126             font-weight: bold;
 127         }
 128
 129         ul.vcsearchpath {
 130             border-width: 1px;
 131             border-style: dashed;
 132             border-color: #000000;
 133             color: #000000;
 134             background-color: #ffeda5;
 135             list-style: none;
 136         }
 137
 138         ul.vcsearchpath li {
 139             margin-bottom: 0;
 140         }
 141
 142         #slogan {
 143             margin-bottom: 0;
 144             padding: 0 1em 1em 1em;
 145             border-width: 0 0 1px 0;
 146             border-style: solid;
 147             border-color: #404040;
 148             text-align: right;
 149             font-size: larger;
 150             font-style: italic;
 151             color: #6599fc;
 152             background-color: inherit;
 153         }
 154
 155         #copyright {
 156             text-align: right;
 157             font-family: georgia, serif;
 158             color: #808080;
 159             background-color: inherit;
 160         }
 161
 162         #compliance {
 163             text-align: right;
 164         }
 165
 166         #compliance img {
 167             border: 0;
 168         }
 169
 170         blockquote {
 171             font-style: italic;
 172         }
 173
 174         form {
 175             margin: 20px;
 176         }
 177     </style>
 178
 179     <title>Visual Leak Detector (Beta)</title>
 180
 181 </head>
 182
 183
 184
 185
 186 <body>
 187
 188 <div id="masthead">
 189
 190 <h1>Visual&nbsp;Leak&nbsp;Detector&nbsp;1.9h (Beta)</h1>
 191
 192 <p id="slogan">Enhanced Memory Leak Detection for Visual&nbsp;C++</p>
 193
 194 </div> <!-- #masthead -->
 195
 196
 197
 198
 199 <div id="content">
 200
 201 <div id="toc">
 202
 203 <h2>Table of Contents</h2>
 204
 205 <ul>
 206     <li><a href="#intro">Introduction</a></li>
 207
 208     <li><a href="#use">Using Visual&nbsp;Leak&nbsp;Detector</a></li>
 209
 210     <li><a href="#configure">Configuration Options</a></li>
 211
 212     <li><a href="#control">Controlling Leak Detection at Runtime</a></li>
 213
 214     <li><a href="#build">Building Visual&nbsp;Leak&nbsp;Detector from Source</a></li>
 215
 216     <li><a href="#x64">Windows x64 Support</a></li>
 217
 218     <li><a href="#faq">Frequently Asked Questions</a></li>
 219
 220     <li><a href="#restrictions">Known Restrictions</a></li>
 221
 222     <li><a href="#contibuting">Contributing</a></li>
 223
 224     <li><a href="#license">License</a></li>
 225
 226     <li><a href="#contact">Contacting the Author</a></li>
 227
 228     <li><a href="#help-wanted">Additional Developers Wanted</a></li>
 229 </ul>
 230
 231 </div> <!-- #toc -->
 232
 233
 234
 235
 236 <h2 id="intro">Introduction</h2>
 237
 238 <p>Visual&nbsp;C++ provides built-in memory leak detection, but its capabilities are minimal at best. This memory leak
 239    detector was created as a free alternative to the built-in memory leak detector provided with Visual&nbsp;C++. Here
 240    are some of Visual&nbsp;Leak&nbsp;Detector's features, none of which exist in the built-in detector:</p>
 241
 242 <ul>
 243     <li>Provides a complete stack trace for each leaked block, including source file and line number information when
 244         available.</li>
 245
 246     <li>Detects most, if not all, types of in-process memory leaks including COM-based leaks, and pure Win32 heap-based
 247     leaks.</li>
 248
 249     <li>Selected modules (DLLs or even the main EXE) can be excluded from leak detection.</li>
 250
 251     <li>Provides complete data dumps (in hex and ASCII) of leaked blocks.</li>
 252
 253     <li>Customizable memory leak report: can be saved to a file or sent to the debugger and can include a variable level
 254     of detail.</li>
 255 </ul>
 256
 257 <p>Other after-market leak detectors for Visual&nbsp;C++ are already available. But most of the really popular ones,
 258    like Purify and BoundsChecker, are very expensive. A few free alternatives exist, but they're often too intrusive,
 259    restrictive, or unreliable. Visual&nbsp;Leak&nbsp;Detector is currently the only freely available memory leak
 260    detector for Visual C++ that provides all of the above professional-level features packaged neatly in an easy-to-use
 261    library.</p>
 262
 263 <p>Visual Leak Detector is <a href="#license">licensed</a> free of charge as a service to the Windows developer
 264    community. If you find it to be useful and would like to just say "Thanks!", or you think it stinks and would like to
 265    say "This thing sucks!", please feel free to <a href="mailto:dmoulding@gmail.com">drop me a note</a>. Or, if you'd
 266    prefer, you can <a href="#contact">contribute a small donation</a>. Both are very appreciated.</p>
 267
 268
 269
 270
 271 <h2 id="use">Using Visual&nbsp;Leak&nbsp;Detector</h2>
 272
 273 <p>This section briefly describes the basics of using Visual&nbsp;Leak&nbsp;Detector (VLD).</p>
 274
 275 <p><strong>Important! :</strong> Before using VLD with any Visual C++ project, you must first add the Visual Leak
 276    Detector include and library directories to the Visual C++ include and library directory search paths:</p>
 277
 278 <ul>
 279     <li><strong>Visual&nbsp;C++ 8 and 9</strong>: Go to Tools -> Options -> Projects and Solutions -> VC++ Directories.
 280         Select "Include files" from the "Show Directories For" drop-down menu. Add the
 281         <span class="filename">include</span> subdirectory from the Visual Leak Detector installation directory. Move it
 282         to the bottom of the list. Then select "Library files" from the drop-down menu and add the
 283         <span class="filename">lib</span> subdirectory from the Visual Leak Detector installation directory. Again, move
 284         it to the bottom of the list.</li>
 285
 286     <li><strong>Visual&nbsp;C++ 7</strong>: Go to Project Properties -> C/C++ -> General -> Additional Include
 287         Directories and add the <span class="filename">include</span> subdirectory from the Visual Leak Detector
 288         installation directory. Move it to the bottom of the list. Then select Additional Library Directories and add
 289         the <span class="filename">lib</span> subdirectory from the Visual Leak Detector installation directory. Again,
 290         move it to the bottom of the list.</li>
 291
 292     <li><strong>Visual&nbsp;C++ 6</strong>: Go to Tools -> Options -> Directories. Select "Include files" from
 293         the "Show Directories For" drop-down menu. Add the <span class="filename">include</span> subdirectory
 294         from the Visual Leak Detector installation directory. Move it to the bottom of the list. Then select "Library
 295         files" from the drop-down menu and add the <span class="filename">lib</span> subdirectory from the Visual Leak
 296         Detector installation directory. Again, move it to the bottom of the list.</li>
 297 </ul>
 298
 299 <p>To use VLD with your project, follow these simple steps:</p>
 300
 301 <ol>
 302     <li>In at least one C/C++ source file from your program, include the <span class="filename">vld.h</span> header
 303         file. It should not matter which file you add the include statement to. It also should not matter in what order
 304         the header is included in relation to other headers. The only exception is
 305         <span class="filename">stdafx.h</span> (or any other precompiled header). A precompiled header, such as
 306         <span class="filename">stdafx.h</span>, must always be the first header included in a source file, so
 307         <span class="filename">vld.h</span> must be included after any precompiled headers.</li>
 308
 309     <li>If your program contains one or more DLLs that you would also like to check for memory leaks, then also include
 310         <span class="filename">vld.h</span> in at least one source file from each DLL to be included in leak
 311         detection.</li>
 312
 313     <li>Build the debug version of your program.</li>
 314 </ol>
 315
 316 <p class="note"><strong>Note:</strong> Unlike earlier (pre-1.9) versions of VLD, it is now acceptable to include
 317    <span class="filename">vld.h</span> in every source file, or to include it in a common header that is included by
 318    many or all source files. Only one copy of the VLD code will be loaded into the process, regardless of how many
 319    source files include <span class="filename">vld.h</span>.</p>
 320
 321 <p>VLD will detect memory leaks in your program whenever you run the debug version. When you run the program under the
 322    Visual&nbsp;C++ debugger, a report of all the memory leaks detected will be displayed in the debugger's output window
 323    when your program exits (the report can optionally be saved to a file instead, see
 324    <span class="option">ReportFile</span> under <a href="#configure">Configuration Options</a>). Double-clicking on a
 325    source file's line number in the memory leak report will take you to that file and line in the editor window,
 326    allowing easy navigation of the code path leading up to the allocation that resulted in the memory leak.</p>
 327
 328 <p class="note"><strong>Note:</strong> When you build release versions of your program, VLD will not be linked into the
 329    executable. So it is safe to leave <span class="filename">vld.h</span> included in your source files when doing
 330    release builds. Doing so will not result in any performance degradation or any other undesirable overhead.</p>
 331
 332
 333
 334
 335 <h2 id="configure">Configuration Options</h2>
 336
 337 <p>There are a several configuration options that control specific aspects of VLD's operation. These configuration
 338    options are stored in the <span class="filename">vld.ini</span> configuration file. By default, the configuration
 339    file should be in the Visual Leak Detector installation directory. However, the configuration file can be copied to
 340    the program's working directory, in which case the configuration settings in that copy of
 341    <span class="filename">vld.ini</span> will apply only when debugging that one program.</p>
 342
 343 <dl>
 344     <dt class="option">VLD</dt>
 345     <dd>
 346         <p>This option acts as a master on/off switch. By default, this option is set to "on". To <em>completely
 347         disable</em> Visual Leak Detector at runtime, set this option to "off". When VLD is turned off using this
 348         option, it will do nothing but print a message to the debugger indicating that it has been turned off.</p>
 349     </dd>
 350
 351     <dt class="option">AggregateDuplicates</dt>
 352     <dd>
 353         <p>Normally, VLD displays each individual leaked block in detail. Setting this option to "yes" will make VLD
 354            aggregate all leaks that share the same size and call stack under a single entry in the memory leak report.
 355            Only the first leaked block will be reported in detail. No other identical leaks will be displayed. Instead,
 356            a tally showing the total number of leaks matching that size and call stack will be shown. This can be useful
 357            if there are only a few sources of leaks, but those few sources are repeatedly leaking a very large number of
 358            memory blocks.</p>
 359     </dd>
 360
 361     <dt class="option">ForceIncludeModules</dt>
 362     <dd>
 363         <p>In some rare cases, it may be necessary to include a module in leak detection, but it may not be possible to
 364            include <span class="filename">vld.h</span> in any of the module's sources. In such cases, this option can be
 365            used to force VLD to include those modules in leak detection. List the names of the modules (DLLs) to be
 366            forcefully included in leak detection. If you do use this option, it's advisable to also add
 367            <span class="filename">vld.lib</span> to the list of library modules in the linker options of your project's
 368            settings.</p>
 369
 370         <p class="note"><strong>Caution:</strong> Use this option only when absolutely necessary. In some situations,
 371            use of this option may result in unpredictable behavior including false leak reports and/or crashes. It's
 372            best to stay away from this option unless you are sure you understand what you are doing.</p>
 373     </dd>
 374
 375     <dt class="option">MaxDataDump</dt>
 376     <dd>
 377         <p>Set this option to an integer value to limit the amount of data displayed in memory block data dumps. When
 378            this number of bytes of data have been dumped, the dump will stop. This can be useful if any of the leaked
 379            blocks are very large and the debugger's output window becomes too cluttered. You can set this option to 0
 380            (zero) if you want to suppress data dumps altogether.</p>
 381     </dd>
 382
 383     <dt class="option">MaxTraceFrames</dt>
 384     <dd>
 385         <p>By default, VLD will trace the call stack for each allocated block as far back as possible. Each frame traced
 386            adds additional overhead (in both CPU time and memory usage) to your debug executable. If you'd like to limit
 387            this overhead, you can define this macro to an integer value. The stack trace will stop when it has traced
 388            this number of frames. The frame count may include some of the "internal" frames which, by default, are not
 389            displayed in the debugger's output window (see <span class="option">TraceInternalFrames</span> below). In
 390            some cases there may be about three or four "internal" frames at the beginning of the call stack. Keep this
 391            in mind when using this macro, or you may not see the number of frames you expect.</p>
 392     </dd>
 393
 394     <dt class="option">ReportEncoding</dt>
 395     <dd>
 396         <p>When the memory leak report is saved to a file, the report may optionally be Unicode encoded instead of using
 397            the default ASCII encoding. This might be useful if the data contained in leaked blocks is likely to consist
 398            of Unicode text. Set this option to "unicode" to generate a Unicode encoded report.</p>
 399     </dd>
 400
 401     <dt class="option">ReportFile</dt>
 402     <dd>
 403         <p>Use this option to specify the name and location of the file in which to save the memory leak report when
 404            using a file as the report destination, as specified by the <span class="option">ReportTo</span> option. If
 405            no file is specified here, then VLD will save the report in a file named "memory_leak_report.txt" in the
 406            working directory of the program.</p>
 407     </dd>
 408
 409     <dt class="option">ReportTo</dt>
 410     <dd>
 411         <p>The memory leak report may be sent to a file in addition to, or instead of, the debugger. Use this option to
 412            specify which type of destination to use. Specify one of "debugger" (the default), "file", or "both".</p>
 413     </dd>
 414
 415     <dt class="option">SelfTest</dt>
 416     <dd>
 417         <p>VLD has the ability to check itself for memory leaks. This feature is always active. Every time you run VLD,
 418            in addition to checking your own program for memory leaks, it is also checking itself for leaks. Setting this
 419            option to "on" forces VLD to intentionally leak a small amount of memory: a 21-character block filled with
 420            the text "Memory Leak Self-Test". This provides a way to test VLD's ability to check itself for memory leaks
 421            and verify that this capability is working correctly. This option is usually only useful for debugging VLD
 422            itself.</p>
 423     </dd>
 424
 425     <dt class="option">SlowDebuggerDump</dt>
 426     <dd>
 427         <p>If enabled, this option causes Visual Leak Detector to write the memory leak report to the debugger's output
 428            window at a slower than normal rate. This option is specifically designed to work around a known issue with
 429            some older versions of Visual Studio where some data sent to the output window might be lost if it is sent
 430            too quickly. If you notice that some information seems to be missing from the memory leak report, try turning
 431            this on.</p>
 432     </dd>
 433
 434     <dt class="option">StackWalkMethod</dt>
 435     <dd>
 436         <p>Selects the method to be used for walking the stack to obtain call stacks for allocated memory blocks. The
 437            default "fast" method may not always be able to successfully trace completely through all call stacks. In
 438            such cases, the "safe" method may prove to be more reliable in obtaining the full stack trace. The
 439            disadvantage with the "safe" method is that it is significantly slower than the "fast" method and will
 440            probably result in very noticeable performance degradation of the program being debugged. In most cases it
 441            should be okay to leave this option set to "fast". If you experience problems getting VLD to show call
 442            stacks, you can try setting this option to "safe".</p>
 443
 444         <p>If you do use the "safe" method, and notice a significant performance decrease, you may want to consider
 445            using the <span class="option">MaxTraceFrames</span> option to limit the number of frames traced to a
 446            relatively small number. This can reduce the amount of time spent tracing the stack by a very large
 447            amount.</p>
 448     </dd>
 449
 450     <dt class="option">StartDisabled</dt>
 451     <dd>
 452         <p>Set this option to "yes" to disable memory leak detection initially. This can be useful if you need to be
 453            able to selectively enable memory leak detection from runtime, without needing to rebuild the executable;
 454            however, this option should be used with caution. Any memory leaks that may occur before memory leak
 455            detection is enabled at runtime will go undetected. For example, if the constructor of some global variable
 456            allocates memory before execution reaches a subsequent call to <span class="function">VLDEnable</span>, then
 457            VLD will not be able to detect if the memory allocated by the global variable is never freed. Refer to the
 458            following section on <a href="#control">controlling leak detection at runtime</a> for details on using the
 459            runtime APIs which can be useful in conjunction with this option.</p>
 460     </dd>
 461
 462     <dt class="option">TraceInternalFrames</dt>
 463     <dd>
 464         <p>This option determines whether or not all frames of the call stack, including frames internal to the heap,
 465            are traced. There will always be a number of frames on the call stack which are internal to Visual Leak
 466            Detector and C/C++ or Win32 heap APIs that aren't generally useful for determining the cause of a leak.
 467            Normally these frames are skipped during the stack trace, which somewhat reduces the time spent tracing and
 468            amount of data collected and stored in memory. Including all frames in the stack trace, all the way down into
 469            VLD's own code can, however, be useful for debugging VLD itself.</p>
 470     </dd>
 471 </dl>
 472
 473
 474
 475
 476 <h2 id="control">Controlling Leak Detection at Runtime</h2>
 477
 478 <p>Using the default configuration, VLD's memory leak detection will be enabled during the entire run of your program.
 479    In certain scenarios it may be desirable to selectively disable memory leak detection in certain segments of your
 480    code. VLD provides simple APIs for controlling the state of memory leak detection at runtime. To access these APIs,
 481    include <span class="filename">vld.h</span> in the source file that needs to use them.</p>
 482
 483 <dl>
 484     <dt class="api">VLDDisable</dt>
 485     <dd>
 486         <p>This function disables memory leak detection. After calling this function, memory leak detection will remain
 487            disabled until it is explicitly re-enabled via a call to VLDEnable.</p>
 488
 489         <pre class="code">void VLDDisable (void);</pre>
 490
 491         <h3>Arguments:</h3>
 492
 493         <p>This function accepts no arguments.</p>
 494
 495         <h3>Return Value:</h3>
 496
 497         <p>None (this function always succeeds).</p>
 498
 499         <h3>Notes:</h3>
 500
 501         <p>This function controls memory leak detection on a per-thread basis. In other words, calling this function
 502            disables memory leak detection for only the thread that called the function. Memory leak detection will
 503            remain enabled for any other threads in the same process. This insulates the programmer from having to
 504            synchronize multiple threads that disable and enable memory leak detection. However, note also that this
 505            means that in order to disable memory leak detection process-wide, this function must be called from every
 506            thread in the process.</p>
 507     </dd>
 508
 509
 510     <dt class="api">VLDEnable</dt>
 511     <dd>
 512         <p>This function enables memory leak detection if it was previously disabled. After calling this function,
 513            memory leak detection will remain enabled unless it is explicitly disabled again via a call to
 514            VLDDisable().</p>
 515
 516         <pre class="code">void VLDEnable (void);</pre>
 517
 518         <h3>Arguments:</h3>
 519
 520         <p>This function accepts no arguments.</p>
 521
 522         <h3>Return Value:</h3>
 523
 524         <p>None (this function always succeeds).</p>
 525
 526         <h3>Notes:</h3>
 527
 528         <p>This function controls memory leak detection on a per-thread basis. See the remarks for
 529            <span class="function">VLDDisable</span> regarding multithreading and memory leak detection for details.
 530            Those same concepts also apply to this function.</p>
 531     </dd>
 532 </dl>
 533
 534
 535
 536
 537 <h2 id="build">Building Visual&nbsp;Leak&nbsp;Detector from Source</h2>
 538
 539 <p>Because Visual&nbsp;Leak&nbsp;Detector is open source, it can be built from source if you want to tweak it to your
 540    liking. As of Visual Studio 2008, the source can usually be built out-of-the-box without downloading or installing
 541    any other tools. If you are using Visual Studio 2008 (or later), you can skip ahead to
 542    <a href="#exec">Executing Your Built vld.dll</a>.
 543
 544 <p>Users with older versions of Visual Studio should continue reading here and follow the instructions in the next
 545    subsection.</p>
 546
 547 <h3>For Older Versions of Visual Studio</h3>
 548
 549 <p>The most difficult part about building VLD from source is getting your build environment correctly set up.
 550    But if you follow these instructions carefully, the  process should be fairly painless.</p>
 551
 552 <ol>
 553     <li>VLD depends on the Debug Help Library. This library is part of
 554         <a href="http://www.microsoft.com/whdc/devtools/debugging/default.mspx">Debugging Tools for Windows</a> (DTfW).
 555         Download and install DTfW in order to install the required headers and libraries. I recommend installing version
 556         6.5 of DTfW, or later. Newer versions tend to  work fine, but older versions will probably not work. Be sure to
 557         manually select to install the SDK files during the DTfW installation or the headers and libraries will not be
 558         installed (they are not always installed with a default installation).</li>
 559
 560     <li>Visual&nbsp;C++ will need to be made aware of where it can find the Debug Help Library header and library files.
 561         Add the <span class="filename">sdk\inc</span> and <span class="filename">sdk\lib</span> subdirectories from the
 562         DTfW installation directory to the include and library search paths in Visual&nbsp;C++. (See the section above
 563         on <a href="#use">using Visual Leak Detector</a> on instructions for adding to these search paths).
 564     </li>
 565
 566     <li>VLD also requires a reasonably up-to-date Platform&nbsp;SDK. It is known to work with the latest SDK (as of this
 567         writing) which is the Windows Server 2003 R2 SDK. It should also work with earlier SDKs, such as the Windows XP
 568         SP2 SDK or may even work with SDKs as old as the February 2003 SDK. If in doubt,
 569         <a href="http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5&amp;displaylang=en">update
 570         your Platform&nbsp;SDK</a> to the latest version.</li>
 571
 572     <li>Again, Visual&nbsp;C++ will need to know where to find the Platform&nbsp;SDK headers and libraries. Add the
 573         <span class="filename">Include</span> and <span class="filename">Lib</span> subdirectories from the
 574         Platform&nbsp;SDK installation directory to the Include and Library search paths, respectively. The
 575         Platform&nbsp;SDK directories should be placed just after the DTfW directories.</li>
 576 </ol>
 577
 578 <p>To summarize, your Visual&nbsp;C++ include search path should look something like this:</p>
 579
 580 <ul class="vcsearchpath">
 581    <li>C:\Program&nbsp;Files\Debugging&nbsp;Tools&nbsp;for&nbsp;Windows\sdk\inc</li>
 582
 583    <li>C:\Program&nbsp;Files\Microsoft&nbsp;Platform&nbsp;SDK\Include</li>
 584
 585    <li>C:\Program&nbsp;Files\Microsoft&nbsp;Visual&nbsp;Studio\VCx\Include</li>
 586
 587    <li>...</li>
 588 </ul>
 589
 590 <p>And your Visual&nbsp;C++ library search path should look like this:</p>
 591
 592 <ul class="vcsearchpath">
 593    <li>C:\Program&nbsp;Files\Debugging&nbsp;Tools&nbsp;for&nbsp;Windows\sdk\lib</li>
 594
 595    <li>C:\Program&nbsp;Files\Microsoft&nbsp;Platform&nbsp;SDK\Lib</li>
 596
 597    <li>C:\Program&nbsp;Files\Microsoft&nbsp;Visual&nbsp;Studio\VCx\Lib</li>
 598
 599    <li>...</li>
 600 </ul>
 601
 602 <p>In the above examples, "VCx" could be "VC", "VC7", or "VC98" (or possibly other values) depending on which version of
 603    Visual Studio you have installed. Also, the name of your Platform&nbsp;SDK directory will probably be different from
 604    the example depending on which version of the Platform&nbsp;SDK you have installed.</p>
 605
 606 <p>Once you have completed all of the above steps, your build environment should be ready. To build VLD, just open the
 607    <span class="filename">vld.sln</span> solution file and do a full build.</p>
 608
 609 <h3 id="exec">Executing Your Built vld.dll</h3>
 610
 611 <p>When actually running the built project, <span class="filename">vld.dll</span> will expect to find the Debug Help
 612    Library as a private assembly. The private assembly must be located in the same directory as
 613    <span class="filename">vld.dll</span> (either the <span class="filename">Release</span> or
 614    <span class="filename">Debug</span> directory by default). Otherwise, when VLD is loaded, an error message will pop
 615    up indicating that the program failed to initialize, and you will see a message similar to the following in the
 616    debugger's output window:</p>
 617    <blockquote><p>LDR: LdrpWalkImportDescriptor() failed to probe C:\Projects\vld\Release\vld.dll for its manifest,
 618    ntstatus 0xc0150002</p></blockquote>
 619
 620 <p>To ensure that <span class="filename">vld.dll</span> finds the required private assembly, you need to copy
 621    <span class="filename">dbghelp.dll</span> and <span class="filename">Microsoft.DTfW.DHL.manifest</span> to the
 622    same directory that <span class="filename">vld.dll</span> is in.</p>
 623
 624
 625
 626
 627 <h2 id="x64">Windows x64 Support</h2>
 628
 629 <p>Currently VLD will not build on x64 due to limitations of the x64 compiler. Some efforts have been undertaken to
 630    get it working in a 64-bit environment, but have not yet been successful. If you need 64-bit support and run into
 631    problems trying to build the source in 64-bit mode, please <a href="mailto:dmoulding@gmail.com">let me know</a>.
 632    I'll be glad to assist in getting the 64-bit code working properly, if at all possible.</p>
 633
 634
 635
 636
 637 <h2 id="faq">Frequently Asked Questions</h2>
 638
 639 <dl>
 640     <dt>When I try to compile my program with VLD, it fails and the compiler gives this error: <strong>Cannot open include file:
 641     'vld.h': No such file or directory</strong>.</dt>
 642     <dd>
 643         <p>The compiler can't find the header file that VLD installed. This probably means that VLD's include
 644         subdirectory has not been added to the Visual C++ include search path. See the section above about
 645         <a href="#use">Using Visual Leak Detector</a> for instructions on how to add VLD's directories to the search
 646         path.</p>
 647     </dd>
 648     <dt>In the memory leak report, the callstack contains many lines that say
 649         <strong>"File and line number unvailable"</strong> or <strong>"Function name unavailable"</strong>.</dt>
 650     <dd>
 651         <p>This may mean that VLD couldn't find the symbol database for your program. The symbol database is ususally in
 652            a file named <span class="filename">[my-program-name].pdb</span>. If this file is not located in the same
 653            directory as the program itself, then VLD will probably not find it and can't show any file or function
 654            names.</p>
 655     </dd>
 656 </dl>
 657
 658
 659
 660
 661 <h2 id="restrictions">Known Restrictions</h2>
 662
 663 <p>Known restrictions/limitations in this version of VLD include:</p>
 664
 665 <ul>
 666    <li>Memory allocations made through calls to functions loaded from a DLL using delayed loading may not be
 667        detected.</li>
 668
 669    <li>Support for programs that use MFC 7.0 or MFC 7.1 is not complete yet. Some memory leaks from such MFC-based
 670        programs may not be detected. A possible workaround for this restriction is to try forcefully including the MFC
 671        DLLs in memory leak detection, by setting the <span class="option">ForceIncludeModules</span> configuration
 672        option to: "mfc70d.dll mfc71d.dll" and explicitly adding <span class="filename">vld.lib</span> as an input file
 673        on the linker command line (can be added through project settings by adding it to the list of library modules in
 674        the linker options). This restriction does not apply to programs that use MFC 4.2, MFC 8.0, or MFC 9.0, which are
 675        all fully supported.</li>
 676
 677    <li>Visual Leak Detector may report leaks internal to Visual Leak Detector if the main thread of the process
 678        terminates while other threads are still running.</li>
 679
 680    <li>On Windows 2000 and earlier operating systems, you may need to manually add the
 681        <span class="filename">bin</span> subdirectory from the Visual Leak Detector installation directory to the system
 682        PATH environment variable. Also, <span class="filename">dbghelp.dll</span> will probably need to be manually copied
 683        to the directory where the program being debugged resides. Otherwise the system may not find the required DLLs when
 684        running VLD.</li>
 685
 686     <li>If more than one copy of the same C Runtime DLL is loaded in the process at the same time, then some leaks may
 687         go undetected (note that loading more than one copy of the C Runtime DLL at the same time is probably a bad idea
 688         to begin with).</li>
 689 </ul>
 690
 691
 692
 693 <h2 id="contibuting">Contributing</h2>
 694
 695 <p>I encourage developers who've added their own features, or fixed bugs they've found, to contribute to the project.
 696    The full version-controlled source tree is available publicly via Git at the URL below. Feel free to clone from this
 697    URL and submit patches for consideration for inclusion in future versions. You can also hop onto
 698    <a href="http://github.com">GitHub</a> (accounts are free) and issue pull requests for changes that you've made and
 699    would like to share.</p>
 700
 701 <p>Git Repository URL: git://github.com/dmoulding/vld.git</p>
 702
 703 <h2 id="license">License</h2>
 704
 705 <p>Visual&nbsp;Leak&nbsp;Detector is distributed under the terms of the
 706    <a href="http://www.gnu.org/copyleft/lesser.html">GNU Lesser General Public License</a>. This license allows you to
 707    use the VLD library with your own programs without restriction. However, if you build a program (or another library)
 708    that is <em>based</em> on the VLD source code, or uses parts of the VLD source code in it, then some restrictions
 709    will apply. What this means is that you are free to ship and use the distributed version of the VLD DLL with regular
 710    commercial programs. But if you create a modified version of VLD, that modified version must remain "free software".
 711    See the <span class="filename"><a href="COPYING.txt">COPYING.txt</a></span> file for details.</p>
 712
 713 <p>The Debug Help Library (<span class="filename">dbghelp.dll</span>) and Microsoft C Runtime Library
 714    (<span class="filename">msvcr80.dll</span>) distributed with this software are not part of
 715    Visual&nbsp;Leak&nbsp;Detector and are not covered under the terms of the GNU Lesser General Public License. They are
 716    separately copyrighted works of Microsoft Corporation. Microsoft reserves all its rights to its copyrights in the
 717    Debug Help Library and Microsoft C Runtime Library. Neither your use of the Visual&nbsp;Leak&nbsp;Detector software,
 718    nor your license under the GNU Lesser General Public license grant you any rights to use the Debug Help Library or
 719    Microsoft C Runtime Library in <strong>ANY WAY</strong> (for example, redistributing them) that would infringe upon
 720    Microsoft Corporation's copyright in the Debug Help Library or Microsoft C Runtime Library.</p>
 721
 722 <h3>NO WARRANTY</h3>
 723
 724 <p>BECAUSE VISUAL LEAK DETECTOR ("THE SOFTWARE") IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO
 725    THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
 726    PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
 727    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
 728    QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
 729    NECESSARY SERVICING, REPAIR OR CORRECTION.</p>
 730
 731 <p>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY
 732    WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE LICENSING TERMS SET FORTH ABOVE, BE LIABLE TO YOU
 733    FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY
 734    TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED
 735    BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR
 736    OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.</p>
 737
 738
 739
 740
 741 <h2 id="contact">Contacting the Author</h2>
 742
 743 <p>Please forward any bug reports, questions, comments or suggestions to me at
 744 <a href="mailto:dmoulding@gmail.com">dmoulding@gmail.com.</a></p>
 745
 746 <p>Donations to help support ongoing development of Visual Leak Detector are very appreciated!</p>
 747
 748 <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
 749     <div>
 750     <input type="hidden" name="cmd" value="_s-xclick" />
 751     <input type="image" src="https://www.paypal.com/en_US/i/btn/x-click-but21.gif" name="submit" alt="Make payments with PayPal - it's fast, free and secure!" />
 752     <input type="hidden" name="encrypted" value="-----BEGIN PKCS7-----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-----END PKCS7-----" />
 754     </div>
 755 </form>
 756
 757
 758
 759 <h2 id="help-wanted">Additional Developers Wanted</h2>
 760
 761 <p>This project is looking for additional developers who have the time, knowledge, and talent, to help make VLD continue
 762    to be a useful utility for the Windows developer community. If you feel that you or someone you know would be
 763    interested in becoming an active member of the Visual Leak Detector development team, please let me know.</p>
 764
 765
 766
 767 <p id="compliance">
 768     <a href="http://validator.w3.org"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a>
 769     <a href="http://jigsaw.w3.org/css-validator"><img id="valid-css" src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" /></a>
 770 </p>
 771
 772
 773
 774 <p id="copyright">Copyright &copy; 2005-2009 Dan Moulding</p>
 775
 776 </div> <!-- #content -->
 777
 778 </body>
 779
 780 </html>