From: David Malcolm <dmalcolm@redhat.com>
To: gcc-patches@gcc.gnu.org, jit@gcc.gnu.org
Cc: David Malcolm <dmalcolm@redhat.com>
Subject: [PATCH 25/27] Documentation: add "internals" subdirectory
Date: Fri, 31 Oct 2014 17:32:00 -0000 [thread overview]
Message-ID: <1414774977-25605-25-git-send-email-dmalcolm@redhat.com> (raw)
In-Reply-To: <1414774977-25605-1-git-send-email-dmalcolm@redhat.com>
This final part of the documentation is a guide to the internals of
the library, aimed at current and future contributors to the library
(including myself).
gcc/jit/
* docs/internals/index.rst: New.
---
gcc/jit/docs/internals/index.rst | 216 +++++++++++++++++++++++++++++++++++++++
1 file changed, 216 insertions(+)
create mode 100644 gcc/jit/docs/internals/index.rst
diff --git a/gcc/jit/docs/internals/index.rst b/gcc/jit/docs/internals/index.rst
new file mode 100644
index 0000000..80626e4
--- /dev/null
+++ b/gcc/jit/docs/internals/index.rst
@@ -0,0 +1,216 @@
+.. Copyright (C) 2014 Free Software Foundation, Inc.
+ Originally contributed by David Malcolm <dmalcolm@redhat.com>
+
+ This is free software: you can redistribute it and/or modify it
+ under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see
+ <http://www.gnu.org/licenses/>.
+
+Internals
+=========
+
+Working on the JIT library
+--------------------------
+Having checked out the source code (to "src"), you can configure and build
+the JIT library like this:
+
+.. code-block:: bash
+
+ mkdir build
+ mkdir install
+ PREFIX=$(pwd)/install
+ cd build
+ ../src/configure \
+ --enable-host-shared \
+ --enable-languages=jit \
+ --disable-bootstrap \
+ --enable-checking=release \
+ --prefix=$PREFIX
+ nice make -j4 # altering the "4" to however many cores you have
+
+This should build a libgccjit.so within jit/build/gcc:
+
+.. code-block:: console
+
+ [build] $ file gcc/libgccjit.so*
+ gcc/libgccjit.so: symbolic link to `libgccjit.so.0'
+ gcc/libgccjit.so.0: symbolic link to `libgccjit.so.0.0.1'
+ gcc/libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, not stripped
+
+Here's what those configuration options mean:
+
+.. option:: --enable-host-shared
+
+ Configuring with this option means that the compiler is built as
+ position-independent code, which incurs a slight performance hit,
+ but it necessary for a shared library.
+
+.. option:: --enable-languages=jit
+
+ This specifies which frontends to build. The JIT library looks like
+ a frontend to the rest of the code.
+
+.. option:: --disable-bootstrap
+
+ For hacking on the "jit" subdirectory, performing a full
+ bootstrap can be overkill, since it's unused by a bootstrap. However,
+ when submitting patches, you should remove this option, to ensure that
+ the compiler can still bootstrap itself.
+
+.. option:: --enable-checking=release
+
+ The compile can perform extensive self-checking as it runs, useful when
+ debugging, but slowing things down.
+
+ For maximum speed, configure with ``--enable-checking=release`` to
+ disable this self-checking.
+
+Running the test suite
+----------------------
+
+.. code-block:: console
+
+ [build] $ cd gcc
+ [gcc] $ make check-jit RUNTESTFLAGS="-v -v -v"
+
+A summary of the tests can then be seen in:
+
+.. code-block:: console
+
+ jit/build/gcc/testsuite/jit/jit.sum
+
+and detailed logs in:
+
+.. code-block:: console
+
+ jit/build/gcc/testsuite/jit/jit.log
+
+The test executables can be seen as:
+
+.. code-block:: console
+
+ jit/build/gcc/testsuite/jit/*.exe
+
+which can be run independently.
+
+You can compile and run individual tests by passing "jit.exp=TESTNAME" to RUNTESTFLAGS e.g.:
+
+.. code-block:: console
+
+ [gcc] $ make check-jit RUNTESTFLAGS="-v -v -v jit.exp=test-factorial.c"
+
+and once a test has been compiled, you can debug it directly:
+
+.. code-block:: console
+
+ [gcc] $ PATH=.:$PATH \
+ LD_LIBRARY_PATH=. \
+ LIBRARY_PATH=. \
+ gdb --args \
+ testsuite/jit/test-factorial.exe
+
+Environment variables
+---------------------
+When running client code against a locally-built libgccjit, three
+environment variables need to be set up:
+
+.. envvar:: LD_LIBRARY_PATH
+
+ `libgccjit.so` is dynamically linked into client code, so if running
+ against a locally-built library, ``LD_LIBRARY_PATH`` needs to be set
+ up appropriately. The library can be found within the "gcc"
+ subdirectory of the build tree:
+
+ .. code-block:: console
+
+ $ file libgccjit.so*
+ libgccjit.so: symbolic link to `libgccjit.so.0'
+ libgccjit.so.0: symbolic link to `libgccjit.so.0.0.1'
+ libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (GNU/Linux), dynamically linked, not stripped
+
+.. envvar:: PATH
+
+ The library uses a driver executable for converting from .s assembler
+ files to .so shared libraries. Specifically, it looks for a name
+ expanded from
+ ``${target_noncanonical}-gcc-${gcc_BASEVER}${exeext}``
+ such as ``x86_64-unknown-linux-gnu-gcc-5.0.0``.
+
+ Hence ``PATH`` needs to include a directory where the library can
+ locate this executable.
+
+ The executable is normally installed to the installation bindir
+ (e.g. /usr/bin), but a copy is also created within the "gcc"
+ subdirectory of the build tree for running the testsuite, and for ease
+ of development.
+
+.. envvar:: LIBRARY_PATH
+
+ The driver executable invokes the linker, and the latter needs to locate
+ support libraries needed by the generated code, or you will see errors
+ like:
+
+ .. code-block:: console
+
+ ld: cannot find crtbeginS.o: No such file or directory
+ ld: cannot find -lgcc
+ ld: cannot find -lgcc_s
+
+ Hence if running directly from a locally-built copy (without installing),
+ ``LIBRARY_PATH`` needs to contain the "gcc" subdirectory of the build
+ tree.
+
+For example, to run a binary that uses the library against a non-installed
+build of the library in LIBGCCJIT_BUILD_DIR you need an invocation of the
+client code like this, to preprend the dir to each of the environment
+variables:
+
+.. code-block:: console
+
+ $ LD_LIBRARY_PATH=$(LIBGCCJIT_BUILD_DIR):$(LD_LIBRARY_PATH) \
+ PATH=$(LIBGCCJIT_BUILD_DIR):$(PATH) \
+ LIBRARY_PATH=$(LIBGCCJIT_BUILD_DIR):$(LIBRARY_PATH) \
+ ./jit-hello-world
+ hello world
+
+Overview of code structure
+--------------------------
+
+* ``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``.
+
+* The gcc::jit::recording classes (within ``jit-recording.c`` and
+ ``jit-recording.h``) record the API calls that are made:
+
+ .. literalinclude:: ../../jit-common.h
+ :start-after: /* Recording types. */
+ :end-before: /* End of recording types. */
+ :language: c++
+
+* When the context is compiled, the gcc::jit::playback classes (within
+ ``jit-playback.c`` and ``jit-playback.h``) replay the API calls
+ within langhook:parse_file:
+
+ .. literalinclude:: ../../jit-common.h
+ :start-after: /* Playback types. */
+ :end-before: /* End of playback types. */
+ :language: c++
+
+ .. literalinclude:: ../../notes.txt
+ :lines: 1-
+
+Here is a high-level summary from ``jit-common.h``:
+
+.. include:: ../../jit-common.h
+ :start-after: This comment is included by the docs.
+ :end-before: End of comment for inclusion in the docs. */
--
1.8.5.3
next prev parent reply other threads:[~2014-10-31 17:31 UTC|newest]
Thread overview: 71+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-10-31 17:07 [PATCH 00/27] Merger of jit branch v3 David Malcolm
2014-10-31 17:07 ` [PATCH 20/27] Documentation: Makefile and conf.py David Malcolm
2014-11-03 21:13 ` Jeff Law
2014-10-31 17:07 ` [PATCH 02/27] JIT-related changes outside of jit subdir David Malcolm
2014-10-31 21:18 ` Jeff Law
2014-10-31 17:07 ` [PATCH 03/27] Add Sphinx to install.texi David Malcolm
2014-10-31 21:18 ` Jeff Law
2014-10-31 17:07 ` [PATCH 07/27] New file: gcc/jit/dummy-frontend.c David Malcolm
2014-11-03 19:26 ` Jeff Law
2014-10-31 17:07 ` [PATCH 01/27] gcc: configure and Makefile changes needed by jit David Malcolm
2014-11-03 21:36 ` Jeff Law
2014-11-13 20:16 ` Thomas Schwinge
2014-10-31 17:07 ` [PATCH 21/27] Documentation: the "examples" subdirectory David Malcolm
2014-10-31 21:31 ` Jeff Law
2014-10-31 17:07 ` [PATCH 06/27] New file: gcc/jit/Make-lang.in David Malcolm
2014-11-03 21:35 ` Jeff Law
2014-10-31 17:07 ` [PATCH 05/27] New file: gcc/jit/config-lang.in David Malcolm
2014-10-31 21:20 ` Jeff Law
2014-10-31 17:07 ` [PATCH 09/27] New file: gcc/jit/libgccjit.map David Malcolm
2014-10-31 21:21 ` Jeff Law
2014-10-31 17:16 ` [PATCH 23/27] Documentation: the "intro" subdirectory David Malcolm
2014-10-31 21:48 ` Jeff Law
2014-10-31 22:12 ` David Malcolm
2014-11-03 16:23 ` Jeff Law
2014-10-31 17:21 ` [PATCH 22/27] Documentation: top-level index.rst David Malcolm
2014-10-31 21:29 ` Jeff Law
2014-10-31 17:28 ` [PATCH 12/27] New file: gcc/jit/jit-recording.h David Malcolm
2014-11-03 21:27 ` Jeff Law
2014-11-04 16:16 ` David Malcolm
2014-11-04 21:23 ` Jeff Law
2014-10-31 17:28 ` [PATCH 11/27] New file: gcc/jit/jit-common.h David Malcolm
2014-11-03 19:34 ` Jeff Law
2014-10-31 17:28 ` [PATCH 18/27] New file: gcc/jit/TODO.rst David Malcolm
2014-10-31 21:26 ` Jeff Law
2014-10-31 17:28 ` [PATCH 10/27] New file: gcc/jit/libgccjit.c David Malcolm
2014-11-03 20:32 ` Jeff Law
2014-11-04 17:02 ` David Malcolm
2014-11-04 21:40 ` Jeff Law
2014-11-05 15:52 ` [jit] Use ISALPHA and ISALNUM rather than writing our own David Malcolm
2014-11-05 20:02 ` Jeff Law
2014-11-05 19:38 ` [PATCH 10/27] New file: gcc/jit/libgccjit.c David Malcolm
2014-11-07 19:47 ` Jeff Law
2014-11-07 20:32 ` David Malcolm
2014-10-31 17:29 ` [PATCH 08/27] New file: gcc/jit/libgccjit.h David Malcolm
2014-11-03 20:22 ` Jeff Law
2014-11-04 1:26 ` David Malcolm
2014-10-31 17:29 ` [PATCH 14/27] New files: gcc/jit/jit-builtins.{c|h} David Malcolm
2014-11-03 21:04 ` Jeff Law
2014-11-04 16:39 ` David Malcolm
2014-10-31 17:30 ` [PATCH 17/27] New file: gcc/jit/libgccjit++.h David Malcolm
2014-11-03 21:12 ` Jeff Law
2014-10-31 17:31 ` [PATCH 24/27] Documentation: add "topics" subdirectory David Malcolm
2014-10-31 17:31 ` [PATCH 16/27] New file: gcc/jit/jit-playback.c David Malcolm
2014-11-04 22:21 ` Jeff Law
2014-11-05 20:23 ` [jit] Drop the disabled debugging code within handle_locations David Malcolm
2014-10-31 17:32 ` David Malcolm [this message]
2014-10-31 17:38 ` [PATCH 13/27] New file: gcc/jit/jit-recording.c David Malcolm
2014-11-03 22:04 ` Jeff Law
2014-11-04 16:29 ` David Malcolm
2014-11-04 21:24 ` Jeff Law
2014-10-31 17:41 ` [PATCH 15/27] New file: gcc/jit/jit-playback.h David Malcolm
2014-11-03 21:10 ` Jeff Law
2014-10-31 17:59 ` [PATCH 04/27] New file: gcc/jit/notes.txt David Malcolm
2014-10-31 21:19 ` Jeff Law
2014-10-31 21:17 ` [PATCH 00/27] Merger of jit branch v3 Jeff Law
2014-11-05 20:47 ` [PATCH 0/3] Minor tweaks to jit David Malcolm
2014-11-05 20:47 ` [PATCH 2/3] Documentation tweak David Malcolm
2014-11-05 20:47 ` [PATCH 3/3] Add comments to various functions in libgccjit.h David Malcolm
2014-11-05 20:47 ` [PATCH 1/3] New test cases David Malcolm
2014-11-06 23:51 ` [PATCH 0/3] Minor tweaks to jit Jeff Law
2014-11-07 1:22 ` David Malcolm
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1414774977-25605-25-git-send-email-dmalcolm@redhat.com \
--to=dmalcolm@redhat.com \
--cc=gcc-patches@gcc.gnu.org \
--cc=jit@gcc.gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).