jit: Add guide for submitting patches to jit docs

gcc/jit/ChangeLog:
	* docs/internals/index.rst (Overview of code structure): Add note
	that the implementation is in C++, despite the .c extension.
	(Submitting patches): New subsection.

From-SVN: r225905

1 files changed, 98 insertions, 0 deletions

diff --git a/gcc/jit/docs/internals/index.rst b/gcc/jit/docs/internals/index.rst
index d0852f9..6f28762 100644
--- a/gcc/jit/docs/internals/index.rst
+++ b/gcc/jit/docs/internals/index.rst
@@ -287,6 +287,9 @@ For example:
 Overview of code structure
 --------------------------
 
+The library is implemented in C++.  The source files have the ``.c``
+extension for legacy reasons.
+
 * ``libgccjit.c`` implements the API entrypoints.  It performs error
   checking, then calls into classes of the gcc::jit::recording namespace
   within ``jit-recording.c`` and ``jit-recording.h``.
@@ -335,3 +338,98 @@ should be rejected via additional checking.  The checking ideally should
 be within the libgccjit API entrypoints in libgccjit.c, since this is as
 close as possible to the error; failing that, a good place is within
 ``recording::context::validate ()`` in jit-recording.c.
+
+Submitting patches
+------------------
+Please read the contribution guidelines for gcc at
+https://gcc.gnu.org/contribute.html.
+
+Patches for the jit should be sent to both the
+gcc-patches@gcc.gnu.org and jit@gcc.gnu.org mailing lists,
+with "jit" and "PATCH" in the Subject line.
+
+You don't need to do a full bootstrap for code that just touches the
+``jit`` and ``testsuite/jit.dg`` subdirectories.  However, please run
+``make check-jit`` before submitting the patch, and mention the results
+in your email (along with the host triple that the tests were run on).
+
+A good patch should contain the information listed in the
+gcc contribution guide linked to above; for a ``jit`` patch, the patch
+shold contain:
+
+  * the code itself (for example, a new API entrypoint will typically
+    touch ``libgccjit.h`` and ``.c``, along with support code in
+    ``jit-recording.[ch]`` and ``jit-playback.[ch]`` as appropriate)
+
+  * test coverage
+
+  * documentation for the C API
+
+  * documentation for the C++ API
+
+A patch that adds new API entrypoints should also contain:
+
+  * a feature macro in ``libgccjit.h`` so that client code that doesn't
+    use a "configure" mechanism can still easily detect the presence of
+    the entrypoint.  See e.g. ``LIBGCCJIT_HAVE_SWITCH_STATEMENTS`` (for
+    a category of entrypoints) and
+    ``LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks``
+    (for an individual entrypoint).
+
+  * a new ABI tag containing the new symbols (in ``libgccjit.map``), so
+    that we can detect client code that uses them
+
+  * Support for :c:func:`gcc_jit_context_dump_reproducer_to_file`.  Most
+    jit testcases attempt to dump their contexts to a .c file; ``jit.exp``
+    then sanity-checks the generated c by compiling them (though
+    not running them).   A new API entrypoint
+    needs to "know" how to write itself back out to C (by implementing
+    ``gcc::jit::recording::memento::write_reproducer`` for the appropriate
+    ``memento`` subclass).
+
+  * C++ bindings for the new entrypoints (see ``libgccjit++.h``); ideally
+    with test coverage, though the C++ API test coverage is admittedly
+    spotty at the moment
+
+  * documentation for the new C entrypoints
+
+  * documentation for the new C++ entrypoints
+
+  * documentation for the new ABI tag (see ``topics/compatibility.rst``).
+
+Depending on the patch you can either extend an existing test case, or
+add a new test case.  If you add an entirely new testcase: ``jit.exp``
+expects jit testcases to begin with ``test-``, or ``test-error-`` (for a
+testcase that generates an error on a :c:type:`gcc_jit_context`).
+
+Every new testcase that doesn't generate errors should also touch
+``gcc/testsuite/jit.dg/all-non-failing-tests.h``:
+
+  * Testcases that don't generate errors should ideally be added to the
+    ``testcases`` array in that file; this means that, in addition
+    to being run standalone, they also get run within
+    ``test-combination.c`` (which runs all successful tests inside one
+    big :c:type:`gcc_jit_context`), and ``test-threads.c`` (which runs all
+    successful tests in one process, each one running in a different
+    thread on a different :c:type:`gcc_jit_context`).
+
+    .. note::
+
+       Given that exported functions within a :c:type:`gcc_jit_context`
+       must have unique names, and most testcases are run within
+       ``test-combination.c``, this means that every jit-compiled test
+       function typically needs a name that's unique across the entire
+       test suite.
+
+  * Testcases that aren't to be added to the ``testcases`` array should
+    instead add a comment to the file clarifying why they're not in that
+    array. See the file for examples.
+
+Typically a patch that touches the .rst documentation will also need the
+texinfo to be regenerated.  You can do this with
+`Sphinx 1.0 <http://sphinx-doc.org/>`_ or later by
+running ``make texinfo`` within ``SRCDIR/gcc/jit/docs``.   Don't do this
+within the patch sent to the mailing list; it can often be relatively
+large and inconsequential (e.g. anchor renumbering), rather like generated
+"configure" changes from configure.ac.  You can regenerate it when
+committing to svn.