tests/doc/vvDoc.tex

   1 \documentclass[12pt]{report}
   2
   3 \usepackage[a4paper, top=1.5cm, bottom=1.5cm, left=1.5cm, right=1.5cm]{geometry}
   4 \usepackage[utf8]{inputenc}
   5 \usepackage[T1]{fontenc}
   6 \usepackage[francais]{babel}
   7 \usepackage{graphicx}
   8 \usepackage{amsmath}
   9 \usepackage{amsthm}
  10 \usepackage{amsfonts}
  11 \usepackage{amssymb}
  12 \usepackage{mathrsfs}
  13 \usepackage{color}
  14 \usepackage{colortbl}
  15 \usepackage{lastpage}
  16 \usepackage{fancyhdr}
  17 \usepackage{hyperref}   % html link
  18 \usepackage{float} %placement images
  19 \usepackage{caption} %légendes centrées
  20 \usepackage{textcomp} %caractères spéciaux
  21 \usepackage{version} %ajoute l'environnement comment pour les commentaires longs
  22
  23 %configure caption
  24 \captionsetup{margin=10pt,font=small,labelfont=bf,justification=centerlast}
  25
  26 %définition des entêtes et pieds de page
  27 \fancyhf{}
  28 \setlength{\headheight}{15pt}
  29 \renewcommand{\headrulewidth}{0pt} %épaisseur ligne de séparation
  30 \renewcommand{\footrulewidth}{0pt}
  31 \pagestyle{fancyplain}
  32 \renewcommand{\chaptermark}[1]{\markboth{#1}{}}
  33 \renewcommand{\sectionmark}[1]{\markright{#1}{}}
  34 \lhead{}
  35 \chead{}
  36 \rhead{}
  37 \lfoot{}
  38 \cfoot{\thepage\ / \pageref{LastPage}}
  39 \rfoot{}
  40 \newenvironment{note}{\textbf{Note:}}{}
  41
  42 \begin{document}
  43 \title{Tester vv}
  44 \maketitle
  45 \thispagestyle{empty} %pas d'entêtes pour la première page
  46 \clearpage
  47
  48 \renewcommand{\contentsname}{Sommaire}
  49 \tableofcontents
  50 \clearpage
  51
  52  \chapter{Intégration continue}
  53 \section{Les options de make}
  54 Il y a principalement quatre \htmladdnormallink{options}{http://www.vtk.org/Wiki/CTest:Nightly,_Experimental,_Continuous} de compilation :
  55 Nightly, Continuous, Experimental et Test.
  56
  57 Quiconque peut lancer une compilation avec l'une de ces options.
  58 \begin{itemize}
  59 \item make Nightly fait un raz des binaires mais garde la configuration, update les sources, build, lance les tests puis submit au dashboard.
  60 \item make Experimental fait un build, lance les tests puis submit au dashboard.
  61 \item make Continous fait un build, lance les tests puis submit au dashboard.
  62 \end{itemize}
  63
  64
  65 \section{Installation des compilations automatiques}
  66 \begin{enumerate}
  67         \item Récupérer les scripts \begin{verbatim}git clone http://russule/gitSources/vvDashboard\end{verbatim}
  68         \item Configurer les scripts
  69         \item Créer la tache sous linux et éventuellement sous windows
  70 \end{enumerate}
  71
  72 \subsection{Configuration des scripts}
  73 Voici un bref résumé du rôle de chacun des scripts
  74 \begin{itemize}
  75  \item builderNightly.bat : Lance les builds pour windows
  76  \item commonConfig.cmake : Arborescence des dossiers, URL des données de test, path vers ITK et VTK
  77  \item continuousBuild.cmake : Amorce un continuous
  78  \item dartConfig.cmake : Configuration du serveur distant
  79  \item fetch\_data\_test.bat : git pull ou clone si le repo n'existe pas
  80  \item fetch\_data\_test.sh : idem pour linux
  81  \item nightlyBuild.cmake : Parse les arguments pour lancer le build correspondant.
  82 L'appèle du script est de la forme
  83 \begin{verbatim}
  84         ctest -S nightlyBuild.cmake,Itkv3.20.0 (ou ,ItkNightly)
  85 # variante : ctest -S nightlyBuild.cmake,Itkv3.20.0,NoTools
  86 # où il faut définir que faire lorsque l'argument NoTools est trouvé (ici, CLITK_BUILD_TOOLS=OFF)
  87 \end{verbatim}
  88  \item startNightlyBuilds.sh : Lance toutes les nightly et lance la vm
  89  \item vmLaunch.sh : Lance toutes les images virtuelles.
  90  \item itkNightlyBuild.cmake : Met à jour le dossier itk from scratch. Ce script est appelé par nightlyBuild.cmake,ItkNightly
  91 \end{itemize}
  92
  93 Les principales informations à modifier sont dans le fichier commonConfig.cmake.\\
  94 Description de commonConfig.cmake
  95 \begin{verbatim}
  96 set(itkBin "${itkVersion}Bin/")
  97 set(dashboard_binary_name "vv${itkVersion}${buildOptions}Bin/")
  98 set(dashboard_source_name "vvSource")
  99 #adresse où télécharger(cloner) les données de test.
 100 set(data_test_path "${CTEST_DASHBOARD_ROOT}${dashboard_binary_name}data/")
 101
 102 #http://192.168.156.8/gitSources/vvDataTest est l'adresse où récupérer les données de test
 103 EXEC_PROGRAM(${CTEST_SCRIPT_DIRECTORY}/fetch_data_test.${ext} ARGS ${data_test_path} http://192.168.156.8/gitSources/vvDataTest)
 104 \end{verbatim}
 105 Exemple d'architecture des dossiers :
 106 \begin{verbatim}
 107 ./vvItkNightlyBin
 108 ./vvItkNightlyNoToolsBin
 109 ./vvItkv3.20.0Bin
 110 ./vvItkv3.20.0NoToolsBin
 111 ./vvItkv3.20.0NoVvBin
 112 ./vvSource
 113 \end{verbatim}
 114
 115 \subsection{Création des taches}
 116 Concernant les compilations automatiques, il est possible de créer une tache appelant le script startNightlyBuilds. \\
 117 Ce dernier exécute pour chacun des builds configurés un raz, une mise à jour, une configuration, une compilation, puis l'exécution des tests et la
 118 soumission de leurs résultats.\\
 119 Il lance également la machine virtuelle, dans laquelle se trouve des builds sous windows.
 120 \begin{itemize}
 121 \item Pour Suse :
 122 \begin{verbatim}
 123   >crontab -l
 124 0  22   *   *   * /home/mpech/workspace/vv/vvDashboard/startNightlyBuilds.sh > /home/mpech/workspace/nightlyLog.log
 125 0  5   *   *   * ctest -S /home/mpech/workspace/vv/vvDashboard/continuousBuild.cmake,ItkNightly -V > /home/mpech/workspace/vvItkNightly/continuousMaster.log 2>&1
 126 \end{verbatim}
 127 A 22h, on commence les builds linux puis on lance la VM. Chaque OS a la responsabilité de s'éteindre.\\
 128 \begin{note}
 129 A 5h tous les jours un continuous est lancé. Il n'est pas nécessaire d'appeler plusieurs fois le continous :
 130 une fois appelé, il dure pendant ''dashboard\_loop'' et tente une mise à jour du repo et soumet un build
 131 au dashboard si le repo a été modifié, tous les ''CTEST\_DELAY\_TIME''. Ces variables
 132 se modifient dans continuousBuild.cmake.
 133 En regardant le script continuousBuild.cmake, on constate qu'il est effectif pendant une durée de \${dashboard\_loop}68400/3600=19h.
 134 \end{note}
 135 \item Sous windows :
 136 Il faut également créer une tâche appelant builderNightly.bat. Ce dernier lance également les builds et une fois ceux-ci finis,
 137 éteint l'OS.
 138 Voici un \htmladdnormallink{lien}{http://www.vistax64.com/tutorials/132903-task-scheduler-create-task.html}.
 139 Démarrer>exécuter>taskschd.msc ou bien clique-droit gérer sur ''Ordinateur'' dans l'explorateur de fichiers.
 140
 141 Sur le pannel de gauche, librairie>windows, créer un dossier par exemple vv, et à l'intérieur créer une nouvelle tache.
 142 Seuls les déclencheurs et l'action (builderNightly.bat) nous intéresse.
 143 \end{itemize}
 144
 145 \section{Configuration du dashboard}
 146 Le dashboard de VV est accessible via ce \htmladdnormallink{lien}{http://my.cdash.org/index.php?project=VV}.\\
 147
 148 Le fuseau horaire d'affichage du dashboard est EDT.\\
 149 Nous sommes CET. Il n'est pas possible de modifier l'heure affichée sur le dashboard pour qu'elle
 150 corresponde à l'heure CET.
 151 En revanche, il est possible de spécifier l'heure de début des nightly : sachant qu'il y a un décalage de 6h
 152 (10h en France équivaut à 4h sur le dashboard). Par exemple si nous soumettons un build à 1h CET le mardi, cela équivaut à soumettre ce build à 19h EDT le lundi.\\
 153 Ce faisant, en indiquant que les nightly commencent à 19h EDT sur le dashboard, notre build sera bien affiché mardi sur le dashboard.
 154
 155
 156  \chapter{Création d'un sous-module pour les données de test}
 157 \section{Git deuxième repo}
 158 Actuellement, un deuxième repo est utilisé pour les données de test.
 159 \begin{verbatim}
 160 http://russule/gitSources/vvDataTest
 161 # ou bien
 162 /home/mpech/workspace/git/vvDataTest
 163 \end{verbatim}
 164
 165 Le serveur n'est pas configuré pour pouvoir pusher par http. Donc soit passer par le repo /home/..., soit
 166 \begin{verbatim}
 167 git push ssh://mpech@russule/home/mpech/workspace/gitSources/vvDataTest
 168 \end{verbatim}
 169
 170 \subsection{Mise en place du Git par http}
 171 \begin{verbatim}
 172 sudo zypper install apache2
 173 cd /srv/www/htdocs
 174 sudo ln -s /home/mpech/workspace/git gitSources
 175 \end{verbatim}
 176 Il est possible que le dossier ne soit pas accessible, s'assurer que FollowSymlinks est bien précisé. Chez moi dans
 177 le fichier ''/etc/apache2/default-server.conf'', rajouter les options si non présentes.\\
 178 Indexes pour afficher la liste des dossiers/fichiers présents dans un répertoire \\
 179 FollowSymLinks pour permettre les liens symboliques depuis le répertoire web vers un répertoire quelconque.
 180 \begin{verbatim}
 181 <Directory "/srv/www/htdocs">
 182         Options Indexes FollowSymLinks
 183 \end{verbatim}
 184
 185 Enfin, après chaque push vers le remote repo, il faut updater le serveur manuellement.
 186 \begin{verbatim}
 187 cd /home/mpech/workspace/git;
 188 git update-server-info
 189 \end{verbatim}
 190 A la place, on peut activer le hook post-update de git (en renommant le post-update.sample sans son suffixe):
 191 \begin{verbatim}
 192 cd /home/mpech/workspace/git/vvDatatest/hooks
 193 mv post-update.sample post-update
 194 \end{verbatim}
 195 De fait, git sera automatiquement mis à jour.
 196 \\
 197 \begin{note}
 198  Ici git ne fait pas référence au données de test, le répertoire git contient
 199 \begin{itemize}
 200 \item vvDataTest qui est le repo qui nous intéresse
 201 \item vvDashboard qui contient les scripts pour les nightly, également versionné
 202 \end{itemize}
 203 \end{note}
 204
 205 \section{Git submodule}
 206 Procédure pour monter le dossier de tests.
 207 Création de notre repo data (qui contiendra les données de test):
 208 \begin{verbatim}
 209 git init --bare data
 210 git clone tests dataCloned
 211 (
 212  cd dataCloned; echo "a">a; git add a; git commit -m "add a";
 213  git push origin master
 214 )
 215 \end{verbatim}
 216 Le fichier ''a'' est accessible aux autres clones de data.
 217
 218 On ajoute notre repo dataCloned en tant que submodule du super repo (par exemple vv).
 219 \begin{verbatim}
 220 cd vv;
 221 git submodule add ../dataCloned tests/data
 222 git commit -m "added the submodule data"
 223 git push
 224 \end{verbatim}
 225
 226 Côté client :
 227 \begin{verbatim}
 228 cd vv;
 229 git pull;
 230 git submodule init;
 231 git submodule update; //now tests/data contain a file named "a"
 232 cd tests/data; echo "b">b; git add b && git commit -m "adding b";
 233 git push
 234 \end{verbatim}
 235
 236 Comme le sous-module a été modifié, on oublie pas de mettre à jour super :
 237 \begin{verbatim}
 238 git submodule add tests/data #remarque : PAS de trailing slash à la fin de data
 239 git commit -m "mise à jour du sous-repos"
 240 git push
 241 \end{verbatim}
 242
 243 Désormais les autres pourront git submodule update avec la dernière version du repo de data.
 244
 245 Si on avait pas commité, alors le submodule update ne tient pas compte des nouvelles modifications
 246 sur le repository data.
 247
 248 \subsection{Enlever des fichiers du repository data}
 249 Si pour une raison x, on veut enlever des fichiers de data. Par exemple heavy.dcm
 250 dans le submodule ou simplement dans dataCloned :
 251 \begin{verbatim}
 252 #modify l'arbre
 253 git filter-branch --index-filter 'git rm --cached --ignore-unmatch heavy.dcm' HEAD
 254 git push origin master --force
 255 \end{verbatim}
 256
 257 dans le bare repo data :
 258 \begin{verbatim}
 259 git reflog expire --expire=now --all
 260 git gc --aggressive --prune=now
 261 \end{verbatim}
 262
 263 Côté super, on met à jour le submodule,
 264 \begin{verbatim}
 265 git pull
 266 #puis on ajoute la nouvelle référence :
 267 git add tests/data; git commit -m "updated submodule"; git push
 268 \end{verbatim}
 269
 270
 271 Côté client, celui-ci n'a plus qu'à runner
 272 \begin{verbatim}
 273 git pull; git submodule update
 274 \end{verbatim}
 275 Si il avait le fichier heavy.dcm, alors celui-ci est potentiellement encore dans le .git du submodule. Il peut l'enlever
 276 à coup de
 277 \begin{verbatim}
 278 rm -rf .git/refs/original
 279 git reflog expire --expire=now --all
 280 git gc --aggressive --prune=now
 281 \end{verbatim}
 282
 283 Source : \htmladdnormallink{github}{http://help.github.com/remove-sensitive-data/}
 284
 285
 286
 287
 288
 289  \chapter{Procédure de test d'outils}
 290 \section{Procédure de test}
 291 \begin{enumerate}
 292         \item Choisir un outil, et une image test d'entrée.
 293         \item Lui faire générer une image
 294         \item Cette image générée sert de référence. L'outil valide doit générer cette image à partir de l'image test d'entrée.
 295         \item Passer l'image test d'entrée et s'assurer que l'outil génère bien l'image de référence.
 296 \end{enumerate}
 297 \section{Step by Step}
 298 \begin{enumerate}
 299         \item Choisir un outils : ex : clitkCropImage
 300         \item Chercher comment le lancer :
 301 \begin{verbatim}
 302 cat $(find -name *CropImage*ggo)
 303 \end{verbatim}
 304         \item Choisir les images qui vont bien: par défaut sont présentes Lung3D.mhd, Deformation4D.mhd (toutes deux de petites
 305 tailles), les paramètres etc...
 306         \item Exécuter l'outil : ./clitkCropImage {parametres}
 307         \item Récupérer la (les) images générées (vérifier qu'elle(s) est(sont) correcte(s)) et les copier dans le dossier
 308 des images de test.
 309         \item Mettre à jour le /tests/tools/CMakeLists.txt en ajoutant le test
 310         \item Vérifier qu'on a bien le test qui passe,
 311 \begin{verbatim}
 312 #on reparse le CMakeLists.txt
 313         cmake ../vvSource
 314 #et on run les tests
 315         make test
 316 \end{verbatim}
 317 Si un test échoue, on peut accéder à la raison via le fichier /Testing/Temporary/lastTest.log
 318         \item Répéter pour autant de tests qu'on veut faire sur un outils
 319         \item Mettre à jour le dashboard ''make Experimental''
 320         \item Commit/Push les images sur le git des images tests
 321         \item Commit du CMakeLists.txt sur le repository de vv
 322 \end{enumerate}
 323
 324
 325 \end{document}