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