---

4.7 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 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 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 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 gcc_jit_context).

  Note: Given that exported functions within a 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.