This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[jit] Update the docs


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  <dmalcolm@redhat.com>
+
+	* 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  <dmalcolm@redhat.com>
 
 	* 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 <https://gcc.gnu.org/wiki/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 <http://www.freedesktop.org/wiki/Software/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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]