Merge ec0f4a5 into 36ee76d

Author: jimklimov

Makefile.am

@@ -9,23 +9,117 @@
 @NUT_AM_MAKE_CAN_EXPORT@@NUT_AM_EXPORT_CCACHE_PATH@export CCACHE_PATH=@CCACHE_PATH@
 @NUT_AM_MAKE_CAN_EXPORT@@NUT_AM_EXPORT_CCACHE_PATH@export PATH=@PATH_DURING_CONFIGURE@
 
-# First target often defines default behavior: all
-# We follow up with another pass to `make doc` because our wild recipes
-# sometimes preclude generating all of them on the first pass (FIXME!)
-# missing e.g. PDF and HTML which then pop up in `make check` footprint,
-# or misses a .prep-src-docs stage needed to pattern-make man page files
-# with some "make" implementations...
-all all-am-local all-local: all-recursive
-	+@$(MAKE) $(AM_MAKEFLAGS) doc
-	+@$(MAKE) $(AM_MAKEFLAGS) doc
-
 # include directory for aclocal
 ACLOCAL_AMFLAGS = -I m4
 
-# subdirectories to build and distribute. The order matters, as
-# several subdirectories depend on stuff in "common" or tools being built first
-SUBDIRS = include common clients conf data docs drivers tools \
-  lib scripts server tests
+# Autotools' SUBDIRS (our values are listed below) allow for powerful recursive
+# recipe automation, with one notable weakness: the dirs are processed in a
+# loop sequentially, even in parallel builds (each such sub-make is parallel
+# then). In our case, the HTML/PDF render of ChangeLog can take a minute of
+# work in "docs" while we are not building anything in other dirs. On the up
+# side, that approach does allow for dirs with dependencies to get built first
+# deterministically. For more details search for "am__recursive_targets" in the
+# generated Makefile.
+#
+# The commonly suggested way out of this predicament is to consolidate numerous
+# Makefile.am recipes into one, which alone properly defines all the needed
+# interdependecies that are "known" to one instance of the `make` process.
+# This however loses the ability to quickly e.g. `cd tests && make check`, so
+# the next layer is to re-introduce Makefiles in sub-directories that define
+# a few popular targets to perform via the one big top-level Makefile.
+#
+# Our approach here is to merge the two solutions: do use SUBDIRS the way
+# autotools handle them for the hordes of `*-recursive` targets for us, but
+# define more explicitly the targets for hot code paths (all, check) so that
+# they can run first for certain different directories (in parallel if asked
+# to) with "knowledge" of dependencies, and then a bit wastefully maybe re-run
+# those directories via autotools integration. They should be quick no-ops by
+# then in the anticipated common use-cases.
+#
+# List of source subdirectories to build and distribute, used to spawn automake
+# (alas sequential) target recipes. The order matters, as several subdirectories
+# depend on stuff in "common" or tools being built first!
+SUBDIRS = include common clients conf data drivers tools \
+  lib scripts server tests docs
+
+# Note: not generated from SUBDIRS, because not all are recursive:
+SUBDIRS_ALL_RECURSIVE = \
+	all/include \
+	all/common \
+	all/clients \
+	all/conf \
+	all-recursive/data \
+	all/docs/man \
+	all/docs \
+	all-recursive/docs \
+	all/drivers \
+	all/tools/nut-scanner \
+	all/tools/nutconf \
+	all-recursive/tools \
+	all/lib \
+	all-recursive/scripts \
+	all/server \
+	all/tests/NIT \
+	all-recursive/tests
+
+# Library creation happens in a number of subdirectories, may be optional
+# (e.g. C++ ones are not built without a suitable compiler and enablement).
+# List maintenance is aided by this query:
+#   git grep -E 'LTLIBRARIES' '*.am'
+SUBDIRS_ALL_LIBS_LOCAL = \
+	all-libs-local/clients \
+	all-libs-local/common  \
+	all-libs-local/drivers \
+	all-libs-local/tests   \
+	all-libs-local/tools/nut-scanner
+
+# First target often defines default behavior, and in automake is always at least:
+#   all: all-recursive
+# with maybe custom dependencies of "all:" from a Makefile.am tacked on too
+# (which used to cause us a lot of headache, building same things twice at
+# the same time).
+
+#all all-recursive all-am-local all-local: all-fanout-maybe
+all-recursive: all-fanout-maybe
+
+# Run the standard build if going sequential (or with unknown MAKEFLAGS),
+# or fanout if parallel (presuming GNU/BSD/Sun make at least):
+all-fanout-maybe:
+	+@if [ x"$(NUT_MAKE_SKIP_FANOUT)" = xtrue ] ; then \
+		echo "  SUBDIR-MAKE       $@: skip optimization for parallel make - NUT_MAKE_SKIP_FANOUT is set" ; exit 0 ; \
+	  fi ; \
+	  case "-$(MAKEFLAGS) $(AM_MAKEFLAGS)" in \
+		*-j|*-j" "*|*-{j,l}{0,1,2,3,4,5,6,7,8,9}*|*-[jl][0123456789]*|*{-l,--jobs,--load-average,--max-load}" "{-,0,1,2,3,4,5,6,7,8,9}*|*--jobserver*|*--jobs" "[0123456789]*|*--load-average" "[0123456789]*|*--max-load" "[0123456789]*) \
+			echo "  SUBDIR-MAKE       $@: implement optimization for parallel make as 'make all-fanout-subdirs'" ; \
+			$(MAKE) $(AM_MAKEFLAGS) all-fanout-subdirs ;; \
+		*)	echo "  SUBDIR-MAKE       $@: skip optimization for parallel make - we seem to run sequentially now, seen MAKEFLAGS='$(MAKEFLAGS)' AM_MAKEFLAGS='$(AM_MAKEFLAGS)'" ;; \
+	  esac
+
+# We start with a pass to `make all` in `common` dir because our wild recipes
+# (with other subdirs ensuring the libraries they need have been built) can
+# sometimes cause parallel compilation and library generation for same files
+# driven by different make processes that do not know they aim for same goal,
+# with some "make" implementations...
+# Just in case we followed up with "make doc", since our wild recipes could end
+# up writing into same files and so corrupting them (fixes applied, but...)
+
+# FIXME: Alas, we still tend to step on our toes when making everything at
+# once from scratch, so still do benefit from pre-making the libraries:
+all-fanout-staged:
+	+$(MAKE) $(AM_MAKEFLAGS) all/include
+	+$(MAKE) $(AM_MAKEFLAGS) all/common
+	+$(MAKE) $(AM_MAKEFLAGS) all-fanout-libs
+	+$(MAKE) $(AM_MAKEFLAGS) all-fanout-subdirs
+
+all-fanout-subdirs: $(SUBDIRS_ALL_RECURSIVE)
+
+all-fanout-libs all-libs-local: $(SUBDIRS_ALL_LIBS_LOCAL)
+
+#all all-am-local all-local:
+#	+@cd common && $(MAKE) $(AM_MAKEFLAGS) all
+#	+@$(MAKE) $(AM_MAKEFLAGS) all-recursive
+#	+@$(MAKE) $(AM_MAKEFLAGS) doc
+#	+@$(MAKE) $(AM_MAKEFLAGS) doc
 
 bindir = @bindir@
 sbindir = @sbindir@
@@ -58,6 +152,122 @@ if KEEP_NUT_REPORT
 nodist_data_DATA = config.nut_report_feature.log
 endif
 
+# Not too different from automake generated recursive rules at first sight,
+# but here we do not loop all subdirs sequentially - instead, a sub-make
+# (maybe parallel itself and with parallel flags passed) with a certain
+# target in specified dir is the goal, all as separate targets for this
+# level's Makefile:
+SUBDIR_TGT_RULE = ( \
+	TGT="`echo '$@' | awk -F/ '{print $$1}'`" ; \
+	DIR="`echo '$@' | sed 's,^[^/]*/,,'`" ; \
+	echo "  SUBDIR-MAKE       STARTING: 'make $$TGT' in $$DIR ..." ; \
+	cd "$(abs_builddir)/$${DIR}" && \
+	$(MAKE) $(AM_MAKEFLAGS) "$${TGT}" || { RES=$$?; echo "  SUBDIR-MAKE       FAILURE: 'make $$TGT' in $$DIR" >&2 ; exit $$RES ; } ; \
+	echo "  SUBDIR-MAKE       SUCCESS: 'make $$TGT' in $$DIR" ; \
+	)
+
+# A way to quickly handle SUBDIRS_ALL_LIBS_LOCAL as dependency for all others
+# (aka `make all-libs-local` also in root dir):
+all-libs-local/common: all/include
+	+@$(SUBDIR_TGT_RULE)
+
+all-libs-local/clients: all-libs-local/common
+	+@$(SUBDIR_TGT_RULE)
+
+all-libs-local/drivers: all-libs-local/common
+	+@$(SUBDIR_TGT_RULE)
+
+all-libs-local/tests: all-libs-local/common
+	+@$(SUBDIR_TGT_RULE)
+
+all-libs-local/tools/nut-scanner: all-libs-local/drivers all-libs-local/clients
+	+@$(SUBDIR_TGT_RULE)
+
+# Handle all SUBDIRS_ALL_RECURSIVE in a way that dependencies can be specified,
+# and portably to different make program implementations. Note we may revisit
+# some dirs via "all-recursive" of a parent after "all" in them first, but it is
+# expected to be a quick no-op (beneficial overall in parallel make situation).
+# NOTE: "lib" dir only delivers pkg-config metadata or legacy scripts for any
+# third-party development to integrate with NUT libs, no library recipes there.
+
+all/include \
+all/conf \
+all/docs/man \
+all/lib \
+all-recursive/data:
+	+@$(SUBDIR_TGT_RULE)
+
+all/docs:
+	+@DOCS_NO_MAN=true; export DOCS_NO_MAN; $(SUBDIR_TGT_RULE)
+
+all-recursive/docs: all/docs all/docs/man
+	+@$(SUBDIR_TGT_RULE)
+
+# Dependencies below are dictated by who needs whose library from another dir
+# (generated by a sub-make there, so we pre-emptively ensure it exists to avoid
+# conflicts of several make's writing to same files). Aided by this query:
+#   git grep -E '/[^ ]*\.la([ :]|$)' '*.am'
+# It does help to spell out all dependencies, even if transitive, to ensure
+# that the top-level make completes needed (all-libs*) targets before drilling.
+all/common: all/include all-libs-local/common
+	+@$(SUBDIR_TGT_RULE)
+
+all/clients: all/common all-libs-local/clients
+	+@$(SUBDIR_TGT_RULE)
+
+# only libupsclient is needed for dummy-ups,
+# but we do wholesale subdir all-libs-local at the moment...
+if SOME_DRIVERS
+all/drivers: all-libs-local/clients all-libs-local/common
+	+@$(SUBDIR_TGT_RULE)
+else !SOME_DRIVERS
+dummy-ups/drivers: all-libs-local/clients all-libs-local/common
+	+@$(SUBDIR_TGT_RULE)
+
+all/drivers: dummy-ups/drivers all/common all-libs-local/drivers
+	+@$(SUBDIR_TGT_RULE)
+endif !SOME_DRIVERS
+
+all/server: all-libs-local/common
+	+@$(SUBDIR_TGT_RULE)
+
+all/tools/nut-scanner: all-libs-local/tools/nut-scanner all-libs-local/drivers all-libs-local/common
+	+@$(SUBDIR_TGT_RULE)
+
+# only libnutscan is needed for nutconf,
+# but we do wholesale subdir all-libs-local at the moment...
+all/tools/nutconf: all-libs-local/tools/nut-scanner all-libs-local/common
+	+@$(SUBDIR_TGT_RULE)
+
+all-recursive/tools: all/tools/nutconf all/tools/nut-scanner
+	+@$(SUBDIR_TGT_RULE)
+
+# At least prereqs for NIT, maybe for certain compiled tests too:
+all/tests/NIT: all/clients all/server all/drivers all-recursive/tools all-recursive/data
+	+@$(SUBDIR_TGT_RULE)
+
+all/tests: all-libs-local/tests all-libs-local/drivers all-libs-local/common all-libs-local/clients
+	+@$(SUBDIR_TGT_RULE)
+
+all-recursive/tests: all/tests/NIT all/tests
+	+@$(SUBDIR_TGT_RULE)
+
+if HAVE_MINGW_RESGEN
+if HAVE_WINDOWS
+all/scripts/Windows: all-libs-local/common
+	+@$(SUBDIR_TGT_RULE)
+else !HAVE_WINDOWS
+all/scripts/Windows:
+	+@$(SUBDIR_TGT_RULE)
+endif !HAVE_WINDOWS
+else !HAVE_MINGW_RESGEN
+all/scripts/Windows:
+	+@$(SUBDIR_TGT_RULE)
+endif !HAVE_MINGW_RESGEN
+
+all-recursive/scripts: all/scripts/Windows
+	+@$(SUBDIR_TGT_RULE)
+
 # ----------------------------------------------------------------------
 # flags to pass to ./configure when calling "make distcheck" and "make
 # distcheck-light". Try to check as many features as possible! Also

clients/Makefile.am

@@ -180,3 +180,6 @@ MAINTAINERCLEANFILES = Makefile.in .dirstamp
 # the root Makefile.am takes care of that!
 #clean-local:
 #	$(AM_V_at)rm -rf $(builddir)/.deps
+
+# Helper for only the enabled libs to get built:
+all-libs-local: $(lib_LTLIBRARIES) $(noinst_LTLIBRARIES) $(EXTRA_LTLIBRARIES)

common/Makefile.am

@@ -164,3 +164,6 @@ MAINTAINERCLEANFILES = Makefile.in .dirstamp
 # the root Makefile.am takes care of that!
 #clean-local:
 #	$(AM_V_at)rm -rf $(builddir)/.deps
+
+# Helper for only the enabled libs to get built:
+all-libs-local: $(lib_LTLIBRARIES) $(noinst_LTLIBRARIES) $(EXTRA_LTLIBRARIES)

docs/.gitignore

@@ -26,3 +26,6 @@ nut.dict.sorted
 docinfo.xml.in.tmp
 /asciidoc-vars.conf.lastrev.tmp
 .prep-src-docs*
+/.check-pdf
+/.check-html-single
+/.check-html-chunked

docs/Makefile.am

@@ -215,13 +215,15 @@ pdf_DATA = $(ASCIIDOC_PDFS)
 endif
 
 # the "for" loops might better use $^ but it might be not portable
-check-pdf: $(ASCIIDOC_PDF)
+check-pdf: .check-pdf
+.check-pdf: $(ASCIIDOC_PDF) Makefile
 	@FAILED=""; LANG=C; LC_ALL=C; export LANG; export LC_ALL; \
 	for F in $(ASCIIDOC_PDF) ; do \
 	    test -s "$$F" && { file "$$F" | $(EGREP) -i 'PDF document' > /dev/null ; } || FAILED="$$FAILED $$F" ; \
 	done; if test -n "$$FAILED" ; then \
 	    echo "FAILED PDF sanity check for:$$FAILED" >&2 ; file $$FAILED >&2 ; exit 1; \
 	fi; echo "PASSED PDF sanity check"; exit 0
+	@touch $@
 
 # Regarding ChangeLog check: sometimes asciidoc gives up early
 # (we have megabytes of text and thousands of sections here).
@@ -244,7 +246,8 @@ check-pdf: $(ASCIIDOC_PDF)
 # (either with different e-mails, or if different author's work
 # is interleaved during the day, e.g. many PRs merged, and no
 # CHANGELOG_REQUIRE_GROUP_BY_DATE_AUTHOR=true setting was in place.
-# NOTE: No dependencies, avoids (re-)generation and log messages.
+# NOTE: No dependencies, avoids (re-)generation and log messages
+# but causes re-run of the check every time.
 ChangeLog.html-contentchecked:
 	@FAILED=""; \
 	 if [ -s '$(top_builddir)/ChangeLog' ] && [ -s ChangeLog.html ] ; then \
@@ -309,7 +312,8 @@ ChangeLog.html-contentchecked:
 	 fi ; \
 	 exit 1
 
-check-html-single: $(ASCIIDOC_HTML_SINGLE)
+check-html-single: .check-html-single
+.check-html-single: $(ASCIIDOC_HTML_SINGLE) Makefile
 	+@FAILED=""; LANG=C; LC_ALL=C; export LANG; export LC_ALL; \
 	 for F in $(ASCIIDOC_HTML_SINGLE) ; do \
 	    test -s "$$F" && { file "$$F" | $(EGREP) -i '(XML|HTML.*document)' > /dev/null ; } || FAILED="$$FAILED $$F" ; \
@@ -321,8 +325,10 @@ check-html-single: $(ASCIIDOC_HTML_SINGLE)
 	 done; if test -n "$$FAILED" ; then \
 	    echo "FAILED HTML-single sanity check for:$$FAILED" >&2 ; file $$FAILED >&2 ; exit 1; \
 	 fi; echo "PASSED HTML-single sanity check"; exit 0
+	@touch $@
 
-check-html-chunked: $(ASCIIDOC_HTML_CHUNKED)
+check-html-chunked: .check-html-chunked
+.check-html-chunked: $(ASCIIDOC_HTML_CHUNKED) Makefile
 	@FAILED=""; LANG=C; LC_ALL=C; export LANG; export LC_ALL; \
 	for D in $(ASCIIDOC_HTML_CHUNKED); do \
 	    for F in "$$D"/*.html ; do \
@@ -334,19 +340,25 @@ check-html-chunked: $(ASCIIDOC_HTML_CHUNKED)
 	done; if test -n "$$FAILED" ; then \
 	    echo "FAILED HTML-chunked sanity check for:$$FAILED" >&2 ; file $$FAILED >&2 ; exit 1; \
 	fi; echo "PASSED HTML-chunked sanity check"; exit 0
+	@touch $@
 
 # Note: usually the results from man-page check will be reported twice:
 # once as a SUBDIRS child makefile, and once via DOC_CHECK_LIST expansion
 # Note: default `make all` in the man directory caters to drivers etc.
 # chosen during configure script execution. The "all-man" and "all-html"
 # rules build everything documented.
+# NOTE; we rig it up with a DOCS_NO_MAN option to simplify parallel work
+# from top-level Makefile, while allowing legacy "cd docs && make" to
+# still do the right thing by default :)
 check-man check-man-man all-man man-man all-html html-man:
-	+cd $(abs_top_builddir)/docs/man/ && $(MAKE) $(AM_MAKEFLAGS) -f Makefile $@
+	+@if [ x"$(DOCS_NO_MAN)" = xtrue ] ; then echo "  DOC-NOT-MAN     SKIP: $@ called in docs/Makefile" ; exit 0 ; fi ; \
+	  cd $(abs_top_builddir)/docs/man/ && $(MAKE) $(AM_MAKEFLAGS) -f Makefile $@
 
 man:
-	+cd $(abs_top_builddir)/docs/man/ && $(MAKE) $(AM_MAKEFLAGS) -f Makefile all
+	+@if [ x"$(DOCS_NO_MAN)" = xtrue ] ; then echo "  DOC-NOT-MAN     SKIP: $@ called in docs/Makefile" ; exit 0 ; fi ; \
+	  cd $(abs_top_builddir)/docs/man/ && $(MAKE) $(AM_MAKEFLAGS) -f Makefile all
 
-CLEANFILES = *.xml *.html *.pdf *-spellchecked *-contentchecked docbook-xsl.css docinfo.xml.in.tmp
+CLEANFILES = *.xml *.html *.pdf *-spellchecked *-contentchecked .check-* docbook-xsl.css docinfo.xml.in.tmp
 CLEANFILES += $(top_builddir)/INSTALL.nut $(top_builddir)/UPGRADING $(top_builddir)/NEWS $(top_builddir)/ChangeLog.adoc $(top_builddir)/README
 CLEANFILES += $(top_builddir)/*.adoc-parsed *.adoc-parsed
 

docs/man/.gitignore

@@ -11,3 +11,6 @@
 /tmp/
 /linkman-driver-names.txt
 /linkman-drivertool-names.txt
+/.check-html-man
+/.check-man-pages
+/.check-man-txt