docs: Add debugging section to contributing docs

[mcrumiller]

This is the followup to #9962, which ended up more of a research project. Thanks to @SeanTroyUWO for figuring out how to attach the Rust debugger to a Python process, which was the most important step to all of this.

This PR introduces a really nice and easy way to set up debugging in VS Code. It allows you to F5 a python script and halt on breakpoints in both your Python and Rust code. The setup is just 2 (maybe 3) steps, which are:

1. Install the LLDB extension in VS Code, and:
2. Add some configuration to your launch.json file.
3. (if necessary) Disable ptrace protection

I added documentation in CONTRIBUTING.md that explains how to set it up (which is easy). There's also a new README.md in the /debug folder that I added, which contains the script used by the debugging config.

I've been using this all the time since I set it up and I would encourage others to do so too and try it out.

[reswqa]

That's great and exactly what I'm looking forward to. Before seeing this, I used to rewrite Python code into equivalent Rust code to debug.(´I`)

[alexander-beedie]

Nice one! Looks incredibly useful :)

Wondering if anybody could add similar guidance for PyCharm/CLion IDEs? (@ritchie46, I recall you use these?) I haven't gone much past dbg! when I'm playing down in the Rust layer, so actually attaching a debugger and walking through the code would feel quite luxurious, heh.

[c-peters]

Love this!

For me the code ran, but lldb gave an error at the end. In order for it to work I had to disable ptrace protection like was mentioned in #9962

echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

[mcrumiller]

@c-peters what OS/system are you running on? I'll add a note in there if I can figure out why some people seem to need to run that.

Edit: I added an optional step for disabling ptrace using your command. I don't have a /yama folder in my WSL, so it's probably only enabled on certain distributions I guess? I wonder if I should document more and/or there are other commands required for people on other distributions.

[c-peters]

I'm on Ubuntu 22.04

[mcrumiller]

Wondering if anybody could add similar guidance for PyCharm/CLion IDEs?

@alexander-beedie it's possible, I'm not familiar with PyCharm or Clion at all. The key element here was that VSCode has a way for debug configurations to "detect" patterns in the debug console and trigger a configuration launch when that pattern appears. The mechanism here is that when the "debug my file" configuration is run, it runs the launch.py script which prints the current pID to the debug console, which then triggers the rust LLDB debugger to attach to the current process using that pID.

[c-peters]

I also got it to work on CLion following this guide: https://www.jetbrains.com/help/clion/debugging-python-extensions.html#debug-custom-py. You can either go for option 1, but that will get annoying fast. If you follow option 2 setting the following custom build target does the trick for me.

[mcrumiller]

Thanks @c-peters. I'll install CLion after work and see if I can get this running and see if I can get into this PR.

Edit: I don't have a license and don't want to pay for it just to make this PR. Perhaps in the future someone else can figure out how to make this work in other IDEs.

@stinodego or @ritchie46 do you want any other improvements for this PR, or are we good to go?

[ritchie46]

@stinodego you are VS-code user right. I leave this one to you.

[reswqa]

@mcrumiller I'm a jetBrains user, I can help verify it, but I suggest not blocking this PR. :)

[stinodego]

I think this is great stuff we should have in our contributing guide somewhere. I'll give this a try sometime this week.

But I am right now in the process of restructuring our docs, including contributing information. So I'd prefer to wait a moment with merging this.

Give it a week or two, and this information will be nicely incorporated in our shiny new Polars docs 👌

[mcrumiller]

Hey @stinodego, I just rebased on main and moved the docs to the new contributing section. Let me know if this is what you had in mind, or if you have any suggested to the documentation. I saw someone on Discord asking about this so I think it's a useful section/feature.

[Kai-Striega]

Thanks @c-peters. I'll install CLion after work and see if I can get this running and see if I can get into this PR.

Edit: I don't have a license and don't want to pay for it just to make this PR. Perhaps in the future someone else can figure out how to make this work in other IDEs.

@mcrumiller JetBrains offers free all products pack for free and open source development. Maybe you could make the argument that it's worth giving you a copy to try it out?

https://www.jetbrains.com/community/opensource/#support

They have also released Rust Rover their version of a rust IDE for free, maybe it's worth trying on that?

[mcrumiller]

@mcrumiller JetBrains offers free all products pack for free and open source development. Maybe you could make the argument that it's worth giving you a copy to try it out?

Thanks @Kai-Striega, I did not know that. I may reach out to them.

[stinodego]

Took me a long time to get back to this one, but it's ready to be merged!

[mcrumiller]

Thanks @stinodego! I think this one will really be helpful to people. I use it all the time.

I think it might be worth adding a quick example with a walk-through, but I'm not sure if I want to make it any longer than it is. What do you think?

[stinodego]

I think it might be worth adding a quick example with a walk-through, but I'm not sure if I want to make it any longer than it is. What do you think?

What did you have in mind exactly? The section already reads like a step-by-step walkthrough of how to set it up and then how to run the debugger. I followed it and it was completely clear to me. I don't think it needs anything else. We don't have to explain the basics of debugging in VSCode, that's best left for the official VSCode docs, in my opinion.

EDIT: I went ahead and merged it as-is, possible adjustments can be made in a separate PR!

[mcrumiller]

Ok great. I was imagining showing an actual sample script and saying "set a breakpoint here in the code", but you're right, that's too much hand-holding and it also be difficult to keep up with code changes.