From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 23287 invoked by alias); 2 Oct 2014 16:16:28 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Received: (qmail 23199 invoked by uid 89); 2 Oct 2014 16:16:28 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.6 required=5.0 tests=AWL,BAYES_00,RP_MATCHES_RCVD,SPF_HELO_PASS,SPF_PASS autolearn=ham version=3.3.2 X-Spam-User: qpsmtpd, 2 recipients X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-GCM-SHA384 encrypted) ESMTPS; Thu, 02 Oct 2014 16:16:24 +0000 Received: from int-mx09.intmail.prod.int.phx2.redhat.com (int-mx09.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s92GGJLE018361 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Thu, 2 Oct 2014 12:16:20 -0400 Received: from surprise.redhat.com (vpn-232-113.phx2.redhat.com [10.3.232.113]) by int-mx09.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id s92GGHZ5025988; Thu, 2 Oct 2014 12:16:18 -0400 From: David Malcolm To: jit@gcc.gnu.org, gcc-patches@gcc.gnu.org Cc: "Joseph S. Myers" , David Malcolm Subject: [jit] Implement documentation targets within jit/Make-lang.in Date: Thu, 02 Oct 2014 16:16:00 -0000 Message-Id: <1412266347-19359-1-git-send-email-dmalcolm@redhat.com> In-Reply-To: References: X-IsSubscribed: yes X-SW-Source: 2014-10/txt/msg00185.txt.bz2 On Tue, 2014-09-23 at 23:27 +0000, Joseph S. Myers wrote: [...] > Shouldn't the jit.pdf, jit.install-html etc. Make-lang.in hooks actually > build / install the documentation for this JIT? [...] I've committed the following to the branch dmalcolm/jit: This patch implements the documentation targets: * jit.info * jit.install-info * jit.dvi * jit.pdf * jit.install-pdf * jit.install-html * jit.html within jit/Make-lang.in, and adds detection of "sphinx-build" to the gcc configure script. It uses sphinx (if available) to generate the HTML jit documentation, with texinfo as a fallback, and texinfo for the other formats. gcc/ChangeLog.jit: * configure.ac (doc_build_sys): New variable, set to "sphinx" if sphinx is installed, falling back to "texinfo" otherwise. * configure: Regenerate. * Makefile.in (doc_build_sys): New. gcc/jit/ChangeLog.jit: * Make-lang.in (jit.info): Implement. (jit.install-info): Implement. (jit.dvi): Implement. (jit.pdf): Implement in terms of new target "jit.texinfo.pdf". (jit.install-pdf): Likewise for new target "jit.texinfo.install-pdf". (jit.install-html): Implement in terms of "jit.$(doc_build_sys).install-html" to redirect to new targets "jit.sphinx.install-html" or "jit.texinfo.install-html". (jit.html): Implement in terms of "jit.$(doc_build_sys).html" to redirect to new targets "jit.sphinx.html" or "jit.texinfo.html". (JIT_TEXI_FILES): New variable. (jit.texinfo.html): New target. (jit.texinfo.install-html): New target. (jit.texinfo.pdf): New target. (jit.texinfo.install-pdf): New target. (SPHINX_BUILD_DIR): New variable. (jit.sphinx.html): New target. (jit_htmldir): New variable. (jit.sphinx.install-html): New target. (jit.sphinx.pdf): New target. --- gcc/Makefile.in | 5 ++ gcc/configure | 46 +++++++++++++++- gcc/configure.ac | 4 ++ gcc/jit/Make-lang.in | 148 ++++++++++++++++++++++++++++++++++++++++++++++++--- 4 files changed, 194 insertions(+), 9 deletions(-) diff --git a/gcc/Makefile.in b/gcc/Makefile.in index f56fa96..ae2c6e5 100644 --- a/gcc/Makefile.in +++ b/gcc/Makefile.in @@ -310,6 +310,11 @@ write_entries_to_file = $(shell rm -f $(2) || :) $(shell touch $(2)) \ $(shell expr $(range) + $(write_entries_to_file_split) - 1), $(1))" \ | tr ' ' '\012' >> $(2))) +# The jit documentation looks better if built with sphinx, but can be +# built with texinfo if sphinx is not available. +# configure sets "doc_build_sys" to "sphinx" or "texinfo" accordingly +doc_build_sys=@doc_build_sys@ + # -------- # UNSORTED # -------- diff --git a/gcc/configure b/gcc/configure index c1922ac..0eccf67 100755 --- a/gcc/configure +++ b/gcc/configure @@ -743,6 +743,7 @@ CXXDEPMODE DEPDIR am__leading_dot CXXCPP +doc_build_sys AR NM BISON @@ -8062,6 +8063,47 @@ fi fi +# The jit documentation looks better if built with sphinx, but can be +# built with texinfo if sphinx is not available. +# Set "doc_build_sys" to "sphinx" or "texinfo" accordingly. +# Extract the first word of "sphinx-build", so it can be a program name with args. +set dummy sphinx-build; ac_word=$2 +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +$as_echo_n "checking for $ac_word... " >&6; } +if test "${ac_cv_prog_doc_build_sys+set}" = set; then : + $as_echo_n "(cached) " >&6 +else + if test -n "$doc_build_sys"; then + ac_cv_prog_doc_build_sys="$doc_build_sys" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_doc_build_sys="sphinx" + $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + + test -z "$ac_cv_prog_doc_build_sys" && ac_cv_prog_doc_build_sys="texinfo" +fi +fi +doc_build_sys=$ac_cv_prog_doc_build_sys +if test -n "$doc_build_sys"; then + { $as_echo "$as_me:${as_lineno-$LINENO}: result: $doc_build_sys" >&5 +$as_echo "$doc_build_sys" >&6; } +else + { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 +$as_echo "no" >&6; } +fi + + # -------------------- # Checks for C headers @@ -18035,7 +18077,7 @@ else lt_dlunknown=0; lt_dlno_uscore=1; lt_dlneed_uscore=2 lt_status=$lt_dlunknown cat > conftest.$ac_ext <<_LT_EOF -#line 18038 "configure" +#line 18080 "configure" #include "confdefs.h" #if HAVE_DLFCN_H @@ -18141,7 +18183,7 @@ else lt_dlunknown=0; lt_dlno_uscore=1; lt_dlneed_uscore=2 lt_status=$lt_dlunknown cat > conftest.$ac_ext <<_LT_EOF -#line 18144 "configure" +#line 18186 "configure" #include "confdefs.h" #if HAVE_DLFCN_H diff --git a/gcc/configure.ac b/gcc/configure.ac index 6164cc2..5b78b65 100644 --- a/gcc/configure.ac +++ b/gcc/configure.ac @@ -972,6 +972,10 @@ else AC_CHECK_PROG(AR, ar, ar, ${CONFIG_SHELL-/bin/sh} ${srcdir}/../missing ar) fi +# The jit documentation looks better if built with sphinx, but can be +# built with texinfo if sphinx is not available. +# Set "doc_build_sys" to "sphinx" or "texinfo" accordingly. +AC_CHECK_PROG(doc_build_sys, sphinx-build, sphinx, texinfo) # -------------------- # Checks for C headers diff --git a/gcc/jit/Make-lang.in b/gcc/jit/Make-lang.in index 26dd022..e79d5d0 100644 --- a/gcc/jit/Make-lang.in +++ b/gcc/jit/Make-lang.in @@ -86,13 +86,147 @@ $(LIBGCCJIT_LINKER_NAME_SYMLINK): $(LIBGCCJIT_SONAME_SYMLINK) jit.all.cross: jit.start.encap: jit.rest.encap: -jit.info: -jit.install-info: -jit.dvi: -jit.pdf: -jit.install-pdf: -jit.install-html: -jit.html: + +# Documentation build hooks. +# +# The documentation can be built using the texinfo toolchain, or +# the sphinx toolchain +# +# The jit documentation is authored using Sphinx, which has numerous +# advantages over Texinfo, including: +# +# * much faster +# +# * use of CSS and JS to provide less of a 1990s feel in the generated +# HTML. +# +# * sane, stable HTML page and anchor names +# +# * sane HTML navigation: ability to move forward and back in the HTML +# at every node to read the HTML like a book +# +# * syntax-coloring of examples +# +# * the ability to "include" fragments of code inline. This is used +# heavily by the jit docs, so that the example code is shared by both +# the test suite and the documentation to ensure that the examples +# appearing in the docs actually compile and work +# +# Sphinx is not a "blessed" dependency, and so a prebuilt libgccjit.texinfo +# file built by Sphinx is checked into the source tree to avoid requiring +# everyone to have Sphinx installed. +# +# This prebuilt libgccjit.texinfo has the "include" fragments "baked in", +# and so contains the content from the sphinx toolchain, but lacks the +# syntax-coloring, and the generated HTML is (IMHO) greatly inferior to +# that generated by Sphinx. + +# These targets redirect HTML creation and installation to either +# jit.sphinx.(install-)html or jit.texinfo.(install-)html. +jit.html: jit.$(doc_build_sys).html +jit.install-html: jit.$(doc_build_sys).install-html + +# For now, use texinfo for pdf, since the sphinx latex toolchain currently +# fails for me deep inside pdflatex (see notes below) +jit.pdf: jit.texinfo.pdf +jit.install-pdf: jit.texinfo.install-pdf + +# Hooks for building docs using texinfo +JIT_TEXI_FILES = $(srcdir)/jit/docs/_build/texinfo/libgccjit.texi + +jit.info: doc/libgccjit.info +doc/libgccjit.info: $(JIT_TEXI_FILES) + if test "x$(BUILD_INFO)" = xinfo; then \ + rm -f doc/libgccjit.info*; \ + $(MAKEINFO) $(MAKEINFOFLAGS) -I $(gcc_docdir) \ + -I $(gcc_docdir)/include -o $@ $<; \ + else true; fi + +jit.install-info: $(DESTDIR)$(infodir)/libgccjit.info + +jit.dvi: doc/libgccjit.dvi +doc/libgccjit.dvi: $(JIT_TEXI_FILES) + $(TEXI2DVI) -I $(abs_docdir) -I $(abs_docdir)/include -o $@ $< + +jit.texinfo.html: $(build_htmldir)/jit/index.html + +$(build_htmldir)/jit/index.html: $(srcdir)/jit/docs/_build/texinfo/libgccjit.texi + $(mkinstalldirs) $(@D) + rm -f $(@D)/* + $(TEXI2HTML) -I $(gcc_docdir)/include -I $(srcdir)/jit -o $(@D) $< + +jit.texinfo.install-html: jit.texinfo.html + @$(NORMAL_INSTALL) + test -z "$(htmldir)" || $(mkinstalldirs) "$(DESTDIR)$(htmldir)" + @for p in $(build_htmldir)/jit; do \ + if test -f "$$p" || test -d "$$p"; then d=""; else d="$(srcdir)/"; fi; \ + f=$(html__strip_dir) \ + if test -d "$$d$$p"; then \ + echo " $(mkinstalldirs) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(mkinstalldirs) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \ + else \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \ + fi; \ + done + +jit.texinfo.pdf: doc/libgccjit.pdf + +doc/libgccjit.pdf: $(JIT_TEXI_FILES) + $(TEXI2PDF) -I $(abs_docdir) -I $(abs_docdir)/include -o $@ $< + +jit.texinfo.install-pdf: doc/libgccjit.pdf + @$(NORMAL_INSTALL) + test -z "$(pdfdir)" || $(mkinstalldirs) "$(DESTDIR)$(pdfdir)/gcc" + @for p in doc/libgccjit.pdf; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(pdf__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/gcc/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/gcc/$$f"; \ + done + +# Hooks for building docs using the Sphinx toolchain: + +SPHINX_BUILD_DIR=jit/sphinx-build + +jit.sphinx.html: + mkdir -p $(SPHINX_BUILD_DIR) + (cd $(srcdir)/jit/docs && \ + make html BUILDDIR=$(PWD)/$(SPHINX_BUILD_DIR) ) + +jit_htmldir=$(htmldir)/jit + +jit.sphinx.install-html: jit.sphinx.html + @$(NORMAL_INSTALL) + test -z "$(jit_htmldir)" || $(mkinstalldirs) "$(DESTDIR)$(jit_htmldir)" + @for f in $(shell cd $(SPHINX_BUILD_DIR)/html && find) ; do \ + if test -f $(SPHINX_BUILD_DIR)/html/"$$f"; then \ + $(INSTALL_DATA) $(SPHINX_BUILD_DIR)/html/"$$f" $(DESTDIR)$(jit_htmldir)/"$$f"; \ + else \ + mkdir $(DESTDIR)$(jit_htmldir)/"$$f"; \ + fi; \ + done + +# (This one is currently failing deep inside pdflatex for me; +# see https://bugzilla.redhat.com/show_bug.cgi?id=1148845 ) +jit.sphinx.pdf: $(SPHINX_BUILD_DIR)/latex/libgccjit.pdf +$(SPHINX_BUILD_DIR)/latex/libgccjit.pdf: + mkdir -p $(SPHINX_BUILD_DIR) + (cd $(srcdir)/jit/docs && \ + make latexpdf BUILDDIR=$(PWD)/$(SPHINX_BUILD_DIR) ) + +jit.sphinx.install-pdf: $(SPHINX_BUILD_DIR)/latex/libgccjit.pdf + @$(NORMAL_INSTALL) + test -z "$(pdfdir)" || $(mkinstalldirs) "$(DESTDIR)$(pdfdir)/gcc" + @for p in $(SPHINX_BUILD_DIR)/latex/libgccjit.pdf; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(pdf__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/gcc/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/gcc/$$f"; \ + done + jit.srcinfo: jit.srcextra: -- 1.7.11.7