Commit 1470e75f by David Malcolm Committed by David Malcolm

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
parent 5bc1c07c
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> 2015-07-09 Andrew MacLeod <amacleod@redhat.com>
* dummy-frontend.c: Adjust includes for flags.h changes. * dummy-frontend.c: Adjust includes for flags.h changes.
......
...@@ -19,7 +19,7 @@ ...@@ -19,7 +19,7 @@
@copying @copying
@quotation @quotation
libgccjit 6.0.0 (experimental 20150701), July 01, 2015 libgccjit 6.0.0 (experimental 20150716), July 16, 2015
David Malcolm David Malcolm
...@@ -353,6 +353,7 @@ Internals ...@@ -353,6 +353,7 @@ Internals
* Packaging notes:: * Packaging notes::
* Overview of code structure:: * Overview of code structure::
* Design notes:: * Design notes::
* Submitting patches::
Running the test suite Running the test suite
...@@ -14043,6 +14044,7 @@ This is a thin wrapper around the ...@@ -14043,6 +14044,7 @@ This is a thin wrapper around the
* Packaging notes:: * Packaging notes::
* Overview of code structure:: * Overview of code structure::
* Design notes:: * Design notes::
* Submitting patches::
@end menu @end menu
...@@ -14395,6 +14397,9 @@ popd ...@@ -14395,6 +14397,9 @@ popd
@section Overview of code structure @section Overview of code structure
The library is implemented in C++. The source files have the @code{.c}
extension for legacy reasons.
@itemize * @itemize *
...@@ -14856,7 +14861,7 @@ JIT: gcc::jit::logger::~logger() ...@@ -14856,7 +14861,7 @@ JIT: gcc::jit::logger::~logger()
@noindent @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} @anchor{internals/index design-notes}@anchor{1b9}
@section Design notes @section Design notes
...@@ -14869,8 +14874,142 @@ be within the libgccjit API entrypoints in libgccjit.c, since this is as ...@@ -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 close as possible to the error; failing that, a good place is within
@code{recording::context::validate ()} in jit-recording.c. @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 @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 @unnumbered Indices and tables
......
...@@ -287,6 +287,9 @@ For example: ...@@ -287,6 +287,9 @@ For example:
Overview of code structure 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 * ``libgccjit.c`` implements the API entrypoints. It performs error
checking, then calls into classes of the gcc::jit::recording namespace checking, then calls into classes of the gcc::jit::recording namespace
within ``jit-recording.c`` and ``jit-recording.h``. within ``jit-recording.c`` and ``jit-recording.h``.
...@@ -335,3 +338,98 @@ should be rejected via additional checking. The checking ideally should ...@@ -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 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 close as possible to the error; failing that, a good place is within
``recording::context::validate ()`` in jit-recording.c. ``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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment