From: Jeff Law <law@redhat.com>
To: David Malcolm <dmalcolm@redhat.com>,
jit@gcc.gnu.org,
"gcc-patches@gcc.gnu.org" <gcc-patches@gcc.gnu.org>
Subject: Re: [PATCH 08/10] Documentation for the JIT library (Re: Patches 5-10 of jit merger)
Date: Wed, 01 Jan 2014 00:00:00 -0000 [thread overview]
Message-ID: <543EDCB7.9040604@redhat.com> (raw)
In-Reply-To: <1413392213.9513.108.camel@surprise>
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
>
>
next prev parent reply other threads:[~2014-10-15 20:44 UTC|newest]
Thread overview: 49+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-01-01 0:00 [PATCH 0/5] Merger of jit branch (v2) David Malcolm
2014-01-01 0:00 ` [PATCH 3/5] timevar.h: Add an auto_timevar class David Malcolm
2014-01-01 0:00 ` Richard Biener
2014-01-01 0:00 ` David Malcolm
2014-01-01 0:00 ` Richard Biener
2014-01-01 0:00 ` Patches 5-10 of jit merger (was: Re: [PATCH 0/5] Merger of jit branch (v2)) David Malcolm
2014-01-01 0:00 ` [PATCH 06/10] Heart of the JIT implementation " David Malcolm
2014-01-01 0:00 ` Joseph S. Myers
2014-01-01 0:00 ` [jit] Error-handling within gcc::jit::dump David Malcolm
2014-01-01 0:00 ` Joseph S. Myers
2014-01-01 0:00 ` [PATCH 06/10] Heart of the JIT implementation (was: Re: [PATCH 0/5] Merger of jit branch (v2)) David Malcolm
2014-01-01 0:00 ` Joseph S. Myers
2014-01-01 0:00 ` [PATCH 06/10] Heart of the JIT implementation Jeff Law
2014-01-01 0:00 ` [PATCH 05/10] JIT-related changes outside of jit subdir David Malcolm
2014-01-01 0:00 ` Jeff Law
2014-01-01 0:00 ` Joseph S. Myers
2014-01-01 0:00 ` [jit] Add Sphinx to install.texi David Malcolm
2014-01-01 0:00 ` Gerald Pfeifer
2014-01-01 0:00 ` David Malcolm
2014-01-01 0:00 ` [jit] Tweaks " David Malcolm
2014-01-01 0:00 ` [jit] Add Sphinx " Joseph S. Myers
2014-01-01 0:00 ` [PATCH 10/10] ChangeLog files (Re: Patches 5-10 of jit merger (was: Re: [PATCH 0/5] Merger of jit branch (v2))) David Malcolm
2014-01-01 0:00 ` [PATCH 10/10] ChangeLog files (Re: Patches 5-10 of jit merger Jeff Law
2014-01-01 0:00 ` [PATCH 09/10] Prebuilt texinfo documentation for the JIT library (Re: Patches 5-10 of jit merger) David Malcolm
2014-01-01 0:00 ` Jeff Law
2014-01-01 0:00 ` [PATCH 08/10] Documentation " David Malcolm
2014-01-01 0:00 ` Jeff Law [this message]
2014-01-01 0:00 ` [jit] Update the docs David Malcolm
2014-01-01 0:00 ` [PATCH 07/10] Testsuite for the JIT (Re: Patches 5-10 of jit merger (was: Re: [PATCH 0/5] Merger of jit branch (v2))) David Malcolm
2014-01-01 0:00 ` [PATCH 07/10] Testsuite for the JIT (Re: Patches 5-10 of jit merger Jeff Law
2014-01-01 0:00 ` Mike Stump
2014-01-01 0:00 ` [PATCH 1/5] libiberty: Expose choose_tmpdir, and fix constness of return type David Malcolm
2014-01-01 0:00 ` Jeff Law
2014-01-01 0:00 ` David Malcolm
2014-01-01 0:00 ` [PATCH 2/5] gcc: configure and Makefile changes needed by jit David Malcolm
2014-01-01 0:00 ` Jeff Law
2014-01-01 0:00 ` David Malcolm
2014-01-01 0:00 ` Joseph S. Myers
2014-01-01 0:00 ` Jeff Law
2014-01-01 0:00 ` David Malcolm
2014-01-01 0:00 ` [PATCH] Avoid the need to install when running the jit testsuite David Malcolm
2014-01-01 0:00 ` Joseph S. Myers
2014-01-01 0:00 ` [jit] Drop libgccjit.pc David Malcolm
2014-01-01 0:00 ` Basile Starynkevitch
2014-01-01 0:00 ` David Malcolm
2014-01-01 0:00 ` [PATCH 4/5] State cleanups David Malcolm
2014-01-01 0:00 ` [PATCH 4/5] State cleanups -- also note for MPX work Jeff Law
2014-01-01 0:00 ` David Malcolm
2014-01-01 0:00 ` Jeff Law
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=543EDCB7.9040604@redhat.com \
--to=law@redhat.com \
--cc=dmalcolm@redhat.com \
--cc=gcc-patches@gcc.gnu.org \
--cc=jit@gcc.gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).