astral-sh / astral-sh/python-build-standalone
Include debug symbols in MacOS for 3.12+
- Dominant language
- Python
- Stars
- 4.4k
- Forks
- 314
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 27
Description
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)](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: https://github.com/python/cpython/issues/95973
- pyenv tracking issue: https://github.com/pyenv/pyenv/issues/2466
- conda-forge discussion: https://github.com/conda-forge/python-feedstock/issues/354
- memray native mode docs: https://bloomberg.github.io/memray/native_mode.html
Contributor guide
Assessment
This issue has not been assessed yet.