From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 8551 invoked by alias); 16 Jul 2015 19:37:05 -0000 Mailing-List: contact jit-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Post: List-Help: List-Subscribe: Sender: jit-owner@gcc.gnu.org Received: (qmail 8532 invoked by uid 89); 16 Jul 2015 19:37:04 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Checked: by ClamAV 0.98.7 on sourceware.org X-Virus-Found: No X-Spam-SWARE-Status: No, score=-0.7 required=5.0 tests=AWL,BAYES_50,KAM_LAZY_DOMAIN_SECURITY,RP_MATCHES_RCVD,SPF_HELO_PASS autolearn=ham version=3.3.2 X-Spam-Status: No, score=-0.7 required=5.0 tests=AWL,BAYES_50,KAM_LAZY_DOMAIN_SECURITY,RP_MATCHES_RCVD,SPF_HELO_PASS autolearn=ham version=3.3.2 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on sourceware.org X-Spam-Level: X-Spam-User: qpsmtpd, 2 recipients X-HELO: mx1.redhat.com From: David Malcolm To: jit@gcc.gnu.org, gcc-patches@gcc.gnu.org Cc: David Malcolm Subject: [PATCH, committed] jit: Add guide for submitting patches to jit docs Date: Thu, 01 Jan 2015 00:00:00 -0000 Message-Id: <1437076254-22619-1-git-send-email-dmalcolm@redhat.com> In-Reply-To: <1436986339.830.59.camel@surprise> References: <1436986339.830.59.camel@surprise> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.23 X-SW-Source: 2015-q3/txt/msg00104.txt.bz2 Committed to trunk as r225905. 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. * docs/_build/texinfo/libgccjit.texi: Regenerate. --- gcc/jit/docs/internals/index.rst | 98 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) 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 `_ 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. -- 1.8.5.3