Debugging Scripts

Le système de script d’Altium Designer offre un environnement de débogage complet. Le débogueur de scripts vous aide à identifier et à résoudre les erreurs dans les scripts en fournissant une gamme d’outils automatisés et de panneaux d’information.

Erreurs de script

Les erreurs courantes incluent des méthodes non valides, des opérateurs de regroupement mal placés, des types incompatibles, des erreurs de logique et des erreurs typographiques. Lorsque le système de script rencontre une erreur, le débogueur met le script en pause et affiche une boîte de dialogue d’erreur indiquant le problème.

L’exemple ci-dessous montre un script avec un caractère de fin manquant ainsi que le message de la boîte de dialogue d’erreur correspondant.

Le débogueur met un script en pause en réponse à des erreurs de compilation ou d’exécution.

Une fois la boîte de dialogue d’erreur fermée, le code peut être corrigé puis le script relancé. Si le script doit être arrêté – par exemple lors d’une exécution pas à pas – utilisez la commande Stop (Run » Stop, Ctrl+F3) ou le bouton ( dans la barre d’outils Script Debug).

Débogage de script

Le système de script propose toute une gamme d’outils pour aider au débogage des scripts. Cela inclut l’application de plusieurs points d’arrêt dans un script, l’utilisation du panneau Watch List pour surveiller la valeur des variables, l’utilisation des signets pour naviguer plus efficacement, ainsi que les fonctions de pas à pas détaillé et de pas à pas principal pour suivre l’exécution des scripts.

Par exemple, les fonctionnalités suivantes peuvent être utilisées lors de la vérification des valeurs des variables et des expressions dans un script :

• Points d’arrêt
• Infobulles d’évaluation d’expression
• Infobulles Insight
• Boîte de dialogue Evaluate
• Expressions surveillées

► Voir Outils de l’éditeur de script pour plus d’informations sur l’utilisation des outils de l’éditeur lors du débogage des scripts.

Traçage

Pour aider à trouver et à résoudre une erreur inconnue dans un script, une série de points d’arrêt peut être insérée dans un script afin de mettre le code en pause à plusieurs endroits pendant que les valeurs des variables et des expressions sont vérifiées.

Cependant, à tout moment où le script est en pause, il peut aussi être avancé d’une ligne fonctionnelle à la fois à l’aide des fonctions de traçage/pas du débogueur. De cette manière, un point d’arrêt peut être utilisé pour mettre initialement le script en pause dans la zone d’intérêt, puis l’avancer ligne par ligne à l’aide de la fonction de traçage. Le processus consistant à exécuter un script une ligne à la fois est appelé traçage ou exécution pas à pas du script.

Le débogueur de scripts fournit des commandes liées au traçage – pas à pas détaillé (Run » Step Into) et pas à pas principal (Run » Step Over). Cela vous permet de suivre le processus du script et d’analyser son comportement lors du débogage du code du script.

Les commandes de débogage disponibles dans le menu Run .

Commande Step Into

Le processus Step Into exécute le script une instruction à la fois. La commande est disponible dans le menu Run , via son bouton associé dans la barre d’outils Script Debug (), ou par la touche de raccourci F7 .

Si l’instruction en cours d’exécution appelle une autre procédure, le pas à pas détaillé transfère le contrôle à la première ligne de la procédure appelée. La surbrillance vert pois dans l’éditeur indique la ligne de code à laquelle le script est rendu. Le processus d’exécution pas à pas du script est annulé avec la commande Run » Stop, le raccourci Ctrl+F3 ou le bouton de la barre d’outils ().

Commande Step Over

Le processus Step Over est similaire à Step Into, sauf que si l’instruction en cours est un appel à une autre procédure, toute la procédure appelée est exécutée sans arrêt, au lieu d’être suivie pas à pas. La commande est disponible dans le menu Run , via son bouton associé (), ou par la touche de raccourci F8 .

Cette commande est utile lorsqu’il a été déterminé qu’une procédure called n’est pas la cause du problème dans la procédure en cours, et évite d’avoir à suivre inutilement la procédure appelée ligne par ligne – cette procédure est alors « ignorée lors du pas à pas ».

Panneau Call Stack

Le panneau Call Stack est utilisé pour afficher la chaîne de procédures et de fonctions qui ont conduit au point d’exécution actuel dans le script en cours de débogage.

Le panneau Call Stack 

Au fur et à mesure du débogage pas à pas de votre script, le panneau affiche le nom de toute fonction ou procédure dans laquelle vous entrez.

Lorsqu’un appel à une autre fonction ou procédure est rencontré, le panneau affiche le nom de cette fonction/procédure supplémentaire au moment où elle est entrée. Comme la fonction/procédure est appelée depuis une autre fonction/procédure, la fonction/procédure d’origine reste affichée dans le panneau.

Une « pile d’appels » est ainsi effectivement constituée, montrant la relation entre les appels descendants de fonctions/procédures. La fonction/procédure d’origine apparaît en bas de la pile, chaque fonction/procédure appelée ensuite apparaissant au-dessus, jusqu’à la fonction/procédure actuellement active en haut de la pile.

Lorsque l’exécution du script sort d’une sous-fonction/procédure et revient dans la fonction/procédure appelante, la première est retirée de la pile et la fonction/procédure appelante devient le sommet de la pile.

Un double-clic sur une entrée du panneau permet d’accéder à la ligne de script correspondante dans laquelle l’appel à la fonction ou procédure sélectionnée est effectué. La ligne sera mise en surbrillance avec la couleur associée aux erreurs de script et le marqueur d’erreur de script sera affiché dans la marge de droite. Cela est utilisé uniquement à des fins de mise en évidence. Il disparaît lorsque vous cliquez sur le document et n’interrompt en aucune façon la session de débogage.

Exceptions et messages

Comme c’est souvent le cas dans tous les projets de programmation, le développement et le débogage du code de script ne s’arrêtent pas nécessairement à un script « fonctionnel ». Il est probable qu’en utilisation pratique, un script rencontre des erreurs imprévues ou ne produise pas les résultats attendus.

Heureusement, il existe plusieurs façons d’utiliser le système de script pour gérer les exceptions d’exécution et fournir un retour utilisateur sur le fonctionnement du script.

Gestionnaires d’exceptions

En DelphiScript, le mot-clé try introduit une instruction try-except ou une instruction try-finally. Ces deux instructions sont liées, mais servent des objectifs différents.

Try Finally

Dans un gestionnaire Try-Finally, les instructions du bloc finally sont toujours exécutées – qu’une exception se soit produite ou non dans le bloc try. Utilisez le bloc try-finally pour libérer des objets temporaires ou d’autres ressources, et pour effectuer les opérations de nettoyage.

Reset(F);
Try
  // process file F
Finally
  CloseFile(F);
End;

Try Except

Utilisez l’instruction Try-Except pour intercepter les exceptions levées et exécuter le code de gestion d’erreur associé. Par exemple, une exception spécifique peut être interceptée et un journal mis à jour, ou une boîte de dialogue d’erreur descriptive ouverte. Une exception de code dans le bloc try entraîne l’exécution du bloc except.

Dans l’exemple ci-dessous, la procédure ApplyOffset est appelée, avec des paramètres appropriés, depuis la procédure DefineOffset. La procédure effectue un simple calcul de division (sur les variables Ydim et Zdim ) et affiche le résultat (Offset) dans une boîte de dialogue standard.

Procedure ApplyOffset(Ydim, Zdim);
Var
   Offset;
Begin;
   Try
      Offset := Ydim div Zdim;
      ShowInfo('Calculated Offset = ' + IntToStr(Offset));
   Except
      ShowWarning('Entered Z dimension must be greater than zero.');
   End;
End;

Procedure DefineOffset;
Begin;
   ApplyOffset(32, 4);
End;

Pour les paramètres ApplyOffset indiqués ci-dessus (32,4), le script exécuté affichera le résultat calculé à l’aide de la procédure ShowMessage, comme illustré ci-dessous.

Sinon, le fait de modifier les paramètres transmis à 32,0 (ApplyOffset(32, 0);) provoque une exception de division par zéro dans le calcul Offset, ce qui déclenche le bloc gestionnaire Except. Celui-ci utilise la procédure ShowWarning pour afficher une boîte de dialogue Warning appropriée.

Raise

Dans la procédure simple de gestion d’erreur ci-dessus, on suppose que l’exception est levée en réponse à une erreur de division par zéro, mais cela signifie que d’autres types d’exceptions ne seront pas signalés avec précision par le texte de la boîte de dialogue d’avertissement. Dans cet exemple toutefois, il s’agit de l’erreur d’exception la plus susceptible d’être rencontrée.

Une certaine forme de détection d’erreur spécifique reste néanmoins souhaitable du point de vue de l’utilisateur. En DelphiScript, le mot-clé Delphi On (pour intercepter un type d’exception spécifié) n’est pas pris en charge, mais l’instruction Raise peut être utilisée dans un bloc Except pour relancer l’exception la plus récente, quel qu’en soit le type.

Try
   Offset := Ydim div Zdim;
   ShowInfo('Calculated Offset = ' + IntToStr(Offset));
Except
   Raise;
End;

De cette manière, lorsque l’essentiel du code d’une procédure se trouve dans le bloc try d’une instruction try-except, toutes les exceptions peuvent être signalées par l’instruction Raise . Notez que la boîte de dialogue d’exception n’affichera que des messages d’erreur génériques, plutôt que des informations spécifiques au script.

Raise peut également être utilisé pour provoquer une exception en réponse à des tests spécifiques, par exemple en appliquant de simples instructions if-then ou case.

Procedure ApplyOffset(Ydim, Zdim);
Var
   Offset;
Begin;
   if Zdim > Ydim then
      Begin;
         Raise('Z dimension must be smaller than Y dimension.');
      End;
   Offset := Ydim div Zdim;
   ShowInfo('Calculated Offset = ' + IntToStr(Offset));
End;

Ici, si le paramètre Zdim de l’exemple ci-dessus est supérieur au paramètre Ydim, une exception (avec message) est levée.

Erreurs dans les scripts VB

L’implémentation VBScript dans le moteur de script d’Altium Designer comporte des fonctions intégrées qui peuvent être utilisées dans les projets de script VBScript, telles que la fonction MsgBox .

L’instruction On Error peut être utilisée lors de l’interception des erreurs dans les scripts VB. Consultez la documentation Microsoft VBScript pour plus d’informations sur l’interception des erreurs.

Messages

En général, les messages constituent le principal moyen d’améliorer le fonctionnement d’un script du point de vue de l’utilisateur.

Les messages peuvent fournir des alertes en cas d’exception ou indiquer des informations d’exécution et des avertissements, et peuvent être insérés dans des routines de script traitant des données d’entrée, des calculs, des opérations sur les fichiers ou toute procédure pour laquelle une visibilité sur le déroulement serait utile.

Boîtes de dialogue de message

En plus de la boîte de dialogue de message de base disponible dans le système de script (ShowMessage), une gamme de boîtes de dialogue spécifiques est disponible afin de fournir un retour utilisateur adapté.

Celles-ci incluent des procédures de message telles que :

• ShowError
• ShowException
• ShowInfo
• ShowWarning
• et bien d’autres..

Panneau Messages

Le panneau Messages  d’Altium Designer peut être un outil de débogage utile pour les scripts, mais il peut également être utilisé pour fournir à l’utilisateur un flux continu d’informations de message utiles.

Le panneau Messages est un objet Workspace Manager accessible depuis l’interface Message Manager. Le panneau Messages peut être utilisé dans un script pour afficher l’état des variables et des propriétés (ou de toute autre donnée) à des fins de débogage comme de retour utilisateur, comme illustré dans l’exemple ci-dessous.

Procedure CreateMessages;
var
   WS : IWorkSpace;
   MM : IMessagesManager;
Begin
   WS := GetWorkSpace;           // obtain Workspace Manager interface
   MM := WS.DM_MessagesManager;  // obtain Message Manager interface
   
   MM.ClearMessages;             // initialize

   MM.BeginUpdate;
   // add relevant messages here using MM.AddMesssage procedures
   MM.EndUpdate;

   WS.DM_ShowMessageView;         // display messages
End;