Re: [PATCH 08/10] Documentation for the JIT library (Re: Patches 5-10 of jit merger)

[Jeff Law <law at redhat dot com>]

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.

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.

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.

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 and I don't 
think you need a page on how to do that.


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.

Jeff






>