Write documented procedures and/or code for supporting debugging FreeCAD c++ and python from CLion and VSCode

bgbsww commented 1 week ago

Proposal description

There appear to be no existing documents on how to use the CLion python debugger against FreeCAD, or both the c++ and python debuggers against FreeCAD. I propose to provide up to date instructions and supporting code snippets to allow the use of both the CLion and VSCode debuggers against FreeCAD c++ and python.

Deliverables

CLion documentation: Necessary setup and procedure for running simultaneous c++ and python debuggers against FreeCAD as patches the developer's handbook
VSCode documentation: Necessary setup and procedure for running debuggers against FreeCAD, simultaneously if possible ( POC not complete ). Patches against the developer's handbook
Code snippets: as required for both platforms. Included in developer's handbook if small enough; otherwise placed somewhere the FPA designates.
Patches to FreeCAD to make connection easier

Timeline

I'll complete both within 2 weeks of proposal approval.

Risks and mitigation

I have done the research and testing for the CLion version, and can at least give a convoluted solution here; the risk is that I can't simplify it enough to be easy for everyone to use.

I trust the statements that the VSCode version works, but I haven't yet replicated, so this could have lurking problems

Note that the expected solution uses only TCP sockets and not OS specific attach mechanisms so should be platform agnostic, but there is a risk that it won't work cleanly outside of the linux platforms it is developed on.

Compensation

$1500 for the entire project.

About you

Bradley McLean / bgbsww @gmail on github, on telegram, on discourse.

I am a frequent FreeCAD contributor, hopefully a known quantity in the community. I have worked in this area before.

shaise commented 1 week ago

On what platform will it work?

bgbsww commented 1 week ago

Ah, yes. Well, I have it working on Linux, and the solution path uses tcp sockets and not per-os process communication or debugging mechanisms like ptrace.

So this should be pretty platform agnostic, but it is reasonable to add to the risks, as I have done. Thanks @shaise

oursland commented 1 week ago

@Pesc0 has written some documentation on the following PR: https://github.com/FreeCAD/DevelopersHandbook/pull/52

An older version of build notes I put together for VS Code using conda are at oursland/FreeCAD-Build-Notes.

Pesc0 commented 1 week ago

Oh yes, it would be nice to have those guides finally merged and added to the handbook. Message me or oursland if you need any information about the current vscode setup :)

yorikvanhavre commented 1 week ago

Awesome idea, IMHO anything related to documentation is almost more important than the code itself :) Totally supporting this.

bgbsww commented 1 week ago

Some credit belongs to chennes who ~challenged me to solve this or end in up in a dunking booth at the Illinois State Fair~ asked politely if I thought it was possible. Sliptonic will tell you those are the same thing when you are nerd sniping

Pesc0 commented 1 week ago

Having a good laugh right now :laughing:

macdroid53 commented 5 days ago

I have vscode setup (on Linux) to debug Python. But, I have never been able to get code completion in vscode. I have always suspected it is because the FreeCAD Python is compiled. I know in Blender there is an addon that provide the (I guess) the non compiled Python so vscode can do code completion. Will this effort result in code completion?

bgbsww commented 5 days ago

Code completion is not one of the goals here, so I'm unsure of if this will change that behavior or document the correct settings. I can certainly look, but I think this will be more of a separate question of how the IDE finds or doesn't find the code base it should work on. Also, FreeCAD isn't directly structured like a pure python code base, so may be confusing VSC.

oursland commented 5 days ago

While not a part of the goals, I have written a brief quick-and-dirty guide on how to generate stubs files for Python from the C++ libraries here: https://github.com/FreeCAD/FreeCAD/discussions/16405

In the longer term, better tooling and process for stubs generation should be developed, documented, and added to the FreeCAD source.

bgbsww commented 5 days ago

Ah, that changes things a little. I am willing to incorporate or reference solved problems in my procedures pages - just the scope of this does not include research beyond the (existing) vscode debugging and the (new) CLion debugging. @oursland I'll be in touch on correct crediting should this go forwards; Pesc0 and I have already talked.

bgbsww commented 5 days ago

Also: I am operating under the presumption that the developer's handbook is the right place to put documentation like this, and it can be referenced by the main code base repo as the place to look. If we think we need a guide in the code repo itself, I'm willing to listen to that argument, but my bias is that the web friendly handbook seems correct.

macdroid53 commented 5 days ago

Code completion is not one of the goals here, so I'm unsure of if this will change that behavior or document the correct settings. I can certainly look, but I think this will be more of a separate question of how the IDE finds or doesn't find the code base it should work on. Also, FreeCAD isn't directly structured like a pure python code base, so may be confusing VSC.

I suspect the way Blender does it is the addon is a set of the Python source that is not in .so files and vscode is pointed to that.

In any case it would be nice to not have to have to have breakpoint to find names, arguments, etc.

bgbsww commented 5 days ago

Note to reviewers: If you would prefer an expanded, two phase proposal that includes stub generation, I am willing to add that. Or wait and submit a second proposal if the community doesn't step up and edit that in. That's additional research that I have not-prechecked for approach and feasibility, although there is clearly some prior art.

oursland commented 5 days ago

@bgbsww

Also: I am operating under the presumption that the developer's handbook is the right place to put documentation like this, and it can be referenced by the main code base repo as the place to look. If we think we need a guide in the code repo itself, I'm willing to listen to that argument, but my bias is that the web friendly handbook seems correct.

The Developer's Handbook is the correct location.

In general, I'm an advocate for tying documentation to the code and having relevant documentation changes be required in a code PR that would necessitate a documentation change. This ensures consistency between the code and the documentation. However, I have not made any formal proposals to do so for FreeCAD.

Note to reviewers: If you would prefer an expanded, two phase proposal that includes stub generation, I am willing to add that. Or wait and submit a second proposal if the community doesn't step up and edit that in. That's additional research that I have not-prechecked for approach and feasibility, although there is clearly some prior art.

I agree stub generation should be a separate task from debugging. More work will need to be done to ensure that all necessary stubs are generated. Work towards complete stub generation should be directed at the GitHub Discussion until the scope has been assessed.

FreeCAD / FPA-grant-proposals