]> Creatis software - clitk.git/blob - tests/doc/vvDoc.tex
Add quotes in case variables are not defined
[clitk.git] / 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}