Débogage
Premier test
Avant de passer à la douloureuse phase de débogage, utilisez l'Atelier test pour vérifier si les tests standards fonctionnent correctement. Si ce n'est pas le cas, c'est peut-être dû a une installation défectueuse.
Ligne de commande
Le débogage de FreeCAD est supporté par quelques mécanismes internes. La version en ligne de commande de FreeCAD fournit des options d'aide au débogage :
Ce sont les options actuellement reconnues par FreeCAD 0.19 :
Options génériques :
-v [ --version ] Affiche la version sous la forme d'une chaîne -h [ --help ] Affiche un message d'aide -c [ --console ] Démarre en mode console --response-file arg Peut également être spécifié avec '@name' --dump-config Charge la configuration --get-config arg Affiche la valeur de la clé de configuration demandée
Configuration :
-l [ --write-log ] Ecrit un fichier journal dans : $HOME/.FreeCAD/FreeCAD.log (Linux) $HOME/Library/Preferences/FreeCAD/FreeCAD.log (macOS) %APPDATA%\FreeCAD\FreeCAD.log (Windows) --log-file arg Contrairement à --write-log cela permet de se connecter à un fichier arbitraire -u [ --user-cfg ] arg Fichier de configuration utilisateur pour charger/enregistrer les paramètres utilisateur -s [ --system-cfg ] arg Fichier de configuration pour charger/enregistrer les paramètres du système -t [ --run-test ] arg Cas de test - ou 0 pour tous -M [ --module-path ] arg Chemin de module supplémentaire -P [ --python-path ] arg Autres chemins Python --single-instance Autoriser à exécuter une seule instance de l'application
Générer un Backtrace
Si vous exécutez une version de FreeCAD à partir de l'extrémité saillante de la courbe de développement, il se peut qu'il se "bloque". Vous pouvez aider à résoudre ces problèmes en fournissant aux développeurs une "backtrace". Pour ce faire, vous devez exécuter une "version de débogage" du logiciel. "Debug build" est un paramètre qui est défini au moment de la compilation, donc vous devrez soit compiler vous-même FreeCAD, soit obtenir une version "debug" précompilée.
Pour Linux
Linux Debugging →
Prérequis :
- le package logiciel gdb installé
- une version de débogage de FreeCAD (pour l'instant uniquement disponible par compilation à partir des sources)
- un modèle FreeCAD qui provoque un crash.
Étapes : Entrez ce qui suit dans votre fenêtre de terminal :
Trouvez le binaire FreeCAD sur votre système :
$ whereis freecad
freecad: /usr/local/freecad <--- for example
$ cd /usr/local/freecad/bin
$ gdb FreeCAD
GNUdebugger affichera des informations d’initialisation. Le (gdb) montre que GNUDebugger est en cours d’exécution dans le terminal, entrez maintenant :
(gdb) handle SIG33 noprint nostop
(gdb) run
FreeCAD va maintenant démarrer. Effectuez les étapes qui provoquent le crash ou le blocage de FreeCAD, puis entrez dans la fenêtre du terminal :
(gdb) bt
Cela va générer une longue liste de ce que le programme faisait quand il s'est planté ou gelé. Incluez ceci avec votre rapport de problème.
(gdb) bt full
Affiche également les valeurs des variables locales. Ceci peut être combiné avec un nombre pour limiter le nombre d'images affichées.
Pour macOS
macOS Debugging →
Prerequis :
- logiciel lldb installé
- une version de débogage de FreeCAD
- un modèle FreeCAD qui provoque un crash
Étapes: Entrez ce qui suit dans la fenêtre de votre terminal :
$ cd FreeCAD/bin
$ lldb FreeCAD
LLDB générera des informations d’initialisation. Le (lldb) montre que le débogueur s'exécute dans le terminal, entrez maintenant :
(lldb) run
FreeCAD va maintenant démarrer. Effectuez les étapes qui provoquent le crash ou le blocage de FreeCAD, puis entrez dans la fenêtre du terminal :
(lldb) bt
Cela va générer une longue liste de ce que le programme faisait quand il s'est bloqué ou arrêté. Incluez ceci avec votre rapport de problème.
Liste des bibliothèques chargées par FreeCAD
(Applicable à Linux et macOS)
Parfois, il est utile de comprendre quelles bibliothèques FreeCAD charge, en particulier s'il y a plusieurs bibliothèques en cours de chargement du même nom mais de versions différentes (collision de versions). Afin de voir quelles bibliothèques sont chargées par FreeCAD lorsqu'il se bloque, vous devez ouvrir un terminal et l'exécuter dans le débogueur. Dans une deuxième fenêtre de terminal, découvrez l'ID du processus de FreeCAD :
ps -A | grep FreeCAD
Utilisez l'ID retourné et transmettez-le à lsof
:
lsof -p process_id
Cela affiche une longue liste de ressources chargées. Ainsi, par exemple, si vous essayez de vérifier si plusieurs versions de la bibliothèque Coin3d sont chargées, faites défiler la liste ou recherchez directement Coin dans la sortie :
lsof -p process_id | grep Coin
Débogage Python
Pour une approche plus moderne du débogage de Python, consultez les articles suivants :
- Debugging macros with VS 2017
- Python workbenches debugging
- python3.dll, Qt5Windgets.dll, Qt5Gui.dll and Qt5Core.dll not found
winpdb
winpdb Debugging →
Voici un exemple d'usage de Winpdb dans FreeCAD :
Nous avons besoin du débogueur Python : Winpdb. Si vous ne l'avez pas installé, vous pouvez le faire sous Ubuntu/Debian avec :
sudo apt-get install winpdb
Vous pouvez maintenant configurer le débogueur.
- Démarrez Winpdb.
- Définissez le mot de passe du débogueur sur "test" : Allez dans le menu "Fichier" → "Mot de passe" et définissez le mot de passe.
Nous allons maintenant exécuter étape par étape un script de test Python dans FreeCAD.
- Lancez winpdb et définissez le mot de passe (par exemple, test)
- Créer un fichier Python avec ce contenu
import rpdb2
rpdb2.start_embedded_debugger("test")
import FreeCAD
import Part
import Draft
print "hello"
print "hello"
import Draft
points=[FreeCAD.Vector(-3.0,-1.0,0.0),FreeCAD.Vector(-2.0,0.0,0.0)]
Draft.makeWire(points,closed=False,face=False,support=None)
- Démarrer FreeCAD et charger le fichier ci-dessus dans FreeCAD
- Appuyez sur F6 pour l'exécuter
- Maintenant, FreeCAD ne répondra plus car le débogueur Python attend
- Passez à l'interface graphique de Windpdb et cliquez sur "Attacher". Après quelques secondes, un élément "<Input>" apparaît où vous devez double-cliquer
- Maintenant, le script actuellement exécuté apparaît dans Winpdb.
- Définir une pause à la dernière ligne et appuyez sur F5
- Maintenant, appuyez sur F7 pour entrer dans le code Python de Draft.makeWire
Code Visual Studio (VS Code)
VS Code Debugging →
Prerequis :
- Le paquet ptvsd doit être installé dans un Python 3 en dehors de FreeCAD, puis le module doit être copié dans le dossier de la bibliothèque Python de FreeCAD.
# In a cmd window that has a path to you local Python 3:
pip install ptvsd
# Then if your Python is installed in C:\Users\<userid>\AppData\Local\Programs\Python\Python37
# and your FreeCAD is installed in C:\freecad\bin
xcopy "C:\Users\<userid>\AppData\Local\Programs\Python\Python37\Lib\site-packages\ptvsd" "C:\freecad\bin\Lib\site-packages\ptvsd"
Documentation du code Visual Studio pour debugging à distance
Étapes :
- Ajoutez le code suivant au début de votre script
import ptvsd
print("Waiting for debugger attach")
# 5678 is the default attach port in the VS Code debug configurations
ptvsd.enable_attach(address=('localhost', 5678), redirect_output=True)
ptvsd.wait_for_attach()
- Ajoutez une configuration de débogage dans le Code Visual Studio Debug → Add Configurations….
- La configuration doit ressembler à ceci :
"configurations": [ { "name": "Python: Attacher", "type": "python", "request": "attach", "port": 5678, "host": "localhost", "pathMappings": [ { "localRoot": "${workspaceFolder}", "remoteRoot": "." } ] },
- Dans VS Code, ajoutez un point d'arrêt où vous voulez.
- Lancez le script dans FreeCAD. FreeCAD se fige en attendant la pièce jointe.
- Dans VS Code commencez le débogage en utilisant la configuration créée. Vous devriez voir des variables dans la zone du débogueur.
- Lors de la mise en place de points d'arrêt, VS Code se plaindra de ne pas trouver le fichier .py ouvert dans l'éditeur VS Code.
- Changer "remoteRoot" : "." en "remoteRoot" : "<directory of file>"
- Par exemple, si le fichier Python se trouve dans /home/FC_myscripts/myscript.py.
- Changez en : "remoteRoot" : "/home/FC_myscripts"
- Si vous ne faites que déboguer les macros FreeCAD depuis le dossier des macros FreeCAD, et que ce dossier est "C:/Users/<userid>/AppData/Roaming/FreeCAD/Macro", alors utilisez :
- "localRoot" : "C:/Users/<userid>/AppData/Roaming/FreeCAD/Macro",
- "remoteRoot" : "C:/Users/<userid>/AppData/Roaming/FreeCAD/Macro".
- Changer "remoteRoot" : "." en "remoteRoot" : "<directory of file>"
- Si votre macro ne trouve pas ptvsd alors que vous l'avez installé quelque part, faites précéder 'import ptvsd' par
from sys import path
sys.path.append('/path/to/site-packages')
Où le chemin est celui du répertoire où ptvsd a été installé.
- Sur le bord inférieur gauche de VSCode, vous pouvez choisir l'exécutable Python - il est préférable de choisir la version fournie avec FreeCAD.
Dans le paquetage Mac c'est /Applications/FreeCAD.App/Contents/Resources/bin/python.
Vous pouvez le trouver sur votre système en tapant
import sys
print(sys.executable)
dans la console Python de FreeCAD.
With LiClipse and AppImage
LiClipse Debugging →
- Extract AppImage.
> ./your location/FreeCAD_xxx.AppImage --appimage-extract
> cd squashfs-root/
- The sqashfs-root location is where the debugger later on is hooked up to.
- Make sure you can start a fc session from within the squashfs-root location.
squashfs-root> ./usr/bin/freecadcmd
- Should start up a freecad commandline session.
- Install LiClipse.
- Comes ready with pydev and has installers for all platforms.
- For linux it is just to extract (to any location) and run.
- Configure liclipse for debugging.
- Right-click pydev icon (upper right corner) and choose customize.
- Activate "PyDev Debug" (through checkbox, or it might be needed to go to tab "Action Set Availability" and activate there first).
- In the pydev menu you can now choose "start debug server".
- Use menu window/open perspective/other > debug.
- Right-click debug icon (upper right corner) and choose customize.
- Checking "Debug" brings the debugging navigation tools to the toolbar.
- Open preferences through menu window/preferences.
- In PyDev/Interpreters add "new Interpreter by browsing".
- The added interpreter should be:
your loc/squashfs-root/usr/bin/python
. - If you are only using this for fc, you can add AddOn workbench folders as well, or do that in a pydev-project later on.
- Right-click pydev icon (upper right corner) and choose customize.
- Find path to
pydevd.py
in your liclipse installation.- Something along the lines of:
your location/liclipse/plugins/org.python.pydev.xx/pysrc
.
- Something along the lines of:
- Create a regular pydev-project in liclipse.
- Import external sources, for example a macro that you want to debug, or an external workbench.
- In that macro (or workbench .py file) add the code lines:
import sys; sys.path.append("path ending with /pysrc") import pydevd; pydevd.settrace()
- This is where the execution will halt when the macro is run.
- Start the liclipse debug server (menu pydev).
- Start fc.
squashfs-root> ./usr/bin/freecad
- Run the macro (or any other file with a
pydevd.settrace()
trigger) from within freecad, as you would normally do.
- Happy debugging.
- The use of LiClipse for remote debugging, and the steps described here related to liclipse, should work on any platform. The parts related to AppImage is for linux only.
Débogage d'OpenCasCade
Pour les développeurs qui ont besoin d'approfondir le noyau d'OpenCasCade, l'utilisateur @abdullah a créé un fil de discussion qui explique comment le faire.
- Scripts FreeCAD : Python, Introduction à Python, Tutoriel sur les scripts Python, Débuter avec les scripts
- Modules : Modules intégrés, Unités, Quantity
- Ateliers : Création d'atelier, Commands Gui, Les commandes, Installer des ateliers supplémentaires
- Maillages et objets Parts : Scripts Mesh, Script de données topologiques, Conversion objet Mesh en Part, PythonOCC
- Objets paramétriques : Objets créés par script, Viewproviders (Icône personnalisée dans l'arborescence)
- Scénographie : Graphe de scène Coin (Inventor), Pivy
- Interface graphique : Création d'interface, Création d'une boite de dialogue (1, 2, 3, 4, 5), PySide, Exemples PySide débutant, intermédiaire, expérimenté
- Macros : Macros, Comment installer des macros
- Intégration : Intégrer FreeCAD, Intégration de FreeCADGui
- Autre : Expressions, Extraits de codes, Fonction - tracer une ligne, Bibliothèque mathématique vectorielle de FreeCAD (déprécié)