Programmation D/Outils

Éléments avancés du langage

Annexes

Programmation D

[ Modifier le sommaire ]

Éléments avancés du langage

Annexes

Compilation et débogage en ligne de commande

Compilation

Pour compiler un programme D, il vous aurez besoin du compilateur ldc et de la bibliothèque standard tango.

Le compilateur ldc offre de nombreuses options de compilation. Vous pouvez lister toutes ces options en tapant :

$ ldc --help

Je vous présente l'usage courant que j'ai du compilateur :

ldc -w -g -O2 src/*.d -od build/ -of build/monProgramme -D -Dd doc/

Ne vous inquiétez pas, les différents arguments sont très simples :

l'option -w pour activer les warnings afin que le compilateur donne des messages clairs pour améliorer votre code
l'option -g pour générer les informations de debug, très utile quand on recherche un bogue dans notre programme
l'option -O2 permet d'optimiser le code machine (il existe 5 niveaux O0 O1 O2 O3 O4 O5)
ensuite vient le chemin vers le dossier contenant les fichiers sources *.d
l'option -od spécifie dans quel répertoire mettre les fichier .o (binaires)
l'option -of spécifie le nom et l'emplacement du fichier exécutable, ici build/monProgramme
l'option -D permet de générer la documentation
l'option -Dd spécifie le dossier où sera mise la documentation

Debogage

Pour déboguer une application écrite en D, vous pouvez utiliser gdb, tout simplement ! Il existe deux cas de figure de l'utilisation de gdb :

déboguer les erreurs de compilation

$ gdb --args <ligne de commande pour compiler>
(gdb) run

soit d'après l'exemple précédent :

$ gdb --args ldc -w -g -O2 src/*.d -od build/ -of build/monProgramme -D -Dd doc/
(gdb) run

déboguer le fichier exécutable d'une application D (valable si l'option -g est utilisée) :

$ gdb monProgramme
(gdb) run

La documentation

Je vous ai déjà donné un aperçu dans Les commentaires. Le compilateur ldc offre la possibilité de générer de la documentation et de la formater pour avoir une belle mise en page html.

La syntaxe

La documentation est structurée en sections.

Qu'est-ce qu'une section ? Sémantiquement parlant, une section est une chaîne de caractères suivie par ':' (attention, les sections sont sensibles à la casse).

Résumé

La section « résumé » est une section n'étant pas soumise à une chaîne de caractères suivie par ':'. Cette section correspond simplement au premier paragraphe et est optionnelle.

/**
 * Ceci est un résumé qui 
 * tient sur un paragraphe
 */

Description

La section « description » est une section n'étant pas soumise à une chaîne de caractères suivie par ':'. Cette section correspond au paragraphe qui suit la section « résumé », tant qu'il ne rencontre aucune section spécifiée par une chaîne de caractères suivie par ':'.

/**
 * Ceci est un résumé qui 
 * tient sur un paragraphe
 *
 * Ceci est une description
 * paragraphe n°1
 *
 * Ceci est une description
 * paragraphe n°2
 */

Auteurs

Cette section liste les auteurs de la manière suivante :

/**
 * Authors: bioinfornatics J. Mercier, bioinfornatics@gmail.com
 */

Bogues

Cette section liste les bogues connus de la manière suivante :

/**
 * Bugs: aucun bogue signalé.
 */

Date

/**
 * Date: September 25, 2010
 */

Dépréciation

/**
 * Deprecated: cette fonction est dépréciée. Utilisez maintenant la nouvelle fonction foo().
 */

Exemples

Cette section permet de documenter avec des exemples. Un exemple d'utilisation de cette section :

/**
 * Examples:
 * Stdout.formatln("3"); // Écrit "3" sur la sortie standard
 */

Historique

Cette section permet d'écrire les différentes modifications effectuées sur la portion de code à la manière d'un « changelog ».

/**
 * History:
 *     version 1 est la version initiale
 *     version 2 ajoute les fonctionnalités suivantes : support de la 3D, utilisation d'un nouveau moteur graphique
 */

Licence

Cette section permet d'écrire la licence sous laquelle est publiée le code.

/**
 * License: GPLv3+
 */

Retour

Cette section détaille la valeur retournée par la fonction. Cette section est évidement inutile pour les fonctions de type void.

/**
 * Returns: Le contenu du fichier
 */

Voir aussi

Cette section décrit les choses se rapprochant du code documenté. Il peut notamment contenir des liens (URL).

/**
 * See_Also:
 *    foo, bar, http://www.dsource.org/projects/tango/docs/stable/
 */

Standards

Cette section permet de spécifier si la partie documentée est en accord avec un quelconque standard que l'on aura défini.

/**
 * Standards: Conforme avec DSPEC-1234
 */

Exception

Cette section permet de lister les exceptions et les circonstances qui les déclenchent.

/**
 * Throws: EcritException est déclenché si l'execution rencontre un echec
 */
void EcrireFichier(char[] nomFichier) { … }

Version

Cette section permet de spécifier la version courante du bloc documenté.

/**
 * Version: 1.6a
 */

Mise en évidence

Avec du code HTML

La documentation autorise l'écriture de portions de code html

 /**
  * <ul>
  * <li> <a href="http://www.dsource.org/projects/tango/">Tango</a></li>
  * <li> <a href="http://www.dsource.org/projects/tango/docs/stable/">Tango Documentation</a></li>
  * </ul>
  */

Sections spéciales

Copyright

Cette section informe sur le copyright. La macro COPYRIGHT prend la valeur de la section quand cette dernière est renseignée. Ce comportement particulier apparaît seulement quand cette section est utilisée pour documenter un module.

/**
 * Copyright: Domaine Publique
 */
module foo;

Params

Cette section permet de documenter les paramètres que prend une fonction. Pour cela, on doit lister chaque paramètre. Chaque ligne commence par le nom de la variable suivi de "=" puis de sa description. La description peut s'étendre sur plusieurs lignes.

/**
 * foo fait plein de choses
 * Params:
 *     x = est utilisé
 *         pour un truc
 *     y = est utilisé pour d'autres choses
 */
void foo (int x, int y){
 …
}

Macros

La section macros suit la même logique que la section params, soit une suite de nom = valeur. Le nom est le nom de la macro et la valeur est le texte de remplacement.

/**
 * Macros:
 *     FOO = maintenant il est temps
 *           de faire de bonnes choses
 *     BAR = bar
 *     MAGENTA = &lt;font color=magenta&gt;&lt;/font&gt;
 */