[libvirt] [PATCH] build: be smarter about building documentation

Daniel P. Berrange berrange at redhat.com
Fri Sep 27 15:48:22 UTC 2013


On Thu, Sep 19, 2013 at 04:27:41PM -0600, Eric Blake wrote:
> I'm tired of cryptic reports on IRC from people who build from
> git, then type 'make install' and have it fail quite a ways down
> the road because the documentation wasn't built.  It's a feature
> that documentation is not built during development if the toolchain
> is not present (not all git developers build tarballs, and the
> tarballs already contain pre-built docs); but this only works as
> long as you don't try to install or make a tarball from that
> setup.  With this patch in place, and without xhtml1-dtds, I now
> get this nice failure:
> 
> $ make install
> cfg.mk:109: *** ERROR: missing doc toolchain (install xhtml1-dtds and xmllint).  Stop.
> 
> and all with no impact to regular 'make' or 'make check'.
> 
> Along the way, I tried to discover why 'yum-builddeps libvirt'
> doesn't always tell developers to install xhtml1-dtds - my conclusion
> was that if the .srpm is unavailable, then yum-builddeps can't
> figure out anything that is required.  The spec file already has
> a BuildRequires on the doc toolchain (and therefore, the docs shipped
> with an rpm are up-to-date, even if the spec file applied patches
> that affect the docs).  So thankfully I don't have to make any
> spec file changes in this patch.
> 
> * cfg.mk: Let 'make install' and 'make dist' error much earlier if
> we detect a build from git without doc toolchain.
> 
> Signed-off-by: Eric Blake <eblake at redhat.com>
> ---
> 
> Heavily influenced by code in gnulib's GNUMakefile :)
> 
>  cfg.mk | 23 +++++++++++++++++++++++
>  1 file changed, 23 insertions(+)
> 
> diff --git a/cfg.mk b/cfg.mk
> index e6584e8..7e17b5c 100644
> --- a/cfg.mk
> +++ b/cfg.mk
> @@ -88,6 +88,29 @@ else
>  distdir: sc_vulnerable_makefile_CVE-2012-3386.z
>  endif
> 
> +# We intentionally don't require the doc toolchain during 'make' during
> +# development, but 'make dist' must ship pre-built docs, and 'make install'
> +# from a git build fails if docs weren't built, both with awkward error
> +# messages if we let the build run that far.  Therefore, bail loud and
> +# early if we detect a git tree but no doc toolchain.
> +ifeq ($(MAKELEVEL),0)
> +  _is-dist-target ?= $(filter-out %clean, \
> +    $(filter maintainer-% dist% alpha beta stable,$(MAKECMDGOALS)))
> +  _is-install-target ?= $(filter-out %check, $(filter install%,$(MAKECMDGOALS)))
> +  ifneq (,$(_is-dist-target)$(_is-install-target))
> +    ifeq ($(shell \
> +	if test -e $(srcdir)/.git; then \
> +	  if test -x $(XMLLINT) && test -x $(XMLCATALOG) && \
> +	    $(XMLCATALOG) '$(XML_CATALOG_FILE)' \
> +	    "-//W3C//DTD XHTML 1.0 Strict//EN" >/dev/null; then \
> +	    echo works; \
> +	  else echo oops; fi;\
> +	else echo tarball; fi),oops)
> +      $(error ERROR: missing doc toolchain (install xhtml1-dtds and xmllint))
> +    endif
> +  endif
> +endif

Can't we just make our existing rules fatal. I really don't see the point
in treating docs errors as non-fatal. If the docs are not built, or are
outdated, we should try to build them and fail if the tools aren't present.
We already require libxml.so be present, so requiring the libxml/libxslt
cli  tools really isn't a burden in the great scheme of things.

IOW, we should remove all the

        @if test -x $(XMLLINT) && test -x $(XMLCATALOG) ; then \
        @if [ -x $(XSLTPROC) ] ; then \

conditionals, and just let 'make' do its normal deps calculation and
errore reporting.

As long as the docs are included in the tar.gz people building fro mthe
tar.gz will still not build the docs.

Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|




More information about the libvir-list mailing list