This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[HTML] Patch to contribute.html: add section about new backends


Hello,

this part of my big patch to contribute.html went uncommented, so I would tend
to assume it is mostly OK. I'm sure Steven will like to double check it, but I
guess it matches his effort on removing old targets and documenting
requirements for new backends.

This part also adds a little section about the use of C90 within GCC.

Validated as XHTML 1.0, OK to commit?

Giovanni Bajo



Index: contribute.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/contribute.html,v
retrieving revision 1.57
diff -c -3 -p -r1.57 contribute.html
*** contribute.html 12 Jan 2004 22:03:21 -0000 1.57
--- contribute.html 21 Jun 2004 00:26:12 -0000
*************** contributions must meet:</p>
*** 24,29 ****
--- 29,35 ----
  <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="#backends">Submitting New Backends</a></li>
  </ul>

  <hr />
*************** href="codingconventions.html">additional
*** 61,66 ****
--- 67,77 ----
  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>

*************** If you already did a complete C,C++,Java
*** 108,114 ****
  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
  make all-target-libstdc++-v3 all-target-libjava   # rebuild compiler and
libraries
  make -k check-c++                                 # run C++/libstdc++
testsuite
  </pre></blockquote>
--- 119,125 ----
  directory before, you can use the following:</p>
  <blockquote><pre>
  make clean-target-libstdc++-v3                    # clean libstdc++ and ...
! 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>
*************** no-one else will need to apply it to the
*** 277,281 ****
--- 286,390 ----
  totally new files may be omitted (especially if large) since they can be
  accessed directly from the repository.</p>

+ <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> (RTL peepholes)
+ to describe peephole optimizations. We are currently trying to remove the
+ old <code>define_peephole</code> (text peepholes) 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 a RTL prolog/epilogue description for function
+ as opposed to the old text prolog/epilogue. We are trying to remove
+ support for the old kind of description 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>



Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]