Include debug symbols in MacOS for 3.12+

[pablogsal]

I think PBS should support the flag I added to ensure the macos builds have a good debugging experience. For this, I would like to change the macOS build so it passes --with-dsymutil to CPython's ./configure, enabling the generation and distribution of .dSYM bundles alongside the built interpreter and shared libraries.

On macOS, debug symbols work differently from Linux. When compiling and linking are done separately, debug symbols stay in the object files: the shipped executable is missing debugging info. A separate call to dsymutil is needed to package the debug symbols into a dSYM bundle that can be distributed with the package.

Starting with Python 3.12, CPython introduced the --with-dsymutil configure option, which automatically packages debug information in interpreter builds for macOS, enabling users to use lldb and other debuggers to debug Python crashes and use native profilers.

Currently, python-build-standalone's macOS builds do not pass this flag, meaning:

• Crashes cannot be symbolicated with lldb
• Native profilers (e.g. Instruments, sample, perf via Rosetta) produce unsymbolicated output
• Tools like [memray](https://github.com/bloomberg/memray) that rely on DWARF info for native-mode profiling cannot resolve Python frames

Most macOS binaries for Python don't include debug information, so reports produced on macOS can be much less accurate. The linker includes only a "debug map" in the executable pointing to object files; dsymutil must then read this map, load DWARF info from the .o files, relocate all addresses, and output a single binary with all DWARF information at their final linked addresses.

Including debug symbols in packages facilitates easier debugging and troubleshooting of issues encountered by users, and developers benefit from having access to debug symbols when investigating issues reported by users.

Users of python-build-standalone who rely on it for toolchain distribution (e.g. via uv, rye, PyOxidizer, etc.) currently have no way to get a macOS Python with proper dSYM bundles without rebuilding from source themselves.

Affected Builds

• x86_64-apple-darwin
• aarch64-apple-darwin
• All Python versions ≥ 3.12 (where --with-dsymutil is natively supported in CPython's configure)

Notes

• Care should be taken to ensure object files are still present on disk at the time dsymutil is invoked, as the tool reads from them to extract DWARF info.
• This is orthogonal to a --with-pydebug / assertions build — it's purely about distributable debug symbols, not a debug interpreter.

References

• CPython --with-dsymutil option: Add an option to include debug information in the Python executable and shared libraries in MacOS python/cpython#95973
• pyenv tracking issue: Include debug symbols in MacOS for 3.9-3.11 pyenv/pyenv#2466
• conda-forge discussion: Debug symbols on macOS conda-forge/python-feedstock#354
• memray native mode docs: https://bloomberg.github.io/memray/native_mode.html

[indygreg]

I guess I assumed CPython included the debug symbols on macOS. TIL.

I wholeheartedly support making the debug symbols available for PBS builds. Oversight on my part they weren't there from the beginning of PBS.

[pablogsal]

I guess I assumed CPython included the debug symbols on macOS. TIL.

I want to make this by default in 3.15 but before it needs to be manually added

[geofft]

Same, I didn't realize it didn't. +1 and now I'm wondering if we should also add a test case to make sure we can get symbolicated backtraces out of the distribution on all platforms.

perf via Rosetta

... Is this a thing?

[pablogsal]

... Is this a thing?

Yeah macOS allows to use Rosetta inside docker to run x86_64 binaries an the sgymbolification just works (kind of)!

But indeed the dSYM angle doesn't apply there since you're fully inside a Linux VM anyway. Sorry for the confusion