Fix: standardize man pages building/installing

This patch makes the build system act as follows:

    if --enable-man-pages:
        if in Git repo:
            require asciidoc/xmlto (configure)
            build man pages (make, make clean)
            install man pages (make install)
            distribute man pages (make dist)
        else:
            if asciidoc/xmlto both exist:
                build man pages (make, make clean)
                install man pages (make install)
                distribute man pages (make dist)
            else:
                warn that asciidoc/xmlto are missing (configure)
                create "error" man page targets in Makefile (make)
                do not clean man pages (make clean not available)
                install distributed man pages (make install)
                distribute distributed man pages (make dist)
    else if --disable-man-pages:
        do not build man pages (make, make clean not available)
        do not install man pages (make install not available)
        do not distribute man pages (make dist not available)

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/configure.ac b/configure.ac
index 47b794f9bc493b5de8207b1a8991d6bc69e75e6d..cfbbe6bba63ca68aaab9f535b2f99a89ee1a32cf 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -494,30 +494,57 @@ fi
 AS_IF([test -f "$srcdir/bootstrap"], [in_git_repo=yes], [in_git_repo=no])
 AM_CONDITIONAL([IN_GIT_REPO], [test "x$in_git_repo" = "xyes"])
 
 AS_IF([test -f "$srcdir/bootstrap"], [in_git_repo=yes], [in_git_repo=no])
 AM_CONDITIONAL([IN_GIT_REPO], [test "x$in_git_repo" = "xyes"])
 

-# enable building man pages
+# enable building man pages (user's intention)

 AC_ARG_ENABLE(
 AC_ARG_ENABLE(

-       build-man-pages,
+       man-pages,

        AS_HELP_STRING(
        AS_HELP_STRING(

-               [--disable-build-man-pages],
-               [Build man pages (already built in a distributed tarball)]
+               [--disable-man-pages],
+               [Build and install man pages (already built in a distributed tarball)]

        ),
        ),

-       [build_man_pages=$enableval],
-       [build_man_pages=yes]
+       [man_pages_opt=$enableval],
+       [man_pages_opt=yes]

 )
 
 )
 

-# export man page build condition
-AM_CONDITIONAL([BUILD_MAN_PAGES], [test "x$build_man_pages" != "xno"])
-

 # check for asciidoc and xmlto if we enabled building the man pages
 # check for asciidoc and xmlto if we enabled building the man pages

-AS_IF([test "x$build_man_pages" = "xyes"], [
+have_asciidoc_xmlto=no
+
+AS_IF([test "x$man_pages_opt" = "xyes"], [

        AC_PATH_PROG([ASCIIDOC], [asciidoc], [no])
        AC_PATH_PROG([XMLTO], [xmlto], [no])
 
        AS_IF([test "x$ASCIIDOC" = "xno" || test "x$XMLTO" = "xno"], [
        AC_PATH_PROG([ASCIIDOC], [asciidoc], [no])
        AC_PATH_PROG([XMLTO], [xmlto], [no])
 
        AS_IF([test "x$ASCIIDOC" = "xno" || test "x$XMLTO" = "xno"], [

-               AC_MSG_ERROR([Both asciidoc and xmlto are needed to build the LTTng man pages.])
+               AS_IF([test "x$in_git_repo" = "xyes"], [
+                       # this is an error because we're in the Git repo, which
+                       # means the man pages are not already generated for us,
+                       # thus asciidoc/xmlto are required because we were asked
+                       # to build the man pages
+                       AC_MSG_ERROR([
+Both asciidoc and xmlto are needed to build the LTTng man pages. Use
+--disable-man-pages to disable building the man pages, in which case
+they will not be installed.
+                       ])
+               ], [
+                       # only warn here: since we're in the tarball, the man
+                       # pages should already be generated at this point, thus
+                       # asciidoc/xmlto are not strictly required
+                       AC_MSG_WARN([
+Both asciidoc and xmlto are needed to build the LTTng man pages. Note
+that the man pages are already built in this distribution tarball, so
+asciidoc and xmlto are only needed if you intend to modify their
+sources. Use --disable-man-pages to completely disable building
+and installing the man pages.
+                       ])
+               ])
+       ], [
+               have_asciidoc_xmlto=yes

        ])
 ])
 
        ])
 ])
 

+# export man page build condition: build the man pages if the user
+# asked for it, and if the tools are available
+AM_CONDITIONAL([MAN_PAGES_OPT], [test "x$man_pages_opt" != "xno"])
+AM_CONDITIONAL([HAVE_ASCIIDOC_XMLTO], [test "x$have_asciidoc_xmlto" = "xyes"])
+

 # Python agent test
 UST_PYTHON_AGENT="lttngust"
 
 # Python agent test
 UST_PYTHON_AGENT="lttngust"
 


@@ -987,25 +1014,29 @@ test "x${enable_python_binding:-yes}" = xyes && value=1 || value=0
 AS_ECHO
 PPRINT_SET_INDENT(0)
 PPRINT_PROP_BOOL([Python binding], $value, $PPRINT_COLOR_SUBTITLE)
 AS_ECHO
 PPRINT_SET_INDENT(0)
 PPRINT_PROP_BOOL([Python binding], $value, $PPRINT_COLOR_SUBTITLE)

-PPRINT_SET_INDENT(1)
-
-AS_ECHO
-PPRINT_SUBTITLE([Man pages])

 
 # man pages build enabled/disabled
 
 # man pages build enabled/disabled

-AS_IF([test "x$build_man_pages" = "xyes"], [
-       PPRINT_PROP_BOOL([Build man pages], 1)
-], [
+m4_pushdef([build_man_pages_msg], [Build and install man pages])
+
+AS_IF([test "x$man_pages_opt" != "xno"], [

        AS_IF([test "x$in_git_repo" = "xyes"], [
        AS_IF([test "x$in_git_repo" = "xyes"], [

-               PPRINT_PROP_BOOL([Build man pages], 0)
+               PPRINT_PROP_BOOL([build_man_pages_msg], 1, $PPRINT_COLOR_SUBTITLE)

        ], [
        ], [

-               PPRINT_PROP_STRING([Build man pages], [${PPRINT_COLOR_BLDGRN}Already built])
+               AS_IF([test "x$have_asciidoc_xmlto" = "xyes"], [
+                       PPRINT_PROP_BOOL([build_man_pages_msg], 1, $PPRINT_COLOR_SUBTITLE)
+               ], [
+                       PPRINT_PROP_STRING([build_man_pages_msg],
+                               [${PPRINT_COLOR_BLDGRN}yes (already built)],
+                               $PPRINT_COLOR_SUBTITLE)
+               ])

        ])
        ])

+], [
+       PPRINT_PROP_BOOL([build_man_pages_msg], 0, $PPRINT_COLOR_SUBTITLE)

 ])
 
 ])
 

-# man pages install enabled/disabled (always true in tarball)
-test "x$build_man_pages" != "xyes" && test "x$in_git_repo" = "xyes" && value=0 || value=1
-PPRINT_PROP_BOOL([Install man pages], $value)
+m4_popdef([build_man_pages_msg])
+
+PPRINT_SET_INDENT(1)

 
 report_bindir="`eval eval echo $bindir`"
 report_libdir="`eval eval echo $libdir`"
 
 report_bindir="`eval eval echo $bindir`"
 report_libdir="`eval eval echo $libdir`"

diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index ac5b21f73e7a8b8b46237ce69f60d9ffabe08635..d8882028a594bcc15b2f650b0184e50401774ca0 100644 (file)
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -1,5 +1,5 @@
-# Man pages are only built if the --enable-build-man-pages option was passed
-# to the configure script.
+# Man pages are only built if the --enable-man-pages option was
+# passed to the configure script.

 #
 # They should always be built before creating a distribution tarball.
 
 #
 # They should always be built before creating a distribution tarball.
 


@@ -38,27 +38,6 @@ MAN1_NO_ASCIIDOC_NAMES =
 MAN3_NO_ASCIIDOC_NAMES = lttng-health-check
 MAN8_NO_ASCIIDOC_NAMES =
 
 MAN3_NO_ASCIIDOC_NAMES = lttng-health-check
 MAN8_NO_ASCIIDOC_NAMES =
 

-# man pages destinations
-MAN1 = $(addsuffix .1,$(MAN1_NAMES))
-MAN3 = $(addsuffix .3,$(MAN3_NAMES))
-MAN8 = $(addsuffix .8,$(MAN8_NAMES))
-MAN1_NO_ASCIIDOC = $(addsuffix .1,$(MAN1_NO_ASCIIDOC_NAMES))
-MAN3_NO_ASCIIDOC = $(addsuffix .3,$(MAN3_NO_ASCIIDOC_NAMES))
-MAN8_NO_ASCIIDOC = $(addsuffix .8,$(MAN8_NO_ASCIIDOC_NAMES))
-MAN = $(MAN1) $(MAN3) $(MAN8)
-
-# those are always installed since they are written in troff
-dist_man1_MANS = $(MAN1_NO_ASCIIDOC)
-dist_man3_MANS = $(MAN3_NO_ASCIIDOC)
-dist_man8_MANS = $(MAN8_NO_ASCIIDOC)
-
-# only build man pages if it was enabled
-if BUILD_MAN_PAGES
-# dist + install
-dist_man1_MANS += $(MAN1)
-dist_man3_MANS += $(MAN3)
-dist_man8_MANS += $(MAN8)
-

 # AsciiDoc sources and outputs
 MAN1_TXT = $(call manaddsuffix,.1.txt,$(MAN1_NAMES))
 MAN3_TXT = $(call manaddsuffix,.3.txt,$(MAN3_NAMES))
 # AsciiDoc sources and outputs
 MAN1_TXT = $(call manaddsuffix,.1.txt,$(MAN1_NAMES))
 MAN3_TXT = $(call manaddsuffix,.3.txt,$(MAN3_NAMES))


@@ -85,9 +64,21 @@ XSL_SRC_FILES = $(addprefix $(srcdir)/xsl/,$(XSL_FILES))
 # common dependencies
 COMMON_DEPS = $(ASCIIDOC_CONF) $(COMMON_TXT)
 
 # common dependencies
 COMMON_DEPS = $(ASCIIDOC_CONF) $(COMMON_TXT)
 

+# man pages destinations
+MAN1 = $(addsuffix .1,$(MAN1_NAMES))
+MAN3 = $(addsuffix .3,$(MAN3_NAMES))
+MAN8 = $(addsuffix .8,$(MAN8_NAMES))
+MAN1_NO_ASCIIDOC = $(addsuffix .1,$(MAN1_NO_ASCIIDOC_NAMES))
+MAN3_NO_ASCIIDOC = $(addsuffix .3,$(MAN3_NO_ASCIIDOC_NAMES))
+MAN8_NO_ASCIIDOC = $(addsuffix .8,$(MAN8_NO_ASCIIDOC_NAMES))
+MAN = $(MAN1) $(MAN3) $(MAN8)
+
+if MAN_PAGES_OPT
+# at this point, we know the user asked to build the man pages
+if HAVE_ASCIIDOC_XMLTO

 # tools
 ADOC = $(ASCIIDOC) -f $(ASCIIDOC_CONF) -d manpage \
 # tools
 ADOC = $(ASCIIDOC) -f $(ASCIIDOC_CONF) -d manpage \

-       -a lttng_version=$(PACKAGE_VERSION)
+       -a lttng_version="$(PACKAGE_VERSION)"

 ADOC_DOCBOOK = $(ADOC) -b docbook
 XTO = $(XMLTO) -m $(firstword $(XSL_SRC_FILES)) man
 
 ADOC_DOCBOOK = $(ADOC) -b docbook
 XTO = $(XMLTO) -m $(firstword $(XSL_SRC_FILES)) man
 


@@ -110,21 +101,39 @@ XTO = $(XMLTO) -m $(firstword $(XSL_SRC_FILES)) man
 %.8: %.8.xml $(XSL_SRC_FILES)
        $(XTO) $<
 
 %.8: %.8.xml $(XSL_SRC_FILES)
        $(XTO) $<
 

-clean-local:
-       rm -rf $(MAN_XML)
-       rm -rf $(MAN)
-else
-if IN_GIT_REPO
-# we are in the Git repo: the man pages should be built for distribution
-dist-hook:
-       @echo
-       @echo 'Error: Please build the man pages before creating a tarball.'
-       @echo
+# only clean the generated files if we have the tools to generate them again
+CLEANFILES = $(MAN_XML) $(MAN)
+else # HAVE_ASCIIDOC_XMLTO
+# create man page targets used to stop the build if we want to
+# build the man pages, but we don't have the necessary tools to do so
+ERR_MSG = "Error: Cannot build target because asciidoc or xmlto tool is missing."
+ERR_MSG += "Make sure both tools are installed and run the configure script again."
+
+%.1: $(srcdir)/%.1.txt $(COMMON_DEPS)
+       @echo $(ERR_MSG)
+       @false
+
+%.3: $(srcdir)/%.3.txt $(COMMON_DEPS)
+       @echo $(ERR_MSG)
+       @false
+
+%.8: $(srcdir)/%.8.txt $(COMMON_DEPS)
+       @echo $(ERR_MSG)

        @false
        @false

-else
-# we are in the tarball, hence the man pages are already built
+endif # HAVE_ASCIIDOC_XMLTO
+endif # MAN_PAGES_OPT
+
+# those are always installed since they are directly written in troff
+dist_man1_MANS = $(MAN1_NO_ASCIIDOC)
+dist_man3_MANS = $(MAN3_NO_ASCIIDOC)
+dist_man8_MANS = $(MAN8_NO_ASCIIDOC)
+
+if MAN_PAGES_OPT
+# building man pages: we can install and distribute them

 dist_man1_MANS += $(MAN1)
 dist_man3_MANS += $(MAN3)
 dist_man8_MANS += $(MAN8)
 dist_man1_MANS += $(MAN1)
 dist_man3_MANS += $(MAN3)
 dist_man8_MANS += $(MAN8)

-endif # IN_GIT_REPO
-endif # BUILD_MAN_PAGES
+endif # MAN_PAGES_OPT
+
+# always distribute the source files
+EXTRA_DIST = $(MAN_TXT) $(COMMON_TXT) $(XSL_SRC_FILES) $(ASCIIDOC_CONF)