@@ -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.