# Introduction

Ce didacticiel est destiné aux nouveaux utilisateurs de la Simple Virtual Machine.

Dans ce didacticiel, vous allez configurer la machine virtuelle pour lancer votre application.

Le temps de lecture de ce didacticiel est estimé à 20 minutes si l'utilisation d'une application a été abordée.

# Mise en place

Pour commencer, créez le canevas de l'application dans le fichier exécutable application.svm en utilisant ce code :

    #!/usr/bin/env svm
    PROCESS "application"
    	CODE "main" INLINE
    	END
    END

# Explication initiale

La première ligne du fichier permet au système UNIX de savoir quelle application peut interpreter le fichier. Ici, c'est la machine virtuelle qui est indiquée, à travers l'utilitaire "env". Le chemin absolu vers le binaire de la machine virtuelle peut également être spécifié.

Le reste de ce fichier est la plus petite application qu'il soit possible d'écrire, et cela sera détaillé à la fin de ce didacticiel.

# Global

## Description

Modifiez le fichier :

    #!/usr/bin/env svm
    DESCRIPTION
    Example of application.

    This description can contain several lines to describe what the application does.
    END
    PROCESS "application"
    	CODE "main" INLINE
    	END
    END

Ce bloc permet d'ajouter du texte de description de l'application. Il est utile pour expliquer l'objectif lorsque l'on ouvre le code source de l'application, et également lorsque l'aide sur l'application est demandée.

Lancez l'application avec l'option -h :

    ./application.svm -h
    ./application.svm [options]

    Example of application.

    This can contain several lines to describe what the application does.

    Options:
            -h        : Display this help
            -v        : Display Simple Virtual Machine version and license
            -d port   : Launch in debug mode on this port
            --        : Separator between options and arguments

## Historique

Modifiez maintenant le code pour obtenir :

    #!/usr/bin/env svm
    DESCRIPTION
    Example of application.

    This description can contain several lines to describe what the application does.
    END
    LOG
    PROCESS "application"
    	CODE "main" INLINE
    	END
    END

L'ajout du mot-clef `LOG` indique à la machine de produire les erreurs d'exécution sur la sortie standard du terminal.

Par défaut, la machine ne produit aucun texte en cas d'erreur pour éviter d'éventuelles fuites de données pouvant être contenues dans les messages d'erreur.

Il est également possible de rediriger ce flux d'erreur :

- dans un fichier en écrivant la ligne `LOG FILE "nom_de_fichier"`,
- ou sur un serveur TCP/IP en écrivant la ligne `LOG SERVER "ip_serveur" "port_serveur"`.

## Débugueur

Modifiez le fichier :

    #!/usr/bin/env svm
    DESCRIPTION
    Example of application.

    This description can contain several lines to describe what the application does.
    END
    LOG
    DEBUG "Application example" STYLE "rounded:default" NETWORK "0.0.0.0" SECURITY 1
    PROCESS "application"
    	CODE "main" INLINE
    	END
    END

La ligne débugueur permet de contrôler comment le débugueur doit se comporter lorsqu'il est activé. Lorsque la ligne est absente, les valeurs prises par défaut sont destinées à un usage en local du débugueur.

La première chaine située après le mot-clef `DEBUG` est le titre situé dans l'application web.

- `STYLE "nom_de_style"` permet de sélectionner un style graphique pour cette application,
- `NETWORK "ip_d_ecoute"` permet de préciser sur quelle IP la machine doit attendre les connexions depuis les navigateurs web,
- `SECURITY niveau_securite` permet d'activer le chiffrement entre le navigateur web et la machine (peut ralentir drastiquement le debugueur, à utiliser avec précaution).

## Mode performance

Lorsque le mode performance est activé, il est possible de rediriger les rapports ou événements produits dans un canal d'historique dédié.

Modifiez le fichier :

    #!/usr/bin/env svm
    DESCRIPTION
    Example of application.

    This description can contain several lines to describe what the application does.
    END
    LOG
    DEBUG "Application example" STYLE "rounded:default" NETWORK "0.0.0.0" SECURITY 1
    PERF LOG FILE "application.svm_perf"
    PROCESS "application"
    	CODE "main" INLINE
    	END
    END

La partie de la ligne suivant le mot-clef `PERF` suit la même syntaxe que la ligne d'historique. Ici, les rapports et événements du mode performance iront dans un fichier.

# Architecture

## Extensions

Modifiez à nouveau le fichier :

    #!/usr/bin/env svm
    DESCRIPTION
    Example of application.

    This description can contain several lines to describe what the application does.
    END
    LOG
    DEBUG "Application example" STYLE "rounded:default" NETWORK "0.0.0.0" SECURITY 1
    PERF LOG FILE "application.svm_perf"
    PLUGIN "svmcom.so"
    PLUGIN "svmrun.so"
    PLUGIN "svmstr.so"
    PLUGIN "svmplugin.so"
    PROCESS "application"
    	CODE "main" INLINE
    		:plugin.dump STDOUT
    	END
    END

Chaque ligne contenant par le mot-clef `PLUGIN` permet d'inclure une extension.

- Pour les extensions officielles livrées avec la machine, le nom du fichier sans chemin suffit,
- Pour les extensions externes délivrées pour une machine donnée, la ligne peut s'écrire `MACHINE PLUGIN "chemin_fichier_depuis_repertoire_installation_machine"`,
- Pour les extensions propres à l'application, la ligne peut s'écrire `LOCAL PLUGIN "chemin_fichier_depuis_repertoire_application"`,
- Dans tous les cas, le mot-clef `PLUGIN` avec le chemin absolu de l'extension fonctionne.

Il est possible que des extensions définissent des options et des arguments pour personnaliser leur fonctionnement. Ces options et ces arguments s'ajoutent à la fin de la ligne d'invocation de l'extension :

- les options s'écrivent avant les arguments,
- les options s'écrivent avec un caractère - suivi d'une lettre ou d'un chiffre,
- certaines options demandent en plus un argument, qui peut être un entier positif ou nul, ou une chaine entre double quotes,
- les arguments sont précédés du délimiteur d'argument --,
- les arguments peuvent être des entiers positifs ou nul, ou des chaines entre double quotes.

# Interface

## Options

Modifiez encore le fichier :

    #!/usr/bin/env svm
    DESCRIPTION
    Example of application.

    This description can contain several lines to describe what the application does.
    END
    LOG
    DEBUG "Application example" STYLE "rounded:default" NETWORK "0.0.0.0" SECURITY 1
    PERF LOG FILE "application.svm_perf"
    PLUGIN "svmcom.so"
    PLUGIN "svmrun.so"
    PLUGIN "svmstr.so"
    PLUGIN "svmplugin.so"
    OPTION -f FLAG flag HELP "a simple flag"
    OPTION -c MULTIPLE FLAG counter HELP "a counter"
    OPTION -i INT integer HELP "an integer"
    OPTION -s STR string HELP "a string"
    OPTION -I MULTIPLE INT integer_array HELP "an array of integers"
    OPTION -S MULTIPLE STR string_array HELP "an array of strings"
    PROCESS "application"
    	CODE "main" INLINE
    		:run.coredump STDOUT
    	END
    	MEMORY ".*"
    END

Vous pouvez lancer l'application avec ces options (vous pouvez relancer avec d'autres valeurs d'options pour voir leur effet) :

    ./application.svm -f -c -c -c -i 17 -s text -I 0 -I 1 -I 2 -S a -S b
    Kernel:
    State: R, transmit_interruption

    Processor:
     State:
       Next instruction: <main:1/1> (Current one: <main:1/0>)
       Current memory  : &0*0
       Allocated memory:
       Aliases         :
       Flags           :
       Cascaded flags  :
       Local interruption handlers:
       Cascaded local interruption handlers:
     Saved states:
     Global interruption handlers:

    Code at <main:1/0>:
    ====== HERE ======
         :run.coredump STDOUT       # <0> @(main, line 1) SYSTEM
    ==================
     Labels:
     Symbols:

    Memory:
      &0: INT 3
      &1: BLN TRUE
      &2: INT 17
      &3: INT 0
      &4: INT 1
      &5: INT 2
      &6: STR "text"
      &7: STR "a"
      &8: STR "b"
     Aliases:
      counter -> &0*1
      flag -> &1*1
      integer -> &2*1
      integer_array -> &3*3
      string -> &6*1
      string_array -> &7*2
     Free space:

Puis lancer à nouveau avec l'option -h :

    ./application.svm -h
    ./application.svm [options]

    Example of application.

    This description can contain several lines to describe what the application does.

    Options:
            -f        : a simple flag
            -c        : a counter (Repeatable option)
            -i integer: an integer
            -s string : a string
            -I integer: an array of integers (Repeatable option)
            -S string : an array of strings (Repeatable option)
            -h        : Display this help
            -v        : Display Simple Virtual Machine version and license
            -d port   : Launch in debug mode on this port
    	-p detail : Launch in performance mode (profiling and code coverage) with this level of details
            --        : Separator between options and arguments

    Integer format: <sign><base><value>
            Sign: - for negative integers, + or void for positive integers
            Base: 0 for octal, 0x for hexadecimal, void for decimal
            Value composed of digits depending on base: 0 to 7 for octal, 0 to 9 for decimal, 0 to 9 and A to F (lower case also accepted) for hexadecimal

Les options deviennent disponibles avec une certaine variabilité dans les valeurs qu'elles produisent en mémoire. De plus, la définition d'une option créée automatiquement une entrée dans l'aide de l'application.

Il est possible de lire les valeurs résultant des options en utilisant l'alias défini sur la ligne `OPTION` correspondante.

## Arguments

Modifiez le fichier pour ajouter des arguments :

    #!/usr/bin/env svm
    DESCRIPTION
    Example of application.

    This description can contain several lines to describe what the application does.
    END
    LOG
    DEBUG "Application example" STYLE "rounded:default" NETWORK "0.0.0.0" SECURITY 1
    PERF LOG FILE "application.svm_perf"
    PLUGIN "svmcom.so"
    PLUGIN "svmrun.so"
    PLUGIN "svmstr.so"
    PLUGIN "svmplugin.so"
    OPTION -f FLAG flag HELP "a simple flag"
    OPTION -c MULTIPLE FLAG counter HELP "a counter"
    OPTION -i INT integer HELP "an integer"
    OPTION -s STR string HELP "a string"
    OPTION -I MULTIPLE INT integer_array HELP "an array of integers"
    OPTION -S MULTIPLE STR string_array HELP "an array of strings"
    ARGUMENT INT arg_integer HELP "an integer"
    ARGUMENT STR arg_string HELP "a string"
    PROCESS "application"
    	CODE "main" INLINE
    		:run.coredump STDOUT
    	END
    	MEMORY ".*"
    END

Puis lancez l'application avec seulement les deux arguments :

    ./application.svm 42 text
    Kernel:
    State: R, transmit_interruption

    Processor:
     State:
       Next instruction: <main:1/1> (Current one: <main:1/0>)
       Current memory  : &0*0
       Allocated memory:
       Aliases         :
       Flags           :
       Cascaded flags  :
       Local interruption handlers:
       Cascaded local interruption handlers:
     Saved states:
     Global interruption handlers:

    Code at <main:1/0>:
    ====== HERE ======
         :run.coredump STDOUT       # <0> @(main, line 1) SYSTEM
    ==================
     Labels:
     Symbols:

    Memory:
      &0: INT 42
      &1: STR "text"
      &2: INT 0
      &3: BLN FALSE
      &4: INT
      &5: STR
     Aliases:
      arg_integer -> &0*1
      arg_string -> &1*1
      counter -> &2*1
      flag -> &3*1
      integer -> &4*1
      integer_array -> &5*0
      string -> &5*1
      string_array -> &6*0
     Free space:

Contrairement aux options, les arguments sont obligatoires sur la ligne de commande. La machine refusera de lancer l'application si un argument est manquant ou incorrect.

Les arguments, tout comme les options, sont automatiquement ajoutés à l'aide de l'application.

Il est possible de lire les valeurs résultant des arguments en utilisant l'alias défini sur la ligne `ARGUMENT` correspondante.

## Arguments supplémentaires

Modifiez le fichier :

    #!/usr/bin/env svm
    DESCRIPTION
    Example of application.

    This description can contain several lines to describe what the application does.
    END
    LOG
    DEBUG "Application example" STYLE "rounded:default" NETWORK "0.0.0.0" SECURITY 1
    PERF LOG FILE "application.svm_perf"
    PLUGIN "svmcom.so"
    PLUGIN "svmrun.so"
    PLUGIN "svmstr.so"
    PLUGIN "svmplugin.so"
    OPTION -f FLAG flag HELP "a simple flag"
    OPTION -c MULTIPLE FLAG counter HELP "a counter"
    OPTION -i INT integer HELP "an integer"
    OPTION -s STR string HELP "a string"
    OPTION -I MULTIPLE INT integer_array HELP "an array of integers"
    OPTION -S MULTIPLE STR string_array HELP "an array of strings"
    ARGUMENT INT arg_integer HELP "an integer"
    ARGUMENT STR arg_string HELP "a string"
    ARGUMENTS arguments
    PROCESS "application"
    	CODE "main" INLINE
    		:run.coredump STDOUT
    	END
    	MEMORY ".*"
    END

Puis relancez une nouvelle fois l'application avec des arguments :

    ./application.svm 42 text a b c d e
    Kernel:
    State: R, transmit_interruption

    Processor:
     State:
       Next instruction: <main:1/1> (Current one: <main:1/0>)
       Current memory  : &0*0
       Allocated memory:
       Aliases         :
       Flags           :
       Cascaded flags  :
       Local interruption handlers:
       Cascaded local interruption handlers:
     Saved states:
     Global interruption handlers:

    Code at <main:1/0>:
    ====== HERE ======
         :run.coredump STDOUT       # <0> @(main, line 1) SYSTEM
    ==================
     Labels:
     Symbols:

    Memory:
      &0: INT 42
      &1: STR "text"
      &2: STR "./application.svm"
      &3: STR "a"
      &4: STR "b"
      &5: STR "c"
      &6: STR "d"
      &7: STR "e"
      &8: INT 0
      &9: BLN FALSE
      &10: INT
      &11: STR
     Aliases:
      arg_integer -> &0*1
      arg_string -> &1*1
      arguments -> &2*6
      counter -> &8*1
      flag -> &9*1
      integer -> &10*1
      integer_array -> &11*0
      string -> &11*1
      string_array -> &12*0
     Free space:

Les arguments placés sur la ligne de commande en plus des arguments obligatoires sont maintenant placés dans la mémoire, sous l'alias défini sur la ligne `ARGUMENTS`.

En prime, la machine place le nom du fichier contenant l'application comme première adresse du pointeur créé.

# Application

## Processus

Une application est constituée de processus. Jusqu'à présent, un seul processus est décrit dans nos applications. Ajouter d'autres processus sera évoqué dans un prochain didacticiel.

Chaque processus porte un nom, utilisé principalement pour des raisons opérationnelles ou dans le débugueur.

## Code

La ligne commençant par le mot-clef `CODE` permet d'initialiser le processeur. En effet, son pointeur d'exécution est placé sur la première instruction du code.

Chaque code contient un nom, également utilisé pour des raisons opérationnelles et dans le débugueur.

Ici, le texte source du code est présenté dans le même fichier, entre les mots-clef `INLINE` et `END`, mais il peut être spécifié par le mot-clef `FILE` suivi du nom de fichier entre double-quotes.

## Mémoire

La ligne avec le mot-clef `MEMORY` permet d'initialiser la mémoire avec les valeurs des options et arguments.

Le mot-clef peut être suivi d'un mélange entre des identifiants (sans double-quotes) et des expressions rationnelles (avec des double-quotes). Chaque identifiant d'option ou d'argument qui correspond à au moins un élément de la liste d'initialisation mémoire sera défini en tant qu'alias avec les valeurs liées à l'option ou l'argument.

# Conclusion

Vous venez de voir comment configurer la machine virtuelle pour une application.

Initialiser correctement la machine permet d'utiliser les pleines possibilités de la machine en termes d'interface et d'opérabilité.

A partir de maintenant, vous êtes capables d'écrire vos propres applications en utilisant la Simple Virtual Machine, en utilisant les pages de manuel pour le détail de l'utilisation de la machine et des extensions.