From patchwork Fri Oct 31 17:02:57 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Malcolm X-Patchwork-Id: 405439 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id E6EC014008B for ; Sat, 1 Nov 2014 04:31:09 +1100 (AEDT) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:from :to:cc:subject:date:message-id:in-reply-to:references; q=dns; s= default; b=hpuErFuvYIWZV17wjyxcHVovhvMz4+Dp9JPxfMtHudC2aVkBDMcch MrgXCr84Gm8q1JO0T3ubtkjXUYDAiGIPzrGU/hFVQq9dJmqrqCBTTHWEuRAdjFwD zS+nrmqp610Z/RLlp+IqETpBBlroGX9szT2eHWKew3wivTRVDX1t8w= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:from :to:cc:subject:date:message-id:in-reply-to:references; s= default; bh=lUXP8n2UovgNat0HGzcOpcLB/vw=; b=yEobjoqs3+cFHf6JNOiq 1KelPNLhqzthek0pzYbDlaOH0VpPZS991o+u6DC4jKZL/IUQTho+k3G3UsUimV8d JbItkBc4eWj+Hz75fxx9ZgUH+OP1mAH4VOkcXMLVIWD/aYlL4uEbh+80W7bjJsm+ l+ZhZ09PynPaBKT4h0T4aWQ= Received: (qmail 23749 invoked by alias); 31 Oct 2014 17:31:02 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 23737 invoked by uid 89); 31 Oct 2014 17:31:02 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.0 required=5.0 tests=AWL, BAYES_00 autolearn=unavailable version=3.3.2 X-HELO: eggs.gnu.org Received: from eggs.gnu.org (HELO eggs.gnu.org) (208.118.235.92) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-SHA encrypted) ESMTPS; Fri, 31 Oct 2014 17:31:00 +0000 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XkFfh-0005x2-MS for gcc-patches@gcc.gnu.org; Fri, 31 Oct 2014 13:07:39 -0400 Received: from mx1.redhat.com ([209.132.183.28]:49323) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XkFfh-0005w8-Di; Fri, 31 Oct 2014 13:07:33 -0400 Received: from int-mx11.intmail.prod.int.phx2.redhat.com (int-mx11.intmail.prod.int.phx2.redhat.com [10.5.11.24]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s9VH7V4O008365 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Fri, 31 Oct 2014 13:07:32 -0400 Received: from surprise.redhat.com (vpn-236-100.phx2.redhat.com [10.3.236.100]) by int-mx11.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id s9VH7ESR008517; Fri, 31 Oct 2014 13:07:31 -0400 From: David Malcolm To: gcc-patches@gcc.gnu.org, jit@gcc.gnu.org Cc: David Malcolm Subject: [PATCH 25/27] Documentation: add "internals" subdirectory Date: Fri, 31 Oct 2014 13:02:57 -0400 Message-Id: <1414774977-25605-25-git-send-email-dmalcolm@redhat.com> In-Reply-To: <1414774977-25605-1-git-send-email-dmalcolm@redhat.com> References: <1414774977-25605-1-git-send-email-dmalcolm@redhat.com> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 209.132.183.28 X-IsSubscribed: yes 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 + + 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 + . + +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. */