docs: added docs on debugging using breakpoints

[LifeLex]

This PR aims to include docs on how to debug your rust code using breakpoints from python.
It also includes the setup for users of VSCode and an automatic setup for Jupyter Notebook users

[ngoldbaum]

I don't use vs code so I didn't look at that part but I have some suggestions for the lldb/gdb content.

Also maybe you can use a tab switcher so people don't have to see both versions? I'm not sure if the pyo3 docs system has a way to have a clickable tab switch between the gdb and lldb instructions.

[LifeLex]

@ngoldbaum For the tab switcher that will be nice but it will require adding the mdbook-tabs plugin, if you think it is the best option I am keen to do it, I just didn't want to add an extra dependency just for this

[davidhewitt]

Thanks for this, a useful collection of options!

I would be ok to add mdbook-tabs, are you happy to do it as part of this PR?

[davidhewitt]

👍 this is a pretty nice trick!

[LifeLex]

@davidhewitt yeah ofc ! More than happy to add it, I'll add it as part of the next commit

[ngoldbaum]

The tab switcher looks great!

[davidhewitt]

Brilliant, thank you!

[LifeLex]

@davidhewitt There seems to be some kind of problem on the CI pipeline on the merge, specifically with Python3.7, not sure about this issue, is this something you might know why its happening ?

[davidhewitt]

The 3.7 issues should not be blocking, I will fix those separately.

Looks like we have some CI bitrot on both test-debug and also graalpy, I will investigate those and try to unblock the pipeline...

[davidhewitt]

It think like the graalpy issue was caused by github flakiness (I'm getting some timeouts from github releases API this morning, I think that's the likely root cause).

It looks like test-debug is a more general break on the jiff functionality, see #4959 (comment)

[LifeLex]

Makes sense thank you, I did check the Github status page and it looked like they had some issues today.
Perfect so I'm guessing we will be able to merge this when that is fixed, thanks again @davidhewitt !

[WSH032]

@LifeLex, have you tested this on Windows?

As far as I know, there is an issue with debug symbols when using maturin on Windows PyO3/maturin#2213, and there might be a similar issue on MacOS.

[LifeLex]

@WSH032 I haven't because I don't have a windows machine at the moment, but I've tested it on both Linux and MacOS and I had no issues, if you are asking because of the CI issue it feels to me that that is related with something else

[WSH032]

@WSH032 I haven't because I don't have a windows machine at the moment, but I've tested it on both Linux and MacOS and I had no issues, if you are asking because of the CI issue it feels to me that that is related with something else

No, this is not related to the CI issue.

On Windows, debug symbols are in separate .pdb files and need to be in the same directory as the dynamic library to work.

When using maturin, it only copies the .dll file without copying the .pdb file, so the debugger cannot find the breakpoints.

Until PyO3/maturin#2220 is merged, the best solution is to manually copy these .pdb files next to the .pyd (aka, .dll).

I think it would be best to document this.

[ngoldbaum]

@WSH032 would you be willing to update these docs once we merge this PR? You're probably better suited to write any windows-specific instructions than @LifeLex

[WSH032]

@ngoldbaum, sure. I'm happy to contribute to pyo3, it has really helped me a lot.

[davidhewitt]

CI issue it feels to me that that is related with something else

Indeed, the cargo xwin download has been flaky on CI for some time. We cache it so in theory the download being flaky should not block merges, but we have a lot of caches and sometimes GitHub will gc the download. After that we have a little bit of pain until it gets repopulated.

There is probably some work due to improve the cache situation, I will try to write an issue about that...