Copy .pdb files to Editable Installations and Wheels for easier debugging on windows

Hi team, first of all, thank you for developing this awesome tool.

Is your feature request related to a problem? Please describe

I have a project that uses the Mixed Rust/Python layout. After running maturin dev, the project layout looks like this:

my-project
├── Cargo.toml
├── my_project
│   ├── __init__.py
│   ├── bar.py
│   └── lib_name.cp310-win_amd64.pyd
├── README.md
└── src
    └── lib.rs

I then started debugging, but was surprised to find that I couldn’t set breakpoints and saw <unknown> entries in the Rust panic backtrace:

  49:     0x7ffecfdaef5c - CallWindowProcW
  50:     0x7ffecfdae684 - DispatchMessageW
  51:     0x7ffe587e6ccf - PyInit__lib_name
  52:     0x7ffe586207db - <unknown>
  53:     0x7ffe58620e5b - <unknown>
  54:     0x7ffe585d2ae1 - <unknown>
  55:     0x7ffe58565089 - <unknown>
  56:     0x7ffe583b0600 - <unknown>
  57:     0x7ffe583b0e2c - <unknown>
  58:     0x7ffe583b7a63 - <unknown>
  59:     0x7ffe586abb29 - PyInit__lib_name

I realized this was likely due to the lib_name.cp310-win_amd64.pyd/.dll not finding the corresponding .pdb file.

Specifically, cargo build produces both lib_name.dll and lib_name.pdb in the same directory (target\debug\), so there is no problem. However, both maturin dev and maturin build only copy the lib_name.dll to another directory without copying the lib_name.pdb, causing the above issue.

Describe the solution you'd like

Running $env:RUSTFLAGS="--print=link-args"; cargo build, I observed that rustc emits the linker flags /DEBUG and /PDBALTPATH:%_PDB%.

This means that as long as lib_name.cp310-win_amd64.pyd and lib_name.pdb are in the same directory, the debug information should load correctly.

After I manually copied target\debug\lib_name.pdb to my_project\lib_name.pdb, the issue was resolved.

Describe your feature request

I am not an expert in debugging, so if my approach is incorrect or there’s a better solution, please correct me!

I would like maturin to automatically copy the .pdb files to the editable installation directory (my_project\) and also include them in the wheel.

Since developers may not always generate .pdb files, or might modify the /PDBALTPATH:%_PDB% flag, I suggest adding a --pdb[=relative_path] option to maturin.

• When the --pdb option is specified, maturin should copy the .pdb file (with the same name as lib_name.dll) to my_project\lib_name.pdb and include it in the wheel.
• When --pdb="foo\bar.pdb" is specified, maturin should copy the .pdb file to my_project\foo\bar.pdb and place it in the corresponding location in the wheel.
  • This is typically used with /PDBALTPATH:<relative_path>

This would only affect Windows, as debugging information on Linux and macOS can be included within the library file.

Describe alternatives you've considered

Manually copying the .pdb files.

Rejection 1

See https://learn.microsoft.com/en-us/visualstudio/debugger/specify-symbol-dot-pdb-and-source-files-in-the-visual-studio-debugger?view=vs-2022

The debugger only loads .pdb files that exactly match the .pdb files created when an app was built (that is, the original .pdb files or copies). This exact duplication is necessary because the layout of apps can change even if the code itself has not changed.

This means manually copying .pdb files every time maturin dev is re-run, which is not ideal.

Rejection 2

Even if developers manually copy the .pdb files, they cannot include them in the wheel.

Additional context

For local development, the debugging experience without .pdb files is very poor, as I am unable to set breakpoints.

If you're curious, Polars has a clever method for setting breakpoints when debugging Python/Rust code.

For wheel users, not having .pdb files means that Rust panic backtraces will only show <unknown> entries, making it harder to report issues to developers. You can see an example here.