Merge pull request #1345 from jimklimov/doc-netbsd

Doc for netbsd builds, more clang 13 support, more manpage related recipes

Author: jimklimov

Makefile.am

@@ -108,7 +108,14 @@ spellcheck spellcheck-interactive:
 	(cd $(builddir)/data && $(MAKE) -s $@) || RES=$$? ; \
 	exit $$RES
 
-doc spellcheck-sortdict:
+# Note: the "all-docs" and "check-docs" targets may require tools not
+# found by `configure` script (and so avoided by conventional recipes)
+# such as PDF generators, so it should only be called at developer's
+# discretion, choice and risk. The "check-man" targets covers source
+# texts, man pages and HTML rendering of man pages, as enabled by tools.
+doc spellcheck-sortdict \
+all-docs check-docs \
+man all-man man-man check-man man-html all-html:
 	cd $(srcdir)/docs && $(MAKE) $@
 
 # This target adds syntax-checking for committed shell script files,

autogen.sh

@@ -15,7 +15,14 @@ if [ -n "${PYTHON-}" ] ; then
 	}
 else
 	PYTHON=""
-	for P in python python3 python2 ; do
+	for P in python python3 python2 \
+		python-3.10 python3.10 \
+		python-3.9 python3.9 \
+		python-3.7 python3.7 \
+		python-3.5 python3.5 \
+		python-3.4 python3.4 \
+		python-2.7 python2.7 \
+	; do
 		if (command -v "$P" >/dev/null) && $P -c "import re,glob,codecs" ; then
 			PYTHON="$P"
 			break
@@ -45,6 +52,7 @@ then
 			touch scripts/augeas/nutupsconf.aug.in scripts/augeas/nutupsconf.aug.in.AUTOGEN_WITHOUT
 		else
 			echo "Aborting $0! To avoid this, please   export WITHOUT_NUT_AUGEAS=true   and re-run" >&2
+			echo "or better yet,    export PYTHON=python-x.y   and re-run" >&2
 			exit 1
 		fi
 	fi

ci_build.sh

@@ -18,6 +18,29 @@ set -e
 #   CI_REQUIRE_GOOD_GITIGNORE="false" CI_FAILFAST=true DO_CLEAN_CHECK=no BUILD_TYPE=fightwarn ./ci_build.sh
 case "$BUILD_TYPE" in
     fightwarn) ;; # for default compiler
+    fightwarn-all)
+        # This recipe allows to test with different (default-named)
+        # compiler suites if available. Primary goal is to see whether
+        # everything is building ok on a given platform, with one shot.
+        TRIED_BUILD=false
+        if (command -v gcc) >/dev/null ; then
+            TRIED_BUILD=true
+            BUILD_TYPE=fightwarn-gcc "$0" || exit
+        else
+            echo "SKIPPING BUILD_TYPE=fightwarn-gcc: compiler not found" >&2
+        fi
+        if (command -v clang) >/dev/null ; then
+            TRIED_BUILD=true
+            BUILD_TYPE=fightwarn-clang "$0" || exit
+        else
+            echo "SKIPPING BUILD_TYPE=fightwarn-clang: compiler not found" >&2
+        fi
+        if ! $TRIED_BUILD ; then
+            echo "FAILED to run: no default-named compilers were found" >&2
+            exit 1
+        fi
+        exit 0
+        ;;
     fightwarn-gcc)
         CC="gcc"
         CXX="g++"
@@ -1401,6 +1424,8 @@ default|default-alldrv|default-alldrv:no-distcheck|default-all-errors|default-sp
             if [ "$RES_ALLERRORS" != 0 ]; then
                 # Leading space is included in FAILED
                 echo "FAILED build(s) with code ${RES_ALLERRORS}:${FAILED}" >&2
+            else
+                echo "(and no build scenarios had failed)" >&2
             fi
 
             echo "Initially estimated ${BUILDSTODO_INITIAL} variations for BUILD_TYPE='$BUILD_TYPE'" >&2

common/parseconf.c

@@ -89,6 +89,7 @@
 
 #include "parseconf.h"
 #include "attribute.h"
+#include "nut_stdint.h"
 
 /* possible states */
 
@@ -241,7 +242,7 @@ static int findwordstart(PCONF_CTX_t *ctx)
 		return STATE_FINDEOL;
 
 	/* space = not in a word yet, so loop back */
-	if (isspace(ctx->ch))
+	if (isspace((size_t)ctx->ch))
 		return STATE_FINDWORDSTART;
 
 	/* \ = literal = accept the next char blindly */
@@ -341,7 +342,7 @@ static int collect(PCONF_CTX_t *ctx)
 	}
 
 	/* space means the word is done */
-	if (isspace(ctx->ch)) {
+	if (isspace((size_t)ctx->ch)) {
 		endofword(ctx);
 
 		return STATE_FINDWORDSTART;

common/str.c

@@ -118,7 +118,7 @@ char	*str_ltrim_space(char *string)
 
 	while (
 		*string != '\0' &&
-		isspace(*string)
+		isspace((size_t)*string)
 	)
 		memmove(string, string + 1, strlen(string));
 
@@ -139,7 +139,7 @@ char	*str_rtrim_space(char *string)
 
 	while (
 		ptr >= string &&
-		isspace(*ptr)
+		isspace((size_t)*ptr)
 	)
 		*ptr-- = '\0';
 
@@ -438,7 +438,7 @@ int	str_to_long_strict(const char *string, long *number, const int base)
 	if (
 		string == NULL ||
 		*string == '\0' ||
-		isspace(*string)
+		isspace((size_t)*string)
 	) {
 		errno = EINVAL;
 		return 0;
@@ -504,7 +504,7 @@ int	str_to_ulong_strict(const char *string, unsigned long *number, const int bas
 		*string == '\0' ||
 		*string == '+' ||
 		*string == '-' ||
-		isspace(*string)
+		isspace((size_t)*string)
 	) {
 		errno = EINVAL;
 		return 0;
@@ -568,7 +568,7 @@ int	str_to_double_strict(const char *string, double *number, const int base)
 	if (
 		string == NULL ||
 		*string == '\0' ||
-		isspace(*string)
+		isspace((size_t)*string)
 	) {
 		errno = EINVAL;
 		return 0;

docs/Makefile.am

@@ -87,7 +87,7 @@ doc: @DOC_BUILD_LIST@
 
 # This target can be called by developers to go around the configure
 # script choices at their risk (e.g. missing tools are possible):
-docs: pdf html-single html-chunked man
+docs: pdf html-single html-chunked man-man html-man
 
 all-docs: docs
 
@@ -130,7 +130,10 @@ check-html-chunked: $(ASCIIDOC_HTML_CHUNKED)
 
 # 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
-check-man:
+# 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.
+check-man all-man man-man all-html html-man:
 	cd $(top_builddir)/docs/man/ && $(MAKE) -f Makefile $@
 
 man:

docs/config-prereqs.txt

@@ -412,9 +412,6 @@ networked repository (4.2.x vs 4.9.x)
 :; pkg_add \
     gd
 
-# Need to find proper package name and/or mirror for this:
-:; pkg_add clang
-
 :; pkg_add \
     cppunit \
     openssl nss \
@@ -470,6 +467,124 @@ scripts), better use this routine to test the config/build:
 Note the lack of `pkg-config` also precludes libcppunit tests, although they
 also tend to mis-compile/mis-link with GCC (while CLANG seems okay).
 
+NetBSD 9.2
+~~~~~~~~~~
+
+Instructions below assume that `pkgin` tool (pkg-src component to
+"install binary packages") is present on the system. Text below
+was prepared with a VM where "everything" was installed from the
+ISO image, including compilers and X11. It is possible that some
+packages provided this way differ from those served by `pkgin`,
+or on the contrary, that the list of suggested tool installation
+below would not include something a bare-minimum system would
+require to build NUT.
+
+Note that `PATH` for builds on NetBSD should include `local` and
+`pkg`; the default after installation of the test system was:
+
+----
+:; PATH="/sbin:/usr/sbin:/bin:/usr/bin:/usr/pkg/sbin:/usr/pkg/bin:/usr/X11R7/bin:/usr/local/sbin:/usr/local/bin"
+:; export PATH
+----
+
+NOTE: You may want to reference `ccache` even before all that,
+as detailed below:
+
+----
+:; PATH="/usr/lib/ccache:$PATH"
+:; export PATH
+----
+
+To use the `ci_build.sh` don't forget `bash` which is not part of OpenBSD
+base installation. It is not required for "legacy" builds arranged by just
+`autogen.sh` and `configure` scripts.
+
+----
+:; pkgin install \
+    git python27 python39 curl \
+    make gmake autoconf automake libltdl libtool \
+    cppcheck \
+    pkgconf \
+    gcc7 clang
+
+;; ( cd /usr/pkg/bin && ( ln -fs python2.7 python2 ; ln -fs python3.9 python3 ) )
+
+# For spell-checking, highly recommended if you would propose pull requests:
+:; pkgin install \
+    aspell aspell-en
+
+# For man-page doc types, footprint on this platform is moderate:
+:; pkgin install \
+    asciidoc
+
+# For other doc types (PDF, HTML) generation - massive packages (TEX, X11):
+:; pkgin install \
+    source-highlight py39-pygments dblatex
+
+# For CGI graph generation - massive packages (X11):
+:; pkgin install \
+    gd openmp
+
+:; pkgin install \
+    cppunit \
+    openssl nss \
+    augeas \
+    libusb libusb1 \
+    neon \
+    net-snmp \
+    avahi
+
+# Select a LUA-5.1 (or possibly 5.2?) version
+:; pkgin install \
+    lua51
+
+:; pkgin install \
+    bash dash ast-ksh oksh
+----
+
+NOTE: 9TBD) On NetBSD 9.2 this package complains that it requires
+OS ABI 9.0, or that `CHECK_OSABI=no` is set in `pkg_install.conf`.
+Such file was not found in the test system...
++
+----
+:; pkgin install \
+    openipmi
+----
+
+Recommended: For compatibility with common setups on other operating
+systems, can add dash-number suffixed symlinks to compiler tools (e.g.
+`gcc-7` beside the `gcc` installed by package) near the original
+binaries and into `/usr/lib/ccache`:
+----
+:; ( cd /usr/bin && for TOOL in cpp gcc g++ ; do \
+        ln -s "$TOOL" "$TOOL-7" ; \
+     done )
+
+# Note that the one delivered binary is `clang-13` and many (unnumbered)
+# symlinks to it. For NUT CI style of support for builds with many
+# compilers, complete the known numbers:
+:; ( cd /usr/pkg/bin && for TOOL in clang-cpp clang++ ; do \
+        ln -s clang-13 "$TOOL-13" ; \
+     done )
+
+:; pkgin install ccache
+:; ( mkdir -p /usr/lib/ccache && cd /usr/lib/ccache && \
+        for TOOL in cpp gcc g++ clang ; do \
+            for VER in "" "-7" ; do \
+                ln -s ../../pkg/bin/ccache "$TOOL$VER" ; \
+            done ; \
+        done ; \
+        for TOOL in clang clang++ clang-cpp ; do \
+            for VER in "" "-13" ; do \
+                ln -s ../../pkg/bin/ccache "$TOOL$VER" ; \
+            done ; \
+        done ; \
+   )
+----
+
+NOTE: For Jenkins agents, also need to `pkgin install openjdk11` (will be
+in `JAVA_HOME=/usr/pkg/java/openjdk11`).
+
 OpenIndiana 2021.10
 ~~~~~~~~~~~~~~~~~~~
 

docs/man/Makefile.am

@@ -735,7 +735,11 @@ HTML_MANS = \
 
 all:
 
-html-man: $(HTML_MANS) index.html
+all-html html-man: $(HTML_MANS) index.html
+
+# Have a way to build all man pages, not just those that fit currently
+# configured drivers, daemons, developer aspect, etc.
+all-man man-man: $(MAN_MANS)
 
 if WITH_MANS
 if ! SKIP_MANS

docs/nut.dict

@@ -1,5 +1,6 @@
-personal_ws-1.1 en 2869 utf-8
+personal_ws-1.1 en 2883 utf-8
 AAS
+ABI
 ACFAIL
 ACFREQ
 ACK
@@ -10,9 +11,9 @@ ACrms
 ADDR
 ADDRCONFIG
 ADDRINFO
+ADELSYSTEM
 ADK
 ADKK
-ADELSYSTEM
 AEC
 AEF
 AEG
@@ -57,7 +58,6 @@ AlmCPol
 AlmEnbl
 Amplon
 Ampère
-Amplon
 Andreas
 Andreassen
 Andrzej
@@ -747,6 +747,7 @@ OMNIVSINT
 ONF
 ONV
 OOM
+OSABI
 OSF
 OSs
 OUTPUTV
@@ -1236,6 +1237,7 @@ VER
 VERFW
 VFI
 VIB
+VM
 VMIN
 VMM
 VMware
@@ -1390,6 +1392,7 @@ ascii
 asciidoc
 asem
 aspell
+ast
 async
 atcl
 ats
@@ -2245,6 +2248,7 @@ offtimedays
 oftd
 oids
 ok
+oksh
 ol
 oldmac
 oldmge
@@ -2262,8 +2266,10 @@ ontimedays
 ontiniedays
 ooce
 openSUSE
+openipmi
 openjdk
 openlog
+openmp
 opensolaris
 openssh
 openssl
@@ -2311,6 +2317,7 @@ pinouts
 pkg
 pkgconf
 pkgconfig
+pkgin
 plaintext
 plugin
 plugnplay