You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Visual Studio Address Sanitizer extended functionality library (VCASan)
10
10
11
-
The "*VCAsan*.lib" libraries implement extended debugger IDE features in Visual Studio. These new features allow the IDE to light up Address Sanitizer errors in live debug sessions, or off-line by saving a crash dump file with new meta-data. In either case, the IDE has new functionality to super-impose. The library is linked any time AddressSanitizer is enabled with the Visual C++ compiler.
11
+
The **VCAsan\*.lib** libraries implement extended debugger IDE features in Visual Studio. These features allow the IDE to light up Address Sanitizer errors in live debug sessions, or offline by saving a crash dump file with metadata. The library is linked any time AddressSanitizer is enabled with the Visual C++ compiler.
Copy file name to clipboardExpand all lines: docs/sanitizers/asan-offline-crash-dumps.md
+25-42Lines changed: 25 additions & 42 deletions
Original file line number
Diff line number
Diff line change
@@ -8,103 +8,86 @@ help viewer_keywords: ["ASan","sanitizers","AddressSanitizer","clang_rt","Clang
8
8
9
9
# Address Sanitizer - Cloud or distributed testing
10
10
11
-
## Overview - new way to report a bug.
11
+
When an Address Sanitizer error is found a crash dump can be created to store all the Address Saniziter-specific context. That crash dump can then be sent to another PC for debugging. This can be a critical time saver when running Address Saniziter in the cloud or in distributed testing: create the dump on failure on that infrastructure and debug it on your developer PC.
12
12
13
-
We've made it possible to store a precisely diagnosed, Address Sanitizer error. The errors reported by the Address Sanitizer runtime carry a large amount of context and may take a long time to reproduce once you find the required input data. Capturing the error for immediate post-mortem analysis, in Visual Studio, on another machine, is a critical time saver.
13
+
The Visual Studio debugger provides precisely diagnosed Address Sanitizer errors, and **you can view these bugs without having to rerun testing, copy huge datasets, discover lost data, or find test machines that went offline: just load up the crash dump.**
14
14
15
-
**You can view precisely diagnosed Address Sanitizer bugs in the Visual Studio debugger IDE. You can view these bugs without having to rerun testing, copy huge data-sets, discover lost data, or find machines that went off line.**
15
+
Crash dumps are created upon Address Sanitizer failures by setting the following environment variable:
16
16
17
-
When compiling with the compiler flag `-fsanitize=address`, the compiler driver (cl.exe) will automatically link a new static library with your application: vcasan.lib. This library has the optional functionality to create a new type of crash dump file upon encountering an exception from the Address Sanitizer. This functionality is enabled with an environment variable by setting an environment variable on the command line:
17
+
`set ASAN_SAVE_DUMPS=MyFileName.dmp`
18
18
19
-
**`set ASAN_SAVE_DUMPS=MyFileName.dmp`**
20
-
21
-
File name must have a suffix ".dmp" for Visual Studio naming conventions.
19
+
> [!NOTE]
20
+
> File name must have a suffix ".dmp" for Visual Studio naming conventions.
22
21
23
-
Your local or remote testing automation could execute this step, before running tests using your code compiled with -fsanitize=address.
22
+
This [dump file](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/proc_snap/export-a-process-snapshot-to-a-file) can be displayed by using Visual Studio at a later date on another machine.
24
23
25
-
### Errors - stored to a new dump file
26
-
27
-
Once you set a file name in the environment variable **ASAN_SAVE_DUMPS** then upon error, your application will produce "MyFileName.dmp", which is a [dump file](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/proc_snap/export-a-process-snapshot-to-a-file) that can be displayed by using Visual Studio at a later date on another machine.
28
-
29
-
The .exe, .pdb and source code used to produce those binaries, must match for Visual Studio to display the Address Sanitizer error. In order to display the error's information, within the context of the original source code, Visual Studio requires [debugging symbols](https://docs.microsoft.com/en-us/windows/win32/dxtecharts/debugging-with-symbols) and [indexing source code](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/source-indexing).
24
+
In order to display the error's information, within the context of the original source code, Visual Studio requires [debugging symbols](https://docs.microsoft.com/en-us/windows/win32/dxtecharts/debugging-with-symbols) and [indexing source code](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/source-indexing). For the best debugging experience the .exe, .pdb and source code used to produce those binaries must match.
30
25
31
26
See the [source and symbols](#Source-and-symbols) section below.
27
+
For implementation details and fine grained control, see the [debugger integration](asan-debugger-integration.md).
32
28
33
29
## Example - build, test, and analyze
34
30
35
-
Assume you have machines A, B, and C. You build on machine B, you run on machine C and then you analyze failures on machine A. The errors are reported against source line and column numbers in your source code. The call stack is displayed with a set of symbols in the PDB file produced from that [exact version of source code](#Source-and-symbols).
31
+
Consider three machines: A, B, and C. Build are done on machine B, tests are run on machine C and then you analyze failures on machine A. The errors are reported against source line and column numbers in your source code. The call stack is displayed with a set of symbols in the PDB file produced from that [exact version of source code](#Source-and-symbols).
36
32
37
33
The following steps are for local or distributed scenarios that lead to creating a .dmp file and viewing that [Address Sanitizer dump file](#View-AddressSanitizer-.dmp-files), off-line.
38
34
39
35
### Steps - locally produced .dmp
40
36
41
-
- Build.
42
-
- Test the (.exe, .pdb).
43
-
- Copy .dmp file to the build directory.
44
-
- Open a .dmp file with the paired .pdb, in the same directory.
37
+
- Build
38
+
- Test the (.exe, .pdb)
39
+
- Copy .dmp file to the build directory
40
+
- Open a .dmp file with the paired .pdb, in the same directory
45
41
46
42
### Steps - distributed system producing a .dmp
47
43
48
-
- Build and [post process the PDB](#Source-and-symbols) for [source indexing data blocks](https://docs.microsoft.com/en-us/windows/win32/debug/source-server-and-source-indexing).
49
-
- Copy the atomic pair of (.exe, .pdb) to the test machine and run tests.
50
-
- Write the atomic pairs of (.pdb, .dmp) to the bug-reporting database.
51
-
- Visual Studio opens a .dmp file with the paired .pdb, in the same directory.
44
+
- Build and [post process the PDB](#Source-and-symbols) for [source indexing data blocks](https://docs.microsoft.com/en-us/windows/win32/debug/source-server-and-source-indexing)
45
+
- Copy the atomic pair of (.exe, .pdb) to the test machine and run tests
46
+
- Write the atomic pairs of (.pdb, .dmp) to the bug-reporting database
47
+
- Visual Studio opens a .dmp file with the paired .pdb, in the same directory
52
48
53
49
Note: The VS2019 machine must have access to GitHub or the internal "\\\Machine\share" where your source "was indexed to".
54
50
55
51
## View Address Sanitizer .dmp files
56
52
57
-
Insure the debugger IDE will be able to get to your `.PDB and source.
53
+
Ensure the debugger IDE will be able to get to your .PDB and source.
58
54
59
55
Open Visual Studio and select **Continue without code**.
60
56
61
-
Then click **File->Open->File** and make sure the file name suffix is **.dmp**
62
-
63
-
It really is that straightforward! Consider the red high lights:
57
+
Then click **File** -> **Open** -> **File** and make sure the file name suffix is **.dmp**
- The Address Sanitizer diagnostic is superimposed on the source used to build the tested EXE.
80
-
- The normal command-line output is presented in the Output pane.
81
-
82
71
## Source and symbols
83
72
84
-
[Source server](https://docs.microsoft.com/en-us/windows/win32/debug/source-server-and-source-indexing) (see Data Block section) enables a client to retrieve the **exact version** of the source files that were used to build an application. Because the source code for an executable or DLL can change between versions and over a course of years, it is important to look at the source code as it existed when the version of the code was built. That version has the memory safety bug the Address Sanitizer caught.
73
+
[Source server](https://docs.microsoft.com/en-us/windows/win32/debug/source-server-and-source-indexing) (see Data Block section) enables a client to retrieve the **exact version** of the source files that were used to build an application. Because the source code for an executable or DLL can change between versions and over a course of years, it is important to look at the source code as it existed when the version of the code was built.
85
74
86
75
While debugging an .EXE with the PDB, the debugger can use the embedded source server data block. It retrieves the appropriate files from source control that map to the fully qualified names that are automatically put in the PDB when compiling with /Zi.
87
76
88
-
To use source server, the application must have been "source indexed". That common phrase means **using pdbstr.exe to write a srcsrv data block into your PDB**. See the Data Block section in [source indexed](https://docs.microsoft.com/en-us/windows/win32/debug/source-server-and-source-indexing).
77
+
To use source server, the application must have been "source indexed": **using pdbstr.exe to write a srcsrv data block into your PDB**. See the Data Block section in [source server documentation](https://docs.microsoft.com/en-us/windows/win32/debug/source-server-and-source-indexing).
89
78
90
79
- See [the steps indexing sources and publishing symbols](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/build/index-sources-publish-symbols?view=azure-devops)
91
80
92
81
- See [how to specify symbols and source code for the debugger IDE will to open your crash dump from the Address Sanitizer](https://docs.microsoft.com/en-us/visualstudio/debugger/specify-symbol-dot-pdb-and-source-files-in-the-visual-studio-debugger?view=vs-2019)
93
82
94
83
For external documentation, see:
95
84
96
-
-[**Source indexing with Git**](https://gist.github.com/baldurk/c6feb31b0305125c6d1a)
85
+
-[Source indexing with Git](https://gist.github.com/baldurk/c6feb31b0305125c6d1a)
97
86
98
87
-[A guide to easier debugging](https://www.codeproject.com/articles/115125/source-indexing-and-symbol-servers-a-guide-to-easi)
99
88
100
89
-[Source Indexing is Underused Awesomeness](https://randomascii.wordpress.com/2011/11/11/source-indexing-is-underused-awesomeness/)
101
90
102
-
## Error reporting to a file - under the covers
103
-
104
-
When your .EXE encounters a runtime error, the Address Sanitizer runtime throws different exceptions. When run from the command-line, the Address Sanitizer runtime will throw an exception and produce textual error information on the console.
105
-
106
-
When run under the Visual Studio debugger, the new debugger IDE displays that error diagnostic, super imposed on your source code. That's due to new meta-data written to the heap. The exceptions the runtime throw, are implemented with an exception record data structure. That record points to the meta-data in the heap and the new IDE can parse it. That same information can also be preserved in a memory dump file for later viewing in the new Visual Studio debugger IDE.
0 commit comments