# Introduction

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

Dans ce didacticiel, vous allez exécuter une application Simple Virtual Machine qui vous est donnée.

Le temps de lecture de ce didacticiel est estimé à 15 minutes si la Simple Virtual Machine est déjà installée et fonctionnelle sur le système.

# Mise en place

Avant de pouvoir lancer une application SVM, il faut en créer une et c'est ce que nous allons faire ensemble ici.

Cependant, nous n'expliquerons pas le texte de l'application ici. Cela viendra progressivement plus tard.

## Vérification de l'installation de la machine virtuelle

Pour vérifier que la Simple Virtual Machine est bien installée, jouez cette commande dans un terminal :

    /usr/bin/env svm -v

Lorsque la machine virtuelle est installée et fonctionnelle, vous obtenez ce message :

    svm version 2.1.20230326  Copyright (C) 2021  Julien BRUGUIER

    This program comes with ABSOLUTELY NO WARRANTY.
    This is free software, and you are welcome to redistribute it under certain conditions.
    See GNU GPLv3 terms for details.

Si ce n'est pas le cas, investiguez et corrigez l'installation jusqu'à obtenir ce message.

## Le code de l'application

Pour commencer, il convient d'ouvrir un fichier texte que nous appellerons application.svm et de copier/coller ce contenu à l'intérieur du fichier :

    #!/usr/bin/env svm
    DESCRIPTION
    Simple test application
    END
    DEBUG "Test" STYLE "default"
    PLUGIN "svmcom.so"
    ARGUMENT INT nb
    PROCESS "application"
    	CODE "main" INLINE
    		:debug BREAK
    		:memory INT/i, INT/s
    		0 -> &i
    		0 -> &s
    	:label loop
    		:shift &i
    		:shift @&i &s
    		:goto loop :when @&i IN &0*@&nb
    		:com.message @&s
    	END
    	MEMORY nb
    END

Assurez-vous que le fichier contient des retours de ligne en mode UNIX. En cas de doute, utilisez la commande dos2unix sur le fichier ainsi créé.

## Rendre le fichier exécutable

Ce fichier contient une application et peut donc être exécutable. Depuis un terminal, allez dans le répertoire où se trouve le fichier exécutable application.svm, puis lancez la commande :

    chmod u+x application.svm

# Première tentative !

Sans sortir du terminal ni changer de répertoire, vous pouvez lancer l'application comme n'importe quel script :

    ./application.svm

Vous devez obtenir ce résultat :

    Boot error: not enough arguments

    ./application.svm [options] [arguments]

    Simple test application

    Options:
            -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

    Arguments:
            integer: nb

    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

Ce message indique que l'invocation a échouée. En effet, l'application attend un argument sur la ligne de commande !

Avant de relancer l'application avec un paramètre, nous allons décortiquer ce premier résultat, généré par la machine virtuelle :

1. la première ligne contient la cause d'erreur :
   - l'erreur est levée au démarrage de la machine (au "Boot"),
   - il manque un argument obligatoire pour le fonctionnement de l'application ;
2. la seconde ligne résume comment invoquer l'application ;
3. la troisième ligne indique ce qu'est ou ce que réalise l'application. Ce texte est extrait depuis le fichier d'application ;
4. vient ensuite la liste des options disponibles pour l'application. Ici, seules les options de base de la machine virtuelle sont présentes ;
5. puis la liste des arguments disponibles pour l'application. Ici, un seul argument obligatoire est demandé et cela doit être un entier ;
6. enfin, les dernières lignes indiquent la syntaxe d'un entier lorsqu'un paramètre entier doit être spécifié.

# Seconde tentative !

Cette fois, essayez avec un argument entier :

    ./application.svm 10

Cette fois, le résultat devient :

    55

L'invocation a fonctionné cette fois. C'est une réussite !

En extra, vous pouvez vous amuser à lancer l'application avec d'autres valeurs, pour voir comment se comportent la machine virtuelle et l'application dans leur ensemble.

# Conclusion

Vous venez de voir sur un exemple d'application simple comment s'invoque la machine virtuelle.

En réalité, son invocation est faite par l'intermédiaire du système en utilisant la première ligne du fichier de l'application (appellée "sheebang" en anglais). Cela rend l'invocation transparente du point de vue de l'utilisateur final.

D'autres applications peuvent demander des options ou des arguments différents, et vont certainement réaliser des fonctionnalités plus impressionnantes. Dans tous les cas, l'option `-h` passée à l'application donnera la liste des options et arguments pour invoquer l'application.