[RFC] Big patch to contribute.html

["Giovanni Bajo" <giovannibajo at libero dot it>]

Hello,

this patch adds two new sections in contribute.html:

* A section about testcase preparation. This explains the guidelines people
should follow while preparing testcases to submit with the patches. It gives a
brief overview of DejaGnu, and how to use the main dg-* commands, with
examples. It also explains where to add the testcases, how to test a specific
testcase and where to find testsuite logs to debug failures. I remember that
when I started contributing to GCC, I had troubles preparing testcases, I was
totally unfamiliar with DejaGnu, and I really missed some documentation like
this.

* A section about contributing a new backend, inspired by the submission of the
CR16C backend back in February
(http://gcc.gnu.org/ml/gcc-patches/2004-02/msg01416.html), which was rejected
for many different reasons. I feel we owe our contributors to document what are
the current de-facto policies on allowing new backends to be added to the GCC
tree, before they waste their time.

I expect the patch to be filled with (not so) small imprecisions, errors,
omissions, and such, this is why this is a RFC. I think I'll reiterate the
patch after about a week collecting all comments and corrections.

A small note is needed for this paragraph:

+ <p>Each testcase which is XFAIL-ed must have a corresponding PR open in the
+ <a href="http://gcc.gnu.org/bugzilla";>bug database</a>, and the PR number
+ must be referenced in a comment in the testcase itself. This makes sure
+ that the failure is not forgotten.</p>

This is a new policy for which there was enough consesus back in February, see
the thread starting here: http://gcc.gnu.org/ml/gcc/2004-02/msg00844.html. With
this patch, we are basically making this go "live". We can then incrementally
file bugs for existing xfails, and maybe bugmasters can spend some time to do
big batches of bug submissions.

Tested with the W3C validator.

Giovanni Bajo


Index: contribute.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/contribute.html,v
retrieving revision 1.57
diff -c -3 -p -u -r1.57 contribute.html
--- contribute.html 12 Jan 2004 22:03:21 -0000 1.57
+++ contribute.html 7 Jun 2004 02:34:39 -0000
@@ -24,6 +29,8 @@ contributions must meet:</p>
 <li><a href="#docchanges">Documentation Changes</a></li>
 <li><a href="#webchanges">Web Site Changes</a></li>
 <li><a href="#patches">Submitting Patches</a></li>
+<li><a href="#testcases">Preparing Testcases</a></li>
+<li><a href="#backends">Submitting New Backends</a></li>
 </ul>

 <hr />
@@ -61,6 +68,11 @@ href="codingconventions.html">additional
 GCC</a>; these include documentation and testsuite requirements as
 well as requirements on code formatting.</p>

+<p>Notice that GCC now requires an ISO C90 compiler to bootstrap,
+so there is no need anymore to make the code conform to K&amp;R C for
+either new files or existing code (no need for the <code>PARAMS</code>
+macro in function prototypes, <code>#elif</code> is available, etc.).</p>
+
 <p>Submissions which do not conform to the standards will be returned
 with a request to address any such problems.</p>

@@ -108,7 +120,7 @@ If you already did a complete C,C++,Java
 directory before, you can use the following:</p>
 <blockquote><pre>
 make clean-target-libstdc++-v3                    # clean libstdc++ and ...
-test -d */libjava && make -C */libjava clean-nat  # ... parts of libjava
+test -d */libjava &amp;&amp; make -C */libjava clean-nat  # ... parts of
libjava
 make all-target-libstdc++-v3 all-target-libjava   # rebuild compiler and
libraries
 make -k check-c++                                 # run C++/libstdc++
testsuite
 </pre></blockquote>
@@ -182,10 +194,8 @@ existing testcases for the problem in th

 <dt>Testcases</dt>
 <dd>
-If you cannot follow the recommendations of the <a
-href="codingconventions.html">GCC coding conventions</a> about
-testcases, you should include a justification for why adequate
-testcases cannot be added.
+Usually, a patch must come with an attacched testcase. Please, read
+the section below on <a href="#testcases">how to prepare a testcase</a>.
 </dd>

 <dt>ChangeLog</dt>
@@ -277,5 +287,637 @@ no-one else will need to apply it to the
 totally new files may be omitted (especially if large) since they can be
 accessed directly from the repository.</p>

+
+<h2><a name="testcases">Preparing Testcases</a></h2>
+
+<p>Every patch submitted for approval should always come with a testcase
+to be added to the testsuite (there are a few exceptions that are listed
+below). The testcase should be able to reproduce the bug on all
+affected platforms, and it is used to make sure that the bug stays fixed.</p>
+
+<p>There are some basic guidelines you should follow while preparing a
+testcase:</p>
+<ul>
+ <li>The testcase should be as small as possible. Most bugs can be
+ minimized to a hanful of lines of code, trying hard enough. Usually,
+ volunteers take care of the minimization if the bug is reported in the
+ <a href="http://gcc.gnu.org/bugzilla/";>bug database</a>.</li>
+
+ <li>The testcase should be atomic. If your patch fixes a bug which can be
+ reproduced with different code sequences (or a family of slightly similar
+ bugs), it is better to prepare several different testcases instead of a
+ longer one.</li>
+
+ <li>If the testcase is for a bug from our bug database, the specific PR
+ must be named with the usual syntax, together with a good summary
+ (e.g. <code>PR c++/2204: Check abstractness of function
+ parameters</code>) within a comment for easier future reference.</li>
+
+ <li>If the testcase fixes a bug which was not submitted to the bug
+ database, include a comment with a short description of the bug, that is
+ what the testcase is meant to check. In some situations, the testcase
+ itself is a crystal clear explanation of the bug (for instance, checking
+ that a specific error message be emitted), so the description can be
+ omitted.</li>
+
+ <li>The testcase should not rely on external files (such as headers, even
+ standard headers), if possible. It is better to manually bring the
+ declarations of the needed functions into scope. For instance,
+ instead of:
+
+<pre><code>#include &lt;stdlib.h&gt;
+void foo(void)
+{
+  abort();
+}
+</code></pre>
+
+ it is better to write:
+
+<pre><code>extern void abort(void);
+void foo(void)
+{
+  abort();
+}
+</code></pre>
+
+ C++ testcases can prepend <code>extern "C"</code> while declaring such
+ functions.</li>
+
+ <li>There are a few excuses for not preparing a testcase. First, it is
+ not strictly necessary for a bug which occurred during GCC bootstrap,
+ as GCC itself is considered a big testcase. Second, there are situations
+ where it is very hard to minimize a bug (a weird garbage collector
+ crash, a very complex C++ testcase causing a failure somewhere deep
+ into RTL optimizers, etc.). Third, a testcase could obviously be alrady
+ present and just XFAIL-ed (see below), in which case it is sufficient to
+ remove the <code>xfail</code> mark.</li>
+
+ <li>Choose carefully the directory where to place the test. Each language
+ has its own directory, and often two directories: one for torture tests,
+ and the other for normal tests. A torture test is a testcase which is
+ compiled and optionally executed with many different optimization level,
+ and it is meant to stress GCC optimizers. Normal tests instead are meant
+ to test for frontend features (which are not affected by optimization
+ levels), or tests which need specific command line options and thus are
+ not suited for the torture testsuite. The following is a list of all
+ the active directories in the testsuite:
+ <ul>
+  <li>gcc/testsuite/ada/ contains Ada tests.</li>
+  <li>gcc/testsuite/gcc.c-torture/ contains C torture tests.</li>
+  <li>gcc/testsuite/gcc.dg/ contains C normal tests.</li>
+  <li>gcc/testsuite/g++.dg/ contains C++ tests.</li>
+  <li>gcc/testsuite/gfortran.fortran-torture/ contains F95
+  torture tests.</li>
+  <li>gcc/testsuite/objc/ constains Objective C torture tests.</li>
+  <li>gcc/testsuite/objc.dg/ contains Object C normal tests.</li>
+  <li>lib*/testsuite/*/ contain tests for the target libraries. </li>
+ </ul>
+
+ The other directiores are obsoleted and freezed, so new tests must not
+ go there.
+ </li>
+
+ <li>To add and test your testcase, it is sufficient to drop it into
+ one of the above directiories, and then run one of the below
+ commands from the build directory:
+
+<blockquote><pre>
+# Generic version.
+make check RUNTESTFLAGS=<i>testsuitename.exp</i>=<i>testcasename.ext</i>
+
+# C++ only
+make -C gcc check-g++
RUNTESTFLAGS==<i>testsuitename.exp</i>=<i>testcasename.ext</i>
+</pre></blockquote>
+
+ <i>testsuitename.exp</i> is the name of the testsuite module (look
+ for a file with extension <code>.exp</code> which is the closest,
+ directory-wise, to the testcase you added). If the testcase does not
+ work as expected, you can inspect the testsuite log, which is generated
+ somewhere deep in the build directory (the logs for the GCC core
+ can be found in <i>build-dir</i>/gcc/testsuite/*.log, while the logs for
+ multilib libraries are at
+ <i>build-dir</i>/<i>target</i>/<i>library</i>/testsuite/*.log, for instance
+ build/i686-pc-linux-gnu/libstdc++-v3/testsuite/libstdc++.log).</li>
+
+</ul>
+
+<p>The testsuite uses
+<a href="http://www.gnu.org/software/dejagnu/";>DejaGnu</a> as its framework.
+The framework parses the testcases looking for special commands, written in
+comments, which describe the tests that must be performed. Each
+testcase might have several different tests performed on it, each one
+described by a command.</p>
+
+<p>Each command issues a specific test to be done. The possible outcomes are
+the following:</p>
+
+<ul>
+ <li><b>PASS</b>: The test was succesfull.</li>
+ <li><b>FAIL</b>: The test failed.</li>
+ <li><b>XFAIL</b>: The test is marked as an expected failure (see below),
+ and it failed indeed.</li>
+ <li><b>XPASS</b>: The test is marked as an expected failure, but passed
+ so it is not a failure anymore.</li>
+</ul>
+
+<p>The testsuite summary lists only the tests that exited with FAIL or XPASS
+status, since the others just behaved as expected. In the former case, it
means
+that the test failed, so your patch probably broke it. In the latter case,
+it means that your patch just fixed a bug which was already present in the
+testcase but marked as an expected failure. This means that a new testcase
+is probably not necessary, and your patch can be updated so that it also
+removes the xfail modifier from the existing testcase.</p>
+
+<p>The main commands that can be used are the following:</p>
+
+<dl>
+<dt><b><code>{ dg-do <i>action</i> }</code></b></dt>
+<dd>Specifies the basic compilation action to be performed on the testcase.
+Valid actions are:
+  <ul>
+    <li><code>preprocess</code>: only run the preprocessor on the file.</li>
+    <li><code>compile</code>: compile the file and emit the assembly
+    code.</li>
+    <li><code>assemble</code>: compile the file, and assemble the assembly
+    code producing the object binary.</li>
+    <li><code>link</code>: compile, assemble and link the testcase, producing
+    an executable.</li>
+    <li><code>run</code>: compile, assemble and link the testcase, and
+    run the generated executable. The executable must then return with exit
+    code 0 for the test to be succesfull.</li>
+  </ul>
+<p>For instance, the following testcases uses a <code>run</code> action:</p>
+
+<pre><code>/* { dg-do run } */
+extern void abort(void);
+static const int a = 3 + 3;
+
+int main(void)
+{
+  if (a != 6)
+    abort();
+  return 0;
+}
+</code></pre>
+
+Techinically, a testcase which exits with exit code different from zero will
+be treated as a failure, but the recommended way is to use
+<code>abort()</code> to make testcase fail, as shown in the example.
+
+<p>By default, when using the <code>assemble</code> or <code>compile</code>
+actions, the framework expects the testcase to compile correctly, without
+any warning or error. If any diagnostic is expected, it must be
+handled with the <code>dg-error/dg-warning</code> commands (see below). Each
of
+these commands match one or more error messages emitted during compilation.
+If all the error messages are matched (no excess errors), the compilation is
+considered a success (even the compiler technically failed on it). Otherwise,
+if there are excess (unmatched) errors, the test fails. The use of
+actions <code>link</code> and <code>run</code> is inappropriate for testcases
+which contain <code>dg-error/dg-warning</code>, because they are expected to
+not compile at all.</p>
+<p />
+</dd>
+
+<dt><b><code>{ dg-options <i>"opts"</i> }</code></b></dt>
+<dd>Specifies command line options to be passed to GCC while compiling the
+testcase. This is useful to enable optimizations, test the behaviour of
+specific options like warnings or attributes, etc.
+<p>The following testcase shows an example of this:</p>
+
+<pre><code>/* { dg-do link } */
+/* { dg-options "-O2" } */
+
+void link_error(void);
+
+int main(void)
+{
+  /* We make sure this check is optimized away, otherwise
+     a call to link_error is performed and there would be
+     an error while linking the testcase (link_error has
+     no definition).  */
+  if (5+6)
+    link_error();
+  return 0;
+}
+</code></pre>
+<p /></dd>
+
+<dt><b><code>{ dg-error <i>"match-regexp"</i> <i>"error-desc"</i>
+<i>line-num</i> }</code></b></dt>
+<dd>Checks for the presence of an error message emitted by the compiler
+for a given line of the testcase. The error text is matched with a regular
+expression which allows a certain degree of freedom in the match.
+The line number is usually omitted, and in that case the compiler error
+is expected for in the line in which the <code>dg-error</code> command is
+defined. The (optional) error description is just a human-readable
+description of the error the command is checking for, and in case of failure
+it is emitted in the testsuite summary.
+
+<p>Usually, the regular expression pattern is just a significant substring
+of the error message that it is meant to match. For instance, consider the
+following testcase:</p>
+
+<pre><code>/* { dg-do compile } */
+struct A {
+  int y : 0;  /* { dg-error "zero width" } */
+};
+</code></pre>
+
+<p>This testcase makes sure that the compiler rejects the code which is
+invalid (a bitfield cannot have a width of zero bits). The error message
+emitted by the compiler is the following:</p>
+
+<pre><code>test.c:4: error: zero width for bit-field `y'</code></pre>
+
+<p>The <code>dg-error</code> command just matches a significant substring
+of the error message, which is enough for the purpose.</p>
+
+<p>In some situations, the compiler emits two (or more) error messages for
+the same line of code. To handle this, it is suggested to use a single
+<code>dg-error</code> command, with two different substring patterns (using
the
+<code>|</code> operator for regular expressions, for instance
+<code>"foo|bar")</code>.</p>
+
+<p>Using <code>""</code> matches any error message on the given line. This
+technique though is <b>strongly</b> discouraged: while it still makes the
+testcase valid, checking that the compiler does emit a diagnostic on the
+line, it does not enforce anymore that the error message is indeed the
+correct one. It is in fact common for the compiler to regress in diagnostic
+quality, and to suddenly change an user-friendly error message with a
+cryptic syntax error, if not a totally wrong message. Such situations can be
+catched immediatly only if the <code>dg-error</code> command does contain
+a matching pattern for the error text.</p>
+<p /></dd>
+
+<dt><b><code>{ dg-warning <i>"match-regexp"</i> <i>"error-desc"</i>
+<i>line-num</i> }</code></b></dt>
+<dd>Behaves exactly like <code>dg-error</code>, but checks for a warning
+instead of an error.<p /></dd>
+
+<dt><b><code>{ dg-excess-errors <i>"match-regexp"</i> }</code></b></dt>
+<dd>Matches excess errors. This command basically checks for matching errors
+emitted on any line of the testcase. It is not meant to be a lazy-man
+version of <code>dg-error</code> to avoid indicating the line where the error
+should happen. Instead, it can be useful for situations where there are too
+many fallout errors (bad error recovery) that would not make sense to match
+(as they could change or even be fixed in the future, and we do not want that
+to be reported as a failure in the testsuite). Moreover, this command
+can be useful to take care of all the additional information notes that the
+compiler emits to help the user fixing the problem: since they all look like:
+<code>foo.c:26: note: blah</code>, it is sufficient to use <code>
+{ dg-excess-errors "note" }</code> to match all of them.
+<p /></dd>
+
+<dt><b><code>{ dg-bogus <i>"match-regexp"</i> <i>"error-desc"</i>
+<i>line-num</i> }</code></b></dt>
+<dd>Behaves like <code>dg-error</code> but with inverted logic: it tests
+for an error matching a certain regular expression <b>not</b> to be
+emitted on the given line. This is useful for situations where we want to
+make sure that a certain error message or warning is not emitted any
+more.
+
+<p>One could ask why to bother at all with <code>dg-bogus</code>. In
+fact, if we want an error not to be emitted while compiling the testcase,
+it is sufficient to do nothing at all. In fact, were the error emitted,
+the testcase compilation (as specified by <code>dg-do</code>) would fail
+for excess errors. In fact, this test is mostly useful in combination with
+the <code>xfail</code> modifier (see below for an example).</p>
+<p /></dd>
+
+<dt><b><code>{ dg-final { <i>final-action</i> } }</code></b></dt>
+<dd>This family of commands executes an action *after* the main action
+(specified by <code>dg-do</code>) is done.
+<p />
+
+ <dl>
+ <dt><b><code>{ dg-final { scan-assembler <i>"match-regexp"</i> } }</code>
+ </b></dt>
+ <dd>Scans the assembly output emitted by GCC during the compilation
+ file, trying to match the given regular expression. The test succeeds
+ if a match is found.
+
+ <p>This command can be useful to check if a specific machine instruction
+ is present in the assembly listing (for instance, generated by an
+ optimization), or if a (possibly mangled) symbol was emitted. The
+ following example highlights one of these usages:</p>
+
+<pre><code>/* Verify that 387 fsincos instruction is generated.  */
+/* { dg-do compile { target "i?86-*-*" } } */
+/* { dg-options "-O -ffast-math -march=i686" } */
+/* { dg-final { scan-assembler "fsincos" } } */
+
+double f1(double x)
+{
+  return sin(x) + cos (x);
+}
+</code></pre>
+
+ <p /></dd>
+
+ <dt><b><code>{ dg-final { scan-assembler-not <i>"match-regexp"</i> } }
+ </code></b></dt>
+ <dd>Similar to <code>scan-assembler</code> but with inverted logic:
+ the test succeeds if <strong>no</strong> match is found while scanning
+ the assembly output.
+ <p /></dd>
+
+ <dt><b><code>{ dg-final { scan-file <i>"filename"</i>
+ <i>"match-regexp"</i> } }</code></b></dt>
+ <dd>Generalized version of <i>scan-assembler</i>, but scans a specific file
+ whose name is specified. This can be used for instance while preparing
+ testcases for the preprocessor to parse the preprocessed output (assuming
+ that <code>dg-do preprocess</code> was used). See the testcases in
+ testsuite/gcc.dg/cpp/ for some examples.
+ <p /></dd>
+
+ <dt><b><code>{ dg-final { scan-file-not <i>"filename"</i>
+ <i>"match-regexp"</i> } }</code></b></dt>
+ <dd>Similar to <code>scan-file</code> but with inverted logic: the test
+ successds if <strong>no</strong> match is found while scanning the specified
+ file.
+ <p /></dd>
+
+ <dt><b><code>{ dg-final { scan-tree-dump-times <i>"match-regexp"</i>
+ <i>num-expected-matches</i> <i>"dump-name"</i> } }</code></b></dt>
+ <dd>Scans a tree dump looking for a certain regular expression pattern,
+ and checks if it matches exactly the expected number of times. This
+ is the main test used to check the functionality of the tree optimizers
+ (you can find a number of tests using this command in
+ testsuite/gcc.dg/tree-ssa/). Each tree optimizer pass has a specific
+ name and can be instructed to emit a tree dump after it runs. By scanning
+ its dump, we can check if it did what we expected it to do.
+
+ <p>For instance, the following testcase checks if the optimizer pass
+ called <code>dce3</code> was able to remove all the occurrences of
+ <code>if</code> conditionals, as we expect it to do:</p>
+
+<pre><code>/* { dg-do compile } */
+/* { dg-options "-O1 -fdump-tree-dce3" } */
+
+int t() __attribute__ ((const));
+q()
+{
+  int i = t();
+  if (!i)
+    i = t();
+}
+/* There should be no IF conditionals.  */
+/* { dg-final { scan-tree-dump-times "if " 0 "dce3"} } */</code></pre>
+
+ <p>Notice that it is necessary to tell GCC to generate the
+ specific tree dump manually, through the <code>dg-options</code>
+ command, otherwise there will be no dump to scan, and
+ <code>scan-tree-dump-times</code> will fail.</p>
+ <p /></dd>
+
+ <dt><b><code>{ dg-final { scan-tree-dump <i>"match-regexp"</i>
+ <i>"dump-name"</i> } }</code></b></dt>
+ <dd>Equivalent to <code>scan-tree-dump-times "match-regexp" 1 "dump-name"
+ </code>
+ <p /></dd>
+
+ <dt><b><code>{ dg-final { scan-tree-dump-not <i>"match-regexp"</i>
+ <i>"dump-name"</i> } }</code></b></dt>
+ <dd>Equivalent to <code>scan-tree-dump-times "match-regexp" 0 "dump-name"
+ </code>
+ <p /></dd>
+
+ </dl>
+
+<p /></dd>
+
+<dt><b><code>{ <i>modifier</i> }</code></b></dt>
+<dd>Modifiers can be combined to any of the above commands, and modify the
+behaviour of the test performed by the commands. To apply a modifier to a
+command, use the following syntax:
+<code>{ command options { modifier } }</code>.
+
+<p>This is a list of
+the common modifers used in the testsuite.</p>
+
+ <dl>
+ <dt><b><code>{ target <i>triplets</i> }</code>
+ </b></dt>
+ <dd>Modifies the command so that the test is executed only on a specific
+ target triplet, or a family of targets (through standard wildcards,
+ <code>?</code> and <code>*</code>). If needed, more than a triplet can
+ be specified.
+
+ <p>This modifier is useful because some tests are not meant to be executed
+ on all targets, as they test specific features of the backends. Note that
+ applying this modifier on the main action means that the whole testcase
+ is conditionally executed.</p>
+
+ <p>The following test is an example of this modifier: it is meant to check
+ for a peephole bug which used to exist in the rs6000 backend, and thus
+ can be triggered on both PowerPC- and POWER-based systems:</p>
+
+<pre><code>
+/* { dg-do compile { target powerpc-*-* rs6000-*-* }  } */
+/* { dg-options "-O3 -mcpu=power2 -fno-schedule-insns -w -mhard-float" } */
+/* This used to ICE as the peephole was not checking to see
+   if the register is a floating point one (I think this cannot
+   happen in real life except in this example).  */
+
+register double t1 __asm__("r14");
+register double t2 __asm__("r15");
+register double t3 __asm__("r16"), t4 __asm__("r17");
+void t(double *a, double *b)
+{
+        t1 = a[-1];
+        t2 = a[0];
+        t3 = a[1];
+        t4 = a[2];
+        b[-1] = t1;
+        b[0] = t2;
+        b[1] = t3;
+        b[2] = t4;
+}
+</code></pre>
+
+ <p /></dd>
+
+ <dt><b><code>{ xfail <i>triplets</i> }</code>
+ </b></dt>
+ <dd>Marks the test as an expected failure in the testsuite. An expected
+ failure is a bug which cannot be fixed at the moment for several reasons,
+ but for which we still need a testcase. Expected failures are not reported
+ in the testsuite summary.
+
+ <p>Only release managers and experienced developers should mark tests
+ with the XFAIL modifier. In fact, XFAIL-ing a testcase hides it in the
+ summary, so it does not immediatly catch the attention of people. If your
+ patch breaks an existing test, it usually means that there is a bug in
+ your patch. If you believe it is not so, you should:</p>
+ <ul>
+  <li>Check if the testcase that is now failing is invalid. For instance,
+  a new patch to the frontend could have caught a bug in an ill-formed
+  testcase that was erroneously submitted. In this case, fix the
+  testcase (or, in the worst case, even remove it).</li>
+  <li>Check if the testcase is failing due to an existing bug exposed
+  by your patch. In this case, you can either try to fix it in your
+  patch (assuming it is related) or cope with it at a later time. In
+  either case, explain your reasoning in your mail to the
+  <a href="http://gcc.gnu.org/ml/gcc-patches/";>gcc-patches</a> mailing
+  list.</li>
+ </ul>
+
+ <p>Each testcase which is XFAIL-ed must have a corresponding PR open in the
+ <a href="http://gcc.gnu.org/bugzilla";>bug database</a>, and the PR number
+ must be referenced in a comment in the testcase itself. This makes sure
+ that the failure is not forgotten.</p>
+
+ <p>Do <b>not</b> use XFAIL to disable tests which cannot be executed on
+ specific targets: this is not what XFAIL is meant for. Use the
+ <code>target</code> modifier for this, as explained above.</p>
+
+ <p>The following example shows an example with a legit use of XFAIL: a
+ bogus error message diagnosed by the compiler which cannot be currently
+ fixed:</p>
+
+<pre><code>/* { dg-do compile } */
+/* { dg-options "-Wtraditional" } */
+
+struct bar
+{
+  int i;
+  long j;
+};
+
+union foo
+{
+  struct bar b;
+  int i;
+  long l;
+};
+
+struct baz
+{
+  int a;
+  double b;
+  union foo c;
+};
+
+static struct baz f1 = { 1, 2, {{1,1}} }; /* { dg-warning "traditional C
rejects" "initialization of unions" } */
+static struct baz f2 = { 1, 2, {{0,0}} }; /* { dg-bogus "traditional C
rejects" "initialization of unions" { xfail *-*-* } } */
+</code></pre>
+
+ <p>This testcase checks if a specific warning is emitted when
+ <code>-Wtraditional</code> is used. This is the case of the
+ initialization of <code>f1</code>, which correctly emits a warning
+ that <code>dg-warning</code> checks for. Instead, the initialization
+ of <code>f2</code> is not supposed to trigger a warning, but it does
+ at the moment: it was agreed that GCC could live with this spurious
+ warning for the time being, so a <code>dg-bogus</code> test was added
+ (<code>dg-bogus</code> checks that a specific warning/error is <b>not</b>
+ emitted) and marked with <code>xfail</code> (since right now the
+ warning is incorrectly emitted). When the bug is fixed and the spurious
+ warning is not emitted anymore, the <code>xfail</code> modifier
+ will be removed from the testcase.</p>
+ <p /></dd>
+
+ </dl>
+
+<p /></dd>
+
+</dl>
+
+<h2><a name="backends">Submitting New Backends</a></h2>
+
+<p>Historically, GCC has been very open to submissions of new backends. While
+this is obviously a good thing, it causes many maintainance headhaches since
+it is very easy for a backend to not be carefully maintained, and become
rotten
+code very quickly. In the past few releases, we have been deprecating and
+removing many backends which were totally broken (and had been like that for
+years).</p>
+
+<p>A backend which is not tested daily or at least weekly, and regulary
+maintained, is bound to break sooner or later (and given the usual speed of
+development, it is probably a matter of a few months). This gives a false
promise
+to our users, as their code will probably not compile, and creates an unwanted
+maintanance burden for the whole core, due to incomplete transitions to new
+technologies which are added to the GCC core. For instance, some backends
+have not yet been converted to use the new DFA for pipeline description, which
+makes us unable to clean the codebase by removing the support for the old
+pipeline description code.</p>
+
+<p>This is why we are currently quite cautious with respect to accepting new
+backends. We urge you to read carefully the following guidelines and to follow
+them while developing a new backend, if you intend to submit it for inclusion
+in the official development tree.</p>
+
+<ul>
+
+<li>The backend must have been carefully tested. This means a full bootstrap,
+with all languages turned on, and a full testsuite run. The compiler must
+have been configured with <code>--enable-checking</code>. We
+<strong>strongly</strong> recommend to enable all the enhanced checks with
+<code>--enable-checking=misc,tree,gc,gcac,rtl,rtlflag</code>, but we
+understand that this might be unfeasable for slow targets. For Java support,
+porting libffi to the new target is needed, but it can be taken care of in a
+follow-up patch. The summary of the testsuite run must be included in your
+submission mail. It is not strictly necessary for all the tests to succeed,
+but the overall view should be pretty good.</li>
+
+<li>The backend must have been developed and tested on the current mainline.
+There is no way we can accept a new backend tested on a release branch, or
+on an old mainline.</li>
+
+<li>As any other patch, the backend must carefully follow our
+<a href="#standards">coding standards </a> throughout the whole code. Being
+new files is no excuse for them not to follow our standards.</li>
+
+<li>All the people involved in the work must have fully completed the
+paperwork with the FSF for copyright assignment for past and future changes.
+Please read our <a href="#legal">legal prerequisites</a> about it.</li>
+
+<li>One or more people involved in the work must volunteer to be appointed
+as official maintainers for the backend. This involves daily (or at least
+weekly) testing of the backend (full bootstrap and testsuite runs, with
+results posted to the
+<a href="http://gcc.gnu.org/ml/gcc-testresults/";>test results mailing
+list</a>), and a commitment to fix the new bugs discovered through such tests,
+or found by users and submitted in our <a href="http://gcc.gnu.org/bugzilla/";>
+bug database</a>.</li>
+
+<li>It is strongly preferred if the patch that adds the new backend does not
+include many changes to the GCC core. Theoretically, the only changes which
+should be needed are the mechanical ones (configuration system, etc.). If
+the new backend exposed bugs in the GCC core, it is preferrable to submit
+the patches that fix them separately from the new backend (after having
+tested them on another, already exising, platform), either before or
+after the backend submission.</li>
+
+<li>The backend must use only <code>define_peephole2</code> to describe
+peepholes optimizations. We are currently trying to remove the old
+<code>define_peephole</code> from our tree.</li>
+
+<li>The backend must not use the <code>cc0</code> pseudo to describe the
+behaviour of flags. Instead, you can use the new <code>MODE_CC</code>
+system. We are trying to remove the support for <code>cc0</code> from
+our tree.</li>
+
+<li>The backend must use the new DFA automata for description of the
+pipeline for scheduling, if you have one. We are trying to remove the
+support for the old description from our tree.</li>
+
+<li>The backend must include full documentation, as explained in our
+internals manual, in the section
+<a href="http://gcc.gnu.org/onlinedocs/gccint/Back-End.html#Back%20End";>
+Anatomy of a Target Backend</a></li>
+
+<li>Do not copy the documentation for target hooks from the internals
+manual in comments preceding the hook itself. It is an unneeded duplicate
+which is doomed to desynchronize sooner or later. You can of course
+comment the hook about everything specific to the backend itself.</li>
+
+<li>We recommend that new backends have a freely available GDB simulator,
+but this is not a requirement. This makes it easier for other people
+to run the testsuite (especially for embedded systems which can be
+pretty slow) and thus to contribute patches to the backend.</li>
+
+</ul>
+
 </body>
 </html>