Compilation et débogage en ligne de commande

modifier

Compilation

modifier

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

modifier

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

modifier

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

modifier

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é

modifier

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

modifier

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

modifier

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

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

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

/**
 * Bugs: aucun bogue signalé.
 */
/**
 * Date: September 25, 2010
 */

Dépréciation

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

Exemples

modifier

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

modifier

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

modifier

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

/**
 * License: GPLv3+
 */

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

modifier

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

modifier

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

modifier

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

modifier

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

/**
 * Version: 1.6a
 */

Mise en évidence

modifier
Avec du code HTML
modifier

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

modifier
modifier

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;

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){
 
}

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;
 */