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

3 files changed, 247 insertions, 3 deletions

diff --git a/gcc/jit/ChangeLog b/gcc/jit/ChangeLog
index cb021a8..e0abaac 100644
--- a/gcc/jit/ChangeLog
+++ b/gcc/jit/ChangeLog
@@ -1,3 +1,10 @@
+2015-07-16  David Malcolm  <dmalcolm@redhat.com>
+
+	* docs/internals/index.rst (Overview of code structure): Add note
+	that the implementation is in C++, despite the .c extension.
+	(Submitting patches): New subsection.
+	* docs/_build/texinfo/libgccjit.texi: Regenerate.
+
 2015-07-09  Andrew MacLeod  <amacleod@redhat.com>
 
 	* dummy-frontend.c: Adjust includes for flags.h changes.
diff --git a/gcc/jit/docs/_build/texinfo/libgccjit.texi b/gcc/jit/docs/_build/texinfo/libgccjit.texi
index bcb8066..c304c26 100644
--- a/gcc/jit/docs/_build/texinfo/libgccjit.texi
+++ b/gcc/jit/docs/_build/texinfo/libgccjit.texi
@@ -19,7 +19,7 @@
 
 @copying
 @quotation
-libgccjit 6.0.0 (experimental 20150701), July 01, 2015
+libgccjit 6.0.0 (experimental 20150716), July 16, 2015
 
 David Malcolm
 
@@ -353,6 +353,7 @@ Internals
 * Packaging notes:: 
 * Overview of code structure:: 
 * Design notes:: 
+* Submitting patches:: 
 
 Running the test suite
 
@@ -14043,6 +14044,7 @@ This is a thin wrapper around the
 * Packaging notes:: 
 * Overview of code structure:: 
 * Design notes:: 
+* Submitting patches:: 
 
 @end menu
 
@@ -14395,6 +14397,9 @@ popd
 @section Overview of code structure
 
 
+The library is implemented in C++.  The source files have the @code{.c}
+extension for legacy reasons.
+
 
 @itemize *
 
@@ -14856,7 +14861,7 @@ JIT: gcc::jit::logger::~logger()
 
 @noindent
 
-@node Design notes,,Overview of code structure,Internals
+@node Design notes,Submitting patches,Overview of code structure,Internals
 @anchor{internals/index design-notes}@anchor{1b9}
 @section Design notes
 
@@ -14869,8 +14874,142 @@ 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
 @code{recording::context::validate ()} in jit-recording.c.
 
+@node Submitting patches,,Design notes,Internals
+@anchor{internals/index submitting-patches}@anchor{1ba}
+@section Submitting patches
+
+
+Please read the contribution guidelines for gcc at
+@indicateurl{https://gcc.gnu.org/contribute.html}.
+
+Patches for the jit should be sent to both the
+@email{gcc-patches@@gcc.gnu.org} and @email{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
+@code{jit} and @code{testsuite/jit.dg} subdirectories.  However, please run
+@code{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 @code{jit} patch, the patch
+shold contain:
+
+@quotation
+
+
+@itemize *
+
+@item 
+the code itself (for example, a new API entrypoint will typically
+touch @code{libgccjit.h} and @code{.c}, along with support code in
+@code{jit-recording.[ch]} and @code{jit-playback.[ch]} as appropriate)
+
+@item 
+test coverage
+
+@item 
+documentation for the C API
+
+@item 
+documentation for the C++ API
+@end itemize
+@end quotation
+
+A patch that adds new API entrypoints should also contain:
+
+@quotation
+
+
+@itemize *
+
+@item 
+a feature macro in @code{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. @code{LIBGCCJIT_HAVE_SWITCH_STATEMENTS} (for
+a category of entrypoints) and
+@code{LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks}
+(for an individual entrypoint).
+
+@item 
+a new ABI tag containing the new symbols (in @code{libgccjit.map}), so
+that we can detect client code that uses them
+
+@item 
+Support for @pxref{5d,,gcc_jit_context_dump_reproducer_to_file()}.  Most
+jit testcases attempt to dump their contexts to a .c file; @code{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
+@code{gcc::jit::recording::memento::write_reproducer} for the appropriate
+@code{memento} subclass).
+
+@item 
+C++ bindings for the new entrypoints (see @code{libgccjit++.h}); ideally
+with test coverage, though the C++ API test coverage is admittedly
+spotty at the moment
+
+@item 
+documentation for the new C entrypoints
+
+@item 
+documentation for the new C++ entrypoints
+
+@item 
+documentation for the new ABI tag (see @code{topics/compatibility.rst}).
+@end itemize
+@end quotation
+
+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: @code{jit.exp}
+expects jit testcases to begin with @code{test-}, or @code{test-error-} (for a
+testcase that generates an error on a @pxref{8,,gcc_jit_context}).
+
+Every new testcase that doesn't generate errors should also touch
+@code{gcc/testsuite/jit.dg/all-non-failing-tests.h}:
+
+@quotation
+
+
+@itemize *
+
+@item 
+Testcases that don't generate errors should ideally be added to the
+@code{testcases} array in that file; this means that, in addition
+to being run standalone, they also get run within
+@code{test-combination.c} (which runs all successful tests inside one
+big @pxref{8,,gcc_jit_context}), and @code{test-threads.c} (which runs all
+successful tests in one process, each one running in a different
+thread on a different @pxref{8,,gcc_jit_context}).
+
+@cartouche
+@quotation Note 
+Given that exported functions within a @pxref{8,,gcc_jit_context}
+must have unique names, and most testcases are run within
+@code{test-combination.c}, this means that every jit-compiled test
+function typically needs a name that's unique across the entire
+test suite.
+@end quotation
+@end cartouche
+
+@item 
+Testcases that aren't to be added to the @code{testcases} array should
+instead add a comment to the file clarifying why they're not in that
+array. See the file for examples.
+@end itemize
+@end quotation
+
+Typically a patch that touches the .rst documentation will also need the
+texinfo to be regenerated.  You can do this with
+Sphinx 1.0@footnote{http://sphinx-doc.org/} or later by
+running @code{make texinfo} within @code{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.
+
 @node Indices and tables,Index,Internals,Top
-@anchor{index indices-and-tables}@anchor{1ba}
+@anchor{index indices-and-tables}@anchor{1bb}
 @unnumbered Indices and tables
 
 
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.