Paramétrage de l’EDI pour la création et le débogage d’extensions

Bien que chaque développeur dispose de son EDI/éditeur de texte préféré, voici quelques recommandations pour paramétrer les EDI populaires pour créer et déboguer des extensions QGIS en Python.

Note sur la configuration de l’EDI sous Windows

On Linux there is no additional configuration needed to develop plug-ins. But on Windows you need to make sure you that you have the same environment settings and use the same libraries and interpreter as QGIS. The fastest way to do this, is to modify the startup batch file of QGIS.

If you used the OSGeo4W Installer, you can find this under the bin folder of your OSGoeW install. Look for something like C:\OSGeo4W\bin\qgis-unstable.bat.

Voici ce que vous avez à faire pour utiliser l’IDE Pyscripter:

  • Make a copy of qgis-unstable.bat and rename it pyscripter.bat.

  • Ouvrez-le dans un éditeur et supprimez la dernière ligne, celle qui lance QGIS.

  • Add a line that points to the your Pyscripter executable and add the commandline argument that sets the version of Python to be used (2.7 in the case of QGIS 2.0)

  • Ajoutez également un argument qui pointe vers le répertoire où Pyscripter peut trouver les DLL Python utilisées par QGIS. Vous pouvez le trouver dans le répertoire bin de votre installation OSGeo4W

    @echo off
SET OSGEO4W_ROOT=C:\OSGeo4W
call "%OSGEO4W_ROOT%"\bin\o4w_env.bat
call "%OSGEO4W_ROOT%"\bin\gdal16.bat
@echo off
path %PATH%;%GISBASE%\bin
Start C:\pyscripter\pyscripter.exe --python25 --pythondllpath=C:\OSGeo4W\bin

Désormais, lorsque vous cliquerez sur ce fichier batch, il lancera Pyscripter avec le chemin correct.

More popular that Pyscripter, Eclipse is a common choice among developers. In the following sections, we will be explaining how to configure it for developing and testing plugins. To prepare your environment for using Eclipse in Windows, you should also create a batch file and use it to start Eclipse.

To create that batch file, follow these steps.

  • Locate the folder where file:qgis_core.dll resides in. Normally this is C:OSGeo4Wappsqgisbin, but if you compiled your own QGIS application this is in your build folder in output/bin/RelWithDebInfo

  • Localisez votre exécutable eclipse.exe.

  • Créez le script qui suit et utilisez-le pour démarrer Eclipse lorsque vous développez des extensions QGIS.

call "C:\OSGeo4W\bin\o4w_env.bat"
set PATH=%PATH%;C:\path\to\your\qgis_core.dll\parent\folder
C:\path\to\your\eclipse.exe

Débogage à l’aide d’Eclipse et PyDev

Installation

Afin d’utiliser Eclipse, assurez-vous d’avoir installé

  • Eclipse
  • Aptana Eclipse Plugin or PyDev
  • QGIS 2.0

Préparation de QGIS

There is some preparation to be done on QGIS itself. Two plugins are of interest: Remote Debug and Plugin reloader.

  • Go to Plugins ‣ Fetch python plugins
  • Search for Remote Debug ( at the moment it’s still experimental, so enable experimental plugins under the Options tab in case it does not show up ). Install it.

  • Cherchez l’extension Plugin reloader et installez-la de la même manière. Elle vous permettra de recharger une extension sans avoir à redémarrer QGIS.

Configuration d’Eclipse

Sous Eclipse, créez un nouveau projet. Vous pouvez choisir Projet Général et relier vos sources réels plus tard. L’endroit où vous placez le projet n’est donc pas vraiment important.

../../_images/eclipsenewproject.png

Projet Eclipse

Now right click your new project and choose New ‣ Folder.

Click [Advanced] and choose Link to alternate location (Linked Folder). In case you already have sources you want to debug, choose these, in case you don’t, create a folder as it was already explained

Désormais, votre arbre de fichiers sources est présent dans la vue Explorateur de Projet et vous pouvez commencer à travailler avec le code. Vous pouvez profiter dès maintenant de la coloration syntaxique ainsi que des autres puissants outils de votre EDI.

Configurer le débogueur

Pour faire fonctionner le débogueur, basculez dans la perspective de Débogage d’Eclipse (Fenêtre ‣ Ouvrir une perspective ‣ Autre ‣ Debug).

Maintenant, démarrez le serveur de débogage PyDev en choisissant PyDev=>Démarrez Serveur de Débogage.

Eclipse is now waiting for a connection from QGIS to its debug server and when QGIS connects to the debug server it will allow it to control the python scripts. That’s exactly what we installed the Remote Debug plugin for. So start QGIS in case you did not already and click the bug symbol .

Now you can set a breakpoint and as soon as the code hits it, execution will stop and you can inspect the current state of your plugin. (The breakpoint is the green dot in the image below, set one by double clicking in the white space left to the line you want the breakpoint to be set)

../../_images/breakpoint.png

Point d’arrêt

Une chose très intéressante que vous pouvez désormais utiliser est la console de débogage. Assurez-vous que l’exécution est parvenue à un point d’arrêt avant de commencer.

Ouvrez la vue Console ((Fenêtre ‣ Montrer la vue). Elle montrera la console Serveur de débogage ce qui n’est pas très intéressant. Mais il existe un bouton [Ouvrir Console] qui vous permet de basculer vers la console de débogage PyDev. Cliquez sur la flèche près de [Ouvrir Console] et choisissez Console PyDev. Une fenêtre apparaît, vous demandant quelle console vous souhaitez lancer. Choisissez Console PyDev Debug. Dans le cas où ce choix est grisé et qu’on vous demande de démarrer le débogueur et de sélectionner le cadre valide, assurez-vous que le débogueur à distance est bien connecté et que vous êtes sur un point d’arrêt.

../../_images/console-buttons.png

Console de débogage de PyDev

vous avez maintenant une console interactive qui vous permet de tester n’importe quelle commande du contexte courant. Vous pouvez manipuler les variables ou lancer des appels à l’API, ou ce que vous voulez.

Un point un peu ennuyeux: chaque fois que vous saisissez une commande, la console bascule vers le Serveur de Débogage. Pour stopper ce comportement, vous pouvez cliquer sur le bouton Attacher la Console lorsque vous êtes sur la page du serveur de débogage. Ce choix devrait perdurer tout le long de la session de débogage courante.

Permettre à Eclipse de comprendre l’API

Une fonctionnalité très pratique est de faire en sorte qu’Eclipse tienne compte de l’API de QGIS. Cela vous permet de vérifier les erreurs de syntaxe. Cela permet également à Eclipse de vous aider grâce au complément automatique du code en fonction des appels à l’API.

Pour faire tout cela, Eclipse analyse les fichiers de bibliothèque QGIS et en récupère toute l’information utile. La seule chose que vous avez à faire est de dire à Eclipse où trouver ces bibliothèques.

Cliquez sur Fenêtre ‣ Préférences ‣ PyDev ‣ Interpreteur ‣ Python.

Vous pourrez observer la configuration de l’interpréteur Python dans la partie supérieure de la fenêtre (pour le moment Python 2.7) ainsi que des onglets dans la partie inférieure. Les onglets qui vous intéressent sont nommés Bibliothèques et Compilation forcée.

../../_images/interpreter-libraries.png

Console de débogage de PyDev

Ouvrez d’abord l’onglet Bibliothèques. Ajoutez un nouveau répertoire et choisissez le répertoire Python de votre installation QGIS. Si vous ne savez pas où est situé ce répertoire (il ne s’agit pas du répertoire des extensions), ouvrez QGIS et démarrez une console Python et entrez simplement qgis en pressant Entrée. Cela vous montrera quel module QGIS est utilisé ainsi que son chemin. Supprimer la fin du chemin qui contient /qgis/__init__.pyc et vous avez l’emplacement que vous cherchez.

You should also add your plugins folder here (on Linux it is ~/.qgis/python/plugins).

Next jump to the Forced Builtins tab, click on New... and enter qgis. This will make Eclipse parse the QGIS API. You probably also want eclipse to know about the PyQt4 API. Therefore also add PyQt4 as forced builtin. That should probably already be present in your libraries tab.

Cliquer sur OK et c’est fini.

Note: every time the QGIS API changes (e.g. if you’re compiling QGIS master and the SIP file changed), you should go back to this page and simply click Apply. This will let Eclipse parse all the libraries again.

Pour une autre configuration d’Eclipse pour travailler avec des extensions Python de QGIS, consultez ce lien

Débogage à l’aide de PDB

Si vous n’utilisez pas d’EDI comme Eclipse, vous pouvez déboguer vos extensions en utilisant PDB et en suivant les étapes qui suivent.

D’abord, ajoutez ce code à l’endroit que vous souhaitez déboguer:

# Use pdb for debugging
import pdb
# These lines allow you to set a breakpoint in the app
pyqtRemoveInputHook()
pdb.set_trace()

Ensuite exécutez QGIS depuis la ligne de commande.

On Linux do:

$ ./Qgis

On Mac OS X do:

$ /Applications/Qgis.app/Contents/MacOS/Qgis

Lorsque votre application atteint le point d’arrêt, vous pouvez taper des commandes dans la console !

**A FAIRE : **

Ajouter des informations sur les tests