QGIS Developers Guide - Version 3.4 QGIS Project - QGIS Documentation
←
→
Transcription du contenu de la page
Si votre navigateur ne rend pas la page correctement, lisez s'il vous plaît le contenu de la page ci-dessous
QGIS Developers Guide
Version 3.4
QGIS Project
août 16, 2019
Contents
1 Standards de développement QGIS 3
2 Bonnes pratiques pour l’IHM (Interface homme-machine) 15
3 Accès GIT 17
4 Découvrir et aller plus loin avec QtCreator et QGIS 25
5 Tests unitaires 33
6 Processing Algorithms Testing 45
7 Tests de conformité OGC 51
i
ii
QGIS Developers Guide, Version 3.4 Bienvenue sur les pages dédiées au développement de QGIS. Vous trouverez ici les règles, les outils et les étapes qui vous permettront de facilement contribuer avec efficacité au code source de QGIS. Contents 1
QGIS Developers Guide, Version 3.4 2 Contents
CHAPTER 1
Standards de développement QGIS
• Classes
– Noms
– Membres
– Fonctions d’accesseurs
– Fonctions
– Arguments de la fonction
– Valeurs de retour de la fonction
• Documentation de l’API
– Méthode
– Variables membres
• Qt Designer
– Les classes générées
– Dialogues
• Fichiers C++
– Noms
– En-tête standard et licence
• Noms de variable
• Énumérations
• Constantes globales et Macros
• Comments
• Signaux Qt et emplacements
• Edition
– Tabulations
3QGIS Developers Guide, Version 3.4
– Indentation
– Accolades
• Compatibilité API
• Liaisons SIP
– Header pre-processing
– Générer le fichier SIP
– Améliorer le script sipify
• Style de code
– Lorsque c’est possible, utiliser du code générique
– Placez les constantes en premier dans les expressions
– Le caractère espace peut être votre ami
– Placer les commandes sur des lignes séparées
– Indenter les modificateurs d’accès
– Recommandation de lecture
• Crédits pour les contributions
Ces standards doivent être suivis par tous les développeurs de QGIS.
1.1 Classes
1.1.1 Noms
Les classes dans QGIS commencent par Qgs et sont nommées en utilisant le camel case.
Exemples:
• QgsPoint
• QgsMapCanvas
• QgsRasterLayer
1.1.2 Membres
Les noms des membres de classe commencent par un m minuscule et sont composés de majuscules et de minus-
cules.
• mMapCanvas
• mCurrentExtent
Tous les membres d’une classe doivent être privés. Il est FORTEMENT déconseillé de déclarer des membres
publics. Les membres protégés doivent être évités pour que le membre soit accessible depuis des sous-classes
Python, car les membres protégés ne peuvent pas être utilisés à partir des liaisons Python.
Les noms des membres mutables des classes statiques doivent commencer par un s minuscule, mais les noms des
membres constants des classes statiques doivent être en majuscules :
• sRefCounter
• DEFAULT_QUEUE_SIZE
4 Chapter 1. Standards de développement QGISQGIS Developers Guide, Version 3.4
1.1.3 Fonctions d’accesseurs
Les valeurs des membres de la classe doivent être obtenues via les fonctions d’accesseur. La fonction doit être
nommée sans préfixe « get ». Les fonctions d’accesseur pour les deux membres privés ci-dessus seraient:
• mapCanvas()
• currentExtent()
Assurez-vous que les accesseurs sont correctement marqués avec const. Le cas échéant, cela peut nécessiter que
les variables membres du type de valeur en cache soient marquées avec mutable.
1.1.4 Fonctions
Les noms de fonction commencent par une minuscule et se composent de minuscules/majuscules. Le nom de
fonction devrait évoquer sa fonctionnalité.
• updateMapExtent()
• setUserOptions()
Par souci de cohérence avec l’API QGIS existante et avec l’API Qt, les abréviations doivent être évitées. Par
exemple, setDestinationSize au lieu de setDestSize, setMaximumValue au lieu de setMaxVal.
Les acronymes devraient également être nommés en utilisant le camel case pour la cohérence. Par exemple,
setXml au lieu de setXML.
1.1.5 Arguments de la fonction
Les noms des arguments de fonctions doivent être descriptifs. Ne pas utiliser de noms à une seule lettre (p. ex.
setColor( const QColor& color ) plutôt que setColor( const QColor& c )).
Portez une attention particulière à quand les arguments devraient être passés par référence. À moins que les objets
argument soient petits et trivialement copiés (tels que les objets QPoint), ils doivent être passés par une référence
const. Par souci de cohérence avec l’API Qt, même les objets partagés implicitement sont passés par une référence
const (p. ex. setTitle( const QString& title ) au lieu de setTitle( QString title ).
1.1.6 Valeurs de retour de la fonction
Renvoie les objets petits et trivialement copiés en tant que valeurs. Les objets plus grands doivent être renvoyés
par une référence const. La seule exception à cela est implicitement les objets partagés, qui sont toujours renvoyés
par valeur. Renvoie « QObject » ou les objets sous-classes en tant que pointeurs.
• int maximumValue() const
• const LayerSet& layers() const
• QString title() const (QString est implicitement partagée)
• QList< QgsMapLayer* > layers() const (QList is implicitly shared)
• QgsVectorLayer *layer() const; (QgsVectorLayer inherits QObject)
• QgsAbstractGeometry *geometry() const; (QgsAbstractGeometry is abstract and will
probably need to be casted)
1.2 Documentation de l’API
Il est requis d’écrire la documentation API pour chaque classe, méthode, enumération et autres codes disponible
dans l’API publique.
1.2. Documentation de l’API 5QGIS Developers Guide, Version 3.4
QGIS utilise Doxygen pour la documentation. Ecrivez des commentaires descriptifs et utiles qui donnent au
lecteur des informations à propos de à quoi s’attendre, de ce qu’il se passe dans les cas limites et qui donne des
indications à propos d’autres interfaces qu’il pourrait rechercher, les bonnes pratiques et des exemples de code.
1.2.1 Méthode
La description des méthodes doit être écrit sous forme descriptive en utilisant la 3ème personne. Les méthodes
nécessitent le mot-clé since‘ qui définit quand elles ont été introduites.
/**
* Cleans the laundry by using water and fast rotation.
* It will use the provided \a detergent during the washing programme.
*
* \returns True if everything was successful. If false is returned, use
* \link error() \endlink to get more information.
*
* \note Make sure to manually call dry() after this method.
*
* \since QGIS 3.0
* \see dry()
*/
1.2.2 Variables membres
Member variables should normally be in the private section and made available via getters and setters. One
exception to this is for data containers like for error reporting. In such cases do not prefix the member with an m.
/**
* \ingroup core
* Represents points on the way along the journey to a destination.
*
* \since QGIS 2.20
*/
class QgsWaypoint
{
/**
* Holds information about results of an operation on a QgsWaypoint.
*
* \since QGIS 3.0
*/
struct OperationResult
{
QgsWaypoint::ResultCode resultCode; //!< Indicates if the operation completed
˓→successfully.
QString message; //!< A human readable localized error message. Only set if
˓→the resultCode is not QgsWaypoint::Success.
QVariant result; //!< The result of the operation. The content depends on the
˓→method that returned it. \since QGIS 3.2
};
};
1.3 Qt Designer
1.3.1 Les classes générées
Les classes QGIS générées depuis des fichiers Qt Designer (.ui) doivent avoir comme suffixe -Base. Cela permet
d’identifier la classe comme étant une classe générée.
6 Chapter 1. Standards de développement QGISQGIS Developers Guide, Version 3.4
Exemples:
• QgsPluginManagerBase
• QgsUserOptionsBase
1.3.2 Dialogues
Toutes les boîtes de dialogue doivent intégrer des info-bulles d’aide pour toutes les icônes de la barre d’outils ainsi
que pour les autres gadgets appropriés. Ces info-bulles apportent beaucoup à la découverte des fonctionnalités
pour les utilisateurs débutants et confirmés.
Assurez-vous que l’ordre des onglets pour les gadgets est bien mis à jour à chaque fois que la boîte de dialogue de
la couche change.
1.4 Fichiers C++
1.4.1 Noms
L’intégration du C++ et des fichiers en-têtes doivent respectivement avoir une extension en .cpp et en .h. Les
fichiers doivent être nommés intégralement en minuscule et, dans le cas des classes, doivent correspondre avec le
nom des classes.
Exemple : Pour la classe QgsFeatureAttribute, les fichiers sources sont qgsfeatureattribute.cpp
et qgsfeatureattribute.h
Note: Si le cas précédent n’est pas assez claire, pour qu’un nom de fichier corresponde au nom d’une classe,
il est implicite que chaque classe soit déclarée et implémentée par son propre fichier. Cela permet aux nouveaux
développeurs d’identifier plus rapidement le code lié à une classe donnée.
1.4.2 En-tête standard et licence
Chaque fichier source doit contenir une en-tête calquée sur l’exemple qui suit:
/***************************************************************************
qgsfield.cpp - Describes a field in a layer or table
--------------------------------------
Date : 01-Jan-2004
Copyright: (C) 2004 by Gary E.Sherman
Email: sherman at mrcc.com
/***************************************************************************
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
***************************************************************************/
Note: Il existe un modèle pour Qt Creator dans le dépôt Git. Pour l’utiliser, copiez-le depuis doc/
qt_creator_license_template vers un emplacement local, adaptez l’adresse de courrier électronique
et, si requis, le nom du développeur et configurez Qt Creator pour utiliser ce modèle: Outils -> Options ->
C++ -> File Naming.
1.4. Fichiers C++ 7QGIS Developers Guide, Version 3.4
1.5 Noms de variable
Les noms des variables locales commencent par une minuscule et sont formés en utilisant des minuscules et
majuscules. Ne pas utiliser de préfixes comme « my » ou « the ».
Exemples:
• mapCanvas
• currentExtent
1.6 Énumérations
Les énumérations doivent être nommés en CamelCase avec une première lettre en majuscule, ex:
enum UnitType
{
Meters,
Feet,
Degrees,
UnknownUnit
};
N’utilisez pas de noms génériques qui peuvent entrer en conflit avec d’autres types. Par exemple, utilisez
UnkownUnit plutôt que Unknown
1.7 Constantes globales et Macros
Les constantes globales et les macros doivent être écrites en majuscules avec des séparateurs en tirets bas, ex:
const long GEOCRS_ID = 3344;
1.8 Comments
Comments to class methods should use a third person indicative style instead of the imperative style:
/**
* Creates a new QgsFeatureFilterModel, optionally specifying a \a parent.
*/
explicit QgsFeatureFilterModel( QObject *parent = nullptr );
~QgsFeatureFilterModel() override;
1.9 Signaux Qt et emplacements
Toutes les connections de signaux ou emplacements doivent être fait en utilisant les connections « new style »
disponible en Qt5. De plus amples informations sur cette exigence sont disponibles dans « QEP #77 ‘_.
Évité d’utiliser l’emplacement de connexion automatique de Qt (c’est-à-dire ceux nommés ‘‘ void
on_mSpinBox_valueChanged‘‘). Les emplacement à connexion automatique sont fragiles et sujets à des ruptures
sans avertissement si les boîtes de dialogue sont remaniées.
8 Chapter 1. Standards de développement QGISQGIS Developers Guide, Version 3.4
1.10 Edition
N’importe quel éditeur ou EDI peut être utilisé pour éditer le code de QGIS, sous réserve qu’il respecte les pré-
requis suivants:
1.10.1 Tabulations
Paramétrez votre éditeur pour remplacer les tabulations par des espaces. L’espacement d’une tabulation doit être
paramétrée pour occuper deux espaces.
Note: Sous Vim, vous pouvez utiliser set expandtab ts=2
1.10.2 Indentation
Source code should be indented to improve readability. There is a scripts/prepare-commit.sh that looks
up the changed files and reindents them using astyle. This should be run before committing. You can also use
scripts/astyle.sh to indent individual files.
As newer versions of astyle indent differently than the version used to do a complete reindentation of the source,
the script uses an old astyle version, that we include in our repository (enable WITH_ASTYLE in cmake to include
it in the build).
1.10.3 Accolades
Les accolades doivent commencer sur la ligne suivant l’expression:
if(foo == 1)
{
// do stuff
...
}
else
{
// do something else
...
}
1.11 Compatibilité API
Il y a une documentation de l’API pour C++.
Nous essayons de conserver l’API stable et rétrocompatible. Les remises à niveau de l’API doivent être réalisées
d’une manière similaire au code source de Qt, par ex.
class Foo
{
public:
/**
* This method will be deprecated, you are encouraged to use
* doSomethingBetter() rather.
* \deprecated doSomethingBetter()
*/
Q_DECL_DEPRECATED bool doSomething();
1.10. Edition 9QGIS Developers Guide, Version 3.4
/**
* Does something a better way.
* \note added in 1.1
*/
bool doSomethingBetter();
signals:
/**
* This signal will is deprecated, you are encouraged to
* connect to somethingHappenedBetter() rather.
* \deprecated use somethingHappenedBetter()
*/
#ifndef Q_MOC_RUN
Q_DECL_DEPRECATED
#endif
bool somethingHappened();
/**
* Something happened
* \note added in 1.1
*/
bool somethingHappenedBetter();
}
1.12 Liaisons SIP
Certain fichiers SIP sont automatiquement générés en utilisant un script dédié.
1.12.1 Header pre-processing
Toutes les informations pour construire proprement le fichier SIP doivent être présentes dans le fichier d’en-tête
C++. Quelques macros sont disponibles pour ces définitions:
• Use #ifdef SIP_RUN to generate code only in SIP files or #ifndef SIP_RUN for C++ code only.
#else statements are handled in both cases.
• Use SIP_SKIP to discard a line
• Les annotations suivante sont traitées:
– SIP_FACTORY: /Factory/
– SIP_OUT: /Out/
– SIP_INOUT: /In,Out/
– SIP_TRANSFER: /Transfer/
– SIP_PYNAME(name): /PyName=name/
– SIP_KEEPREFERENCE: /KeepReference/
– SIP_TRANSFERTHIS: /TransferThis/
– SIP_TRANSFERBACK: /TransferBack/
• private sections are not displayed, except if you use a #ifdef SIP_RUN statement in this block.
• SIP_PYDEFAULTVALUE(value) can be used to define an alternative default value of the python
method. If the default value contains a comma ,, the value should be surrounded by single quotes '
• SIP_PYTYPE(type) can be used to define an alternative type for an argument of the python method. If
the type contains a comma ,, the type should be surrounded by single quotes '
10 Chapter 1. Standards de développement QGISQGIS Developers Guide, Version 3.4
A demo file can be found in tests/scripts/sipifyheader.h.
1.12.2 Générer le fichier SIP
Le fichier SIP peut être généré en utilisant un script dédié. Par exemple :
scripts/sipify.pl src/core/qgsvectorlayer.h > python/core/qgsvectorlayer.sip
As soon as a SIP file is added to one of the source file (python/core/core.sip, python/gui/gui.sip
or python/analysis/analysis.sip), it will be considered as generated automatically. A test on Travis
will ensure that this file is up to date with its corresponding header.
Older files for which the automatic creation is not enabled yet are listed in python/auto_sip.blacklist.
1.12.3 Améliorer le script sipify
Si des améliorations sont nécessaire pour le script sipify, merci d’ajouter l’élément manquant au fichier
de demonstration tests/scripts/sipifyheader.h et créer l’en-tête attendu tests/scripts/
sipifyheader.expected.si. Ceci sera aussi automatiquement testé sur Travis en tant qu’une unité de
test du script.
1.13 Style de code
Voici quelques trucs et astuces de programmation qui, nous l’espérons, vous aideront à réduire les erreurs, le temps
de développement et la maintenance.
1.13.1 Lorsque c’est possible, utiliser du code générique
Si vous copiez-collez du code, ou si vous écrivez la même chose plusieurs fois, pensez à consolider le code en une
seule fonction.
Cela permettra:
• Autorisez les changements à s’effectuer à un seul endroit plutôt qu’en de multiples emplacements.
• de prévenir le code pourri
• de rendre plus difficile l’évolution différenciée de plusieurs copies au fil du temps, phénomène qui rend plus
difficile la compréhension et la maintenance pour les autres développeurs
1.13.2 Placez les constantes en premier dans les expressions
Placez les constantes en premier dans les expressions
0 == value à la place de value == 0
Cela empêchera les développeurs d’utiliser accidentellement = au lieu de ==, ce qui peut introduire des bogues
logiques et subtils. Le compilateur générera une erreur si vous utilisez accidentellement = à la place de == pour
les comparaisons puisque les constantes ne peuvent pas se voir assigner des valeurs.
1.13.3 Le caractère espace peut être votre ami
Ajouter des espaces entre les opérateurs, les instructions et les fonctions rendent le code plus lisible.
Ce qui est plus facile à lire, ceci:
1.13. Style de code 11QGIS Developers Guide, Version 3.4
if (!a&&b)
ou ceci:
if ( ! a && b )
Note: scripts/prepare-commit.sh will take care of this.
1.13.4 Placer les commandes sur des lignes séparées
Lors de la lecture du code il est facile de rater des commandes, si elles ne sont pas en début de ligne. Lors d’une
lecture rapide, il est courant de sauter des lignes si elles ne semblent pas correspondre avec ce que l’on cherche
dans les premiers caractères. Il est aussi commun de s’attendre à une commande après un conditionnel comme
if.
Considérez ceci:
if (foo) bar();
baz(); bar();
Il est très facile de rater des extraits dans le flux de contrôle. Au lieu de cela, utiliser
if (foo)
bar();
baz();
bar();
1.13.5 Indenter les modificateurs d’accès
Les modificateurs d’accès structurent une classe en sections publique, protégée et privée de l’API. Les mod-
ificateurs d’accès eux-mêmes groupent le code dans cette structure. Indentez les modificateurs d’accès et les
déclarations.
class QgsStructure
{
public:
/**
* Constructor
*/
explicit QgsStructure();
}
1.13.6 Recommandation de lecture
• Effective Modern C++, Scott Meyers
• More Effective C++, Scott Meyers
• Effective STL, Scott Meyers
• Design Patterns, GoF
You should also really read this article from Qt Quarterly on designing Qt style (APIs)
12 Chapter 1. Standards de développement QGISQGIS Developers Guide, Version 3.4
1.14 Crédits pour les contributions
Les contributeurs aux nouvelles fonctionnalités sont encouragés à faire connaître aux gens leur contribution via:
• l’ajout d’une note au fichier de changement lors de la première incorporation du code auquel ils ont con-
tribué, du type:
This feature was funded by: Olmiomland https://olmiomland.ol
This feature was developed by: Chuck Norris https://chucknorris.kr
• writing an article about the new feature on a blog, and add it to the QGIS planet https://plugins.qgis.org/
planet/
• Ajout de leur nom à:
– https://github.com/qgis/QGIS/blob/master/doc/CONTRIBUTORS
– https://github.com/qgis/QGIS/blob/master/doc/AUTHORS
– https://github.com/qgis/QGIS/blob/master/doc/contributors.json
1.14. Crédits pour les contributions 13QGIS Developers Guide, Version 3.4 14 Chapter 1. Standards de développement QGIS
CHAPTER 2
Bonnes pratiques pour l’IHM (Interface homme-machine)
Il est important de suivre les bonnes pratiques d’agencement et de design d’interfaces graphiques qui suivent,
dans l’objectif d’amener de la consistance dans l’affichage des éléments d’interface ainsi que pour permettre aux
utilisateurs d’utiliser instinctivement les boîtes de dialogue.
1. Regrouper les éléments liés entre eux en utilisant des boîtes de groupe: Essayer d’identifier les éléments
qui peuvent être regroupés ensemble et utiliser ensuite des boîtes de groupe avec une étiquette permet-
tant d’identifier le sujet du groupe. Éviter d’utiliser des boîtes de groupe avec un seul élément/contrôle à
l’intérieur.
2. Mettre en majuscule uniquement la première lettre dans les étiquettes, les infobulles, les descriptions et tout
texte qui n’est ni un titre ni une entête: elles doivent être rédigées sous forme d’expression avec la première
lettre en majuscule. Les autres mots doivent être écrits avec la première lettre en minuscule, sauf si ce sont
des noms.
3. Mettre en majuscule la première lettre de tous les mots contenus dans un titre (boîte de groupe, onglet,
entête de vues. . . ), les fonctions (éléments de menus, boutons) et tous les éléments sélectionnables (élé-
ments de liste déroulante, de tableaux. . . ): tous les mots hormis les prépositions de moins de 5 lettres (par
exemple “with” mais “Without”), les conjonctions (par exemple, “and” ou “but”) et les articles (a, an, the).
Cependant, il faudra toujours mettre en majuscule la première lettre des premier et dernier mots.
4. Ne pas mettre de caractère « deux-points » à la fin des étiquettes, des widgets ou des boîtes de groupe:
Ajouter le caractère « deux-points » perturbe la vision et n’apporte aucune signification supplémentaire; ne
pas les utiliser. Il peut être fait exception à cette règle lorsque vous avez deux étiquettes qui se suivent; par
exemple: Label1 Plugin (Path:) Label2 [/path/to/plugins]
5. Éloigner les actions dangereuses des actions sans incidence : Si vous avez des actions de “suppression”
ou “d’effacement”, etc. essayez d’imposer un espace adéquat entre ces actions « dangereuses » et les
actions sans conséquences de manière à ce que les utilisateurs ne cliquent pas par inadvertance sur l’action
dangereuse.
6. Utiliser toujours un QButtonBox pour les boutons “Ok”, “Annuler”, etc: Utiliser une boîte à boutons
permet de s’assurer que l’ordre des boutons “Ok”, “Annuler”, etc. sera cohérent pas rapport au système
d’exploitation, la langue, l’environnement du bureau utilisé par l’utilisateur final.
7. Les onglets ne doivent pas être imbriqués. Si vous utilisez les onglets, suivez le style des onglets de QgsVec-
torLayerProperties / QgsProjectProperties, etc., c’est à dire, des onglets en haut avec des icônes de 22x22.
8. Les empilements de widget doivent être évités le plus possible. Ils causent des problèmes de mise en page
et des re-dimensionnements inexplicables (pour l’utilisateur) pour afficher les widgets non visibles.
15QGIS Developers Guide, Version 3.4
9. Éviter d’utiliser des termes techniques et utiliser plutôt des équivalents simples, ex: utiliser le mot “Trans-
parence” plutôt que “Canal Alpha”, “Texte” à la place de “Chaîne de caractères”, etc.
10. Utilisez une iconographie cohérente. Si vous avez besoin d’icône ou d’éléments d’iĉones, merci de contacter
Robert Szczepanek sur la liste de diffusion pour de l’assistance.
11. Placer les longues listes de contrôles dans des boîtes à défilement (scroll). Aucune boîte de dialogue ne doit
mesurer plus de 580 pixels de haut et 1000 pixels de large.
12. Séparer les options avancées des fonctions basiques. Les utilisateurs novices doivent être capables d’accéder
facilement aux éléments indispensables aux activités basiques sans être inquiétés par la complexité des
fonctionnalités avancées. Les fonctionnalités avancées devraient être placées en dessous d’une ligne de
séparation ou placées dans un onglet séparé.
13. Ne pas ajouter d’option dans le seul objectif d’avoir de nombreuses options. Lutter pour conserver
l’interface utilisateur minimaliste et utiliser des options par défaut adaptées.
14. Si un bouton doit ouvrir une nouvelle boîte de dialogue, des points de suspension (. . . ) doivent être ajoutés
en suffixe du texte du bouton. Assurez-vous de bien utiliser le caractère « U+2026 » du point de suspension
et non trois points consécutifs.
2.1 Auteurs
• Tim Sutton (auteur et éditeur)
• Gary Sherman
• Marco Hugentobler
• Matthias Kuhn
16 Chapter 2. Bonnes pratiques pour l’IHM (Interface homme-machine)CHAPTER 3
Accès GIT
• Installation
– Installation de git pour GNU/Linux
– Installation de git sous Windows
– Installation de git sous macOS
• Accéder au Répertoire
• Basculer vers une branche
• Sources de la documentation de QGIS
• Sources du site web QGIS
• Documentation GIT
• Le développement par branches
– Objectif
– Procédure
– Tester avant de fusionner avec la branche master
• Envoi de correctifs et de demandes
– Envoi des demandes
* Bonnes pratiques pour la création de pull request
* Notifications destinées à la documentation
* Pour fusionner une pull request
• Nom des fichiers de patch
• Créez votre patch à la racine du répertoire des sources QGIS
– Faire en sorte que votre patch soit remarqué
– Vérifications nécessaires
• Obtenir les droits d’écriture dans Git
17QGIS Developers Guide, Version 3.4 Ce chapitre décrit comment se lancer dans l’utilisation du dépôt GIT de QGIS. Avant de commencer, assurez-vous de disposer d’un client git installé sur votre système d’exploitation. 3.1 Installation 3.1.1 Installation de git pour GNU/Linux Les utilisateurs d’une distribution Debian ou dérivée peuvent faire: sudo apt install git 3.1.2 Installation de git sous Windows Les utilisateurs de MS Windows peuvent utiliser msys git ou utiliser le client git distribué avec cygwin. 3.1.3 Installation de git sous macOS Le projet git dispose d’un binaire téléchargeable de git. Assurez-vous de prendre le paquet conforme à votre processeur (x86_64 la plupart du temps, seuls les premiers Macs Intel utiliseront le paquet i386). Une fois téléchargé, ouvrez l’image disque et lancez l’installeur. Note pour l’architecture PPC/Source Le site de git ne met pas à disposition des binaires pour PPC. Si vous en avez besoin ou si vous voulez plus de contrôle sur l’installation, vous devrez compiler git vous-même. Téléchargez les sources depuis https://git-scm.com/. Décompressez-les dans un répertoire. Ouvrez un terminal pointant sur ce répertoire puis : make prefix=/usr/local sudo make prefix=/usr/local install Si vous n’avez pas besoin des extensions, de Perl, de Python ou de TclTk (GUI), vous pouvez les désactiver avant de lancer make avec: export NO_PERL= export NO_TCLTK= export NO_PYTHON= 3.2 Accéder au Répertoire Clôner la branche “master” de QGIS : git clone git://github.com/qgis/QGIS.git 3.3 Basculer vers une branche Pour basculer vers une branche (checkout), par exemple la branche de la version 2.6.1, faites: cd QGIS git fetch git branch --track origin release-2_6_1 git checkout release-2_6_1 18 Chapter 3. Accès GIT
QGIS Developers Guide, Version 3.4
Pour basculer sur la branche maitre:
cd QGIS
git checkout master
Note: Dans QGIS, nous conservons le code le plus stable dans la branche de la version publiée. La branche
master contient le code pour la série de version appelée “non stable”. Périodiquement nous créons une branche à
publier depuis la branche master et non continuons la stabilisation ainsi que l’incorporation sélective de nouvelles
fonctionnalités dans la branche master.
Consultez le fichier INSTALL dans l’arbre des sources pour plus d’instruction sur la compilation des versions de
développement.
3.4 Sources de la documentation de QGIS
Si vous voulez vérifier les sources de la documentation QGIS:
git clone git@github.com:qgis/QGIS-Documentation.git
Vous pouvez également jeter un oeil au fichier Lisez-moi qui est inclus dans le dépôt de la documentation pour
plus d’information.
3.5 Sources du site web QGIS
Si vous voulez vérifier les sources du site web de QGIS:
git clone git@github.com:qgis/QGIS-Website.git
Vous pouvez également jeter un oeil au fichier Lisez-moi qui est inclus dans le dépôt du site web pour plus
d’information.
3.6 Documentation GIT
Consultez les sites suivants pour plus d’information sur Git.
• https://services.github.com/
• https://progit.org
• http://gitready.com
3.7 Le développement par branches
3.7.1 Objectif
La complexité du code source de QGIS s’est considérablement accrue ces dernières années. Dès lors, il est
difficile d’anticiper les effets de bord induits par l’ajout de fonctionnalités. Dans le passé, le projet QGIS avait de
très long cycle de publication du fait du lourd travail à effectuer pour rétablir la stabilité du logiciel après l’ajout
de nouvelles fonctionnalités. Pour dépasser ce problème, QGIS a basculé sur un modèle de développement où
les nouvelles fonctionnalités sont d’abord programmées dans des branches GIT, puis fusionnées avec la branche
3.4. Sources de la documentation de QGIS 19QGIS Developers Guide, Version 3.4
principale (“master”) lorsqu’elles sont finalisées et stables. Cette section décrit la procédure pour créer et fusionner
des branches dans le projet QGIS.
3.7.2 Procédure
• Annonce initiale sur la liste de diffusion : Avant de commencer, faites une annonce sur la liste de diffu-
sion des développeurs pour voir si personne d’autre que vous ne travaille déjà sur la même fonction-
nalité. Prenez également contact avec le conseiller technique du comité de direction du projet (PSC).
Si la nouvelle fonctionnalité impose des changements d’architecture dans QGIS, un avis (RFC) est
obligatoire.
Créer une branche : créer une nouvelle branche GIT pour le développement d’une nouvelle fonctionnalité.
git checkout -b newfeature
Vous pouvez maintenant commencer le développement. Si vous pensez travailler intensément sur cette branche
et que vous voulez partager ce travail avec d’autres développeurs et avoir accès en écriture au dépôt amont, vous
pouvez pousser votre dépôt dans le dépôt QGIS officiel par:
git push origin newfeature
Note: Si la branche existe déjà, les modifications seront ajoutées dans celle-ci.
Rebaser régulièrement vers la branche master: il est recommandé de réaliser un rebasage pour incorporer les
changements de la branche master vers la branche courante, de manière régulière. Cela permet de faciliter la
fusion ultérieure de la branche courante vers la branche master. Après un rebasage, vous devez lancer git push
-f` dans votre dépôt dupliqué.
Note: Ne faites jamais git push -f sur le dépôt d’origine! Ne l’utilisez que dans votre propre branche de
production.
git rebase master
3.7.3 Tester avant de fusionner avec la branche master
Lorsque vous avez terminé avec la nouvelle fonctionnalité et êtes satisfait de sa stabilité, faites une annonce sur la
liste des développeurs. Avant la fusion, les modifications seront testées par les développeurs et les utilisateurs.
3.8 Envoi de correctifs et de demandes
Il y a quelques règles qui vous aideront à obtenir vos correctifs et à extraire facilement les demandes dans QGIS,
et à nous aider à traiter les correctifs envoyés plus facilement.
3.8.1 Envoi des demandes
Il est en général plus facile pour les développeurs que vous soumettiez des pull requests GitHub. Nous ne décrirons
pas le mécanisme de pull requests ici mais vous pouvez vous référer à la documentation GitHub sur les pull
requests.
Si vous avez créé une pull request, nous vous demandons de faire régulièrement une fusion de master vers la
branche de votre PR de manière à ce que cette dernière puisse être toujours fusionnable directement avec la
branche master.
20 Chapter 3. Accès GITQGIS Developers Guide, Version 3.4
Si vous êtes un développeur et que vous voulez évaluer la file de pull requests, il existe un outil simple qui vous
permettra de le faire en ligne de commande.
Merci de consulter le chapitre ci-dessous sur comment “notifier votre patch”. En général, lorsque vous soumettez
une PR, vous devrez prendre la responsabilité de la suivre au long de son intégration, en répondant aux questions
posées par les autres développeurs, trouver un “champion” pour cette fonctionnalité et envoyer un courtois rappel
si vous constatez que votre PR n’attire pas trop l’attention. Merci de garder à l’esprit que QGIS est un projet
conduit par des volontaires et qu’il est probable que votre PR n’attire pas l’attention immédiatement. Si vous
pensez que la PR ne reçoit pas l’attention qu’elle mérite, voici vos options pour accélérer son intégration (par
ordre de priorité):
• Envoyez un message à la liste de diffusion à propos de votre PR pour nous dire combien il est important
qu’elle puisse être intégrée au code principal.
• Envoyer un message à la personne à qui est attribuée la PR dans la liste.
• Envoyer un message à Marco Hugentobler (qui gère la file d’attente des PR)
• Envoyez un message au comité de direction du projet en leur demandant assistance pour incorporer votre
PR au code principal.
Bonnes pratiques pour la création de pull request
• Commencez toujours une nouvelle branche pour une fonctionnalité à partir de la branche master actuelle.
• Si vous développez une branche de nouvelle fonctionnalité, ne fusionnez rien dans cette branche. A la place,
effectuez un rebasement (rebase) comme décrit dans le prochain point, de manière à conserver un historique
propre.
• Avant de créer une pull request, lancez git fetch origin et git rebase origin/master (ori-
gin étant ici le dépôt distant amont et non votre propre dépôt, vérifiez votre fichier .git/config ou
faites: git remote -v | grep github.com/qgis pour identifier le nom utilisé dans votre con-
figuration).
• Vous pouvez faire un git rebase comme dans la ligne précédente de manière répétée sans dommage (du
moment que l’objectif de votre branche est d’être fusionnée dans la branche master).
• Attention, après une opération de rebasement, vous devrez faire un git push -f vers votre dépôt forké.
DÉVELOPPEURS PRINCIPAUX: NE FAITES PAS CELA DANS LE DEPÔT QGIS PUBLIC !
Notifications destinées à la documentation
Outre les tags habituels pour classer votre PR, il existe des tags spéciaux permettant de générer automatiquement
des tickets dans le dépôt de la documentation dès lors que votre PR est accepté.
• [needs-docs] permet aux rédacteurs d’identifier des correctifs ou des améliorations apportées à une
fonctionnalité déjà existante.
• [feature] dans le cas où une nouvelle fonctionnalité est introduite. Fournir une bonne description de
vos modifications est aussi vivement conseillé/apprécié.
Les développeurs sont donc priés de bien vouloir ajouter ces tags (insensibles à la casse) afin de faciliter la
gestion des tickets pour la documentation mais aussi pour l’aperçu global des modifications liées à la version.
Mais, veuillez s’il vous plaît prendre le temps d’ajouter quelques commentaires: soit dans le commit, soit dans la
documentation elle-même.
Pour fusionner une pull request
Option A:
• cliquez sur le bouton merge (crée une fusion sans avance rapide)
Option B:
3.8. Envoi de correctifs et de demandes 21QGIS Developers Guide, Version 3.4
• Vérifiez une pull request
• Test (également requis pour l’option A évidemment)
• checkout master, git merge pr/1234
• En option: git pull --rebase: Crée une avance rapide, aucun commit de fusion n’est réalisé.
Meilleur historique mais il est plus difficile de revenir en arrière.
• git push (NE JAMAIS utiliser l’option -f ici)
3.9 Nom des fichiers de patch
If the patch is a fix for a specific bug, please name the file with the bug number in it e.g. bug777fix.patch, and
attach it to the original bug report in GitHub.
If the bug is an enhancement or new feature, it’s usually a good idea to create a ticket in GitHub first and then
attach your patch.
3.10 Créez votre patch à la racine du répertoire des sources QGIS
Cela permet d’appliquer le patch plus facilement étant donné que nous n’aurons pas besoin de naviguer dans un
emplacement spécifique des sources. De plus, lorsque je reçois des patchs, je les inspecte en utilisant merge et
avoir le patch à la racine du répertoire des sources est bien plus facile. Ci-dessous, voici un exemple pour inclure
plusieurs changements de fichiers dans votre patch à partir de la racine des sources:
cd QGIS
git checkout master
git pull origin master
git checkout newfeature
git format-patch master --stdout > bug777fix.patch
Cela permettra de vous assurer que la branche master est synchronisée avec la branche du dépôt amont et cela
générera un patch contenant le delta entre votre branche de nouvelle fonctionnalité et ce qui se trouve dans la
branche master.
3.10.1 Faire en sorte que votre patch soit remarqué
QGIS developers are busy folk. We do scan the incoming patches on bug reports but sometimes we miss things.
Don’t be offended or alarmed. Try to identify a developer to help you and contact them asking them if they can
look at your patch. If you don’t get any response, you can escalate your query to one of the Project Steering
Committee members (contact details also available in the Technical Resources).
3.10.2 Vérifications nécessaires
QGIS est sous licence GPL. Vous devez vous assurer que vous soumettez des patchs non encombrés de problème
de propriété intellectuelle. Ne soumettez pas de code non disponible sous licence GPL.
3.11 Obtenir les droits d’écriture dans Git
L’accès en écriture à l’arbre des sources QGIS se fait par invitation. Généralement, lorsqu’une personne soumet
plusieurs patchs conséquents (sans nombre fixe de participation) qui démontre de solides compétences et com-
préhension du C++ et des conventions de code QGIS, un des membres du PSC ou d’autres développeurs QGIS
peuvent proposer au PSC de lui fournir les droits d’écriture. La personne qui recommande le nouveau venu doit
22 Chapter 3. Accès GITQGIS Developers Guide, Version 3.4 rédiger un paragraphe promotionnel pour expliquer pourquoi il pense que la personne citée doit obtenir les droits d’écriture. Dans certains cas, nous donnerons accès à des développeurs non C++ comme des traducteurs et des personnes en charge de la documentation. Dans ce cas, la personne doit avoir fait la preuve de son habileté à proposer des patchs et devrait avoir soumis plusieurs patchs démontrant sa compréhension de la modification de la base de code, de manière propre, sans rien casser, etc. Note: Depuis le passage à Git, nous sommes moins enclins à fournir des droits en écriture aux nouveaux développeurs car il est maintenant trivial de partager du code sous GitHub en forkant QGIS et en proposant des pull requests. Merci de vérifier que tout se compile correctement avant de créer des commits ou des pull requests. Essayez de rester attentif aux possibles problèmes que vos commits peuvent générer pour les développeurs compilant sur d’autres plateformes ou avec des versions plus ou moins récentes des différentes bibliothèques. Lorsque vous faites un commit, votre éditeur de texte (défini dans la variable d’environnement $EDITOR) appa- raîtra et vous devriez écrire un commentaire au début du fichier (au dessus de la partie qui indique “ne modifiez pas ceci”). Inscrivez un commentaire descriptif et faites plutôt plusieurs petits commits si vous effectuez des changements sur des fichiers qui ne sont pas liés entre eux. Inversement, nous préférerions que vous regroupiez les changements liés entre eux dans un seul commit. 3.11. Obtenir les droits d’écriture dans Git 23
QGIS Developers Guide, Version 3.4 24 Chapter 3. Accès GIT
CHAPTER 4
Découvrir et aller plus loin avec QtCreator et QGIS
• Installation de QtCreator
• Paramétrer votre projet
• Paramétrez votre environnement de compilation
• Paramétrez votre environnement de lancement
• Exécution et déboguage
QtCreator est un EDI développé par les concepteurs de la bibliothèque Qt. Avec QtCreator, vous pouvez construire
n’importe quel projet C++, mais l’EDI est vraiment optimisé pour les personnes qui travaillent sur des applications
basées sur Qt(4) (y compris les applications mobiles). Tout ce est décrit ci-dessous présume que vous travaillez
avec Ubuntu 11.04 “Natty”.
4.1 Installation de QtCreator
Cette partie est simple:
sudo apt-get install qtcreator qtcreator-doc
Une fois l’installation terminée, vous le trouverez dans votre menu GNOME.
4.2 Paramétrer votre projet
Je suppose que vous avez déjà un clone local de QGIS contenant le code source et que vous avez installé et compilé
toutes les dépendances nécessaires, etc. Vous trouverez des instructions détaillées sous accès git et installation de
dépendances.
Sur mon système j’ai placé le code dans $HOME/dev/cpp/QGIS et le reste de cet article a été rédigé en pré-
sumant de cet emplacement pour ce répertoire. Vous pouvez mettre à jour ces chemins pour les adapter à votre
système local.
Lors du lancement de QtCreator, faire:
25QGIS Developers Guide, Version 3.4 Fichier -> Ouvrir un Fichier ou Projet Utilisez ensuite la boîte de dialogue de sélection de fichier pour naviguer et ouvrir ce fichier: $HOME/dev/cpp/QGIS/CMakeLists.txt Ensuite, on vous demandera l’emplacement d’un répertoire de compilation. Je créé un répertoire dédié au travail de QtCreator: $HOME/dev/cpp/QGIS/build-master-qtcreator Il est généralement bon de séparer les répertoires de compilation par branches différentes, si vous pouvez vous le permettre par rapport à l’occupation disque. 26 Chapter 4. Découvrir et aller plus loin avec QtCreator et QGIS
QGIS Developers Guide, Version 3.4 Ensuite, on vous demandera si vous avez une ou plusieurs options de compilation CMake à transmettre à CMake. Nous allons indiquer à CMake que nous voulons une compilation en mode déboguage en ajoutant l’option suiv- ante: -DCMAKE_BUILD_TYPE=Debug Voilà la base. Une fois que vous avez fermé l’assistant, QtCreator lancera une recherche dans l’arborescence du code source pour la gestion de l’autocomplétion et pour d’autres opérations, en tâche de fond. Avant de lancer la compilation, nous voulons encore paramétrer finement certains éléments. 4.3 Paramétrez votre environnement de compilation Cliquez sur l’icône “Projets” à la gauche de la fenêtre QtCreator. 4.3. Paramétrez votre environnement de compilation 27
QGIS Developers Guide, Version 3.4
Choisissez l’onglet de paramètres de compilation (normalement, actif par défaut).
Nous allons maintenant ajouter une étape supplémentaire. Pourquoi ? Comme QGIS ne peut actuellement être
lancé qu’à partir d’un répertoire d’installation et non depuis le répertoire de construction, il est indispensable de
s’assurer que QGIS est installé lorsqu’il est compilé. Sous “Étapes de compilation”, cliquez sur le bouton “Ajouter
l’étape compiler” et choisissez “Étape personnalisée”.
Maintenant, nous paramétrons les détails suivants:
Autoriser une étape personnalisée: [oui]
Commande: faire
Répertoire de travail: $HOME/dev/cpp/QGIS/build-master-qtcreator
Arguments de la commande: install
28 Chapter 4. Découvrir et aller plus loin avec QtCreator et QGISQGIS Developers Guide, Version 3.4 Vous êtes pratiquement prêts à compiler. Une dernière note: QtCreator a besoin des droits d’écriture sur le répertoire d’installation. Par défaut (ce que j’utilise ici), QGIS sera installé dans /usr/local. Pour mes besoins sur ma machine de développement, je me suis simplement donné des droits d’écriture dans le répertoire /usr/local. Pour commencer la compilation, cliquez sur l’icône en forme de gros marteau dans le coin inférieur gauche de la fenêtre. 4.4 Paramétrez votre environnement de lancement Comme mentionné ci-dessus, nous ne pouvons pas lancer QGIS directement depuis le répertoire de construction et nous devons donc créer une cible de lancement pour indiquer à QtCreator de lancer QGIS à partir du répertoire d’installation (dans mon cas /usr/local/). Pour cela, retournez dans l’écran de configuration des projets. 4.4. Paramétrez votre environnement de lancement 29
QGIS Developers Guide, Version 3.4 Sélectionnez maintenant l’onglet “Paramètres d’exécution”. Nous devons mettre à jour les paramètres d’exécution par défaut en remplaçant la configuration d’exécution “qgis” par une commande personnalisée. Pour cela, cliquez sur le bouton “Ajouter v” à côté de la liste déroulante “Configuration d’exécution” et choisissez “Exécutable personnalisé” à partir du haut de la liste. 30 Chapter 4. Découvrir et aller plus loin avec QtCreator et QGIS
QGIS Developers Guide, Version 3.4
Maintenant, indiquez les éléments suivants dans les propriétés:
Exécutable: /usr/local/bin/qgis
Arguments:
Répertoire de travail: $HOME
Lancer dans un terminal: [non]
Débogueur: C++ [oui]
Qml [no]
Cliquez ensuite sur le bouton “Renommer” et donnez à votre exécutable personnalisé un nom significatif, ex:
“QGIS installé”.
4.5 Exécution et déboguage
Maintenant, vous êtes prêts à lancer et à déboguer QGIS. Pour insérer un point d’arrêt, ouvrez simplement un
fichier source et cliquez dans la colonne de gauche.
Maintenant, lancez QGIS dans le débogueur en cliquant sur l’icône avec un bogue dessus dans le coin en bas à
gauche de la fenêtre.
4.5. Exécution et déboguage 31QGIS Developers Guide, Version 3.4 32 Chapter 4. Découvrir et aller plus loin avec QtCreator et QGIS
CHAPTER 5
Tests unitaires
• L’environnement de test de QGIS: un aperçu
• Créer un test unitaire
– Implementing a regression test
• Comparer des images pour tests de rendu
• Ajouter votre test unitaire à CMakeLists.txt
– La macro ADD_QGIS_TEST expliquée
• Compiler votre test unitaire
• Lancer vos tests
– Debugging unit tests
– Amusez-vous
À partir de novembre 2007 nous exigeons que les nouvelles fonctionnalités de la branche master soient accompa-
gnées d’un test unitaire. Nous avions initialement limité cette exigence à la partie qgis_core et nous allons étendre
ce point aux autres parties du code une fois que les développeurs se seront familiarisés avec les procédures des
tests unitaires, expliquées dans les sections qui suivent.
5.1 L’environnement de test de QGIS: un aperçu
Unit testing is carried out using a combination of QTestLib (the Qt testing library) and CTest (a framework for
compiling and running tests as part of the CMake build process). Lets take an overview of the process before we
delve into the details:
1. Prenons du code que vous voulez tester, par exemple, une classe ou une fonction. Les partisans de la
programmation Extreme suggèrent que l’écriture du code ne commence pas tant que vous n’avez pas lancé
la construction des tests. Ainsi, une fois que vous avez commencé à implémenter votre code, vous pouvez
immédiatement valider chaque nouvelle partie fonctionnelle avec vos tests. Dans la pratique, vous devrez
sans doute écrire des tests pour des parties déjà en place dans QGIS car nous avons lancé l’environnement
de test bien après que la logique de l’application ait été déjà implémentée.
33QGIS Developers Guide, Version 3.4
2. Créez un test unitaire. Tout se passe dans /tests/src/core dans le cas d’une bibliothèque du coeur du
projet. Le test est essentiellement un client qui créé une instance de la classe et l’appelle avec des méthodes
de classe. Cela permet de vérifier que le retour de chaque méthode renvoie bien la valeur attendue. Si un
seul des appels échoue, le test sera également en échec.
3. Incluez les macros QTestLib dans votre classe de test. Cette macro est prise en compte par le compilateur
de méta-objets Qt (moc) et elle transformera votre classe de test en application exécutable.
4. Ajoutez une section au fichier CMakeLists.txt dans le répertoire des tests qui construira votre test.
5. Assurez-vous d’avoir la variable ENABLE_TESTING activée dans ccmake / cmakesetup. Cela permettra
de s’assurer que vos tests seront compilés lorsque vous lancerez make.
6. You optionally add test data to /tests/testdata if your test is data driven
(e.g. needs to load a shapefile). These test data should be as small as possible and wherever possible you
should use the existing datasets already there. Your tests should never modify this data in situ, but rather
make a temporary copy somewhere if needed.
7. Compilez vos sources et installez. Vous pouvez le faire avec le traditionnel make && (sudo) make
install.
8. You run your tests. This is normally done simply by doing make test after the make install step,
though we will explain other aproaches that offer more fine grained control over running tests.
Right with that overview in mind, we will delve into a bit of detail. We’ve already done much of the configuration
for you in CMake and other places in the source tree so all you need to do are the easy bits - writing unit tests!
5.2 Créer un test unitaire
Creating a unit test is easy - typically you will do this by just creating a single .cpp file (not .h file is used)
and implement all your test methods as public methods that return void. We’ll use a simple test class for
QgsRasterLayer throughout the section that follows to illustrate. By convention we will name our test with
the same name as the class they are testing but prefixed with “Test”. So our test implementation goes in a file
called testqgsrasterlayer.cpp and the class itself will be TestQgsRasterLayer. First we add our
standard copyright banner:
/***************************************************************************
testqgsvectorfilewriter.cpp
--------------------------------------
Date : Friday, Jan 27, 2015
Copyright: (C) 2015 by Tim Sutton
Email: tim@kartoza.com
***************************************************************************
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
***************************************************************************/
Next we start our includes needed for the tests we plan to run. There is one special include all tests should have:
#include
Ensuite, vous pouvez implémenter votre classe normalement en ajoutant les en-têtes dont vous pourrez avoir
besoin:
//Qt includes...
#include
#include
#include
34 Chapter 5. Tests unitairesVous pouvez aussi lire
