diff --git a/docs/workflow/building/coreclr/macos-instructions.md b/docs/workflow/building/coreclr/macos-instructions.md index 8deaf4578bccef..7ac0d0c6e0f859 100644 --- a/docs/workflow/building/coreclr/macos-instructions.md +++ b/docs/workflow/building/coreclr/macos-instructions.md @@ -33,6 +33,16 @@ It is possible to get a macOS ARM64 build using an Intel x64 Mac and vice versa, The Core_Root provides one of the main ways to test your build. Full instructions on how to build it in the [CoreCLR testing doc](/docs/workflow/testing/coreclr/testing.md), and we also have a detailed guide on how to use it for your own testing in [its own dedicated doc](/docs/workflow/testing/using-corerun-and-coreroot.md). +## Debugging information + +The build process puts native component symbol and debugging information into `.dwarf` files, one for each built binary. This is not the native format used by macOS, and debuggers like LLDB can't automatically find them. The native format used by macOS is `.dSYM` bundles. To build `.dSYM` bundles and get a better inner-loop developer experience on macOS (e.g., have the LLDB debugger automatically find program symbols and display source code lines, etc.), build as follows: + +```bash +./build.sh --subset clr --cmakeargs "-DCLR_CMAKE_APPLE_DSYM=TRUE" +``` + +(Note: converting the entire build process to build and package `.dSYM` bundles on macOS by default is tracked by [this](https://github.com/dotnet/runtime/issues/92911) issue.) + ## Native Sanitizers CoreCLR can be built with native sanitizers like AddressSanitizer to help catch memory safety issues. To build the project with native sanitizers, add the `-fsanitize address` argument to the build script like the following: diff --git a/eng/native/functions.cmake b/eng/native/functions.cmake index d4a7e1bee92edb..6629e926afacf6 100644 --- a/eng/native/functions.cmake +++ b/eng/native/functions.cmake @@ -378,7 +378,11 @@ endfunction() function (get_symbol_file_name targetName outputSymbolFilename) if (CLR_CMAKE_HOST_UNIX) if (CLR_CMAKE_TARGET_APPLE) - set(strip_destination_file $.dwarf) + if (CLR_CMAKE_APPLE_DSYM) + set(strip_destination_file $.dSYM) + else () + set(strip_destination_file $.dwarf) + endif () else () set(strip_destination_file $.dbg) endif () @@ -425,7 +429,9 @@ function(strip_symbols targetName outputFilename) OUTPUT_VARIABLE DSYMUTIL_HELP_OUTPUT ) - set(DSYMUTIL_OPTS "--flat") + if (NOT CLR_CMAKE_APPLE_DSYM) + set(DSYMUTIL_OPTS "--flat") + endif () if ("${DSYMUTIL_HELP_OUTPUT}" MATCHES "--minimize") list(APPEND DSYMUTIL_OPTS "--minimize") endif ()