Skip to content

Commit 21d25d1

Browse files
chenneschennes
authored
Merge pull request #103 from bgbsww/bgbsww-DebuggerInstructions
Add CLion debugging instructions, incorporate existing VSCode debugging instructions
2 parents 8db1b02 + f2da5ab commit 21d25d1

20 files changed

+293
-0
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,6 @@ _site/
1010
.bundle/**
1111
!.bundle/config
1212
vendor/
13+
14+
# Ignore IDE directories
15+
.idea/

‎gettingstarted/CLion.md

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
layout: default
3+
---
4+
5+
# Getting Started
6+
7+
If you don't already have CLion installed, download it, license it, install it per JetBrains instructions.
8+
9+
### Checking out FreeCAD
10+
11+
**Command line:** `git clone https://github.com/FreeCAD/FreeCAD` and then File -> Open or New Project on that directory.
12+
13+
**IDE:** From upper left, choose Project from Version Control. Use https://github.com/FreeCAD/FreeCAD
14+
![Pict8](./resources/CLionPythonDebug8.png)
15+
### Building CMake
16+
17+
CLion should automatically refresh the CMake build for the application. You see results or rerun using the cmake
18+
selection at the lower right
19+
![Pict9](./resources/CLionPythonDebug9.png)
20+
21+
### Building Application
22+
23+
Choose a configuration ( Debug ) and a target ( FreeCADMain ) from the top bar. First time through, use the menus to
24+
run 'Build All in Debug' from the Build Menu. After that point you can generally just Run or Debug and it will build
25+
any dependencies for you. Note that if you switch branches you may sometimes need to "Rebuild All in Debug" to force
26+
a clean full rebuild.
27+
28+
![Pict10](./resources/CLionPythonDebug10.png)
29+
![Pict11](./resources/CLionPythonDebug11.png)
30+
31+
### Running Application
32+
33+
Use the Run or Debug Icons from the top bar shown in the prior image.
34+
35+
## Debugging
36+
37+
*note* This depends on https://github.com/FreeCAD/FreeCAD/pull/16850 getting merged!
38+
39+
While CLion supports both a C++ debugger and a Python debugger, it generally does not support
40+
embedded Python interpreters, nor debugging both simultaneously. However, there are workaround
41+
procedures that will allow this.
42+
43+
### Basic C++ concept
44+
45+
CLion invokes an underlying debugger that launches or connects to the program under
46+
test. You can see this in the "Attach to Process" dialog under the Run menu. After
47+
choosing a process, you will be asked to attach with GDB or LLDB; CLion uses the
48+
appropriate API to communicate with the debugger, which uses OS specific mechanisms
49+
to control the program under test.
50+
51+
### Basic Python concept
52+
53+
The pydevd debugger is run inside of the python interpreter under test. This provides
54+
a network socket, normally connected _from_ the interpreter under test to a listening
55+
socket in the controlling debugger UI. This port defaults to 5678 for non-CLion uses. CLion
56+
generates a random port number, and then passes this into the pydevd initialization code;
57+
if you run a python program then this is accomplished by directly running a shim with
58+
parameters that include the port number and the program to be debugged. In an attach
59+
scenario, CLion _launches a C++ debugger_ to inject the pydevd initialization into the
60+
running python interpreter and cause it to make the socket connection back to the UI. Note
61+
that since you generally cannot have more than one c++ debugger attached to a program,
62+
this mechanism cannot work for a program already under c++ debugging, and since it assumes
63+
that the c++ program is in fact a python process, it won't work for embedded python either.
64+
65+
### Technique for getting Python testing working
66+
67+
The challenge here is to get CLion to listen on a port for the incoming connection from pydevd,
68+
and to execute pydevd on that port in the program under test. Since CLion does not support this
69+
natively, we trick it. To do this we need to have a pydevd installed in the python interpreter in
70+
FreeCAD.
71+
72+
### Running a basic c++ debug
73+
74+
Simply choose the debug option to start FreeCAD, and you're good to go.
75+
76+
### Setting up for python debugging in CLion
77+
78+
Install pydevd in the interpreter that FreeCAD is using. 'pip3 install pydevd' from the correct
79+
venv is one way to accomplish this.
80+
81+
Use the settings button in the upper right, the File Menu -> Settings, or the Ctrl-Alt-S shortcut
82+
to open the settings dialog, expand the Build, Execution, Deployment tree item, and select a Python
83+
Interpreter:
84+
85+
![Pict1](./resources/CLionPythonDebug1.png)
86+
87+
Switch to the Python Debugger settings, and change the Attach To Process name from python to 'Freecad'
88+
You may need to change this back if you use the IDE for other applications.
89+
90+
![Pict2](./resources/CLionPythonDebug2.png)
91+
92+
Now there are three approaches here:
93+
1. Wait for CLion 2024.3 which is supposed to have a static port listener option with a
94+
configurable port available in the 'Python Debugger' pane of the CMake profile you use.
95+
[see context](https://youtrack.jetbrains.com/issue/CPP-5797/Cross-debugging-Python-and-C#focus=Comments-27-10655987.0-0)
96+
and [see planned fix.](https://youtrack.jetbrains.com/issue/PY-21325/Add-an-ability-to-specify-debugger-port) Port should be 5679 if you use the macro below.
97+
2. Find the attach_pydevd.py file in your CLion installation, and modify it using the
98+
contrib/clion/attach_pydevd.py.patch in the source code. Then use the macro below.
99+
3. Use this elaborate work around:
100+
101+
### Running a python or simultaneous debug using the non intrusive procedure
102+
103+
1. You can start your FreeCAD independently, via CLion, or in c++ debug mode under CLion.
104+
105+
2. Regardless of the starting technique, once FreeCAD is up, if there is no code in your FreeCAD supporting
106+
CLion debugging, then:
107+
1. Go to the python console and import pydevd.
108+
Then go ahead and pretype in the settrace call, leaving the cursor poised to enter a port name but not executing the line.
109+
2. Alternatively, go to the Macro -> Attach to remote debugger dialog and switch to the CLion tab.
110+
111+
![Pict1](./resources/CLionPythonDebug6.png)
112+
113+
3. Return to CLion, and start Attach to Process from the run menu:
114+
115+
![Pict1](./resources/CLionPythonDebug3.png)
116+
117+
4. Find the Freecad process, which may be well down at the bottom of the list. It is the configuration
118+
from earlier that makes Freecad processes appear in the list as Python debuggable. Highlight this entry
119+
and press the Attach with Python Debugger button.
120+
121+
![Pict1](./resources/CLionPythonDebug4.png)
122+
123+
5. Now it's time to move FAST. You have about 10 to 15 seconds to complete the following:
124+
Scroll to the top of the console window and find the (random) port number that CLion has chosen to listen
125+
on. Ignore everything else:
126+
127+
![Pict1](./resources/CLionPythonDebug5.png)
128+
129+
6. Switch to the FreeCAD window and complete the port number in either the console's settrace line or the attach dialog
130+
and execute it:
131+
132+
![Pict1](./resources/CLionPythonDebug6.png)
133+
134+
7. Note the appearance of a "Connected to pydev debugger" line in the CLion console. Shortly before or after that
135+
message, you will also see the timeout of CLion's attempt to use a debugger to trigger an attach. Ignore this
136+
error.
137+
138+
![Pict1](./resources/CLionPythonDebug7.png)
139+
140+
8. Proceed to debug normally: any existing breakpoints you have either in c++ code or python code will be hit, you
141+
can step, examine variables, the whole deal.
142+
143+
### Running a python or simultaneous debug using updated CLion or the patched attach_pydevd.py
144+
145+
1. Start FreeCAD running. You can do this from any place for just a python debug; or you can launch a c++ debug
146+
in CLion for simultaneous debugging.
147+
2. Run the contrib/clion/GetCLionDebugPort.FCMacro in FreeCAD. The cleanest way to do this is just to add it as
148+
first parameter of the FreeCAD or FreeCADCmd command line. Editing your FreeCADMain run/debug configuration in
149+
CLion is the best way to do this - set it once, and python debugging is always there whether you run a c++ debug
150+
or not, with no effective performance penalty.
151+
152+
#### Caveats
153+
154+
- Sometimes you may get one spurious breakpoint hit in the python debugger. Just hit the continue run button to keep
155+
going. FreeCAD triggers a python exception during startup, and the default CLion debugger settings are to break on this
156+
- condition.
157+
- The python files are copied from the source into the build directory. You must use these build directory versions
158+
of the python files if you want to set breakpoints. So if you're built to `cmake-build-debug` for instance, then you
159+
- want `cmake-debug-build/Mod/BIM/Arch.py` and not `src/Mod/BIM/Arch.py`. This also means that you need to be careful
160+
when editing files - anything in the build directory is essentially temporary and will be overwritten on the next build,
161+
but if you change something in the source directory then you need to run a build on an appropriate target to copy the
162+
changed python file to the build directory. CLion does not support specifying mapping directories for this python code,
163+
and there is no evidence of it changing soon.

‎gettingstarted/VSCode.md

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
2+
# Getting started with VSCode
3+
4+
A convenient way of working with the FreeCAD source code is to use an IDE or Integrated Development Environment. The FreeCAD repository contains a VSCode configuration which makes it particularly easy to get started with.
5+
6+
Get VSCode here https://code.visualstudio.com/download and Git here https://git-scm.com/downloads
7+
8+
After that go to github and create your own fork of the FreeCAD repository by clicking the fork button. Once that's done, clone your fork to your local computer that you will be using for development.
9+
10+
Note: if you are using VSCode on an Ubuntu based Linux, please avoid using the snap version - it won't work properly with FreeCAD.
11+
12+
```
13+
git clone https://github.com/YourUsername/FreeCAD --recurse-submodules
14+
```
15+
16+
Open VSCode and select `File > Open Folder`, then select the folder where you have cloned your fork of the repo.
17+
18+
Be sure to copy the `.vscode` folder inside `/contrib` to the root directory of the repo (`/.vscode`)
19+
20+
VSCode will probably ask to install the recommended extensions: say `yes`. If it doesn't you'll need to manually install these extensions
21+
```
22+
ms-vscode.cpptools-extension-pack
23+
ms-python.python
24+
```
25+
26+
## Select build configuration
27+
28+
<video autoplay muted playsinline loop src="resources/configure.mp4" type="video/mp4"></video>
29+
30+
First on the bottom left corner, in the status bar, select the build type. Options are:
31+
- debug
32+
- release
33+
- conda debug
34+
- conda release
35+
36+
If you are using conda please select one of the respective ones.
37+
38+
Cmake should automatically configure the project with the selected configuration.
39+
40+
## First build
41+
42+
<video autoplay muted playsinline loop src="resources/build.mp4" type="video/mp4"></video>
43+
44+
Press `Ctrl + Shift + B`, or click the build button with the cog icon in the status bar, or run the `CMake: build` task.
45+
46+
**NOTE:** The first build takes a while.
47+
48+
**NOTE:** If you change configuration (see step above) you will have to build again.
49+
50+
## Launching the built executable and debugging
51+
52+
<video autoplay muted playsinline loop src="resources/debug.mp4" type="video/mp4"></video>
53+
54+
On the left panel go to the debug section and click the little green play button. Alternatively press `F5`. Every time you launch the debugger a build is triggered, to ensure all the latest changes you made to the code are compiled in.
55+
56+
You should see freecad launching and the debugger attaching to the process. If an error pops up the python debugger failed to attach (there's 30 second timeout).
57+
Close FreeCAD and try launching it again. If it still fails try increasing the timeout located in the file `.vscode/scripts/WaitForDebugpy.py`
58+
59+
To debug please refer to the [documentation](https://code.visualstudio.com/docs/editor/debugging#_debug-actions) or search for a tutorial online.
60+
61+
**NOTE:** VSCode has an option called 'run without debugging'. This doesn't work, don't use it. If you just want to run the application launch with `F5` and ignore the debugger.
62+
63+
**NOTE:** There's actually two debuggers: on the top panel you can see a dropdown to select either the c++ debugger or the python one.
64+
65+
**NOTE:** Don't use the restart button. It only restarts the selected debugger, which definitely is not what you want. Instead press the stop button (which stops both debuggers) and launch again.
66+
67+
## Running tests
68+
69+
<video autoplay muted playsinline loop src="resources/testing.mp4" type="video/mp4"></video>
70+
71+
The IDE supports running FreeCAD tests as well. On the left panel go to the testing section and click the play button. A build takes place and then all the tests are run and results reported.
72+
73+
**NOTE:** This is much slower than running the `Tests_run` executable directly. The video above is sped up.
74+
75+
**NOTE:** Only c++ tests are currently integrated. Python tests are run from the `Test workbench` or with the command `FreeCAD -t 0`.
76+
77+
Alternatively, there are two vscode tasks that can be used to run the cpp and python tests directly.
78+
79+
**NOTE:** The debug tests button does not currently work. More configuration is needed to get that to work.
80+
81+
## General features of VSCode
82+
83+
On the left panel you can see the following sections:
84+
85+
- File manager: here you can control fils and search them with `Ctrl+F`. Press `F2` to rename the selected file.
86+
- Source control: here you can control git from the graphical user interface.
87+
- Search: powerful tool that can search all files and replace text.
88+
89+
In the status bar on the bottom:
90+
- You can see which branch you are on and change it from there
91+
- Click the error/warning counter to open the `PROBLEMS` panel. Here you will have a convenient collection of all the compiler warnings, cmake warnings, and problems from the workspace.
92+
93+
General editor useful shortcuts:
94+
- Rename all occurrencies of a symbol (e.g. a function name) with `F2`
95+
- Easily navigate code with the tools in the right click menu. For example `Go to definition` and `Find all references`.
96+
- Press `Ctrl+P` and type a file name to jump to that file.
97+
- Press `Ctrl+F` to search the current file.
98+
- Use `Alt+Up/Down` to move rows of text up and down.
99+
- Use `Ctrl+C/X/V` without selecting any text to copy/cut/paste entire rows.
100+
- Use `Ctrl+Shift+Up/Down` to create more cursors and edit many rows at the same time. Press `Esc` to go back to one cursor.
101+
- Hold `Ctrl` while moving left/right to move the cursor entire words at a time.
102+
- Hold `Shift` while moving left/right/up/down to select text with the cursor.
103+
104+
Read the documentation for more:
105+
106+
- [basic editing](https://code.visualstudio.com/docs/editor/codebasics)
107+
- [code navigaton](https://code.visualstudio.com/docs/editor/editingevolved)
108+
- [refactoring](https://code.visualstudio.com/docs/editor/refactoring)
109+
110+
Other useful extensions, recommended but not necessary are
111+
- ```gruntfuggly.todo-tree```: Scans all the files and reports where particular keywords appear. For example `TODO`, `FIXME`, `BUG`...
112+
113+
- ```mhutchie.git-graph```: Helps visualize git commits and branches.
114+
115+
- ```donjayamanne.githistory```: Adds two buttons to the right-click menu: `git: view file history` and `git: view line history`
116+
117+
118+
![](resources/extensions.png)
119+
120+
- On the very left you can see the `Todo-Tree` extension reporting `TODO`s and `FIXME`
121+
- On the left half you can see the `git graph` extension showing all the commits on different branches. You can click a commit to see exactly what was modified by it.
122+
- On the right half you can see the `git history` of the DocumentObject.cpp file.

‎gettingstarted/index.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,11 @@ that you can run your build system in. For example, on MacOS from the top of a F
7575
- `git branch fixTheThing`
7676
- `git checkout fixTheThing` (or both commands in one go: `git checkout -b fixTheThing`)
7777

78+
## Running and Debugging
79+
80+
- [Visual Studio Code](gettingstarted/VSCode)
81+
- [CLion](gettindstarted/CLion)
82+
7883
## Submitting a PR
7984

8085
The basic process is:

‎gettingstarted/resources/CLionPythonDebug1.png

142 KB
Loading

‎gettingstarted/resources/CLionPythonDebug10.png

141 KB
Loading

‎gettingstarted/resources/CLionPythonDebug11.png

31.3 KB
Loading

‎gettingstarted/resources/CLionPythonDebug2.png

162 KB
Loading

‎gettingstarted/resources/CLionPythonDebug3.png

352 KB
Loading

‎gettingstarted/resources/CLionPythonDebug4.png

213 KB
Loading

0 commit comments

Comments
 (0)