Re: [PATCH] Makefile: Fix in-tree builds when Sphinx is available

["Alex Bennée" <alex.bennee@linaro.org>]

Peter Maydell <peter.maydell@linaro.org> writes:

> In commit 27a296fce9821e we switched the qemu-ga manpage over to
> being built from Sphinx.  The makefile rules for this were correct
> for an out-of-tree build, but break for in-tree builds if Sphinx is
> present and we're trying to build the documentation.
>
> Specifically, because Sphinx refuses to build output files into
> the same directory as its sources, for an in-tree build we tell
> it to build into a subdirectory docs/built, and set up a makefile
> variable MANUAL_BUILDDIR indicating where the docs are going.
> The makefile rule telling Make how to build qemu-ga.8 correctly
> used this variable, but the lines adding qemu-ga.8 to the list
> of DOCS to be built and the 'make install' rune did not. The
> effect was that for an in-tree build we told Make to build
> 'docs/interop/qemu-ga.8' but did not provide a specific rule for
> doing so, which caused Make to fall back to the old rules.make
> rule for building any "%.8" file. Make tried to invoke texi2pod
> with a bogus command line, resulting in the error:
>
>   GEN     docs/interop/qemu-ga.8
> No filename or title
> make: *** [rules.mak:394: docs/interop/qemu-ga.8]
>
> Fix this by using $(MANUAL_BUILDDIR) when constructing the
> list of DOCS files we want to build and also in the source
> file name we install for 'make install'.
>
> (Among other things, this broke the Shippable CI builds.)
>
> Reported-by: Eric Blake <eblake@redhat.com>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

heh I'd manually rebuilt the patch from your last email. I guess you can
apply this one directly though and I'll clean-up when I rebase for the PR.

> ---
>  Makefile | 26 +++++++++++++-------------
>  1 file changed, 13 insertions(+), 13 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index 111082ce545..a0c1430b407 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -324,8 +324,19 @@ endif
>  endif
>  endif
>
> +# Sphinx does not allow building manuals into the same directory as
> +# the source files, so if we're doing an in-tree QEMU build we must
> +# build the manuals into a subdirectory (and then install them from
> +# there for 'make install'). For an out-of-tree build we can just
> +# use the docs/ subdirectory in the build tree as normal.
> +ifeq ($(realpath $(SRC_PATH)),$(realpath .))
> +MANUAL_BUILDDIR := docs/built
> +else
> +MANUAL_BUILDDIR := docs
> +endif
> +
>  ifdef BUILD_DOCS
> -DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 docs/interop/qemu-ga.8
> +DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 $(MANUAL_BUILDDIR)/interop/qemu-ga.8
>  DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7
>  DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7
>  DOCS+=docs/qemu-block-drivers.7
> @@ -699,17 +710,6 @@ dist: qemu-$(VERSION).tar.bz2
>  qemu-%.tar.bz2:
>  	$(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)"
>
> -# Sphinx does not allow building manuals into the same directory as
> -# the source files, so if we're doing an in-tree QEMU build we must
> -# build the manuals into a subdirectory (and then install them from
> -# there for 'make install'). For an out-of-tree build we can just
> -# use the docs/ subdirectory in the build tree as normal.
> -ifeq ($(realpath $(SRC_PATH)),$(realpath .))
> -MANUAL_BUILDDIR := docs/built
> -else
> -MANUAL_BUILDDIR := docs
> -endif
> -
>  define clean-manual =
>  rm -rf $(MANUAL_BUILDDIR)/$1/_static
>  rm -f $(MANUAL_BUILDDIR)/$1/objects.inv $(MANUAL_BUILDDIR)/$1/searchindex.js $(MANUAL_BUILDDIR)/$1/*.html
> @@ -819,7 +819,7 @@ ifdef CONFIG_TRACE_SYSTEMTAP
>  	$(INSTALL_DATA) scripts/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
>  endif
>  ifneq (,$(findstring qemu-ga,$(TOOLS)))
> -	$(INSTALL_DATA) docs/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
> +	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
>  	$(INSTALL_DATA) docs/interop/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)"
>  	$(INSTALL_DATA) docs/interop/qemu-ga-ref.txt "$(DESTDIR)$(qemu_docdir)"
>  	$(INSTALL_DATA) docs/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7"


--
Alex Bennée