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