From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 3630 invoked by alias); 21 Oct 2014 18:56:29 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Received: (qmail 3602 invoked by uid 89); 21 Oct 2014 18:56:26 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.4 required=5.0 tests=AWL,BAYES_50,RP_MATCHES_RCVD,SPF_HELO_PASS,SPF_PASS autolearn=ham version=3.3.2 X-Spam-User: qpsmtpd, 2 recipients X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-GCM-SHA384 encrypted) ESMTPS; Tue, 21 Oct 2014 18:56:23 +0000 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 s9LIuLmi030831 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Tue, 21 Oct 2014 14:56:21 -0400 Received: from surprise.redhat.com (vpn-233-214.phx2.redhat.com [10.3.233.214]) by int-mx11.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id s9LIuKm3017347; Tue, 21 Oct 2014 14:56:21 -0400 From: David Malcolm To: jit@gcc.gnu.org, gcc-patches@gcc.gnu.org, Jeff Law Cc: David Malcolm Subject: [jit] Update the docs Date: Tue, 21 Oct 2014 19:02:00 -0000 Message-Id: <1413917536-21738-1-git-send-email-dmalcolm@redhat.com> In-Reply-To: <543EDCB7.9040604@redhat.com> References: <543EDCB7.9040604@redhat.com> X-IsSubscribed: yes X-SW-Source: 2014-10/txt/msg02166.txt.bz2 On Wed, 2014-10-15 at 14:44 -0600, Jeff Law wrote: > On 10/15/14 10:56, David Malcolm wrote: > > On Tue, 2014-10-14 at 11:09 -0400, David Malcolm wrote: > >> On Mon, 2014-10-13 at 13:45 -0400, David Malcolm wrote: > >>> I'd like to merge the JIT branch into trunk: > >>> https://gcc.gnu.org/wiki/JIT > >>> > >>> This is "v2" since it incorporates fixes for the various issues > >>> identified by Joseph in an earlier submission: > >>> https://gcc.gnu.org/ml/gcc-patches/2014-09/msg02056.html > >>> > >>> I've split up the current diff between trunk and the branch into 5 > >>> areas for ease of review (and to allow for early merger of the > >>> supporting work, if it's deemed ready): > >>> > >>> patch 1: exposes an entrypoint in libiberty that I need > >>> patch 2: configure and Makefile changes in "gcc" > >>> patch 3: timevar.h: Add an auto_timevar class > >>> patch 4: State cleanups in "gcc" > >>> patch 5: Add the "jit" code itself > >>> > >>> [this is a diff of trunk r215958 aka > >>> e012cdc775868e9922f5fef9068a764546876d93 which is from 2014-10-06, > >>> vs jit branch version 75b3ee7acdc6de55354d65bb7d619386463e50a1]. > >>> > >>> I've successfully bootstrapped and regression-tested the cumulative > >>> result of all of the patches against a control build, building them > >>> both with --enable-host-shared, and with > >>> --enable-languages=c,c++,objc,obj-c++,java,fortran,ada,go,lto > >>> adding ",jit" to the test build (both on x86_64-unknown-linux-gnu; > >>> Fedora 20). > >>> > >>> There were no regressions vs the control build, and the patched build > >>> gains a jit.sum, with 4663 passes (and no failures). > >>> > >>> OK for trunk? > >> > >> Patch 5 seems to have been too large, even compressed, so I'm breaking > >> it up into separate pieces and compressing, giving 10 patches in total > >> > >> Patches 1-4 are as above. > >> > >> Patch 5: remaining JIT-related changes outside of the gcc/jit/ subdir > >> > >> Patch 6: the core of the JIT implementation: the gcc/jit subdir > >> > >> Patch 7: the testsuite: gcc/testsuite/jit.dg > >> > >> Patch 8: sphinx-based documentation: the gcc/jit/docs subdir > >> > >> Patch 9: texinfo documentation autogenerated from the sphinx sources. > >> > >> Patch 10: the ChangeLog.jit logs from the branch. > > > > For some reason, patches 8 and 9 don't seem to have made it through to > > the list, even after a couple of attempts. > > > > Here's the ChangeLog for patch 8: > > > > gcc/jit/ChangeLog: > > > > * docs/Makefile: New. > > * docs/conf.py: New. > > * docs/examples/install-hello-world.c: New. > > * docs/examples/tut01-square.c: New. > > * docs/examples/tut02-sum-of-squares.c: New. > > * docs/examples/tut03-toyvm/Makefile: New. > > * docs/examples/tut03-toyvm/factorial.toy: New. > > * docs/examples/tut03-toyvm/fibonacci.toy: New. > > * docs/examples/tut03-toyvm/toyvm.c: New. > > * docs/index.rst: New. > > * docs/internals/index.rst: New. > > * docs/intro/factorial.png: New. > > * docs/intro/index.rst: New. > > * docs/intro/install.rst: New. > > * docs/intro/sum-of-squares.png: New. > > * docs/intro/tutorial01.rst: New. > > * docs/intro/tutorial02.rst: New. > > * docs/intro/tutorial03.rst: New. > > * docs/topics/contexts.rst: New. > > * docs/topics/expressions.rst: New. > > * docs/topics/functions.rst: New. > > * docs/topics/index.rst: New. > > * docs/topics/locations.rst: New. > > * docs/topics/objects.rst: New. > > * docs/topics/results.rst: New. > > * docs/topics/types.rst: New. > > > > The new files can be seen at: > > https://gcc.gnu.org/git/?p=gcc.git;a=tree;f=gcc/jit/docs;h=a31ffa5d5068f088a314bad3f904887f6dfa3098 > > > > HTML built from these (via sphinx) can be seen at: > > https://dmalcolm.fedorapeople.org/gcc/libgccjit-api-docs/index.html > So I'm reading this and the first thing that comes to mind is *way* too > much on installation via packages. That documentation may be > appropriate elsewhere, but I don't think it makes sense in GCC. I've moved all info on installation via packages to the wiki. > As far as installation from source, assuming the bits are integrated > onto the trunk, this section should be dramatically simplified and in > fact ought to be removed. I've eliminated much of this, moving what remains to the final page of the docs, which is aimed at contributors (and, in particular, myself). > For the examples, assume folks have built from source and installed into > whatever prefix they selected. ie, I thik that section becomes > > gcc jit-hello-world.c -o jit-hello-world -lgccjit > > All the other stuff is unwanted/unneeded. No need to talk about running > from different prefixes, locally built trees. Remove the pkg-config > stuff, that's not a way we do things in the gcc-world. If you want to > make an argument for pkg-config, then that's independent of this work > and should be made pervasive in GCC if we were to decide to go that > route. Having it just for the plugin is inconsistent and confusing. I'll make that argument another time. For now, I've removed it for the sake of getting the code into trunk. In the patch below I've removed mentions of it from the docs. > Similarly for the stuff for how to use a working copy without > installing. Might be useful to document somewhere, but for GCC, we > expect folks to build & install. Running the testsuite should just be > make check, which is no different than other parts of GCC I've updated the testsuite to no longer need an install, so I've updated the final page of the docs to reflect that. > and I don't think you need a page on how to do that. Sadly, *I* do need such a page :) This may turn into a rant; sorry... IIRC, it took me several hours way back when to figure out how to just run one specific testcase (as opposed to the whole suite), and I can never remember the right incantation, so I wrote it up on the wiki page, and now just go there when I find myself wondering the right incantation. I can never find things in the .texi files or the HTML built from them. So right now there *is* a page that I use to tell me how to do that, but it's on the wiki... Having vital documentation live on a *wiki* disturbs me. There's an excellent talk from Jacob Kaplan-Moss: "Writing Great Documentation" (PyCon Atlanta 2011): https://www.youtube.com/watch?v=z3fRu9pkuXE with the quote: "a wiki is where good documentation goes to die" I recommend watching the whole talk (e.g. for the material about how good documentation is fractal in nature [1]). I have a pet theory that any time that I have to use a wiki can be seen as a symptom of dysfunction in a project - why am I editing a wiki, rather that a file in a source tree? Some of the reasons might be (not singling out gcc here): * a project has chosen an overly cumbersome source representation for its docs, and is using a wiki to avoid e.g. having to type DocBook (I speak as a reformed former DocBook enthusiast). * a project doesn't have a good place to put said documentation (e.g. we have a user manual and an installation manual; do we have a contributor manual? Though why make such distinctions? Maybe we can build a smoother on-ramp for turning users into contributors?) ...etc So I need somewhere to put this documentation, and I'd rather take the best parts of the wiki page and put them in a contributor guide. Given that this is Sphinx-based, there's already a degree of separation between these docs and the existing GCC docs - this isn't going to be a part of the GCC manual at this time, it's going to be a sibling document. Hence I think it's reasonable for this guide to cover both users of *and* contributors to the JIT library, with the contributor-focussed content isolated from the user-focussed content as a appendix. There's also what I call the "man page disease", where documentation is written as if only saying anything once is a virtue. I believe most developers only read small parts of documentation based on skimming and on the pages they see in internet search results, hence I believe redundancy is a virtue: it's OK to repeat ourselves, to restate things with examples for clarity. This may be a generation-gap thing. A use-case for the contributor-focussed content is for things like "I'm debugging a local build of GNU Octave, running against a local (not-installed) build of libgccjit, and need to make a one-line change to libgccjit. What exactly needs to be set in the environment when invoking gdb?" It's painful figuring this out by hand, and it needs to be captured in the docs somewhere. OK, rant over :) > So I think the general comment is assume the normal build/install > scenario, removing all the stuff that becomes extraneous. Assume your > target audience isn't hacking GCC itself and simplify appropriately. > > If you want to pull those developer-oriented docs somewhere on the GCC > web site, I think we can find a way to make that happen, but I don't > think all that stuf needs to be in the GCC manual. The following patch: * eliminates all mentions of pkg-config * eliminates the installation section and the discussion of packages * converts the final page (docs/internals/index.rst) into a short guide for contributors to the project. I think having it next to the rest of the docs is reasonable. I've committed it to the dmalcolm/jit branch, and prebuilt HTML can be seen at: https://dmalcolm.fedorapeople.org/gcc/libgccjit-api-docs/index.html as before. The significant changes can be seen on the first page of the tutorial: https://dmalcolm.fedorapeople.org/gcc/libgccjit-api-docs/intro/tutorial01.html and in the final page of the docs: https://dmalcolm.fedorapeople.org/gcc/libgccjit-api-docs/internals/index.html which as I said above is a compendium of contributor docs, of which I'm the primary consumer. Is this more acceptable? After this patch, the "intro/install.rst" becomes a poor name. I've renamed it in a followup patch to "intro/tutorial01.rst". [1] 21 minutes in fwiw, but really, watch it all, it's a great talk. Committed to branch dmalcolm/jit: gcc/jit/ChangeLog.jit: * docs/intro/install.rst ("Installation via packages"): Drop this section. ("Installation from source"): Drop this section, moving parts of it to https://gcc.gnu.org/wiki/JIT and some others to docs/internals/index.rst. ("Hello world"): This section becomes the only remaining part of this file. Eliminate references to pkg-config. * docs/internals/index.rst ("Using a working copy without installing every time"): Rewrite as... ("Working on the JIT library"): ...new section, aimed at contributors (and myself) working from a build directory, eliminating references to installation. Add description of pertinent configuration options. ("Running the test suite"): Add setting of LIBRARY_PATH to description of how to run a built binary outside of the test suite. ("Environment variables"): New section, describing pertinent environment variables. --- gcc/jit/ChangeLog.jit | 23 +++++ gcc/jit/docs/internals/index.rst | 133 +++++++++++++++++++------- gcc/jit/docs/intro/install.rst | 201 +++------------------------------------ 3 files changed, 132 insertions(+), 225 deletions(-) diff --git a/gcc/jit/ChangeLog.jit b/gcc/jit/ChangeLog.jit index 02664f0..ab09b9d 100644 --- a/gcc/jit/ChangeLog.jit +++ b/gcc/jit/ChangeLog.jit @@ -1,3 +1,26 @@ +2014-10-21 David Malcolm + + * docs/intro/install.rst ("Installation via packages"): Drop + this section. + ("Installation from source"): Drop this section, moving parts + of it to https://gcc.gnu.org/wiki/JIT and some others to + docs/internals/index.rst. + ("Hello world"): This section becomes the only remaining part + of this file. Eliminate references to pkg-config. + + * docs/internals/index.rst + ("Using a working copy without installing every time"): Rewrite + as... + ("Working on the JIT library"): ...new section, aimed at + contributors (and myself) working from a build directory, + eliminating references to installation. Add description + of pertinent configuration options. + ("Running the test suite"): Add setting of LIBRARY_PATH to + description of how to run a built binary outside of the test + suite. + ("Environment variables"): New section, describing pertinent + environment variables. + 2014-10-20 David Malcolm * jit-recording.c (gcc::jit::dump::dump): Handle fopen failures diff --git a/gcc/jit/docs/internals/index.rst b/gcc/jit/docs/internals/index.rst index 1e3952c..80626e4 100644 --- a/gcc/jit/docs/internals/index.rst +++ b/gcc/jit/docs/internals/index.rst @@ -18,20 +18,10 @@ Internals ========= -Using a working copy without installing every time --------------------------------------------------- -When directly working on the library you can avoid needing to install to -test every change. - -You need to do a ``make install`` of the ``gcc`` subdirectory to install -the driver binary (the top-level ``gcc`` binary). This is used internally -by the library for converting from .s assembler files to .so shared -libraries. Specifically, it looks for an executable on the ``$PATH`` with -a name expanded by the ``configure`` script from -``${target_noncanonical}-gcc-${gcc_BASEVER}${exeext}``, -such as ``x86_64-unknown-linux-gnu-gcc-5.0.0``. - -For example, if you configured with a prefix of ``$PREFIX`` like this: +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 @@ -45,39 +35,44 @@ For example, if you configured with a prefix of ``$PREFIX`` like this: --disable-bootstrap \ --enable-checking=release \ --prefix=$PREFIX + nice make -j4 # altering the "4" to however many cores you have -then you can install (once) to ensure that ``$PREFIX/bin/`` is populated: +This should build a libgccjit.so within jit/build/gcc: .. code-block:: console - [build]$ ll ../install/bin/*gcc* - -rwxr-xr-x. 3 david david 2733458 Oct 6 14:25 ../install/bin/gcc - -rwxr-xr-x. 2 david david 136921 Oct 6 14:25 ../install/bin/gcc-ar - -rwxr-xr-x. 2 david david 136857 Oct 6 14:25 ../install/bin/gcc-nm - -rwxr-xr-x. 2 david david 136869 Oct 6 14:25 ../install/bin/gcc-ranlib - -rwxr-xr-x. 3 david david 2733458 Oct 6 14:25 ../install/bin/x86_64-unknown-linux-gnu-gcc - -rwxr-xr-x. 3 david david 2733458 Oct 6 14:25 ../install/bin/x86_64-unknown-linux-gnu-gcc-5.0.0 - -rwxr-xr-x. 2 david david 136921 Oct 6 14:25 ../install/bin/x86_64-unknown-linux-gnu-gcc-ar - -rwxr-xr-x. 2 david david 136857 Oct 6 14:25 ../install/bin/x86_64-unknown-linux-gnu-gcc-nm - -rwxr-xr-x. 2 david david 136869 Oct 6 14:25 ../install/bin/x86_64-unknown-linux-gnu-gcc-ranlib + [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 -Note the presence above of ``../install/bin/x86_64-unknown-linux-gnu-gcc``. +Here's what those configuration options mean: -When building code using the API you need to ensure that ``-I`` points to -the directory containing ``libgccjit.h`` and ``-L`` points to the -directory containing the built library. +.. option:: --enable-host-shared -When running binaries (or debugging them), you'll need to manually set -``LD_LIBRARY_PATH`` to the directory containing ``libgccjit.so``, and -``PATH`` needs to contain the path to the installed binaries. + 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. -and then you can run from a built (but not installed) copy: +.. option:: --enable-languages=jit -.. code-block:: console + 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. - [gcc]$ PATH=../../install/bin:$PATH LD_LIBRARY_PATH=. ./testsuite/jit/test-factorial.exe +.. option:: --enable-checking=release -without needing to reinstall everything for every tweak to the library. + 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 ---------------------- @@ -117,11 +112,75 @@ and once a test has been compiled, you can debug it directly: .. code-block:: console - [gcc] $ PATH=../../install/bin:$PATH \ + [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 -------------------------- diff --git a/gcc/jit/docs/intro/install.rst b/gcc/jit/docs/intro/install.rst index a0641b7..3f61684 100644 --- a/gcc/jit/docs/intro/install.rst +++ b/gcc/jit/docs/intro/install.rst @@ -17,153 +17,25 @@ .. default-domain:: c -Getting Started ---------------- +Getting Started: "Hello world" +============================== -Installation via packages -========================= - -It's easiest to use pre-built packages of the library. - -Fedora and RHEL -*************** -RPM packages of libgccjit (and its Python 2 and 3 bindings) are -available for Fedora and RHEL, for i386 and x86_64. - -These currently should be treated as experimental. - -See https://copr.fedoraproject.org/coprs/dmalcolm/libgccjit/ -for information on subscribing to the appropriate repository for -your system. Having done this, - -.. code-block:: bash - - sudo yum install libgccjit-devel - -should give you both the JIT library (`libgccjit`) and the header files -needed to develop against it (`libgccjit-devel`): - -.. code-block:: console - - $ rpm -qlv libgccjit - lrwxrwxrwx 1 root root 18 Aug 12 07:56 /usr/lib64/libgccjit.so.0 -> libgccjit.so.0.0.1 - -rwxr-xr-x 1 root root 14463448 Aug 12 07:57 /usr/lib64/libgccjit.so.0.0.1 - - $ rpm -qlv libgccjit-devel - -rwxr-xr-x 1 root root 37654 Aug 12 07:56 /usr/include/libgccjit++.h - -rwxr-xr-x 1 root root 28967 Aug 12 07:56 /usr/include/libgccjit.h - lrwxrwxrwx 1 root root 14 Aug 12 07:56 /usr/lib64/libgccjit.so -> libgccjit.so.0 - - -Other distributions -******************* - -Prebuilt packages for other distributions would be most welcome; please -contact the `jit mailing list`_. - - -Installation from source -======================== -If pre-built packages are not available, you can built the library from -source. Doing so currently requires about 4.2G of drive space (for -the combination of the source tree, the build directory, and the -installation path). - -The code can currently be seen within the git branch "dmalcolm/jit" here: - http://gcc.gnu.org/git/?p=gcc.git;a=shortlog;h=refs/heads/dmalcolm/jit - -The following will check out a copy of the appropriate branch, to the -"jit/src" subdirectory: - -.. code-block:: bash - - mkdir jit - cd jit - git clone \ - -b dmalcolm/jit \ - git://gcc.gnu.org/git/gcc.git \ - src - -The source tree currently occupies about 2.8G of disk space. - -To build it (within the "jit/build" subdirectory, installing to -"jit/install"): - -.. 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 - -On my 4-core laptop this takes 17 minutes and 1.1G of disk space -(it's much faster with many cores and a corresponding -j setting). - -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 - -Note that this is a branch of GCC, so if it fails to build, you might want -to consult the `general GCC FAQ `_ for some -common issues, before checking on the `jit mailing list`_. - -.. _jit mailing list: https://gcc.gnu.org/ml/jit/ - -You should then be able to install it (to the `--prefix` specified -earlier) via: - -.. code-block:: bash - - make install - -On my laptop this uses a further 0.4G of disk space. - -You should be able to see the header files within the `include` -subdirectory of the installation prefix: - -.. code-block:: console - - $ find $PREFIX/include - /home/david/gcc-jit/install/include - /home/david/gcc-jit/install/include/libgccjit.h - /home/david/gcc-jit/install/include/libgccjit++.h - -and the library within the `lib` subdirectory: - -.. code-block:: console - - $ find $PREFIX/lib/libgccjit.* - /home/david/gcc-jit/install/lib/libgccjit.so - /home/david/gcc-jit/install/lib/libgccjit.so.0 - /home/david/gcc-jit/install/lib/libgccjit.so.0.0.1 - - -"Hello world" -============= - -Let's look at how to build and run programs that use the library. +Before we look at the details of the API, let's look at building and +running programs that use the library. Here's a toy "hello world" program that uses the library to synthesize -a call to `printf` and use it to write a message to stdout. +a call to `printf` and uses it to write a message to stdout. + +Don't worry about the content of the program for now; we'll cover +the details in later parts of this tutorial. .. literalinclude:: ../examples/install-hello-world.c :language: c -Copy it to `jit-hello-world.c`. +Copy the above to `jit-hello-world.c`. -To build it with prebuilt packages, use: +Assuming you have the jit library installed, build the test program +using: .. code-block:: console @@ -172,56 +44,9 @@ To build it with prebuilt packages, use: -o jit-hello-world \ -lgccjit - # Run the built program: - $ ./jit-hello-world - hello world - - -If building against an locally-built install (to `$PREFIX`), you can use -`pkg-config `_ to -specify the compilation and linkage flags: +You should then be able to run the built program: .. code-block:: console - $ export PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig - $ gcc \ - jit-hello-world.c \ - -o jit-hello-world \ - $(pkg-config libgccjit --cflags --libs) - -This is equivalent to handcoding the include and library paths with `-I` -and `-L` and specifying `-lgccjit` (i.e. linkage against libgccjit): - -.. code-block:: console - - $ gcc \ - jit-hello-world.c \ - -o jit-hello-world \ - -lgccjit \ - -I$PREFIX/include -L$PREFIX/lib - -When running the built test program against a locally-built tree, two -environment variables need to be set up: - -* `LD_LIBRARY_PATH` needs to be set up appropriately so that the dynamic - linker can locate the `libgccjit.so` - -* `PATH` needs to include the `bin` subdirectory below the installation - prefix, so that the library can locate a driver binary. This is used - internally by the library for converting from .s assembler files to - .so shared libraries. - - .. - Specifically, it looks for a name expanded from - ``${target_noncanonical}-gcc-${gcc_BASEVER}${exeext}`` on the - ``$PATH``, such as ``x86_64-unknown-linux-gnu-gcc-5.0.0``). - -For example, if you configured with a prefix of ``$PREFIX`` like above, -you need an invocation like this: - -.. code-block:: console - - $ LD_LIBRARY_PATH=$PREFIX/lib:$LD_LIBRARY_PATH \ - PATH=$PREFIX/bin:$PATH \ - ./jit-hello-world + $ ./jit-hello-world hello world -- 1.7.11.7