How to Build C++ Projects with the Address Sanitizer on Windows memory bug detection via compiler extension

22.09.2020 Alessandro Ambrosano 5 comments

Memory bugs are tricky. Leaks have a clear impact on performance, and quickly become hard to spot when heap allocated objects move too much. Memory access bugs, on the other hand, make your program crash right away, if you’re lucky. In less desirable cases, they may end up corrupting random objects on the heap, and only end up in a crash much later. Or even worse, leading to undetected undefined behaviours or wrong computations.

This is the reason why there are a number of standalone tools (e.g. valgrind, Dr.Memory), as well as compiler extensions (e.g. AddressSanitizer, MemorySanitizer, LeakSanitizer) to help with memory bug detection.

On Windows, and especially using Qt, things are a bit harder, as valgrind is not an option and Dr.Memory often crashes with Qt applications. Unless you use WSL, this only leaves compiler tools on the table.

Memory Sanitizers on Windows

First of all, what are our choices when it comes to using memory sanitizers on Windows?

There are two options:

1. with Visual Studio’s cl compiler
   • VS2019 v16.4 and above – x86/Release builds only (experimental) – AddressSanitizer only
   • VS2019 v16.7 and above {x86,amd64}/{Release,Debug} builds – AddressSanitizer only
2. with LLVM’s clang/clang-cl compilers (also available through Visual Studio)
   • {x86,amd64}/Release builds only – AddressSanitizer only

So using AddressSanitizer (from now on ASAN) is the only viable option for memory bug detection with memory sanitizers on Windows. Also, since the support for the cl compiler is still incomplete, in this post we will be using clang.

Furthermore, we will be using Visual Studios’s bundled clang to make it possible to generate Visual Studio solutions. If you’re using your own clang installation, you should update the following paths accordingly. You can find Visual Studio 2019’s clang in the following directories:

• For x86: %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Professional\VC\Tools\Llvm\bin
• For x64: %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Professional\VC\Tools\Llvm\x64\bin

Note that you will need to add the right directory manually to the PATH when using the command line, as there is no vcvars script available for clang tools.

From now on I’m going to assume for all paths that we’re using Visual Studio 2019 Professional and we’re building 64 bit applications.

Compile an executable with the static C++ runtime (/MT)

If you build and link in one go, it is enough to compile with -fsanitize=address

clang-cl -fsanitize=address main.cpp

When doing compilation and linking in separate steps, we need an extra step to provide the ASAN runtime explicitly.

clang-cl -fsanitize=address -c main.cpp -o main.o
# Call vcvars64 here so lld-link will be able to link all the default libraries
lld-link main.o -libpath:"%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Professional\VC\Tools\Llvm\x64\lib\clang\10.0.0\lib\windows" ^
    -wholearchive:clang_rt.asan-x86_64.lib -wholearchive:clang_rt.asan_cxx-x86_64.lib

The linker will implicitly link the program against the static CRT (/MT) and with the static version of clang’s ASAN runtime. Note the use of -wholearchive to force the compiler to include all the symbols from the library, avoiding optimizations.

If the program consumes a library which is also being sanitized, then said library (which should be linked against the dynamic CRT with /MD) should be linked against clang_rt.asan_dll_thunk-x86_64.lib. In this way, the library (or libraries) will use the shadow memory of the statically linked ASAN runtime in the executable.

Compile an executable with the dynamic C++ runtime (/MD)

Again, it is easy to compile and link in one go:

clang-cl -fsanitize=address /MD main.cpp

But now the executable should use a different ASAN runtime when linked:

clang-cl -fsanitize=address -c main.cpp -o main.o
# Call vcvars64 here so all the default libraries are added to lld-link
lld-link main.o -libpath:"%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Professional\VC\Tools\Llvm\x64\lib\clang\10.0.0\lib\windows" ^
    clang_rt.asan_dynamic-x86_64.lib -wholearchive:clang_rt.asan_dynamic_runtime_thunk-x86_64.lib

Note that only clang_rt.asan_dynamic_runtime_thunk-x86_64.lib needs the -wholearchive flag here.

All the included dlls that are also sanitized (which should always be using the dynamic CRT) should be linked against the same ASAN runtime libraries as the executable.

Since clang_rt.asan_dynamic-x86_64.lib is an import lib pointing to clang_rt.asan_dynamic-x86_64.dll, when running a sanitized executable (or loading a sanitized lib) its folder should be in the PATH. You can find the dll alongside the .lib in %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Professional\VC\Tools\Llvm\x64\lib\clang\10.0.0\lib\windows.

Using ASAN with CMake

If you want to use ninja or any other generator other than Visual Studio, just point CMake to your clang-cl installation and add the necessary flags to your targets. Adjust your flags for plain clang if you don’t need or don’t care about clang-cl.

add_executable(exec main.cpp)
target_compile_options(exec PRIVATE -fsanitize=address) # /MD will be used implicitly
target_link_directories(exec PRIVATE "${ENV:PROGRAMFILES\(X86\)}/Microsoft Visual Studio/2019/Professional/VC/Tools/Llvm/x64/lib/clang/10.0.0/lib/windows")
target_link_libraries(exec PRIVATE clang_rt.asan_dynamic-x86_64 clang_rt.asan_dynamic_runtime_thunk-x86_64)
target_link_options(exec PRIVATE /wholearchive:clang_rt.asan_dynamic_runtime_thunk-x86_64.lib)

CMake will always need to be invoked with -DCMAKE_BUILD_TYPE=Release otherwise the compilation will fail.

To generate a Visual Studio solution, you need to pass a few extra arguments to CMake:

• Generate a Visual Studio solution: -G "Visual Studio 16 2019"
• Choose between 32 or 64 bit target: -A {Win32,x64}
• Use the clang toolkit: -T ClangCL

Or, if you are using Visual Studio Code just select the right entry from the kit list (e.g. Clang 10.0.0 for MSVC with Visual Studio Professional 2019 Release (amd64)).

Conclusions

Using tools to track down memory bugs helps saving time and effort, especially on complex projects. On Windows, the available tooling is limited, and a step by step documentation on how to use what’s available may be hard to come by. With this blog post, it will be hopefully easier for you to leverage the AddressSanitizer on Windows and keep memory bugs in your projects under control.

If you’d like to learn more about the tooling available for C++ developers working with Microsoft Windows on the desktop, you might be interested in our Debugging and Profiling C++ Applications on Windows training.