Re: [Xen-devel] [PATCH] docs: check for documentation generation tools in docs/configure.

[Matt Wilson <msw@xxxxxxxxxx>]

On Thu, Dec 06, 2012 at 11:06:54AM +0000, Ian Campbell wrote:
> It is sometimes hard to discover all the optional tools that should be
> on a system to build all available Xen documentation. By checking for
> documentation generation tools at ./configure time and displaying a
> warning, Xen packagers will more easily learn about new optional build
> dependencies, like markdown, when they are introduced.
> 
> Based on a patch by Matt Wilson. Changed to use a separate
> docs/configure which is called from the top-level in the same manner
> as stubdoms.
> 
> Rerun autogen.sh and "git add docs/configure" after applying this patch.
> 
> Signed-off-by: Matt Wilson <msw@xxxxxxxxxx>
> Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
> Cc: "Fioravante, Matthew E." <Matthew.Fioravante@xxxxxxxxxx>
> Cc: Roger Pau Monné <roger.pau@xxxxxxxxxx>

For the change to introduce docs/configure:

Acked-by: Matt Wilson <msw@xxxxxxxxxx>

> ---
> Applies on top of Matthew's "Add autoconf to stubdom" and "Add a top
> level configure script".
> ---
>  .gitignore            |    1 +
>  .hgignore             |    1 +
>  README                |    2 +-
>  autogen.sh            |   15 ++++++---
>  config/Docs.mk.in     |   20 +++++++++++
>  configure             |    4 +-
>  configure.ac          |    2 +-
>  docs/Docs.mk          |   12 -------
>  docs/Makefile         |   86 +++++++++++++++++++++++++++++++++---------------
>  docs/configure.ac     |   27 +++++++++++++++
>  docs/figs/Makefile    |    2 +-
>  docs/xen-api/Makefile |    7 +++-
>  m4/docs_tool.m4       |   17 ++++++++++
>  13 files changed, 146 insertions(+), 50 deletions(-)
>  create mode 100644 config/Docs.mk.in
>  delete mode 100644 docs/Docs.mk
>  create mode 100644 docs/configure.ac
>  create mode 100644 m4/docs_tool.m4
> 
> diff --git a/.gitignore b/.gitignore
> index 46ce63a..a4cdd6c 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -120,6 +120,7 @@ config.status
>  config.cache
>  config/Tools.mk
>  config/Stubdom.mk
> +config/Docs.mk
>  tools/blktap2/daemon/blktapctrl
>  tools/blktap2/drivers/img2qcow
>  tools/blktap2/drivers/lock-util
> diff --git a/.hgignore b/.hgignore
> index 0392a56..da3a7e6 100644
> --- a/.hgignore
> +++ b/.hgignore
> @@ -312,6 +312,7 @@
>  ^tools/config\.cache$
>  ^config/Tools\.mk$
>  ^config/Stubdom\.mk$
> +^config/Docs\.mk$
>  ^xen/\.banner.*$
>  ^xen/BLOG$
>  ^xen/System.map$
> diff --git a/README b/README
> index f5d5530..88401f7 100644
> --- a/README
> +++ b/README
> @@ -57,7 +57,6 @@ provided by your OS distributor:
>      * GNU gettext
>      * 16-bit x86 assembler, loader and compiler (dev86 rpm or bin86 & bcc 
> debs)
>      * ACPI ASL compiler (iasl)
> -    * markdown
>  
>  In addition to the above there are a number of optional build
>  prerequisites. Omitting these will cause the related features to be
> @@ -65,6 +64,7 @@ disabled at compile time:
>      * Development install of Ocaml (e.g. ocaml-nox and
>        ocaml-findlib). Required to build ocaml components which
>        includes the alternative ocaml xenstored.
> +    * markdown
>  
>  Second, you need to acquire a suitable kernel for use in domain 0. If
>  possible you should use a kernel provided by your OS distributor. If
> diff --git a/autogen.sh b/autogen.sh
> index 1456d94..b5c9688 100755
> --- a/autogen.sh
> +++ b/autogen.sh
> @@ -1,7 +1,12 @@
>  #!/bin/sh -e
>  autoconf
> -cd tools
> -autoconf
> -autoheader
> -cd ../stubdom
> -autoconf
> +( cd tools
> +  autoconf
> +  autoheader
> +)
> +( cd stubdom
> +  autoconf
> +)
> +( cd docs
> +  autoconf
> +)
> diff --git a/config/Docs.mk.in b/config/Docs.mk.in
> new file mode 100644
> index 0000000..b6ab6fe
> --- /dev/null
> +++ b/config/Docs.mk.in
> @@ -0,0 +1,20 @@
> +# Prefix and install folder
> +prefix              := @prefix@
> +PREFIX              := $(prefix)
> +exec_prefix         := @exec_prefix@
> +libdir              := @libdir@
> +LIBDIR              := $(libdir)
> +
> +# Tools
> +PS2PDF              := @PS2PDF@
> +DVIPS               := @DVIPS@
> +LATEX               := @LATEX@
> +FIG2DEV             := @FIG2DEV@
> +LATEX2HTML          := @LATEX2HTML@
> +DOXYGEN             := @DOXYGEN@
> +POD2MAN             := @POD2MAN@
> +POD2HTML            := @POD2HTML@
> +POD2TEXT            := @POD2TEXT@
> +DOT                 := @DOT@
> +NEATO               := @NEATO@
> +MARKDOWN            := @MARKDOWN@
> diff --git a/configure b/configure
> index 649708f..a307f3a 100755
> --- a/configure
> +++ b/configure
> @@ -606,7 +606,7 @@ enable_option_checking
>        ac_precious_vars='build_alias
>  host_alias
>  target_alias'
> -ac_subdirs_all='tools stubdom'
> +ac_subdirs_all='tools docs stubdom'
>  
>  # Initialize some variables set by options.
>  ac_init_help=
> @@ -1675,7 +1675,7 @@ ac_configure="$SHELL $ac_aux_dir/configure"  # Please 
> don't use this var.
>  
>  
>  
> -subdirs="$subdirs tools stubdom"
> +subdirs="$subdirs tools docs stubdom"
>  
>  
>  cat >confcache <<\_ACEOF
> diff --git a/configure.ac b/configure.ac
> index 0497d97..637b35b 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -6,6 +6,6 @@ AC_INIT([Xen Hypervisor], m4_esyscmd([./version.sh 
> ./xen/Makefile]),
>      [xen-devel@xxxxxxxxxxxxx], [xen], [http://www.xen.org/])
>  AC_CONFIG_SRCDIR([./xen/common/kernel.c])
>  
> -AC_CONFIG_SUBDIRS([tools stubdom])
> +AC_CONFIG_SUBDIRS([tools docs stubdom])
>  
>  AC_OUTPUT()
> diff --git a/docs/Docs.mk b/docs/Docs.mk
> deleted file mode 100644
> index aa653d3..0000000
> --- a/docs/Docs.mk
> +++ /dev/null
> @@ -1,12 +0,0 @@
> -PS2PDF               := ps2pdf
> -DVIPS                := dvips
> -LATEX                := latex
> -FIG2DEV              := fig2dev
> -LATEX2HTML   := latex2html
> -DOXYGEN              := doxygen
> -POD2MAN              := pod2man
> -POD2HTML     := pod2html
> -POD2TEXT     := pod2text
> -DOT          := dot
> -NEATO                := neato
> -MARKDOWN     := markdown
> diff --git a/docs/Makefile b/docs/Makefile
> index 03f141a..03621f7 100644
> --- a/docs/Makefile
> +++ b/docs/Makefile
> @@ -2,7 +2,7 @@
>  
>  XEN_ROOT=$(CURDIR)/..
>  include $(XEN_ROOT)/Config.mk
> -include $(XEN_ROOT)/docs/Docs.mk
> +include $(XEN_ROOT)/config/Docs.mk
>  
>  VERSION              = xen-unstable
>  
> @@ -26,10 +26,12 @@ all: build
>  
>  .PHONY: build
>  build: html txt man-pages figs
> -     @if which $(DOT) 1>/dev/null 2>/dev/null ; then              \
> -     $(MAKE) -C xen-api build ; else                              \
> -        echo "Graphviz (dot) not installed; skipping xen-api." ; fi
> +ifdef DOT
> +     $(MAKE) -C xen-api build
>       rm -f *.aux *.dvi *.bbl *.blg *.glo *.idx *.ilg *.log *.ind *.toc
> +else
> +     @echo "Graphviz (dot) not installed; skipping xen-api."
> +endif
>  
>  .PHONY: dev-docs
>  dev-docs: python-dev-docs
> @@ -39,30 +41,37 @@ html: $(DOC_HTML) html/index.html
>  
>  .PHONY: txt
>  txt:
> -     @if which $(POD2TEXT) 1>/dev/null 2>/dev/null; then \
> -     $(MAKE) $(DOC_TXT); else              \
> -     echo "pod2text not installed; skipping text outputs."; fi
> +ifdef POD2TEXT
> +     $(MAKE) $(DOC_TXT)
> +else
> +     @echo "pod2text not installed; skipping text outputs."
> +endif
>  
>  .PHONY: figs
>  figs:
> -     @set -e ; if which $(FIG2DEV) 1>/dev/null 2>/dev/null; then \
> -     set -x; $(MAKE) -C figs ; else                   \
> -     echo "fig2dev (transfig) not installed; skipping figs."; fi
> +ifdef FIG2DEV
> +     set -x; $(MAKE) -C figs
> +else
> +     @echo "fig2dev (transfig) not installed; skipping figs."
> +endif
>  
>  .PHONY: python-dev-docs
>  python-dev-docs:
> -     @mkdir -v -p api/tools/python
> -     @set -e ; if which $(DOXYGEN) 1>/dev/null 2>/dev/null; then \
> -        echo "Running doxygen to generate Python tools APIs ... "; \
> -     $(DOXYGEN) Doxyfile;                                       \
> -     $(MAKE) -C api/tools/python/latex ; else                   \
> -        echo "Doxygen not installed; skipping python-dev-docs."; fi
> +ifdef DOXYGEN
> +     @echo "Running doxygen to generate Python tools APIs ... "
> +     mkdir -v -p api/tools/python
> +     $(DOXYGEN) Doxyfile && $(MAKE) -C api/tools/python/latex
> +else
> +     @echo "Doxygen not installed; skipping python-dev-docs."
> +endif
>  
>  .PHONY: man-pages
>  man-pages:
> -     @if which $(POD2MAN) 1>/dev/null 2>/dev/null; then \
> -     $(MAKE) $(DOC_MAN1) $(DOC_MAN5); else              \
> -     echo "pod2man not installed; skipping man-pages."; fi
> +ifdef POD2MAN
> +     $(MAKE) $(DOC_MAN1) $(DOC_MAN5)
> +else
> +     @echo "pod2man not installed; skipping man-pages."
> +endif
>  
>  man1/%.1: man/%.pod.1 Makefile
>       $(INSTALL_DIR) $(@D)
> @@ -87,6 +96,7 @@ clean:
>  
>  .PHONY: distclean
>  distclean: clean
> +     rm -rf ../config/Docs.mk config.log config.status autom4te.cache
>  
>  .PHONY: install
>  install: all
> @@ -104,30 +114,40 @@ html/index.html: $(DOC_HTML) ./gen-html-index INDEX
>       perl -w -- ./gen-html-index -i INDEX html $(DOC_HTML)
>  
>  html/%.html: %.markdown
> -     @$(INSTALL_DIR) $(@D)
> -     @set -e ; if which $(MARKDOWN) 1>/dev/null 2>/dev/null; then \
> -     echo "Running markdown to generate $*.html ... "; \
> +     $(INSTALL_DIR) $(@D)
> +ifdef MARKDOWN
> +     @echo "Running markdown to generate $*.html ... "
>       $(MARKDOWN) $< > $@.tmp ; \
> -     $(call move-if-changed,$@.tmp,$@) ; else \
> -     echo "markdown not installed; skipping $*.html."; fi
> +     $(call move-if-changed,$@.tmp,$@)
> +else
> +     @echo "markdown not installed; skipping $*.html."
> +endif
>  
>  html/%.txt: %.txt
> -     @$(INSTALL_DIR) $(@D)
> +     $(INSTALL_DIR) $(@D)
>       cp $< $@
>  
>  html/man/%.1.html: man/%.pod.1 Makefile
>       $(INSTALL_DIR) $(@D)
> +ifdef POD2HTML
>       $(POD2HTML) --infile=$< --outfile=$@.tmp
>       $(call move-if-changed,$@.tmp,$@)
> +else
> +     @echo "pod2html not installed; skipping $<."
> +endif
>  
>  html/man/%.5.html: man/%.pod.5 Makefile
>       $(INSTALL_DIR) $(@D)
> +ifdef POD2HTML
>       $(POD2HTML) --infile=$< --outfile=$@.tmp
>       $(call move-if-changed,$@.tmp,$@)
> +else
> +     @echo "pod2html not installed; skipping $<."
> +endif
>  
>  html/hypercall/index.html: ./xen-headers
>       rm -rf $(@D)
> -     @$(INSTALL_DIR) $(@D)
> +     $(INSTALL_DIR) $(@D)
>       ./xen-headers -O $(@D) \
>               -T 'arch-x86_64 - Xen public headers' \
>               -X arch-ia64 -X arch-x86_32 -X xen-x86_32 -X arch-arm \
> @@ -147,11 +167,23 @@ txt/%.txt: %.markdown
>  
>  txt/man/%.1.txt: man/%.pod.1 Makefile
>       $(INSTALL_DIR) $(@D)
> +ifdef POD2TEXT
>       $(POD2TEXT) $< $@.tmp
>       $(call move-if-changed,$@.tmp,$@)
> +else
> +     @echo "pod2text not installed; skipping $<."
> +endif
>  
>  txt/man/%.5.txt: man/%.pod.5 Makefile
>       $(INSTALL_DIR) $(@D)
> +ifdef POD2TEXT
>       $(POD2TEXT) $< $@.tmp
>       $(call move-if-changed,$@.tmp,$@)
> -
> +else
> +     @echo "pod2text not installed; skipping $<."
> +endif
> +
> +ifeq (,$(findstring clean,$(MAKECMDGOALS)))
> +$(XEN_ROOT)/config/Docs.mk:
> +     $(error You have to run ./configure before building docs)
> +endif
> diff --git a/docs/configure.ac b/docs/configure.ac
> new file mode 100644
> index 0000000..45dc9b8
> --- /dev/null
> +++ b/docs/configure.ac
> @@ -0,0 +1,27 @@
> +#                                               -*- Autoconf -*-
> +# Process this file with autoconf to produce a configure script.
> +
> +AC_PREREQ([2.67])
> +AC_INIT([Xen Hypervisor Documentation], m4_esyscmd([../version.sh 
> ../xen/Makefile]),
> +    [xen-devel@xxxxxxxxxxxxx], [xen], [http://www.xen.org/])
> +AC_CONFIG_SRCDIR([misc/xen-command-line.markdown])
> +AC_CONFIG_FILES([../config/Docs.mk])
> +AC_CONFIG_AUX_DIR([../])
> +
> +# M4 Macro includes
> +m4_include([../m4/docs_tool.m4])
> +
> +AX_DOCS_TOOL_PROG([PS2PDF], [ps2pdf])
> +AX_DOCS_TOOL_PROG([DVIPS], [dvips])
> +AX_DOCS_TOOL_PROG([LATEX], [latex])
> +AX_DOCS_TOOL_PROG([FIG2DEV], [fig2dev])
> +AX_DOCS_TOOL_PROG([LATEX2HTML], [latex2html])
> +AX_DOCS_TOOL_PROG([DOXYGEN], [doxygen])
> +AX_DOCS_TOOL_PROG([POD2MAN], [pod2man])
> +AX_DOCS_TOOL_PROG([POD2HTML], [pod2html])
> +AX_DOCS_TOOL_PROG([POD2TEXT], [pod2text])
> +AX_DOCS_TOOL_PROG([DOT], [dot])
> +AX_DOCS_TOOL_PROG([NEATO], [neato])
> +AX_DOCS_TOOL_PROGS([MARKDOWN], [markdown], [markdown markdown_py])
> +
> +AC_OUTPUT()
> diff --git a/docs/figs/Makefile b/docs/figs/Makefile
> index 5ecdae3..f782dc1 100644
> --- a/docs/figs/Makefile
> +++ b/docs/figs/Makefile
> @@ -1,7 +1,7 @@
>  
>  XEN_ROOT=$(CURDIR)/../..
>  include $(XEN_ROOT)/Config.mk
> -include $(XEN_ROOT)/docs/Docs.mk
> +include $(XEN_ROOT)/config/Docs.mk
>  
>  TARGETS= network-bridge.png network-basic.png
>  
> diff --git a/docs/xen-api/Makefile b/docs/xen-api/Makefile
> index 77a0117..b2da651 100644
> --- a/docs/xen-api/Makefile
> +++ b/docs/xen-api/Makefile
> @@ -2,7 +2,7 @@
>  
>  XEN_ROOT=$(CURDIR)/../..
>  include $(XEN_ROOT)/Config.mk
> -include $(XEN_ROOT)/docs/Docs.mk
> +-include $(XEN_ROOT)/config/Docs.mk
>  
>  
>  TEX := $(wildcard *.tex)
> @@ -42,3 +42,8 @@ xenapi-datamodel-graph.eps: xenapi-datamodel-graph.dot
>  .PHONY: clean
>  clean:
>       rm -f *.pdf *.ps *.dvi *.aux *.log *.out $(EPSDOT)
> +
> +ifeq (,$(findstring clean,$(MAKECMDGOALS)))
> +$(XEN_ROOT)/config/Docs.mk:
> +     $(error You have to run ./configure before building docs)
> +endif
> diff --git a/m4/docs_tool.m4 b/m4/docs_tool.m4
> new file mode 100644
> index 0000000..3e8814a
> --- /dev/null
> +++ b/m4/docs_tool.m4
> @@ -0,0 +1,17 @@
> +AC_DEFUN([AX_DOCS_TOOL_PROG], [
> +dnl
> +    AC_ARG_VAR([$1], [Path to $2 tool])
> +    AC_PATH_PROG([$1], [$2])
> +    AS_IF([! test -x "$ac_cv_path_$1"], [
> +        AC_MSG_WARN([$2 is not available so some documentation won't be 
> built])
> +    ])
> +])
> +
> +AC_DEFUN([AX_DOCS_TOOL_PROGS], [
> +dnl
> +    AC_ARG_VAR([$1], [Path to $2 tool])
> +    AC_PATH_PROGS([$1], [$3])
> +    AS_IF([! test -x "$ac_cv_path_$1"], [
> +        AC_MSG_WARN([$2 is not available so some documentation won't be 
> built])
> +    ])
> +])
> -- 
> 1.7.2.5

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel