Skip to content

Commit eb41333

Browse files
TylerMSFTTylerMSFT
TylerMSFT
authored and
TylerMSFT
committed
alt-text improvements, screenshot improvements, and fix steps for CMake projects
1 parent b78a9bb commit eb41333

File tree

6 files changed

+74
-20
lines changed

6 files changed

+74
-20
lines changed

‎docs/sanitizers/asan.md

Lines changed: 74 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "AddressSanitizer"
33
description: "Top-level description of the AddressSanitizer feature for Microsoft C/C++."
4-
ms.date: 03/05/2021
4+
ms.date: 06/13/2023
55
f1_keywords: ["AddressSanitizer"]
66
helpviewer_keywords: ["ASan", "AddressSanitizer", "Address Sanitizer", "compiling for AddressSanitizer"]
77
---
@@ -32,23 +32,21 @@ Use AddressSanitizer to reduce your time spent on:
3232
- Stress testing
3333
- Integrating new code
3434

35-
AddressSanitizer, originally [introduced by Google](https://www.usenix.org/conference/atc12/technical-sessions/presentation/serebryany), provides run-time bug-finding technologies that use your existing build systems and existing test assets directly.
35+
AddressSanitizer, originally [introduced by Google](https://www.usenix.org/conference/atc12/technical-sessions/presentation/serebryany), provides runtime bug-finding technologies that use your existing build systems and existing test assets directly.
3636

3737
AddressSanitizer is integrated with the Visual Studio project system, the CMake build system, and the IDE. Projects can enable AddressSanitizer by setting a project property, or by using one extra compiler option: **`/fsanitize=address`**. The new option is compatible with all levels of optimization and configurations of x86 and x64. However, it isn't compatible with [edit-and-continue](/visualstudio/debugger/edit-and-continue-visual-cpp), [incremental linking](../build/reference/incremental-link-incrementally.md), and [`/RTC`](../build/reference/rtc-run-time-error-checks.md).
3838

39-
Starting in Visual Studio 2019 version 16.9, Microsoft's AddressSanitizer technology enables integration with the Visual Studio IDE. The functionality can optionally create a crash dump file when the sanitizer finds a bug at runtime. If you set the `ASAN_SAVE_DUMPS=MyFileName.dmp` environment variable before you run your program, a crash dump file gets created with extra metadata for efficient [post-mortem debugging](#crash-dumps) of precisely diagnosed bugs. These dump files make extended use of AddressSanitizer easier for:
39+
Starting in Visual Studio 2019 version 16.9, Microsoft's AddressSanitizer technology enables integration with the Visual Studio IDE. The functionality can optionally create a crash dump file when the sanitizer finds a bug at runtime. If you set the `ASAN_SAVE_DUMPS=MyFileName.dmp` environment variable before you run your program, a crash dump file is created with extra metadata for efficient [post-mortem debugging](#crash-dumps) of precisely diagnosed bugs. These dump files make extended use of AddressSanitizer easier for:
4040

41-
- Local machine testing,
42-
- On-premise distributed testing, and
43-
- Cloud-based workflows for testing.
41+
- Local machine testing
42+
- On-premise distributed testing
43+
- Cloud-based workflows for testing
4444

4545
### Install AddressSanitizer
4646

47-
C++ workloads in the Visual Studio Installer install the AddressSanitizer libraries and IDE integration by default. However, if you're upgrading from an older version of Visual Studio 2019, use the Installer to enable ASan support after the upgrade:
47+
C++ workloads in the Visual Studio Installer install the AddressSanitizer libraries and IDE integration by default. However, if you're upgrading from an older version of Visual Studio 2019, use the Installer to enable ASan support after the upgrade. You can open the installer from the Visual Studio main menu via **Tools** > **Get Tools and Features...** Choose **Modify** on your existing Visual Studio installation from the Visual Studio Installer to get to the following screen.
4848

49-
:::image type="content" source="media/asan-installer-option.png" alt-text="Visual Studio Installer screenshot highlighting the C++ AddressSanitizer component":::
50-
51-
You can choose **Modify** on your existing Visual Studio installation from the Visual Studio Installer to get to the screen above.
49+
:::image type="content" source="media/asan-installer-option.png" alt-text="Screenshot of the Visual Studio Installer. The C++ AddressSanitizer component, under the Optional section, is highlighted":::
5250

5351
> [!NOTE]
5452
> If you run Visual Studio on the new update but haven't installed ASan, you'll get an error when you run your code:
@@ -105,13 +103,15 @@ int main() {
105103

106104
Using a developer command prompt for Visual Studio 2019, compile *`main.cpp`* using `/fsanitize=address /Zi`
107105

108-
:::image type="content" source="media/asan-command-basic-global-overflow.png" alt-text="Screenshot of a command prompt showing the command to compile with AddressSanitizer options.":::
106+
:::image type="content" source="media/asan-command-basic-global-overflow.png" alt-text="Screenshot of a command prompt showing the command to compile with AddressSanitizer options. The command is: cl main.cpp -faanitize-address /Zi.":::
109107

110108
When you run the resulting *`main.exe`* at the command line, it creates the formatted error report seen below.
111109

112110
Consider the overlaid, red boxes that highlight seven key pieces of information:
113111

114-
:::image type="content" source="media/asan-basic-global-overflow.png" alt-text="Screenshot of the debugger showing a basic global overflow error.":::
112+
:::image type="complex" source="media/asan-basic-global-overflow.png" alt-text="Screenshot of the debugger showing a basic global overflow error.":::
113+
There are seven red highlights identifying key pieces of information in the error report. They map to the numbered list that follows this screenshot. The numbered boxes highlight the following text: 1) global-buffer-overflow 2) WRITE of size 4 3) basic-global-overflow.cpp 7 4) to the right of global variable 'x' defined in 'basic-global-overflow.cpp:3:8' 5) of size 400 6) 00 00[f9]f9 f9 7) Box is in the shadow byte legend area and contains Global redzone: f9
114+
:::image-end:::
115115

116116
### Red highlights, from top to bottom
117117

@@ -138,33 +138,87 @@ To build from the IDE, opt out of any [incompatible options](./asan-known-issues
138138
- Turn off [`/RTC1` (runtime checks)](../build/reference/rtc-run-time-error-checks.md)
139139
- Turn off [`/INCREMENTAL` (incremental linking)](../build/reference/incremental-link-incrementally.md)
140140

141-
To build and run the debugger, enter **F5**. You'll see this window in Visual Studio:
141+
To build and run the debugger, press **F5**. You'll see an **Exception Thrown** window in Visual Studio:
142142

143143
:::image type="content" source="media/asan-global-buffer-overflow-F5.png" alt-text="Screenshot of the debugger showing a global buffer overflow error.":::
144144

145145
## <a name="ide-cmake"></a> Use AddressSanitizer from Visual Studio: CMake
146146

147-
To enable AddressSanitizer for [a CMake project created to target Windows](../build/cmake-projects-in-visual-studio.md), take these steps:
147+
To enable AddressSanitizer for a [CMake project created to target Windows](../build/cmake-projects-in-visual-studio.md), take these steps:
148148

149149
1. Open the **Configurations** dropdown in the toolbar at the top of the IDE and select **Manage Configurations**.
150150

151151
:::image type="content" source="media/asan-cmake-configuration-dropdown.png" alt-text="Screenshot of the CMake configuration dropdown.":::
152152

153-
That selection opens the CMake Project Settings editor, which is saved in a CMakeSettings.json file.
153+
That selection opens the CMake Project Settings editor, which reflects the contents of the `CMakeSettings.json` file in your project.
154154

155155
1. Choose the **Edit JSON** link in the editor. This selection switches the view to raw JSON.
156156

157-
1. Add the property: **"addressSanitizerEnabled": true**
157+
1. Add the following snippet to the `"windows-base"` preset, inside `"configurePresets":` to turn on Address Sanitizer:
158+
159+
```json
160+
"environment": {
161+
"CFLAGS": "/fsanitize=address",
162+
"CXXFLAGS": "/fsanitize=address"
163+
}
164+
```
165+
166+
It will look something like this, afterwards:
167+
168+
```json
169+
"configurePresets": [
170+
{
171+
"name": "windows-base",
172+
"hidden": true,
173+
"generator": "Ninja",
174+
"binaryDir": "${sourceDir}/out/build/${presetName}",
175+
"installDir": "${sourceDir}/out/install/${presetName}",
176+
"cacheVariables": {
177+
"CMAKE_C_COMPILER": "cl.exe",
178+
"CMAKE_CXX_COMPILER": "cl.exe"
179+
},
180+
"condition": {
181+
"type": "equals",
182+
"lhs": "${hostSystemName}",
183+
"rhs": "Windows"
184+
},
185+
"environment": {
186+
"CFLAGS": "/fsanitize=address",
187+
"CXXFLAGS": "/fsanitize=address"
188+
}
189+
},
190+
```
191+
192+
1. Address sanitizer doesn't work if edit-and-continue is specified (`/ZI`), which is enabled by default for new CMake projects. In `CMakeLists.txt`, comment out (prefix with `#`) the line that starts with `set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT"`. That line will look something like this, afterwards:
193+
194+
```json
195+
# set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT "$<IF:$<AND:$<C_COMPILER_ID:MSVC>,$<CXX_COMPILER_ID:MSVC>>,$<$<CONFIG:Debug,RelWithDebInfo>:EditAndContinue>,$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>>")
196+
```
197+
198+
1. Enter **Ctrl+S** to save this JSON file
199+
1. Clear your CMake cache directory and reconfigure: choose **Project** > **Delete cache and Reconfigure**. Choose **Yes** when the prompt appears to clear your cache directory and reconfigure.
200+
1. Replace the contents of the cpp file (for example, `CMakeProject1.cpp`) with the following:
158201

159-
This image is of CMakeSettings.json after that change:
202+
```cpp
203+
// CMakeProject1.cpp : Defines the entry point for the application
204+
205+
#include <stdio.h>
206+
207+
int x[100];
160208

161-
:::image type="content" source="media/asan-cmake-json.png" alt-text="Screenshot of the text editor view of CMakeSettings.json.":::
209+
int main()
210+
{
211+
printf("Hello!\n");
212+
x[100] = 5; // Boom!
213+
return 0;
214+
}
215+
```
162216

163-
1. Enter **Ctrl+S** to save this JSON file, then enter **F5** to recompile and run under the debugger.
217+
1. Choose **F5** to recompile and run under the debugger.
164218

165219
This screenshot captures the error from the CMake build.
166220

167-
:::image type="content" source="media/asan-cmake-error-f5.png" alt-text="Screenshot of the CMake build error message.":::
221+
:::image type="content" source="media/asan-cmake-error-f5.png" alt-text="Screenshot of an exception that says: Address Sanitizer Error: Global buffer overflow". In the background, address sanitizer output is visible in command window:::
168222

169223
## <a name="crash-dumps"></a> AddressSanitizer crash dumps
170224

‎docs/sanitizers/media/asan-basic-global-overflow.png

70.1 KB
Loading

‎docs/sanitizers/media/asan-cmake-configuration-dropdown.png

-224 KB
Loading

‎docs/sanitizers/media/asan-cmake-json.png

-96.9 KB
Binary file not shown.

‎docs/sanitizers/media/asan-global-buffer-overflow-f5.png

-308 KB
Loading

‎docs/sanitizers/media/asan-project-system-dialog.png

-121 KB
Loading

0 commit comments

Comments
 (0)