Merge pull request #2368 from jimklimov/apc-modbus-doc-only

APC Modbus doc updates

Author: jimklimov

Jenkinsfile-dynamatrix

@@ -25,7 +25,8 @@ import org.nut.dynamatrix.*;
     def dynacfgPipeline = [:]
 
     // NOTE: These can be further disabled or active in different combo specs
-    // below based on branch names
+    // below based on branch names. Also note that the values are somewhat
+    // "inversed" -- e.g. that "disabledSomething = false" means "enable it".
     dynacfgPipeline.disableSlowBuildAutotools = false
     dynacfgPipeline.disableSlowBuildCIBuild = false
     dynacfgPipeline.disableSlowBuildCIBuildExperimental = false
@@ -427,12 +428,12 @@ set | sort -n """
         //'bodyParStages': {}
         ] // one slowBuild filter configuration, autotools-Wall
 
-        ,[name: 'Default autotools driven build with default configuration, bitness and warning levels on each NUT CI farm platform (but with fatal warnings as of gnu99/gnu++11)',
+        ,[name: 'Default autotools driven build with default configuration, bitness and warning levels on each NUT CI farm platform (but with fatal warnings as of gnu99/gnu++11, must pass where enabled)',
          disabled: dynacfgPipeline.disableSlowBuildAutotools,
-         branchRegexSource: ~/^(PR-.+|fightwarn.*)$/,
-         branchRegexTarget: dynacfgPipeline.branchStableRegex,
+         //branchRegexSource: ~/^(PR-.+|fightwarn.*)$/,
+         //branchRegexTarget: dynacfgPipeline.branchStableRegex,
          //branchRegexTarget: ~/fightwarn/,
-         appliesToChangedFilesRegex: dynacfgPipeline.appliesToChangedFilesRegex_C,
+         //appliesToChangedFilesRegex: dynacfgPipeline.appliesToChangedFilesRegex_C,
          'getParStages': { def dynamatrix, Closure body ->
             return dynamatrix.generateBuild([
                 //commonLabelExpr: dynacfgBase.commonLabelExpr,

docs/man/Makefile.am

@@ -950,7 +950,7 @@ CLEANFILES = *-spellchecked .prep-src-docs *-prepped
 
 SUFFIXES = .txt-prepped .txt .html .1 .3 .5 .8
 
-# For builds with allowed installation of prebuild man pages, check that
+# For builds with allowed installation of prebuilt man pages, check that
 # they exist in sources (make would pull them automatically as a fallback
 # from failed lookup in build products). For builds that require rebuild
 # of man pages, abort with error if build product is missing.

docs/man/apc_modbus.txt

@@ -83,6 +83,66 @@ Set the Modbus slave id. The default slave id is 1.
 Set the Modbus response timeout. The default timeout is set by libmodbus. It can
 be good to set a higher timeout on TCP connections with high latency.
 
+BUGS
+----
+
+This driver relies on advanced features of `libmodbus` to talk Modbus protocol
+over USB specifically (Serial and TCP are part of common library codebase).
+At the time of this writing, the common library project is just expecting a
+merge of the pull request with this ability.
+
+For the time being, if your OS distribution does not ship the required feature
+set, you may have to build your own `libmodbus` and subsequently (re-)build NUT
+against this library, as detailed in the NUT GitHub Wiki at
+https://github.com/networkupstools/nut/wiki/APC-UPS-with-Modbus-protocol
+
+The short sequence may be like follows:
+------
+cd ~/
+git clone -b rtu_usb https://github.com/networkupstools/libmodbus
+cd libmodbus
+./autogen.sh
+./configure --with-libusb --prefix=/path/to/prefix
+make install
+------
+
+[NOTE]
+======
+* you may need to `make && sudo make install` if you want to place this library
+  files' variant into a system path (like `--prefix=/usr/local/ups` to match
+  NUT defaults -- this activity would need privilege elevation via `sudo`),
+  and not into your home directory or some `/tmp` location.
+* conversely, you may want to
+  `./configure --with-libusb --enable-static --disable-shared --prefix=/path/to/prefix`
+  and only build and install a static `libmodbus.a` (can well be installed into
+  `/tmp` or similarly short-lived location), so that the customized Modbus+USB
+  logic gets built directly into `apc_modbus` binary program and there would be
+  no potential run-time conflict with a dynamic library file available elsewhere
+  in the system.
+======
+
+------
+cd ~/
+git clone https://github.com/networkupstools/nut
+cd nut
+./autogen.sh
+./configure --with-drivers=apc_modbus --with-usb --with-modbus \
+   --with-modbus-includes=-I/path/to/prefix/include/modbus \
+   --with-modbus-libs="-L/path/to/prefix/lib -lmodbus"
+make
+------
+
+[NOTE]
+======
+* Other NUT `configure` options may be needed for proper behavior, such as
+`--prefix`, `--with-sysconfdir`, `--with-user` and `--with-group` to match
+your packaged or otherwise preceding NUT installation.
+======
+
+The `./configure --enable-inplace-runtime` may be a good start to inherit
+build configuration from an existing NUT deployment, as further detailed at
+https://github.com/networkupstools/nut/wiki/Building-NUT-for-in%E2%80%90place-upgrades-or-non%E2%80%90disruptive-tests
+
 AUTHORS
 -------
 

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3478 utf-8
+personal_ws-1.1 en 3480 utf-8
 AAC
 AAS
 ABI
@@ -2431,6 +2431,7 @@ lk
 lldb
 llvm
 lm
+lmodbus
 ln
 lnetsnmp
 loadPercentage
@@ -2940,6 +2941,7 @@ rqt
 rsa
 rsync
 rts
+rtu
 ru
 rubygem
 runlevel

m4/nut_check_libmodbus.m4

@@ -72,7 +72,12 @@ if test -z "${nut_have_libmodbus_seen}"; then
 	AC_CHECK_FUNCS(modbus_set_byte_timeout, [], [nut_have_libmodbus=no])
 	AC_CHECK_FUNCS(modbus_set_response_timeout, [], [nut_have_libmodbus=no])
 
-	AC_CHECK_FUNCS(modbus_new_rtu_usb, [nut_have_libmodbus_usb=yes], [nut_have_libmodbus_usb=no])
+	AC_CHECK_FUNCS(modbus_new_rtu_usb, [nut_have_libmodbus_usb=yes], [
+		AS_IF([test x"${nut_with_usb}" = xyes && test x"${nut_with_modbus}" = xyes && test x"${nut_have_libmodbus}" = xyes ], [
+			AC_MSG_WARN([Both --with-modbus and --with-usb were requested, and a libmodbus was found, but it seems to not support USB. You may require a custom build per https://github.com/networkupstools/nut/wiki/APC-UPS-with-Modbus-protocol])
+		])
+		nut_have_libmodbus_usb=no
+	])
 
 	dnl modbus_set_byte_timeout() and modbus_set_response_timeout()
 	dnl in 3.0.x and 3.1.x have different args (since ~2013): the

tools/nut-scanner/scan_snmp.c

@@ -1033,7 +1033,24 @@ nutscan_device_t * nutscan_scan_snmp(const char * start_ip, const char * stop_ip
 
 # ifdef HAVE_SEMAPHORE
 	if (max_threads_scantype > 0) {
+#ifdef HAVE_PRAGMAS_FOR_GCC_DIAGNOSTIC_IGNORED_UNREACHABLE_CODE
+#pragma GCC diagnostic push
+#endif
+#ifdef HAVE_PRAGMA_GCC_DIAGNOSTIC_IGNORED_UNREACHABLE_CODE
+#pragma GCC diagnostic ignored "-Wunreachable-code"
+#endif
+#ifdef __clang__
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wunreachable-code"
+#endif
+		/* Different platforms, different sizes, none fits all... */
 		if (SIZE_MAX > UINT_MAX && max_threads_scantype > UINT_MAX) {
+#ifdef __clang__
+#pragma clang diagnostic pop
+#endif
+#ifdef HAVE_PRAGMAS_FOR_GCC_DIAGNOSTIC_IGNORED_UNREACHABLE_CODE
+#pragma GCC diagnostic pop
+#endif
 			upsdebugx(1,
 				"WARNING: %s: Limiting max_threads_scantype to range acceptable for sem_init()",
 				__func__);

tools/nut-scanner/scan_xml_http.c

@@ -454,7 +454,24 @@ nutscan_device_t * nutscan_scan_xml_http_range(const char * start_ip, const char
 
 # ifdef HAVE_SEMAPHORE
 			if (max_threads_scantype > 0) {
+#ifdef HAVE_PRAGMAS_FOR_GCC_DIAGNOSTIC_IGNORED_UNREACHABLE_CODE
+#pragma GCC diagnostic push
+#endif
+#ifdef HAVE_PRAGMA_GCC_DIAGNOSTIC_IGNORED_UNREACHABLE_CODE
+#pragma GCC diagnostic ignored "-Wunreachable-code"
+#endif
+#ifdef __clang__
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wunreachable-code"
+#endif
+				/* Different platforms, different sizes, none fits all... */
 				if (SIZE_MAX > UINT_MAX && max_threads_scantype > UINT_MAX) {
+#ifdef __clang__
+#pragma clang diagnostic pop
+#endif
+#ifdef HAVE_PRAGMAS_FOR_GCC_DIAGNOSTIC_IGNORED_UNREACHABLE_CODE
+#pragma GCC diagnostic pop
+#endif
 					upsdebugx(1,
 						"WARNING: %s: Limiting max_threads_scantype to range acceptable for sem_init()",
 						__func__);