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
This commit is contained in:
David Malcolm
David Malcolm
parent
5bc1c07c4a
commit
1470e75f92
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue