From 1470e75f92c375cb27c473fd5f26af4a7b3bf1cd Mon Sep 17 00:00:00 2001 From: David Malcolm Date: Thu, 16 Jul 2015 19:35:10 +0000 Subject: [PATCH] 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 --- gcc/jit/ChangeLog | 7 + gcc/jit/docs/_build/texinfo/libgccjit.texi | 145 ++++++++++++++++++++- gcc/jit/docs/internals/index.rst | 98 ++++++++++++++ 3 files changed, 247 insertions(+), 3 deletions(-) diff --git a/gcc/jit/ChangeLog b/gcc/jit/ChangeLog index cb021a82b49..e0abaac8eb7 100644 --- a/gcc/jit/ChangeLog +++ b/gcc/jit/ChangeLog @@ -1,3 +1,10 @@ +2015-07-16 David Malcolm + + * 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 * 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 bcb8066218a..c304c26be3e 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 d0852f9285d..6f287626d58 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 `_ 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. -- 2.30.2