@copying
@quotation
-libgccjit 6.0.0 (experimental 20150701), July 01, 2015
+libgccjit 6.0.0 (experimental 20150716), July 16, 2015
David Malcolm
* Packaging notes::
* Overview of code structure::
* Design notes::
+* Submitting patches::
Running the test suite
* Packaging notes::
* Overview of code structure::
* Design notes::
+* Submitting patches::
@end menu
@section Overview of code structure
+The library is implemented in C++. The source files have the @code{.c}
+extension for legacy reasons.
+
@itemize *
@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
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
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``.
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.
projects / gcc.git / commitdiff