* Bug #14605 fixed - bench_run was too strict about testnames specification
[scilab.git] / scilab / modules / development_tools / help / fr_FR / bench_run.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="bench_run" xml:lang="fr">
17     <refnamediv>
18         <refname>bench_run</refname>
19         <refpurpose>Lance les tests de performances</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntaxe</title>
23         <synopsis>
24             [modutests_names, elapsed_time, nb_iterations] = bench_run()
25             [modutests_names, elapsed_time, nb_iterations] = bench_run(module[, test_name[, options, [exportToFile]])
26             [modutests_names, elapsed_time, nb_iterations] = bench_run(path_to_module[, test_name[, options, [exportToFile]])
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>module</term>
34                 <listitem>
35                     <para>Vecteur de chaînes de caractères. Noms des modules internes à Scilab à tester.</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>path_to_module</term>
40                 <listitem>
41                     <para>
42                         Vecteur de chaînes de caractères. Contient les chemins des modules à tester. Si <literal>"/chemin/vers/module"</literal> est donné en argument d'entrée, les tests sont récupérés dans le sous répertoire
43                         <literal>
44                             /chemin/vers/module/<emphasis role="bold">tests/benchmarks</emphasis>
45                         </literal>
46                         .A utiliser pour les tests de performance maison.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>test_name</term>
52                 <listitem>
53                     <para>Vecteur de chaînes de caractères. Contient les noms des tests à effectuer.</para>
54                     <para>
55                         Le nom d'un test est le nom du fichier sans <literal>.tst</literal>. Si plusieurs modules ou répertoires sont donnés comme premier argument d'entrée, recherche les tests dans chacun de ces modules ou répertoires.
56                     </para>
57                     <note>
58                         Il est possible d'utiliser un libellé partiel/générique
59                         afin de lancer plusieurs bancs-tests dédiés à la même
60                         fonction/fonctionnalité. Par exemple, spécifier
61                         <literal>"ascii"</literal> sélectionnera tous les tests
62                         (dans les modules ciblés) dont le nom contient
63                         <literal>"ascii"</literal> (voir les exemples).
64                     </note>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>options</term>
69                 <listitem>
70                     <para>Vecteur de chaînes de caractères. Options parmi:</para>
71                     <itemizedlist>
72                         <listitem>
73                             <para>
74                                 <literal>"list"</literal> : liste les tests de performance (<literal>test_name</literal>) présents dans un module
75                             </para>
76                         </listitem>
77                         <listitem>
78                             <para>
79                                 <literal>"help"</literal> : affiche quelques exemples d'utilisation en console
80                             </para>
81                         </listitem>
82                         <listitem>
83                             <para>
84                                 <literal>"nb_run=value"</literal> : lance <literal>value</literal> fois chaque tests, par défaut <function>bench_run</function> effectue 10000 fois le code présent entre les balises BENCH START et BENCH END (voir ci-après). Remplace la valeur spécifiée dans la balise <literal>BENCH NB RUN</literal> pour les scripts de tests.
85                             </para>
86                         </listitem>
87                     </itemizedlist>
88                 </listitem>
89             </varlistentry>
90             <varlistentry>
91                 <term>exportToFile</term>
92                 <listitem>
93                     <para>une chaîne de caractères</para>
94                     <para>
95                         Chemin du fichier d'export des résultats de <function>bench_run</function> au format xml. Par défaut ou si <literal>"", []</literal> ou <literal>"[]"</literal> sont donnés en paramètres d'entrée, the répertoire de sortie est <literal>TMPDIR/benchmarks/</literal>.
96                     </para>
97                     <para>
98                         Si <literal>exportToFile</literal> est un répertoire, crée un fichier horodaté dans le répertoire, sinon crée le fichier <literal>exportToFile</literal>. Si ce fichier n'a pas pu être créé, un avertissement est affiché et le fichier est créé sous le répertoire <literal>TMPDIR/benchmarks/</literal>.
99                     </para>
100                 </listitem>
101             </varlistentry>
102             <varlistentry>
103                 <term>modutests_names</term>
104                 <listitem>
105                     <para>matrice de chaînes de caractères de taille N-par-2</para>
106                     <para>
107                         La première colonne représente les modules et chemins vers les fichiers testés par <function>bench_run</function>, la seconde colonne représente les noms des tests de performance.
108                     </para>
109                 </listitem>
110             </varlistentry>
111             <varlistentry>
112                 <term>elapsed_time</term>
113                 <listitem>
114                     <para>vecteur de décimaux</para>
115                     <para>temps d'execution pour chaque test de performance</para>
116                 </listitem>
117             </varlistentry>
118             <varlistentry>
119                 <term>nb_iterations</term>
120                 <listitem>
121                     <para>vecteur de décimaux de taille N</para>
122                     <para>nombre de fois que chaque a été lancé respectivement</para>
123                 </listitem>
124             </varlistentry>
125         </variablelist>
126     </refsection>
127     <refsection>
128         <title>Description</title>
129         <para>
130             Effectue des tests de performance, mesure les temps d'exécution et produit un rapport d'exécution pour ces tests.
131         </para>
132         <para>
133             Recherche tous les fichiers <literal>.tst</literal> sous le répertoire <literal>tests/benchmarks</literal> présent dans les modules internes scilab ou dans les chemins fournis en variable d'entrée, exécute ces fichiers 10000 fois et produit un rapport d'exécution.
134         </para>
135         <para>
136             Des balises présentes dans le fichier <literal>.tst</literal> permettent de contrôler le processus du test correspondant. Ces balises sont recherchées dans les commentaires du scripts.
137         </para>
138         <para>Les balises disponibles sont :</para>
139         <itemizedlist>
140             <listitem>
141                 <para>
142                     <literal>&lt;-- BENCH NB RUN : 10 --&gt;</literal>
143                 </para>
144                 <para>
145                     Par défaut, le test sera répété 10 fois, sauf si l'option <literal>"nb_run=###"</literal> de <literal>bench_run(...)</literal> est utilisée. Toute valeur entière peut être donnée pour cette balise.
146                 </para>
147             </listitem>
148             <listitem>
149                 <para>
150                     <programlisting role="no-scilab-exec"><![CDATA[
151 //    <-- BENCH START -->
152 [code à exécuter]
153 //    <-- BENCH END -->
154 ]]></programlisting>
155                 </para>
156                 <para>
157                     Le code entre ces deux balises sera répétée lors du test de performance.
158                     Le code présent avant/après ces balises est exécuté une seule fois
159                     avant/après la répétition et n'est pas chronométré.
160                     Si ces balises sont absentes, le code entier sera répété.
161                 </para>
162             </listitem>
163         </itemizedlist>
164     </refsection>
165     <refsection>
166         <title>Exemples</title>
167         <para>
168             Quelques exemples d'utilisation de <function>bench_run</function>
169         </para>
170         <programlisting role="example"><![CDATA[
171 // Lance tous les tests
172 // Cela peut prendre du temps...
173 // bench_run();
174 // bench_run([]);
175 // bench_run([],[]);
176
177 // Test d'un ou de plusieurs modules
178 bench_run('core');
179 bench_run('core',[]);
180 bench_run(['core','string']);
181
182 // Lance des tests spécifiques sur un module
183 bench_run('core',['trycatch','opcode']);
184
185 // Avec des options
186 bench_run([],[],'list');
187 bench_run([],[],'help');
188 bench_run("string", [], 'nb_run=100');
189 // Résultats dans un ficher sous le répertoire local
190 bench_run("string", [], 'nb_run=100', 'my_output_file.xml');
191 // Résultats dans un répertoire, par défaut sous TMPDIR/benchmarks
192 bench_run("string", [], 'nb_run=100', TMPDIR);
193  ]]></programlisting>
194         <para> Exemple de fichier de test
195             SCI/modules/linear_algebra/tests/benchmarks/bench_chol.tst.
196         </para>
197         <programlisting role="example"><![CDATA[
198 // =============================================================================
199 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
200 // Copyright (C) 2007-2008 - INRIA
201 //
202 //  This file is distributed under the same license as the Scilab package.
203 // =============================================================================
204
205 //==============================================================================
206 // Benchmark for chol function
207 //==============================================================================
208
209 // <-- BENCH NB RUN : 10 -->
210
211 a = 0;
212 b = 0;
213 a = rand(900, 900, 'n');
214 a = a'*a;
215
216 // <-- BENCH START -->
217 b = chol(a);
218 // <-- BENCH END -->
219 ]]></programlisting>
220         <para>résultat du test</para>
221         <screen><![CDATA[
222 -->bench_run('linear_algebra','bench_chol')
223
224           For Loop (as reference) ...........................      33.20 ms [ 1000000 x]
225
226 001/001 - [linear_algebra] bench_chol ......................     1233.93 ms [      10 x]
227   ]]></screen>
228     <para>
229     Lancer un lot de tests dédiés à une même fonctionalité en utilisant un
230     libellé partiel/générique :
231     <screen><![CDATA[
232 --> bench_run string ascii
233
234          For Loop (as reference) ...........................      102.98 ms [ 1000000 x]
235
236  001/005 - [string] bench_ascii_1 ...........................      447.40 ms [   10000 x]
237  002/005 - [string] bench_ascii_2 ...........................    31727.98 ms [ 1000000 x]
238  003/005 - [string] bench_ascii_3 ...........................     4173.69 ms [   10000 x]
239  004/005 - [string] bench_ascii_4 ...........................     5145.06 ms [   10000 x]
240  005/005 - [string] bench_ascii_UTF8 ........................       23.26 ms [      10 x]
241 ]]></screen>
242     </para>
243     </refsection>
244     <refsection role="see also">
245         <title>Voir aussi</title>
246         <simplelist type="inline">
247             <member>
248                 <link linkend="test_run">test_run</link>
249             </member>
250             <member>
251                 <link linkend="covStart">coverage</link>
252             </member>
253             <member>
254                 <link linkend="slint">slint</link>
255             </member>
256             <member>
257                 <link linkend="debug">debug</link>
258             </member>
259         </simplelist>
260     </refsection>
261     <refsection role="history">
262         <title>Historique</title>
263         <revhistory>
264             <revision>
265                 <revnumber>6.0</revnumber>
266                 <revdescription>
267                     <itemizedlist>
268                         <listitem>
269                             <literal>bench_run()</literal> peut maintenant retourner les résultats des tests de performance via les nouveaux paramètres de sortie
270                             <literal>modutests_names</literal>, <literal>elapsed_time</literal> et <literal>nb_iterations</literal>
271                         </listitem>
272                         <listitem>
273                             L'export des résultats au format XML est désormais possible
274                         </listitem>
275                         <listitem>
276                             Les paramètres de  configuration globale
277                             mode(),format(), ieee(), warning() et funcprot()
278                             sont protégés lors des tests.
279                         </listitem>
280                         <listitem>
281                             Les libellés partiels/génériques de tests sont désormais
282                             permis afin de lancer un lot de tests dédiés à la même
283                             fonction/fonctionnalité.
284                         </listitem>
285                     </itemizedlist>
286                 </revdescription>
287             </revision>
288         </revhistory>
289     </refsection>
290 </refentry>