From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 31855 invoked by alias); 15 Oct 2014 20:44:44 -0000 Mailing-List: contact jit-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Post: List-Help: List-Subscribe: Sender: jit-owner@gcc.gnu.org Received: (qmail 31834 invoked by uid 89); 15 Oct 2014 20:44:43 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Checked: by ClamAV 0.98.4 on sourceware.org X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.8 required=5.0 tests=AWL,BAYES_00,SPF_HELO_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-Spam-Status: No, score=-1.8 required=5.0 tests=AWL,BAYES_00,SPF_HELO_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on sourceware.org X-Spam-Level: X-Spam-User: qpsmtpd, 2 recipients X-HELO: mx1.redhat.com Message-ID: <543EDCB7.9040604@redhat.com> Date: Wed, 01 Jan 2014 00:00:00 -0000 From: Jeff Law User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.1.1 MIME-Version: 1.0 To: David Malcolm , jit@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) References: <1413222308-25753-1-git-send-email-dmalcolm@redhat.com> <1413299342.9513.50.camel@surprise> <1413392213.9513.108.camel@surprise> In-Reply-To: <1413392213.9513.108.camel@surprise> Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit X-Scanned-By: MIMEDefang 2.68 on 10.5.11.24 X-SW-Source: 2014-q4/txt/msg00037.txt.bz2 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 > >