[jit] Implement documentation targets within jit/Make-lang.in
David Malcolm
dmalcolm@redhat.com
Thu Oct 2 16:16:00 GMT 2014
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
More information about the Gcc-patches
mailing list