Add -D handling to all interactive NUT programs

.gitignore

@@ -52,6 +52,7 @@ tags
 /VERSION_FORCED
 /VERSION_FORCED_SEMVER
 /install-sh
+/.libs-dev-PATH
 /libtool
 /ltmain.sh
 /missing

Makefile.am

@@ -162,8 +162,8 @@ SUBDIR_MAKE_VERBOSE = default
 
 # Run the standard build if going sequential (or with unknown MAKEFLAGS),
 # or fanout if parallel (presuming GNU/BSD/Sun make at least):
-CLEANFILES += include/.all.nut_version-generated.timestamp clients/.all.libupsclient_version-generated.timestamp
-all-fanout-maybe: @dotMAKE@
+CLEANFILES += .libs-dev-PATH include/.all.nut_version-generated.timestamp clients/.all.libupsclient_version-generated.timestamp
+all-fanout-maybe: .libs-dev-PATH @dotMAKE@
 	@rm -f include/.all.nut_version-generated.timestamp \
 	       clients/.all.libupsclient_version-generated.timestamp
 	+@if [ x"$(NUT_MAKE_SKIP_FANOUT)" = xtrue ] ; then \
@@ -190,6 +190,27 @@ all-fanout-maybe: @dotMAKE@
 			;; \
 	  esac
 
+.libs-dev-PATH: Makefile
+	echo '# Sourcable script for developers to run built progs with their shared libs:' > '$@'
+	echo 'for D in common clients drivers tools/nut-scanner ; do \
+	    for S in "" "/.libs" ; do \
+	        DN="$(abs_top_builddir)/$${D}$${S}" ; \
+	        case "$${PATH}" in \
+	            "$${DN}"|*:"$${DN}}"|"$${DN}":*|*:"$${DN}":*) ;; \
+	            "") PATH="$${DN}" ;; \
+	            *)  PATH="$${DN}:$${PATH}" ;; \
+	        esac ; \
+	        case "$${LD_LIBRARY_PATH}" in \
+	            "$${DN}"|*:"$${DN}}"|"$${DN}":*|*:"$${DN}":*) ;; \
+	            "") LD_LIBRARY_PATH="$${DN}" ;; \
+	            *)  LD_LIBRARY_PATH="$${DN}:$${LD_LIBRARY_PATH}" ;; \
+	        esac ; \
+	    done ; \
+	done ; \
+	export PATH ; \
+	export LD_LIBRARY_PATH ; \
+	' >> '$@'
+
 # 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
@@ -208,7 +229,7 @@ all-fanout-staged: @dotMAKE@
 
 all-fanout-subdirs: $(SUBDIRS_ALL_RECURSIVE)
 
-all-fanout-libs all-libs-local: $(SUBDIRS_ALL_LIBS_LOCAL)
+all-fanout-libs all-libs-local: $(SUBDIRS_ALL_LIBS_LOCAL) .libs-dev-PATH
 
 #all all-am-local all-local: @dotMAKE@
 #	+@cd common && $(MAKE) $(AM_MAKEFLAGS) all
@@ -855,9 +876,21 @@ SET_PARMAKES_OPT = \
 		;; \
 	esac
 
+all-quick: @dotMAKE@
+	+@$(SET_PARMAKES_OPT); \
+	  $(MAKE) $(AM_MAKEFLAGS) -k -s $${PARMAKES_OPT} all
+
+install-quick: @dotMAKE@
+	+@$(SET_PARMAKES_OPT); \
+	  $(MAKE) $(AM_MAKEFLAGS) -k -s $${PARMAKES_OPT} install
+
+check-quick: @dotMAKE@
+	+@$(SET_PARMAKES_OPT); \
+	  $(MAKE) $(AM_MAKEFLAGS) -k -s $${PARMAKES_OPT} check
+
 spellcheck-quick: @dotMAKE@
 	+@$(SET_PARMAKES_OPT); \
-	  $(MAKE) $(AM_MAKEFLAGS) -k -s ${PARMAKES_OPT} spellcheck
+	  $(MAKE) $(AM_MAKEFLAGS) -k -s $${PARMAKES_OPT} spellcheck
 
 # Run auto-parallel recipe, and if something fails - re-run interactively:
 spellcheck-interactive-quick: @dotMAKE@

NEWS.adoc

@@ -137,6 +137,12 @@ but the `nutshutdown` script would bail out quickly and quietly. [PR #3008]
    * Ported C client library `libupsclient` support logic for SSL connections
      into C++ client library `libnutclient` and added tests for it. [issues
      #1599, #1711, PR #3353]
+   * Added support for command-line debugging with `-D` option into `upsc`,
+     `upscmd` and `upsrw` command-line clients, and the `nutconf` tool.
+     Revised handling of `-D` and/or `NUT_DEBUG_LEVEL` environment variable
+     in other programs. Extended public API of libupsclient and libnutscan
+     to diligently arrange debug-logging when at run-time those libraries
+     actually have different copies of the methods and data involved. [#3378]
 
  - NUT for Windows specific updates:
    * Revised detection of (relative) paths to program and configuration files
@@ -395,7 +401,8 @@ several `FSD` notifications into one executed action. [PR #3097]
 
  - `upsc` has now optional JSON output [issue #3172, PR #3178]
 
- - `upsset` should now recognize `RANGE NUMBER` and `NUMBER` types. [#3164]
+ - `upsset` CGI tool should now recognize `RANGE NUMBER` and `NUMBER` types.
+   [#3164]
 
  - `upsstats` CGI tool updates:
    * Now has JSON output mode via `?json` (or `&json`) CGI query parameter.
@@ -540,6 +547,9 @@ several `FSD` notifications into one executed action. [PR #3097]
      which should now not re-check source texts that were okay with the previous
      dictionary contents, in case some new terms have to be added. [PRs #3186,
      #2871]
+   * Added `make .libs-dev-PATH` recipe to generate a file which developers
+     or CI scripts can source to prefer freshly built NUT libraries and some
+     tools in their `LD_LIBRARY_PATH` and `PATH`. [#3379]
    * Introduced `make distcheck-completeness` goal to verify that our
      distribution archives can exactly reproduce themselves. [#2829]
    * Added a GitHub Actions CI job to generate, upload and recycle `make dist`

clients/Makefile.am

@@ -219,7 +219,7 @@ endif WITH_SSL
 # for the run-time dynamic linker resolution? For now the shared-library
 # builds are "exotic", but it makes sense to deprecate this export in a
 # future release.
-libupsclient_la_LDFLAGS = -version-info 7:0:0
+libupsclient_la_LDFLAGS = -version-info 8:0:1
 libupsclient_la_LDFLAGS += -export-symbols-regex '^(upscli_|nut_debug_level)'
 #|s_upsdebug|fatalx|fatal_with_errno|xcalloc|xbasename|print_banner_once)'
 if HAVE_WINDOWS

clients/upsc.c

@@ -35,30 +35,18 @@
 /* network timeout for initial connection, in seconds */
 #define UPSCLI_DEFAULT_CONNECT_TIMEOUT	"10"
 
+/* name-swap in libupsclient consumer to simplify the look of code base */
+#define builtin_setproctag(x)	setproctag(x)
+#define setproctag(x)	do { builtin_setproctag(x); upscli_upslog_setproctag(x, nut_common_cookie()); } while(0)
+
 static char		*upsname = NULL, *hostname = NULL;
 static UPSCONN_t	*ups = NULL;
 static int	output_json = 0;
 
-static void fatalx_error_json_simple(int msg_is_simple, const char *msg)
-	__attribute__((noreturn));
-
-static void fatalx_error_json_simple(int msg_is_simple, const char *msg) {
-	/* To be used in simpler cases, where the possible JSON
-	 * message is not embedded into other lists/objects */
-	if (output_json) {
-		if (msg_is_simple) {
-			/* Caller knows there is nothing to escape here, pass through */
-			printf("{\"error\": \"%s\"}\n", NUT_STRARG(msg));
-		} else {
-			printf("{\"error\": \"");
-			json_print_esc(msg);
-			printf("\"}\n");
-		}
-	}
-	fatalx(EXIT_FAILURE, "Error: %s", NUT_STRARG(msg));
-}
+/* For getopt loops below: */
+static const char	optstring[] = "+DhlLcVW:j";
 
-static void usage(const char *prog)
+static void help(const char *prog)
 {
 	print_banner_once(prog, 2);
 	printf("NUT read-only client program to display UPS variables.\n");
@@ -88,6 +76,7 @@ static void usage(const char *prog)
 	printf("  -V         - display the version of this software\n");
 	printf("  -W <secs>  - network timeout for initial connections (default: %s)\n",
 		UPSCLI_DEFAULT_CONNECT_TIMEOUT);
+	printf("  -D         - raise debugging level\n");
 	printf("  -h         - display this help text\n");
 
 	nut_report_config_flags();
@@ -96,6 +85,25 @@ static void usage(const char *prog)
 	printf("\n%s", suggest_doc_links(prog, NULL));
 }
 
+static void fatalx_error_json_simple(int msg_is_simple, const char *msg)
+	__attribute__((noreturn));
+
+static void fatalx_error_json_simple(int msg_is_simple, const char *msg) {
+	/* To be used in simpler cases, where the possible JSON
+	 * message is not embedded into other lists/objects */
+	if (output_json) {
+		if (msg_is_simple) {
+			/* Caller knows there is nothing to escape here, pass through */
+			printf("{\"error\": \"%s\"}\n", NUT_STRARG(msg));
+		} else {
+			printf("{\"error\": \"");
+			json_print_esc(msg);
+			printf("\"}\n");
+		}
+	}
+	fatalx(EXIT_FAILURE, "Error: %s", NUT_STRARG(msg));
+}
+
 static void printvar(const char *var)
 {
 	int		ret;
@@ -381,41 +389,72 @@ static void clean_exit(void)
 	free(hostname);
 	free(ups);
 
-	/* Not a sub-process (do not let common::proctag_cleanup() mis-report us as such) */
+	upscli_cleanup();
+
 	upsdebugx(1, "%s: finished, exiting", __func__);
-	setproctag(NULL);
 }
 
 int main(int argc, char **argv)
 {
-	int	i = 0;
+	/* Make sure all related logs (copies of code that may
+	 * be spread in different NUT common libs) start on the
+	 * same note; execute this call before everything else,
+	 * at the cost of a temporary otherwise useless variable. */
+	const struct timeval	*upslog_start_tmp = upscli_upslog_start_sync(upslog_start_sync(NULL), nut_common_cookie());
+	int	opt_ret = 0;
 	uint16_t	port;
 	int	varlist = 0, clientlist = 0, verbose = 0;
-	const char	*prog = xbasename(argv[0]);
+	const char	*prog = getprogname_argv0_default(argc > 0 ? argv[0] : NULL, "upsc");
 	const char	*net_connect_timeout = NULL;
-	char	*s = NULL;
 
-	setproctag(prog);
-	/* NOTE: Caller must `export NUT_DEBUG_LEVEL` to see debugs for upsc
-	 * and NUT methods called from it. This line aims to just initialize
-	 * the subsystem, and set initial timestamp. Debugging the client is
-	 * primarily of use to developers, so is not exposed via `-D` args.
+	NUT_UNUSED_VARIABLE(upslog_start_tmp);
+	upscli_upslog_setprocname(xstrdup(getmyprocname()), nut_common_cookie());
+
+	/* NOTE: Debugging the client is primarily of use to developers, so
+	 *  it was not at all exposed via `-D[D...]` args until NUT v2.8.5.
+	 *  Since earlier 2.8.x releases, caller could `export NUT_DEBUG_LEVEL`
+	 *  to see debugs for the client and for NUT methods called from it.
 	 */
-	s = getenv("NUT_DEBUG_LEVEL");
-	if (s && str_to_int(s, &i, 10) && i > 0) {
-		nut_debug_level = i;
-		upscli_set_debug_level(nut_debug_level);
+
+	/* Parse command line options -- First loop: only get debug level */
+	/* Suppress error messages, for now -- leave them to the second loop. */
+	opterr = 0;
+	while ((opt_ret = getopt(argc, argv, optstring)) != -1) {
+		if (opt_ret == 'D')
+			nut_debug_level++;
 	}
+
+	if (!nut_debug_level) {
+		char	*s = getenv("NUT_DEBUG_LEVEL");
+		int	l;
+		if (s && str_to_int(s, &l, 10) && l > 0) {
+			nut_debug_level = l;
+			upsdebugx(1, "Defaulting debug verbosity to NUT_DEBUG_LEVEL=%d "
+				"since none was requested by command-line options", l);
+		}	/* else follow -D settings */
+	}
+
+	/* These lines aim to just initialize the logging subsystem, and set
+	 * initial timestamp, for the eventuality that debugs would be printed:
+	 */
+	upscli_upslog_set_debug_level(nut_debug_level, nut_common_cookie());
+	setproctag(prog);
 	upsdebugx(1, "Starting NUT client: %s", prog);
 
 #if (defined NUT_PLATFORM_AIX) && (defined ENABLE_SHARED_PRIVATE_LIBS) && ENABLE_SHARED_PRIVATE_LIBS
 	callback_upsconf_args = do_upsconf_args;
 #endif
 
-	while ((i = getopt(argc, argv, "+hlLcVW:j")) != -1) {
+	/* Parse command line options -- Second loop: everything else */
+	/* Restore error messages... */
+	opterr = 1;
+	/* ...and index of the item to be processed by getopt(). */
+	optind = 1;
+	while ((opt_ret = getopt(argc, argv, optstring)) != -1) {
 
-		switch (i)
+		switch (opt_ret)
 		{
+		case 'D': break;	/* See nut_debug_level handled above */
 		case 'L':
 			verbose = 1;
 			goto fallthrough_case_l;
@@ -445,7 +484,7 @@ int main(int argc, char **argv)
 
 		case 'h':
 		default:
-			usage(prog);
+			help(prog);
 			exit(EXIT_SUCCESS);
 		}
 	}
@@ -456,6 +495,8 @@ int main(int argc, char **argv)
 		fatalx_error_json_simple(0, msg);
 	}
 
+	/* Simplify offset numbering to look at command-line
+	 * arguments (if any) after the options checked above */
 	argc -= optind;
 	argv += optind;
 
@@ -471,7 +512,7 @@ int main(int argc, char **argv)
 			fatalx_error_json_simple(0, "invalid UPS definition.\nRequired format: upsname[@hostname[:port]]");
 		}
 	}
-	setproctag(argv[0]);
+	setproctag(argv[0]);	/* ups[@host[:port]] */
 	upsdebugx(1, "upsname='%s' hostname='%s' port='%" PRIu16 "'",
 		NUT_STRARG(upsname), NUT_STRARG(hostname), port);
 
@@ -484,15 +525,13 @@ int main(int argc, char **argv)
 	if (varlist) {
 		upsdebugx(1, "Calling list_upses()");
 		list_upses(verbose);
-		exit(EXIT_SUCCESS);
 	}
-
+	else
 	if (clientlist) {
 		upsdebugx(1, "Calling list_clients()");
 		list_clients(upsname);
-		exit(EXIT_SUCCESS);
 	}
-
+	else
 	if (argc > 1) {
 		upsdebugx(1, "Calling printvar(%s)", argv[1]);
 		printvar(argv[1]);
@@ -501,6 +540,8 @@ int main(int argc, char **argv)
 		list_vars();
 	}
 
+	/* Not a sub-process (do not let common::proctag_cleanup() mis-report us as such) */
+	setproctag(prog);
 	exit(EXIT_SUCCESS);
 }
 

clients/upsclient.c

@@ -2272,12 +2272,59 @@ int	upscli_str_add_unique_token(char *tgt, size_t tgtsize, const char *token,
  * active memory, and upsdebugx() calls suffer if the library's copy
  * is never changed from zero.
  */
-void upscli_set_debug_level(int lvl)
+
+/* privately exported from common.c for internal libs */
+const char *setproctag_lib_once(const char *val);
+
+const void *upscli_upslog_cookie(void)
+{
+	return nut_common_cookie();
+}
+
+void upscli_upslog_set_debug_level(int lvl, const void *cookie)
 {
 	nut_debug_level = lvl;
+
+	if (cookie == upscli_upslog_cookie())
+		return;
+
+	setproctag_lib_once("libupsclient");
 }
 
-int  upscli_get_debug_level(void)
+int upscli_upslog_get_debug_level(void)
 {
 	return nut_debug_level;
 }
+
+/* Avoid re-querying /proc or equivalent and logging about it,
+ * if the caller is a NUT program that already knows its name:
+ * see getmyprocname() in NUT common library */
+void upscli_upslog_setprocname(const char *pn, const void *cookie)
+{
+	if (cookie != upscli_upslog_cookie())
+		setproctag_lib_once("libupsclient");
+
+	setmyprocname(pn);
+}
+
+void upscli_upslog_setproctag(const char *tag, const void *cookie)
+{
+	if (cookie != upscli_upslog_cookie())
+		setproctag_lib_once("libupsclient");
+
+	setproctag(tag);
+}
+
+const char *upscli_upslog_getproctag(void)
+{
+	return getproctag();
+}
+
+struct timeval *upscli_upslog_start_sync(struct timeval *tv, const void *cookie)
+{
+	if (cookie != upscli_upslog_cookie())
+		setproctag_lib_once("libupsclient");
+
+	/* No-op if internal tv equals passed tv */
+	return upslog_start_sync(tv);
+}