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

[bgbsww]

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]

On what platform will it work?

[bgbsww]

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]

@Pesc0 has written some documentation on the following PR: FreeCAD/DevelopersHandbook#52

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

[Pesc0]

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]

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

[bgbsww]

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]

Having a good laugh right now 😆

[macdroid53]

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]

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]

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: FreeCAD/FreeCAD#16405

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

[bgbsww]

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]

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]

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]

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.