Re: [jit] Update the docs

Re: [jit] Update the docs

[Manuel López-Ibáñez]

> 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.

This is documented in several places:

https://gcc.gnu.org/install/test.html
https://gcc.gnu.org/wiki/Testing_GCC
https://gcc.gnu.org/wiki/HowToPrepareATestcase?highlight=%28RUNTESTFLAGS%29
https://gcc.gnu.org/wiki/TestCaseWriting?highlight=%28RUNTESTFLAGS%29

I'm not saying that you should have found it, but that the information
is not easy to find even if it is there. The question is why?

> I can never find things in the .texi files or the HTML built from them.

Or the ones that we do not build from them, since a lot of important
information is not on the *.texi files but in other HTML pages...

> Having vital documentation live on a *wiki* disturbs me.

Well, it is better than having really outdated documentation or not
having any documentation at all, which is often the case in GCC. I
would like to think of the wiki as a prototyping/staging area.
Unfortunately, right now it is more like a landfill.

> 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

and I would add (singling out GCC here):

* Documentation spread between webpages, html pages generated from
*.texi and the wiki.

* From all the above, the wiki is in fact the easiest to edit because...

* texi requires review, reviews require someone to review, and if
there are too few people reviewing patches, there are even fewer
people reviewing doc patches. If I find something wrong or that should
be better documented, I need: to write a patch, to write a changelog,
submit it, wait from days to weeks (if ever reviewed), get feedback,
write another patch, perhaps another changelog, submit it, wait from
days to weeks (if ever reviewed)...

* html pages: CVS. Do I need to say more?

* Plus all this: https://gcc.gnu.org/wiki/DocumentationOverviewIssues

Example: if someone says for the nth time "I know my code is undefined
but...". I could fight with CVS, submit a patch for
https://gcc.gnu.org/faq.html, wait wait wait wait wait, get it
reviewed, then CVS, ups I did some html mistake, so it was not
applied, fix it, then CVS, then send the link to the user. Or, I could
directly edit https://gcc.gnu.org/wiki/FAQ#undefinedbut, then send the
link to the user.

And IMHO, the result in the wiki, despite all the shortcomings of
MoinMoin (which are plenty), looks nicer than both the CVS html
webpages and the HTML generated from texi.

I'm not arguing that the reviewers are not doing their job. I fully
understand that they are doing as much as they can and that GCC is
lacking contributors and the situation is not getting better. My
argument would go in the other direction:

* Do not require any pre-commit review, except for major rewrites and additions.

* Do not require changelogs for documentation patches: a commit
message and 'svn log --verbose' should be enough.

* Get rid of CVS.

* Put all HTML pages in SVN under trunk/ and add a commit-hook to
upload it, so there is the shortest delay possible between commit and
showing up online.

* Anything that looks remotely like documentation should come from the
same sources as the real documentation (FAQs, Howtos, etc.), and
hyperlink the hell out of it.

* Add a Getting Started/Contributor manual. Add one per piece of GCC:
Ada, libstdc++, etc...

* Aggressively move things that are nice from the wiki to the
documentation and hyperlink to it.

* Aggressively cleanup the wiki from outdated and incoherent stuff.

In summary, I totally agree with your rant.

>   "a wiki is where good documentation goes to die"

Indeed: https://gcc.gnu.org/wiki/GettingStarted
Indeed2: https://gcc.gnu.org/wiki/Visibility
Indeed3: https://gcc.gnu.org/wiki/LinkTimeOptimizationFAQ
Indeed4: https://gcc.gnu.org/wiki/Math_Optimization_Flags

Cheers,

    Manuel.

Bonus: Try to see how long can you go answering every question about
using/developing GCC with a link to the documentation or the wiki.

Bonusx2: Mentor someone to become a new contributor: Try to answer
each of their questions with a link to the documentation or the wiki.
See how long until they give up.

[jit] Update the docs

[David Malcolm]

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