352ab1710d595a69e2144cc59f20bfaa42a44e1f
[platform/upstream/gcc48.git] / INSTALL / test.html
1 <html lang="en">
2 <head>
3 <title>Installing GCC: Testing</title>
4 <meta http-equiv="Content-Type" content="text/html">
5 <meta name="description" content="Installing GCC: Testing">
6 <meta name="generator" content="makeinfo 4.13">
7 <link title="Top" rel="top" href="#Top">
8 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
9 <!--
10 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997,
11 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
12 2010 Free Software Foundation, Inc.
13
14    Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.3 or
16 any later version published by the Free Software Foundation; with no
17 Invariant Sections, the Front-Cover texts being (a) (see below), and
18 with the Back-Cover Texts being (b) (see below).  A copy of the
19 license is included in the section entitled "GNU Free Documentation License".
20
21 (a) The FSF's Front-Cover Text is:
22
23      A GNU Manual
24
25 (b) The FSF's Back-Cover Text is:
26
27      You have freedom to copy and modify this GNU Manual, like GNU
28      software.  Copies published by the Free Software Foundation raise
29      funds for GNU development.-->
30 <meta http-equiv="Content-Style-Type" content="text/css">
31 <style type="text/css"><!--
32   pre.display { font-family:inherit }
33   pre.format  { font-family:inherit }
34   pre.smalldisplay { font-family:inherit; font-size:smaller }
35   pre.smallformat  { font-family:inherit; font-size:smaller }
36   pre.smallexample { font-size:smaller }
37   pre.smalllisp    { font-size:smaller }
38   span.sc    { font-variant:small-caps }
39   span.roman { font-family:serif; font-weight:normal; } 
40   span.sansserif { font-family:sans-serif; font-weight:normal; } 
41 --></style>
42 </head>
43 <body>
44 <h1 class="settitle">Installing GCC: Testing</h1>
45 <a name="index-Testing-1"></a><a name="index-Installing-GCC_003a-Testing-2"></a><a name="index-Testsuite-3"></a>
46 Before you install GCC, we encourage you to run the testsuites and to
47 compare your results with results from a similar configuration that have
48 been submitted to the
49 <a href="http://gcc.gnu.org/ml/gcc-testresults/">gcc-testresults mailing list</a>. 
50 Some of these archived results are linked from the build status lists
51 at <a href="http://gcc.gnu.org/buildstat.html">http://gcc.gnu.org/buildstat.html</a>, although not everyone who
52 reports a successful build runs the testsuites and submits the results. 
53 This step is optional and may require you to download additional software,
54 but it can give you confidence in your new GCC installation or point out
55 problems before you install and start using your new GCC.
56
57    <p>First, you must have <a href="download.html">downloaded the testsuites</a>. 
58 These are part of the full distribution, but if you downloaded the
59 &ldquo;core&rdquo; compiler plus any front ends, you must download the testsuites
60 separately.
61
62    <p>Second, you must have the testing tools installed.  This includes
63 <a href="http://www.gnu.org/software/dejagnu/">DejaGnu</a>, Tcl, and Expect;
64 the DejaGnu site has links to these.
65
66    <p>If the directories where <samp><span class="command">runtest</span></samp> and <samp><span class="command">expect</span></samp> were
67 installed are not in the <samp><span class="env">PATH</span></samp>, you may need to set the following
68 environment variables appropriately, as in the following example (which
69 assumes that DejaGnu has been installed under <samp><span class="file">/usr/local</span></samp>):
70
71 <pre class="smallexample">     TCL_LIBRARY = /usr/local/share/tcl8.0
72      DEJAGNULIBS = /usr/local/share/dejagnu
73 </pre>
74    <p>(On systems such as Cygwin, these paths are required to be actual
75 paths, not mounts or links; presumably this is due to some lack of
76 portability in the DejaGnu code.)
77
78    <p>Finally, you can run the testsuite (which may take a long time):
79 <pre class="smallexample">     cd <var>objdir</var>; make -k check
80 </pre>
81    <p>This will test various components of GCC, such as compiler
82 front ends and runtime libraries.  While running the testsuite, DejaGnu
83 might emit some harmless messages resembling
84 &lsquo;<samp><span class="samp">WARNING: Couldn't find the global config file.</span></samp>&rsquo; or
85 &lsquo;<samp><span class="samp">WARNING: Couldn't find tool init file</span></samp>&rsquo; that can be ignored.
86
87    <p>If you are testing a cross-compiler, you may want to run the testsuite
88 on a simulator as described at <a href="http://gcc.gnu.org/simtest-howto.html">http://gcc.gnu.org/simtest-howto.html</a>.
89
90 <h3 class="section"><a name="TOC0"></a>How can you run the testsuite on selected tests?</h3>
91
92 <p>In order to run sets of tests selectively, there are targets
93 &lsquo;<samp><span class="samp">make check-gcc</span></samp>&rsquo; and language specific &lsquo;<samp><span class="samp">make check-c</span></samp>&rsquo;,
94 &lsquo;<samp><span class="samp">make check-c++</span></samp>&rsquo;, &lsquo;<samp><span class="samp">make check-fortran</span></samp>&rsquo;, &lsquo;<samp><span class="samp">make check-java</span></samp>&rsquo;,
95 &lsquo;<samp><span class="samp">make check-ada</span></samp>&rsquo;, &lsquo;<samp><span class="samp">make check-objc</span></samp>&rsquo;, &lsquo;<samp><span class="samp">make check-obj-c++</span></samp>&rsquo;,
96 &lsquo;<samp><span class="samp">make check-lto</span></samp>&rsquo;
97 in the <samp><span class="file">gcc</span></samp> subdirectory of the object directory.  You can also
98 just run &lsquo;<samp><span class="samp">make check</span></samp>&rsquo; in a subdirectory of the object directory.
99
100    <p>A more selective way to just run all <samp><span class="command">gcc</span></samp> execute tests in the
101 testsuite is to use
102
103 <pre class="smallexample">     make check-gcc RUNTESTFLAGS="execute.exp <var>other-options</var>"
104 </pre>
105    <p>Likewise, in order to run only the <samp><span class="command">g++</span></samp> &ldquo;old-deja&rdquo; tests in
106 the testsuite with filenames matching &lsquo;<samp><span class="samp">9805*</span></samp>&rsquo;, you would use
107
108 <pre class="smallexample">     make check-g++ RUNTESTFLAGS="old-deja.exp=9805* <var>other-options</var>"
109 </pre>
110    <p>The <samp><span class="file">*.exp</span></samp> files are located in the testsuite directories of the GCC
111 source, the most important ones being <samp><span class="file">compile.exp</span></samp>,
112 <samp><span class="file">execute.exp</span></samp>, <samp><span class="file">dg.exp</span></samp> and <samp><span class="file">old-deja.exp</span></samp>. 
113 To get a list of the possible <samp><span class="file">*.exp</span></samp> files, pipe the
114 output of &lsquo;<samp><span class="samp">make check</span></samp>&rsquo; into a file and look at the
115 &lsquo;<samp><span class="samp">Running ...  .exp</span></samp>&rsquo; lines.
116
117 <h3 class="section"><a name="TOC1"></a>Passing options and running multiple testsuites</h3>
118
119 <p>You can pass multiple options to the testsuite using the
120 &lsquo;<samp><span class="samp">--target_board</span></samp>&rsquo; option of DejaGNU, either passed as part of
121 &lsquo;<samp><span class="samp">RUNTESTFLAGS</span></samp>&rsquo;, or directly to <samp><span class="command">runtest</span></samp> if you prefer to
122 work outside the makefiles.  For example,
123
124 <pre class="smallexample">     make check-g++ RUNTESTFLAGS="--target_board=unix/-O3/-fmerge-constants"
125 </pre>
126    <p>will run the standard <samp><span class="command">g++</span></samp> testsuites (&ldquo;unix&rdquo; is the target name
127 for a standard native testsuite situation), passing
128 &lsquo;<samp><span class="samp">-O3 -fmerge-constants</span></samp>&rsquo; to the compiler on every test, i.e.,
129 slashes separate options.
130
131    <p>You can run the testsuites multiple times using combinations of options
132 with a syntax similar to the brace expansion of popular shells:
133
134 <pre class="smallexample">     ..."--target_board=arm-sim\{-mhard-float,-msoft-float\}\{-O1,-O2,-O3,\}"
135 </pre>
136    <p>(Note the empty option caused by the trailing comma in the final group.) 
137 The following will run each testsuite eight times using the &lsquo;<samp><span class="samp">arm-sim</span></samp>&rsquo;
138 target, as if you had specified all possible combinations yourself:
139
140 <pre class="smallexample">     --target_board=arm-sim/-mhard-float/-O1
141      --target_board=arm-sim/-mhard-float/-O2
142      --target_board=arm-sim/-mhard-float/-O3
143      --target_board=arm-sim/-mhard-float
144      --target_board=arm-sim/-msoft-float/-O1
145      --target_board=arm-sim/-msoft-float/-O2
146      --target_board=arm-sim/-msoft-float/-O3
147      --target_board=arm-sim/-msoft-float
148 </pre>
149    <p>They can be combined as many times as you wish, in arbitrary ways.  This
150 list:
151
152 <pre class="smallexample">     ..."--target_board=unix/-Wextra\{-O3,-fno-strength\}\{-fomit-frame,\}"
153 </pre>
154    <p>will generate four combinations, all involving &lsquo;<samp><span class="samp">-Wextra</span></samp>&rsquo;.
155
156    <p>The disadvantage to this method is that the testsuites are run in serial,
157 which is a waste on multiprocessor systems.  For users with GNU Make and
158 a shell which performs brace expansion, you can run the testsuites in
159 parallel by having the shell perform the combinations and <samp><span class="command">make</span></samp>
160 do the parallel runs.  Instead of using &lsquo;<samp><span class="samp">--target_board</span></samp>&rsquo;, use a
161 special makefile target:
162
163 <pre class="smallexample">     make -j<var>N</var> check-<var>testsuite</var>//<var>test-target</var>/<var>option1</var>/<var>option2</var>/...
164 </pre>
165    <p>For example,
166
167 <pre class="smallexample">     make -j3 check-gcc//sh-hms-sim/{-m1,-m2,-m3,-m3e,-m4}/{,-nofpu}
168 </pre>
169    <p>will run three concurrent &ldquo;make-gcc&rdquo; testsuites, eventually testing all
170 ten combinations as described above.  Note that this is currently only
171 supported in the <samp><span class="file">gcc</span></samp> subdirectory.  (To see how this works, try
172 typing <samp><span class="command">echo</span></samp> before the example given here.)
173
174 <h3 class="section"><a name="TOC2"></a>Additional testing for Java Class Libraries</h3>
175
176 <p>The Java runtime tests can be executed via &lsquo;<samp><span class="samp">make check</span></samp>&rsquo;
177 in the <samp><var>target</var><span class="file">/libjava/testsuite</span></samp> directory in
178 the build tree.
179
180    <p>The <a href="http://sourceware.org/mauve/">Mauve Project</a> provides
181 a suite of tests for the Java Class Libraries.  This suite can be run
182 as part of libgcj testing by placing the Mauve tree within the libjava
183 testsuite at <samp><span class="file">libjava/testsuite/libjava.mauve/mauve</span></samp>, or by
184 specifying the location of that tree when invoking &lsquo;<samp><span class="samp">make</span></samp>&rsquo;, as in
185 &lsquo;<samp><span class="samp">make MAUVEDIR=~/mauve check</span></samp>&rsquo;.
186
187 <h3 class="section"><a name="TOC3"></a>How to interpret test results</h3>
188
189 <p>The result of running the testsuite are various <samp><span class="file">*.sum</span></samp> and <samp><span class="file">*.log</span></samp>
190 files in the testsuite subdirectories.  The <samp><span class="file">*.log</span></samp> files contain a
191 detailed log of the compiler invocations and the corresponding
192 results, the <samp><span class="file">*.sum</span></samp> files summarize the results.  These summaries
193 contain status codes for all tests:
194
195      <ul>
196 <li>PASS: the test passed as expected
197 <li>XPASS: the test unexpectedly passed
198 <li>FAIL: the test unexpectedly failed
199 <li>XFAIL: the test failed as expected
200 <li>UNSUPPORTED: the test is not supported on this platform
201 <li>ERROR: the testsuite detected an error
202 <li>WARNING: the testsuite detected a possible problem
203 </ul>
204
205    <p>It is normal for some tests to report unexpected failures.  At the
206 current time the testing harness does not allow fine grained control
207 over whether or not a test is expected to fail.  This problem should
208 be fixed in future releases.
209
210 <h3 class="section"><a name="TOC4"></a>Submitting test results</h3>
211
212 <p>If you want to report the results to the GCC project, use the
213 <samp><span class="file">contrib/test_summary</span></samp> shell script.  Start it in the <var>objdir</var> with
214
215 <pre class="smallexample">     <var>srcdir</var>/contrib/test_summary -p your_commentary.txt \
216          -m gcc-testresults@gcc.gnu.org |sh
217 </pre>
218    <p>This script uses the <samp><span class="command">Mail</span></samp> program to send the results, so
219 make sure it is in your <samp><span class="env">PATH</span></samp>.  The file <samp><span class="file">your_commentary.txt</span></samp> is
220 prepended to the testsuite summary and should contain any special
221 remarks you have on your results or your build environment.  Please
222 do not edit the testsuite result block or the subject line, as these
223 messages may be automatically processed.
224
225    <p><hr />
226 <p><a href="./index.html">Return to the GCC Installation page</a>
227
228 <!-- ***Final install*********************************************************** -->
229 <!-- ***Binaries**************************************************************** -->
230 <!-- ***Specific**************************************************************** -->
231 <!-- ***Old documentation****************************************************** -->
232 <!-- ***GFDL******************************************************************** -->
233 <!-- *************************************************************************** -->
234 <!-- Part 6 The End of the Document -->
235 </body></html>
236