Commit 6eaadd9d authored by Guillaume Huard's avatar Guillaume Huard
Browse files

Doc de local.sh

parent 6e352bc6
......@@ -28,48 +28,37 @@ intégrée une activité complète dans un seul fichier, consultez l'URL :
* Prérequis
Le script =local.sh= utilise d'autres scripts et fichiers de VPLPP. Il est donc conseillé de
Le script =local.sh= utilise d'autres scripts et fichiers de VPL++. Il est donc conseillé de
télécharger le dépôt entier et de laisser =local.sh= dans le répertoire correspondant.
* Les fichiers attendus par =local.sh=
L'ensemble des scripts de VPL++ travaillent sur une activité de nom =X= en consultant un fichier
nommé =X.org= permettant de générer tous les fichiers attendus par l'activité
='Basic system programming'=. Le fichier =X.org= doit donc contenir des blocs de code dotés
d'arguments =:tangle= permettant d'indiquer le nom du fichier dans lequel ils doivent être écrits.
Tous ces fichiers doivent être écrits dans un sous-répertoire du répertoire =X= dépendant de leur
fonction :
- =ef= : fichiers necessaires à l'exécution et à l'évaluation de l'activité. Ce sous-répertoire
concerne entre autres =vpl_evaluate.cases= et =vpl_custom_setup.sh= ;
- =rf= : fichiers fournis comme base aux étudiants, typiquement des fichiers à trous à compléter ;
- =cf= : fichiers faisant partie de la correction écrite par l'enseignant, non fournie aux
étudiants, consultable sur caséine par les enseignants. Pour chaque fichiers de =cf=, si un
fichier de =rf= de même nom n'existe pas, les scripts de VPL++ en génèrent un vide (base de
travail vierge pour l'étudiant) ;
Dans le répertoire courant (celui depuis lequel il est invoqué), =local.sh= s'attend à trouver les
répertoires et fichiers suivants :
- =vpl_id.txt= : ce fichier doit contenir le numéro du VPL concerné lors d'un /upload/ ;
- =intro.html= : fichier optionnel contenant la description du VPL ;
- =ef= : répertoire contenant les fichiers necessaires à l'exécution et à l'évaluation de
l'activité. Il doit contenir les fichiers des répertoires =ef= de =Basic_System= (dans le dépôt de
VPL++) et de ses extensions utilisées. Ce répertoire doit aussi contenir =vpl_evaluate.cases= et
(le cas échéant) =vpl_custom_setup.sh= ;
- =rf= : répertoire contenant les fichiers fournis comme base aux étudiants, typiquement des
fichiers à trous à compléter ;
- =cf= : répertoire contenant les fichiers faisant partie de la correction écrite par l'enseignant,
non fournie aux étudiants, consultable sur caséine par les enseignants. Pour chaque fichiers de
=cf=, si un fichier de =rf= de même nom n'existe pas, les scripts de VPL++ en génèrent un vide
(base de travail vierge pour l'étudiant) ;
- =hf= : similaire à =cf= mais ne donne pas lieu à une génération de fichier dans =rf=.
Les propriétés données en début du fichier d'exemple =Hello.org= correspondent au comportement
généralement souhaité :
- =:eval never= : les scripts de VPL++ commencent par évaluer les blocs de code d'un fichier
=X.org=. Ceci ne concerne pas les fichiers de l'activité (nous verrons plus loin l'utilité de
cette fonctionnalité) qui ne sont donc par défaut jamais évaluables ;
- =:mkdirp yes= : la génération des fichiers de l'activité doit créer les répertoires intermédiaires
au besoin ;
- =:exports none= : les fichiers de l'activité de font pas partie de la description de celle-ci.
* L'exécution locale
Lors de l'exécution ou l'évaluation d'une activité =X=, une fois les fichiers générés à partir de
=X.org=, l'exécution proprement dite se déroule dans le répertoire =X/local_run=. Contrairement à ce
Elle se fait en invoquant =local.sh= avec pour argument =run=, =debug= ou =evaluate=. L'exécution
proprement dite se déroule dans le répertoire =local_run= créé par =local.sh=. Contrairement à ce
que fait le module VPL, cette exécution se déroule sans isolation (pas de =chroot= ou de limites sur
les resources), elle ne remplace donc pas une exécution en conditions réelles sur le serveur mais
permet de tester son activité durant la phase de développement.
L'évaluation locale supporte un mode de débogage similaire à celui disponible dans l'activité
='Basic system programming'=. Pour l'activer il suffit d'ajouter le mot clé ='debug'= à la
commande :
#+BEGIN_SRC shell :exports code
vpl evaluate debug Hello
#+END_SRC
='Basic system programming'=. Pour l'activer il suffit d'ajouter aux arguments le mot clé =debug=.
En mode de débogage, l'évaluation locale affiche la table de hachage obtenue après évaluation du
fichier =vpl_evaluate.cases= ainsi que davantage de sorties pour les tests réussis. En outre, tous
les fichiers générés par l'évaluation sont conservés dans le dossier =local_run= : en évaluant un
......@@ -83,166 +72,6 @@ Si votre terminal le supporte, l'exécution locale se fait en couleurs, en :
* L'/upload/
Les scripts de VPL++ sont capables d'envoyer sur le serveur tous les fichiers de l'activité. Pour
cela il faut que le fichier =X.org= d'une activité =X= permette de générer un fichier =vpl_id.txt=
dans le répertoire =X= contenant l'identifiant de l'activité. L'activité devra donc tout de même
être créée manuellement au préalable.
La description de l'activité est générée au format html à partir du fichier =X.org= lors de
l'utilisation de la commande =vpl=. Elle est envoyée sur le serveur lors du push. Elle se trouve
dans le fichier =intro.html= du répertoire =X= et peut donc être consultée pour vérification avant
d'effectuer un =push=.
* Organiser son activité
Le format =org= permet d'organiser son texte à l'aide d'une syntaxe simple similaire à celle de
=markdown=. En particulier, il est possible de manipuler des listes numérotées ou non, de découper son
texte en sections, sous-sections, sous-sous-sections, etc. Le document peut ensuite être exporté vers
plusieurs formats classiques (=latex=, =html=, ...). Présenter toutes les fonctionnalités d'
=org= n'est pas le but de cette documentation et le lecteur curieux est invité à se référer à
la documentation officielle : [[https://orgmode.org/manual]]
Le but de cette section est essentiellement de donner des pistes afin de découper son activité en
exercices décrits par des parties indépendantes du fichier au format =org= et d'éviter la
duplication de certaines parties du texte. Cela repose essentiellement sur les idées suivantes :
- la table de hachage résultant de l'évaluation de =vpl_evaluate.cases= peut être en partie
construite de manière programmatique ;
- le fichier =vpl_evaluate.cases= est un code en =Perl= qu'il est possible de découper en plusieurs
blocs de code concaténés les uns aux autres à l'aide de l'argument =:output append= (comportement
par défaut mais le demander explicitement ne fait pas de mal) ;
- =org= mode supporte la syntaxe =noweb= pour manipuler des blocs de code. En particulier :
- une activité est nommée à l'aide de la propriété =#+NAME= ;
- un bloc de code ayant pour argument =:noweb yes= peut inclure un bloc de code nommé s'il
contient, seule sur une ligne, une référence de la forme suivante : =<<nom>>=
- il est possible, à l'aide de tags, de ne pas inclure certaines sections dans l'export de la
description. Cela permet de profiter du /folding/ d'=emacs= pour toutes les parties du fichier de
description de l'activité.
Tout ceci est illustré par l'exemple =Hello= étendu avec un cas de test en français :
#+BEGIN_SRC org :exports code
,* Réglages :noexport:
,#+OPTIONS: num:nil
,#+OPTIONS: toc:nil
,#+OPTIONS: html-postamble:nil
,#+OPTIONS: html-preamble:nil
,#+LANGUAGE: fr
,#+EXPORT_EXCLUDE_TAGS: noexport
,#+PROPERTY: header-args :eval never :mkdirp yes :exports none
,#+BEGIN_SRC txt :tangle Hello/vpl_id.txt
26126
,#+END_SRC
,#+BEGIN_SRC perl :tangle Hello/ef/vpl_evaluate.cases
# On initialise une table de hachage vide
my $cases = {};
,#+END_SRC
,* Hello world
Écrire un programme qui affiche ='Hello world !'=.
,#+BEGIN_SRC shell :tangle Hello/cf/hello_world.sh
echo "Hello world !"
,#+END_SRC
,#+BEGIN_SRC perl :tangle Hello/ef/vpl_evaluate.cases :output append
# Ajout du premier cas de test
$cases->{"hello_world.sh"} = {
tests => {
test_1 => { show => 1, output => "Hello world !" }
}
};
,#+END_SRC
,* Salut monde
Écrire un programme qui affiche ='Salut monde !'=.
,#+NAME: solution_salut
,#+BEGIN_SRC shell :tangle Hello/cf/salut_monde.sh
echo "Salut monde !"
,#+END_SRC
,#+BEGIN_SRC perl :tangle Hello/ef/vpl_evaluate.cases :output append :noweb yes
# l'opérateur q{} marcherait aussi, mais le 'here document' avec quotes est la
# forme d'inclusion la moins sensible à la présence de caractères d'échappement
my $solution = <<'END';
<<solution_salut>>
END
# Ajout du second cas de test
$cases->{"salut_monde.sh"} = {
solution => $solution,
tests => {
test_1 => {}
}
};
,#+END_SRC
,* Epilogue :noexport:
,#+BEGIN_SRC perl :tangle Hello/ef/vpl_evaluate.cases :output append
# suppression d'un ou plusieurs cas de test, utile lors du developpement de l'activité
# delete($cases->{"hello_world.sh"});
# delete($cases->{"salut_monde.sh"});
$cases;
,#+END_SRC
#+END_SRC
Ce fichier permet de générer la description en html de l'activité ainsi que les fichiers suivants :
- dans =Hello/ef=, =vpl_evaluate.cases= :
#+BEGIN_SRC perl :export code
# On initialise une table de hachage vide
my $cases = {};
# Ajout du premier cas de test
$cases->{"hello_world.sh"} = {
tests => {
test_1 => { show => 1, output => "Hello world !" }
}
};
# l'opérateur q{} marcherait aussi, mais le 'here document' avec quotes est la
# forme d'inclusion la moins sensible à la présence de caractères d'échappement
my $solution = <<'END';
echo "Salut monde !"
END
# Ajout du second cas de test
$cases->{"salut_monde.sh"} = {
solution => $solution,
tests => {
test_1 => {}
}
};
# suppression d'un ou plusieurs cas de test, utile lors du developpement de l'activité
# delete($cases->{"hello_world.sh"});
# delete($cases->{"salut_monde.sh"});
$cases;
#+END_SRC
- dans =Hello/cf=, =hello_world.sh= :
#+BEGIN_SRC shell :export code
echo "Hello world !"
#+END_SRC
- dans =Hello/cf=, =salut_monde.sh= :
#+BEGIN_SRC shell :export code
echo "Salut monde !"
#+END_SRC
* Fichiers externes
Il n'est pas toujours possible d'inclure l'intégralité d'une activité dans un seul fichier,
quand celle-ci est trop grosse ou quand elle dépend de fichiers provenants de plusieurs projets
logiciels distincts. Il est alors possible de fournir les fichiers de l'activité =X= dans un
répertoire =X_files= qui peut être fabriqué par un bloc de code contenu dans =X.org=. Dans ce cas,
ce bloc de code devra être exécutable (argument =:eval yes=). Le répertoire =X_files= doit suivre la
même organisation que le répertoire =X= généré par =X.org=, autrement dit, ses fichiers doivent se
trouver dans les bons sous répertoires =ef=, =cf=, =rf=, =hf=.
A titre d'exemple, dans l'activité =Hello=, plutôt que d'include la solution du cas de test
="hello_world.sh"= dans =Hello.org=, celle ci aurait pu être récupérée de la manière suivante :
#+BEGIN_SRC org :exports code
,#+BEGIN_SRC shell :eval yes
mkdir -p Hello_files/cf
cp Chemin_vers_mes_fichiers_solution/hello_world.sh Hello_files/cf
,#+END_SRC
#+END_SRC
Il se fait en invoquant =local.sh= avec pour argument =push=. Les scripts de VPL++ sont capables
d'envoyer sur le serveur tous les fichiers de l'activité, mais l'activité devra donc tout de même
être créée manuellement au préalable, de même que le fichier =vpl_id.txt= associé.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment