UPDATED: doc (ABI comparison) and various other fixes (#324)

* doc: qbarray.h: fix garbled Doxygen markup

* build: follow-up for and fine-tuning of a rushed 6d62b64 commit
  (It made a service as-was, but being afforded more time, this would
  have accompanied that commit right away, for better understanding,
  brevity and uniformity.)

* build: prune superfluous Makefile declarations within tests directory
  There was a significant redundancy wrt. build flags and EXTRA_DIST
  assignment (the latter become redundant as of f6e4042 at latest)
  spread all over the place (vivat copy&paste).  Also, in one instance,
  CPPFLAGS (used) was confused with CFLAGS (meant).

* maint: check abi: fix two issues with abi-compliance-checker/libstdc++
1. ABICC >= 2 needs to be passed -cxx-incompatible switch because C is
   no longer a default for this tool (used to be vice versa),
   plus current version will stop choking on C vs. C++ (our C code with
   C++ compatibility wrapping being viewed from C++ perspective for the
   purpose of dumping the declared symbols, which somewhat conflicts
   with internal masking of the C++ keywords being used as valid C
   identifiers [yet some instances must not be masked here, see
   lvc/abi-compliance-checker#64) only
  if _also_ something like this is applied:
   lvc/abi-compliance-checker#70
2. since 20246f5, libqb.so no longer poses a symlink to the actual
   version-qualified shared library, but rather a standalone linker
   script, which confuses ABICC, so blacklist that file for the scanning
   purposes explicitly, together with referring to the library through
   it's basic version qualification (which alone, sadly, is not
   sufficient as ABICC proceeds to scan whole containing directory
   despite particular file is specified)

* maint: check abi: switch to abi-dumper for creating "ABI dumps"
Beside avoiding issues with abi-compliance-checker in the role of ABI
dumps producer (see the preceding commit), it also seems to generate
more accurate picture (maybe because it expressly requires compiling
with debugging information requested).

* Low: qblist.h: fix incompatibility with C++ & check it regularly

* tests: check_list.c: start zeroing in on the gaps in tests' coverage

* tests: print_ver: make preprocessor emit "note" rather than warning

IIRC, Chrissie asked about this around inclusion of the test at
hand, and it seemed there was no way but to emit a warning to get
something output at all.  Now it turns wrong, and moreover, we
make the code not fixed on GCC specific pragmas, with a bit of
luck, "#pragma message" approach is adopted more widely by compilers.

Signed-off-by: Jan Pokorný <[email protected]>

* Replace ck_assert_uint_eq() with ck_assert_int_eq()
it's not available in check 0.9

* Proper check for C++ compiler (from Fabio)
* add (c) to copyright dates

build-aux/abi-check-templ.xml

@@ -6,7 +6,10 @@
 <headers>
 	@PREFIX@/usr/include/qb
 </headers>
+@SKIPLIB_CMT@<skip_libs>
+@SKIPLIB_CMT@	@PREFIX@/usr/lib64/libqb.so
+@SKIPLIB_CMT@</skip_libs>
 <libs>
-	@PREFIX@/usr/lib64/libqb.so
+	@PREFIX@/usr/lib64/libqb.so@LIB_SUFFIX@
 </libs>
 </descriptor>

check

@@ -211,6 +211,8 @@ check_clang() {
 }
 
 check_abi() {
+	# XXX abi-compliance-checker >= 2 will likely require equivalent of
+	#     https://github.com/lvc/abi-compliance-checker/pull/70
 	ver1=$1
 	ver2=$2
 	if [ -z "$ver1" ] ; then
@@ -224,26 +226,46 @@ check_abi() {
 
 	TMPL=build-aux/abi-check-templ.xml
 	checker=abi-compliance-checker
+	if abi-compliance-checker -info | grep -Fqe '-cxx-incompatible'; then
+		checker="${checker} -cxx-incompatible"
+	fi
 
 	mkdir -p abi_dumps/libqb
+	# ABICC only: current script always accompanied with current template
+	#for v in $ver1 $ver2; do cp "${TMPL}" "abi_dumps/libqb/${v}.tmpl"; done
+
 	for v in $ver1 $ver2
 	do
-		p=$(pwd)_inst_$v
-		sed -e "s|@PREFIX@|$p|" -e "s|@VERSION@|$v|" $TMPL > abi_dumps/libqb/$v.xml
-	done
-	for v in $ver1 $ver2
-	do
-		p=$(pwd)_inst_$v
-		t=v$v
-		echo "== Version $v =="
-		if [ ! -f abi_dumps/libqb/libqb_$v.abi.tar.gz ]
+		p=$(pwd)_inst_${v}
+		t=v${v}
+		echo "== Version ${v} =="
+		if [ ! -f "abi_dumps/libqb/libqb_${v}.abi.tar.gz" ]
 		then
-			git checkout $t
+			git checkout "${t}"
 			./autogen.sh
-			./configure
+			# XXX still complains about missing -Og (-O0 is used)
+			./configure --enable-debug
 			make
-			make install DESTDIR=$p
-			$checker -l libqb -dump_abi abi_dumps/libqb/$v.xml
+			make install DESTDIR="${p}"
+			lib_suffix=$(cut -c 1-32 "${p}/usr/lib64/libqb.so" \
+			             | sed -n 's/^INPUT(libqb\.so\([^)]*\).*$/\1/p;q')
+			# this is currently recommended way of using abi-dumper
+			# instead of relying on internal processing with ABICC
+			# itself (still kept around for reference below)
+			abi-dumper -loud -debug "${p}/usr/lib64/libqb.so${lib_suffix}" \
+			  -vnum "${v}" -o "abi_dumps/libqb/libqb_${v}.abi.tar.gz"
+
+			# former approach of relying solely on ABICC (XXX -lang C)
+			#skiplib_cmt=
+			#[ -n "${lib_suffix}" ] || skiplib_cmt='#'
+			#sed -e "s|@PREFIX@|${p}|" \
+			#    -e "s|@VERSION@|${v}|" \
+			#    -e "s|@SKIPLIB_CMT@|${skiplib_cmt}|" \
+			#    -e "s|@LIB_SUFFIX@|${lib_suffix}|" \
+			#    "abi_dumps/libqb/${v}.tmpl" > "abi_dumps/libqb/${v}.xml"
+			#rm -f "abi_dumps/libqb/${v}.tmpl"
+			#${checker} -l libqb -dump_abi "abi_dumps/libqb/${v}.xml" \
+			#    -dump-path "abi_dumps/libqb/libqb_${v}.abi.tar.gz"
 		fi
 	done
 
@@ -334,4 +356,3 @@ case $command in
 esac
 cd -
 exit 0
-

configure.ac

@@ -77,6 +77,7 @@ if ! ${MAKE-make} --version /cannot/make/this >/dev/null 2>&1; then
 fi
 
 AC_PROG_CXX
+AM_CONDITIONAL(HAVE_GXX, [test "x$GXX" = xyes]) 
 AC_PROG_AWK
 AC_PROG_CC
 AC_PROG_CPP
@@ -682,7 +683,7 @@ if test "x${GCC}" = xyes; then
 			               && my_var == 3  /* for 2.29.1+ */);
 			        return *((int *) __start___verbose); }]]
 			)],
-			[gcc_has_attribute_section=yes; cp "conftest${ac_exeext}" "conftest.so"],
+			[gcc_has_attribute_section=yes; cp "conftest${ac_exeext}" "conftest${shrext_cmds}"],
 			[gcc_has_attribute_section=no]
 		)
 		AX_RESTORE_FLAGS

include/qb/qbarray.h

@@ -52,8 +52,8 @@ extern "C" {
  * indexing, this gives a valid index range [0, @c QB_ARRAY_MAX_ELEMENTS),
  * where the notation denotes the beginning of the interval is included and
  * the end is excluded.  In other words, client space shall avoid a pitfall
- * of relying solely on the type of @max_elements parameter to
- * @ref qb_array_create and/or of @idx parameter to @ref qb_array_index
+ * of relying solely on the type of @c max_elements parameter to
+ * @ref qb_array_create and/or of @c idx parameter to @ref qb_array_index
  * (these types conflict, anyway).
  */
 

include/qb/qblist.h

@@ -109,16 +109,16 @@ static inline void qb_list_del(struct qb_list_head *_remove)
 
 /**
  * Replace old entry by new one
- * @param old: the element to be replaced
- * @param new: the new element to insert
+ * @param old_one: the element to be replaced
+ * @param new_one: the new element to insert
  */
-static inline void qb_list_replace(struct qb_list_head *old,
-		struct qb_list_head *new)
+static inline void qb_list_replace(struct qb_list_head *old_one,
+		struct qb_list_head *new_one)
 {
-	new->next = old->next;
-	new->next->prev = new;
-	new->prev = old->prev;
-	new->prev->next = new;
+	new_one->next = old_one->next;
+	new_one->next->prev = new_one;
+	new_one->prev = old_one->prev;
+	new_one->prev->next = new_one;
 }
 
 /**

include/qb/qblog.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017 Red Hat, Inc.
+ * Copyright (c) 2017 Red Hat, Inc.
  *
  * All rights reserved.
  *

lib/Makefile.am

@@ -100,10 +100,9 @@ else
 endif
 endif
 
+# nested sed expression is also escaping meta character for the outer one
 qblog_script.ld: %.ld: %.ld.in
-	$(AM_V_GEN)$(CPP) -C -D_GNU_SOURCE -P \
-	  -I$(top_srcdir)/include -I$(top_builddir)/include \
-	  -xc $< \
+	$(AM_V_GEN)$(CPP) -C -D_GNU_SOURCE -P $(AM_CPPFLAGS) -xc $< \
 	  | sed -n "/$$(sed -n '/^[^#]/{s/[*\/]/\\&/g;p;q;}' $<)/,$$ p" \
 	  > $@
 

tests/Makefile.am

@@ -33,23 +33,23 @@ noinst_HEADERS = check_common.h
 format_compare_speed_SOURCES = format_compare_speed.c $(top_builddir)/include/qb/qbutil.h
 format_compare_speed_LDADD = $(top_builddir)/lib/libqb.la
 
-bmc_SOURCES = bmc.c $(top_builddir)/include/qb/qbipcc.h
+bmc_SOURCES = bmc.c
 bmc_LDADD = $(top_builddir)/lib/libqb.la
 
-bmcpt_SOURCES = bmcpt.c $(top_builddir)/include/qb/qbipcc.h
+bmcpt_SOURCES = bmcpt.c
 bmcpt_LDADD = $(top_builddir)/lib/libqb.la
 
-bms_SOURCES = bms.c $(top_builddir)/include/qb/qbipcs.h
-bms_CPPFLAGS = -I$(top_builddir)/include -I$(top_srcdir)/include $(GLIB_CFLAGS)
+bms_SOURCES = bms.c
+bms_CFLAGS = $(GLIB_CFLAGS)
 bms_LDADD = $(top_builddir)/lib/libqb.la $(GLIB_LIBS)
 
-rbwriter_SOURCES = rbwriter.c $(top_builddir)/include/qb/qbrb.h
+rbwriter_SOURCES = rbwriter.c
 rbwriter_LDADD = $(top_builddir)/lib/libqb.la
 
-rbreader_SOURCES = rbreader.c $(top_builddir)/include/qb/qbrb.h
+rbreader_SOURCES = rbreader.c
 rbreader_LDADD = $(top_builddir)/lib/libqb.la
 
-loop_SOURCES = loop.c $(top_builddir)/include/qb/qbloop.h
+loop_SOURCES = loop.c
 loop_LDADD = $(top_builddir)/lib/libqb.la
 
 inc_dir = $(top_srcdir)/include/qb
@@ -78,7 +78,17 @@ check: check-headers
 
 # rely on implicit automake rule to include right (local) includes
 .PHONY: check-headers
-check-headers: $(auto_c_files:.c=.o)
+check-headers: $(auto_c_files:.c=.o) $(auto_c_files:.c=.opp)
+
+# this is to check basic sanity of using libqb from C++ code, if possible
+%.opp: %.c
+if HAVE_GXX
+	$(AM_V_GEN)$(CXX) $(AM_CPPFLAGS) -c $(CPPFLAGS) $(CXXFLAGS) -o $@ $<
+else
+	@echo "C++ compatibility tests not run"
+endif
+
+CLEANFILES += ${auto_c_files:.c=.opp}
 
 distclean-local:
 	rm -rf auto_*.c
@@ -99,20 +109,21 @@ $(builddir)/auto_write_logs.c: make-log-test.sh
 endif
 endif
 
-bench_log_SOURCES = bench-log.c $(top_builddir)/include/qb/qblog.h
-bench_log_CPPFLAGS = -I$(top_builddir)/include -I$(top_srcdir)/include
+bench_log_SOURCES = bench-log.c
 bench_log_LDADD = $(top_builddir)/lib/libqb.la
 
 if HAVE_CHECK
 EXTRA_DIST += start.test resources.test
 EXTRA_DIST += blackbox-segfault.sh
 
-TESTS = start.test array.test map.test rb.test log.test blackbox-segfault.sh loop.test ipc.test resources.test
+TESTS = start.test array.test map.test rb.test list.test log.test blackbox-segfault.sh loop.test ipc.test resources.test
 
 resources.log: rb.log log.log ipc.log
 
 check_LTLIBRARIES =
-check_PROGRAMS = array.test map.test rb.test log.test loop.test ipc.test util.test crash_test_dummy file_change_bytes
+check_PROGRAMS = array.test ipc.test list.test log.test loop.test \
+		 map.test rb.test util.test \
+		 crash_test_dummy file_change_bytes
 dist_check_SCRIPTS = start.test resources.test blackbox-segfault.sh
 
 if HAVE_SLOW_TESTS
@@ -122,28 +133,28 @@ endif
 
 file_change_bytes_SOURCES = file_change_bytes.c
 
-crash_test_dummy_SOURCES = crash_test_dummy.c $(top_builddir)/include/qb/qblog.h
-crash_test_dummy_CFLAGS = @CHECK_CFLAGS@ -I$(top_srcdir)/include
+crash_test_dummy_SOURCES = crash_test_dummy.c
+crash_test_dummy_CFLAGS = @CHECK_CFLAGS@
 crash_test_dummy_LDADD = $(top_builddir)/lib/libqb.la @CHECK_LIBS@
 
-array_test_SOURCES = check_array.c $(top_builddir)/include/qb/qbarray.h
-array_test_CFLAGS = @CHECK_CFLAGS@ -I$(top_srcdir)/include
+array_test_SOURCES = check_array.c
+array_test_CFLAGS = @CHECK_CFLAGS@
 array_test_LDADD = $(top_builddir)/lib/libqb.la @CHECK_LIBS@
 
-map_test_SOURCES = check_map.c $(top_builddir)/include/qb/qbmap.h
-map_test_CFLAGS = @CHECK_CFLAGS@ -I$(top_srcdir)/include
+map_test_SOURCES = check_map.c
+map_test_CFLAGS = @CHECK_CFLAGS@
 map_test_LDADD = $(top_builddir)/lib/libqb.la @CHECK_LIBS@
 
-rb_test_SOURCES = check_rb.c $(top_builddir)/include/qb/qbrb.h
-rb_test_CFLAGS = @CHECK_CFLAGS@ -I$(top_srcdir)/include
+rb_test_SOURCES = check_rb.c
+rb_test_CFLAGS = @CHECK_CFLAGS@
 rb_test_LDADD = $(top_builddir)/lib/libqb.la @CHECK_LIBS@
 
-loop_test_SOURCES = check_loop.c $(top_builddir)/include/qb/qbloop.h
-loop_test_CFLAGS = @CHECK_CFLAGS@ -I$(top_srcdir)/include
+loop_test_SOURCES = check_loop.c
+loop_test_CFLAGS = @CHECK_CFLAGS@
 loop_test_LDADD = $(top_builddir)/lib/libqb.la @CHECK_LIBS@
 
-ipc_test_SOURCES = check_ipc.c $(top_builddir)/include/qb/qbipcc.h $(top_builddir)/include/qb/qbipcs.h
-ipc_test_CFLAGS = @CHECK_CFLAGS@ -I$(top_srcdir)/include
+ipc_test_SOURCES = check_ipc.c
+ipc_test_CFLAGS = @CHECK_CFLAGS@
 ipc_test_LDADD = $(top_builddir)/lib/libqb.la @CHECK_LIBS@
 if HAVE_FAILURE_INJECTION
 ipc_test_LDADD += _failure_injection.la
@@ -158,15 +169,19 @@ check_LTLIBRARIES += _syslog_override.la
 _syslog_override_la_SOURCES = _syslog_override.c _syslog_override.h
 _syslog_override_la_LDFLAGS = -module
 
-log_test_SOURCES = check_log.c $(top_builddir)/include/qb/qblog.h
-log_test_CFLAGS = @CHECK_CFLAGS@ -I$(top_srcdir)/include
+log_test_SOURCES = check_log.c
+log_test_CFLAGS = @CHECK_CFLAGS@
 log_test_LDADD = $(top_builddir)/lib/libqb.la @CHECK_LIBS@
 log_test_LDADD += _syslog_override.la
 
-util_test_SOURCES = check_util.c $(top_builddir)/include/qb/qbutil.h
-util_test_CFLAGS = @CHECK_CFLAGS@ -I$(top_srcdir)/include
+util_test_SOURCES = check_util.c
+util_test_CFLAGS = @CHECK_CFLAGS@
 util_test_LDADD = $(top_builddir)/lib/libqb.la @CHECK_LIBS@
 
+list_test_SOURCES = check_list.c
+list_test_CFLAGS = @CHECK_CFLAGS@
+list_test_LDADD = $(top_builddir)/lib/libqb.la @CHECK_LIBS@
+
 endif
 
 clean-local: