From 927aa57a4e9c27f4f0aa3db453988603a1738abf Mon Sep 17 00:00:00 2001 From: Matthew Hoffman Date: Fri, 9 May 2025 10:22:29 -0500 Subject: [PATCH] Document ASAN (with leak detection) on MacOS (#8716) * Revert "Optional CMake flag for enabling ASAN for backend and its tests. (#8696)" This reverts commit 543b93939ae03fd0d9d1373c5160a231e061df77. There were other already existing ways to achieve this without the need for new flags. * Add documentation on running with ASAN and leak detection on mac. BUGS=[398198310] --- docs_src/src/SUMMARY.md | 1 + docs_src/src/notes/asan_ubsan.md | 41 ++++++++++++++++++++++++++++++++ filament/backend/CMakeLists.txt | 20 ---------------- ios/samples/README.md | 3 ++- 4 files changed, 44 insertions(+), 21 deletions(-) create mode 100644 docs_src/src/notes/asan_ubsan.md diff --git a/docs_src/src/SUMMARY.md b/docs_src/src/SUMMARY.md index 7b756517f4..bf81247de2 100644 --- a/docs_src/src/SUMMARY.md +++ b/docs_src/src/SUMMARY.md @@ -18,6 +18,7 @@ - [Metal](./notes/metal_debugging.md) - [Vulkan](./notes/vulkan_debugging.md) - [SPIR-V](./notes/spirv_debugging.md) + - [Running with ASAN and UBSAN](./notes/asan_ubsan.md) - [Libraries](./notes/libs.md) - [bluegl](./dup/bluegl.md) - [bluevk](./dup/bluevk.md) diff --git a/docs_src/src/notes/asan_ubsan.md b/docs_src/src/notes/asan_ubsan.md new file mode 100644 index 0000000000..230795c8f4 --- /dev/null +++ b/docs_src/src/notes/asan_ubsan.md @@ -0,0 +1,41 @@ +# Running with ASAN/UBSAN + +## Enabling + +When building though build.sh, pass the `-b` flag. This sets the cmake variable +`FILAMENT_ENABLE_ASAN_UBSAN=ON` which eventually passes `"-fsanitize=address -fsanitize=undefined"` +to all compile and link operations. + +If building through CMake directly, or an IDE like CLion that doesn't use build.sh, instead pass +`-DFILAMENT_ENABLE_ASAN_UBSAN=ON` to cmake in order to get the same result. + +## Getting memory leak detection on Mac + +Memory leak detection isn't enabled by default on MacOS. There are two issues to address, first is +using a version of clang that supports memory leak detection and second is enabling it at runtime. + +The version of clang distributed by Apple (with a version like "Apple clang version 16.0.0") doesn't +currently support leak detection at all. Instead you will need to get or build a different LLVM, +such as the one distributed through homebrew and get CMake to use that instead. + +Then during runtime you'll need to have the environment variable `ASAN_OPTIONS` include the option +`detect_leaks=1`. Multiple `ASAN_OPTIONS` values are concatenated with `:`. + +## Getting memory leak output in CLion + +### Setting variables + +Under `Settings | Build, Execution, Deployment | Dynamic Analysis Tools | Sanitizers` there is an +ASAN Settings field that overrides whatever other `ASAN_OPTIONS` you might set elsewhere, so you +must use that instead of setting it through your Run/Debug Configuration. + +To pass `-DFILAMENT_ENABLE_ASAN_UBSAN=ON` to CMake you'll want to create a new CMake Profile and +pass it as a CMake argument. + +### Avoiding losing output + +CMake will consume ASAN output and display it through a separate "Sanitizers" tab. Unfortunately +certain leak detection errors that interrupt the executable seem to not show up in this tab, but are +still removed from the user-visible console output. If this is happening and you need to see the +unfiltered console output you'll need to go to `Settings | Build, Execution, Deployment | Dynamic +Analysis Tools | Sanitizers` and uncheck "Use visual representation for Sanitizer's output". diff --git a/filament/backend/CMakeLists.txt b/filament/backend/CMakeLists.txt index 9d8dfae47d..6669898637 100644 --- a/filament/backend/CMakeLists.txt +++ b/filament/backend/CMakeLists.txt @@ -5,18 +5,6 @@ set(TARGET backend) set(PUBLIC_HDR_DIR include) set(GENERATION_ROOT ${CMAKE_CURRENT_BINARY_DIR}) -# ================================================================================================== -# Compilation options -# ================================================================================================== -# -set(BACKEND_SANITIZATION "" CACHE STRING "Sanitization option") -set_property(CACHE BACKEND_SANITIZATION PROPERTY STRINGS ";ASAN") - -set(BACKEND_SANITIZERS) -if (BACKEND_SANITIZATION STREQUAL "ASAN") - set(BACKEND_SANITIZERS -fsanitize=address) -endif() - # ================================================================================================== # Sources and headers # ================================================================================================== @@ -484,7 +472,6 @@ target_compile_options(${TARGET} PRIVATE ${OSMESA_COMPILE_FLAGS} $<$:${OPTIMIZATION_FLAGS}> $<$,$>:${DARWIN_OPTIMIZATION_FLAGS}> - ${BACKEND_SANITIZERS} ) if (FILAMENT_SUPPORTS_METAL) @@ -495,8 +482,6 @@ if (FILAMENT_SUPPORTS_WEBGPU) target_compile_definitions(${TARGET} PRIVATE $<$:FILAMENT_WEBGPU_IMMEDIATE_ERROR_HANDLING>) endif() -target_link_options(${TARGET} PRIVATE ${BACKEND_SANITIZERS}) - target_link_libraries(${TARGET} PRIVATE ${OSMESA_LINKER_FLAGS} $<$,$>:${LINUX_LINKER_OPTIMIZATION_FLAGS}> @@ -566,8 +551,6 @@ if (APPLE AND NOT IOS) test/test_RenderExternalImage.cpp) add_library(backend_test STATIC ${BACKEND_TEST_SRC}) target_link_libraries(backend_test PUBLIC ${BACKEND_TEST_LIBS}) - target_compile_options(backend_test PRIVATE ${BACKEND_SANITIZERS}) - target_link_options(backend_test PRIVATE ${BACKEND_SANITIZERS}) set(BACKEND_TEST_DEPS OSDependent @@ -606,7 +589,6 @@ if (APPLE AND NOT IOS) # linker from removing "unused" symbols. target_link_libraries(backend_test_mac PRIVATE -force_load backend_test) set_target_properties(backend_test_mac PROPERTIES FOLDER Tests) - target_link_options(backend_test_mac PRIVATE ${BACKEND_SANITIZERS}) # This is needed after XCode 15.3 set_target_properties(backend_test_mac PROPERTIES BUILD_WITH_INSTALL_RPATH TRUE) @@ -616,8 +598,6 @@ endif() if (LINUX) add_executable(backend_test_linux test/linux_runner.cpp ${BACKEND_TEST_SRC}) - target_compile_options(backend_test_linux PRIVATE ${BACKEND_SANITIZERS}) - target_link_options(backend_test_linux PRIVATE ${BACKEND_SANITIZERS}) target_link_libraries(backend_test_linux PRIVATE ${BACKEND_TEST_LIBS}) set_target_properties(backend_test_linux PROPERTIES FOLDER Tests) endif() diff --git a/ios/samples/README.md b/ios/samples/README.md index 4c132849ee..fc72408c70 100644 --- a/ios/samples/README.md +++ b/ios/samples/README.md @@ -102,7 +102,8 @@ project in Xcode to see changes take effect. ## Building iOS Samples with ASan / UBSan -1. Turn on ASan / UBSan in Filament's top-level CMakeLists.txt by uncommenting the following line: +1. Turn on ASan / UBSan in Filament's top-level CMakeLists.txt by passing + `-DFILAMENT_ENABLE_ASAN_UBSAN=1` to trigger the following line: ``` set(EXTRA_SANITIZE_OPTIONS "-fsanitize=undefined -fsanitize=address")