On Tue, 2015-03-03 at 11:49 +0100, Matthias Klose wrote:
> Both gccjit and gnat now use sphinx to build the documentation. While not a
> direct part of the build process, it would be nice to document the
> requirements
> on sphinx, and agree on a common version used to generate that documentation.
>
> Coming from a distro background where I have to "build from source", I know
> that
> sphinx is a bit less stable than say doxygen and texinfo. So some kind of
> version information, about not using sphinx plugins, etc. would be
> appreciated.
gcc/doc/install.texi currently has this text:
@item Sphinx version 1.0 (or later)
Necessary to regenerate @file{jit/docs/_build/texinfo} from the
@file{.rst}
files in the directories below @file{jit/docs}.
For libgccjit, I author the docs in .rst format using sphinx, but I've
been regenerating and checking in a libgccjit.texi file into svn each
time I change the docs (or one of the included files), so sphinx
shouldn't be absolutely needed as a dependency.
gcc/configure.ac currently has:
# 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)
i.e. at configure time it looks for sphinx-build in the PATH, but falls
back to the texinfo toolchain if it isn't found.
Building the jit docs from .rst (as HTML, or for regenerating
libgccjit.texi) requires sphinx >= 1.0; that probably ought to be
expressed in the configure script.
The gcc/jit/Make-lang.in has some more notes on this (including the
rationale). Note that it only attempts to build the *HTML* jit docs
using sphinx, since the PDF sphinx toolchain seems to be much less
reliable and isn't such a clear win for sphinx when compared to HTML
generation (so e.g. jit/Make-lang.in unconditionally uses TEXI2PDF for
PDFs).
The HTML docs on the gcc website:
https://gcc.gnu.org/onlinedocs/jit/
are built using a different script
(maintainer-scripts/update_web_docs_svn) on a cronjob (using sphinx
1.0.8, installed to a non-standard location, as noted in that script).
My understanding is that the gnat docs require a more recent version of
sphinx than 1.0.8, but presumably Arnaud can speak to that.
On the subject of packaging: when building libgccjit,
--enable-host-shared is needed, to get position-independent code, which
will slow down the regular compiler by a few percent. Hence when
packaging gcc with libgccjit, please configure and build twice: once
without --enable-host-shared for most languages, and once with
--enable-host-shared for the jit (this is what Jakub's done for Fedora
packages of gcc 5). AIUI, one should "make install" both
configurations, presumably installing the configuration with
--enable-host-shared, *then* the one without, so that the faster build
of "cc1" et al overwrites the slower build.
(assuming all of the above is correct, I'll write it up for the jit
docs).
Hope this is helpful
Dave
