* doxygen2man: Add utility to generate man pages from doxygen
This is in here from kronosnet so it cna be used by other parts
of the cluster stack.
* [man] drop trailing white spaces
Signed-off-by: Fabio M. Di Nitto <fdinitto@redhat.com>
* [build] cleanup variable names
Signed-off-by: Fabio M. Di Nitto <fdinitto@redhat.com>
* [build] add conditionals to use internal or external doxygen2man
Signed-off-by: Fabio M. Di Nitto <fdinitto@redhat.com>
* Update .gitignore
Signed-off-by: Fabio M. Di Nitto <fdinitto@redhat.com>
Co-authored-by: Christine Caulfield <ccaulfie@redhat.com>
These are for quick manual sanity checking, assuming the target audience
-- maintainers -- are clear on the context of use and the purpose
(perhaps with the help of static files for comparison and/or additional
checking harness, usually available through "make check", but not to be
confused with regular unit + broader tests). These test are meant to be
compiled on demand only, not during the standard building routine, for
which a trick leveraging GNUmakefile-Makefile precedence with GNU make
was devised (GNU make/gmake already required by configure script for
other reasons [some pattern-based matching not available with FreeBSD's
default "make", IIRC], so this introduces no new build dependency).
The respective new tests are meant to simulate logging variants in two
different library consumption models:
a. regular: linking against system-wide library
b. developmental: consuming library from a local sub-checkout tree,
using libtool conventions and hence attaching the
library through libqb.la intermediate library
descriptor of libtool
and between up to three possibly affected logging system participants
(discrete compilation units):
1. libqb itself will emit log messages in boundary conditions or
for tracing purposes
2. client program that consumes libqb's logging API directly
3. ditto, but the client program furthermore links with a library
(referred to as "interlib") that itself exercises the logging
API (it's also linked with libqb) -- through induction, this
should cover whole class of N interlib cases
Especially the latter perspective makes for a test matrix to possibly
(hopefully) demonstrate a fix allowing to cope with the changed
behaviour of ld from binutils 2.29+ wrt. boundaries denoting symbols for
a (custom) orphan section that are no longer externally visible. Such
commit is in the pipeline...
Developmental consumption model (a.) is now also tested automatically
in Travis CI runs and as a part of %check within upstream-suggested
libqb.spec for RPM packaging, whereas the regular one (b.) serves as
a building block for new log_test_mock.sh runner of said test matrix
-- it iterates through all the possible permutations of linker-imposed
implicit visibility of mentioned symbols between various affected
link participants all making use of logging (see 1. - 3. above) so as
to demonstrate A/ the impact of the problem (see table below), and
subsequently B/ that the fix is effective in all these situations
(updated table will be provided as well) once it lands. This script
also allows convoluting the test matrix further, notably with on-demand
defusing the self-checks based on QB_LOG_INIT_DATA macro, which is
of significance as demonstrated below (and will become even more
important with upcoming patches in this series).
* * *
Current state for such matrix, in which participants 1. - 3. map like:
1. ~ libqb(Y)
2. ~ "direct"
3. ~ libX(Y) [a.k.a. interlib]
and where "X(Y)" denotes "X linked with linker Y":
X(a) .. ld.bfd < 2.29
X(b) .. ld.bfd = 2.29 (and only 2.29),
goes like this:
+=========+=========+=========+=========+=========+=========+=========+
#client(x)# libqb(a) usage # libqb(b) usage #
# vvv #---------+---------+---------+---------+---------+---------+
# V # direct | libX(a) : libX(b) # direct | libX(a) : libX(b) #
+=========+=========+=========+=========+=========+=========+=========+
# x = a # OK | OK : BAD[*2] # BAD[*1] | BAD[*D] : BAD[*3] #
# x = b # BAD[*A] | BAD[*B] : BAD[*C] # BAD[*1] | BAD[*C] : BAD[*3] #
+=========+=========+=========+=========+=========+=========+=========+
whereas if we swap 2.29 for 2.29.1, i.e., X(b) .. ld.bfd = 2.29.1, we
can observe a somewhat simpler story (DEP ~ "depends"):
+=========+=========+=========+=========+=========+=========+=========+
#client(x)# libqb(a) usage # libqb(b) usage #
# vvv #---------+---------+---------+---------+---------+---------+
# V # direct | libX(a) : libX(b) # direct | libX(a) : libX(b) #
+=========+=========+=========+=========+=========+=========+=========+
# x = a # OK | OK : DEP[*J] # BAD[*1] | BAD[*1] : BAD[*L] #
# x = b # DEP[*I] | DEP[*I] : DEP[*K] # BAD[*1] | BAD[*1] : BAD[*L] #
+=========+=========+=========+=========+=========+=========+=========+
* * *
[*1] client logging not working
[*2] interlib logging not working
[*3] both client and interlib logging not working
[*A] boils down to [*1], unless QB_LOG_INIT_DATA used on client side,
which fails on 'implicit callsite section is populated' assertion
[*B] boils down to [*1], unless QB_LOG_INIT_DATA used on interlib side,
which fails on 'implicit callsite section is populated' assertion
[*C] boils down to [*3], unless QB_LOG_INIT_DATA used on interlib side,
which fails on 'implicit callsite section is populated' assertion
[*D] boils down to [*3], unless QB_LOG_INIT_DATA used on interlib side,
which makes it boil down just to [*1] (hypothesis: mere internal
self-reference to the section's boundary symbols makes them
overcome some kind of symbol garbage collection at the linkage
stage, so they are exposed even they wouldn't be otherwise as
demonstrated with the initial, plain case of [*3])
[*I] boils down to [*1], unless QB_LOG_INIT_DATA used on client side,
which makes it, likely through self-reference keepalive (see
below) work OK
[*J] boils down to [*2], unless QB_LOG_INIT_DATA used on interlib side,
which makes it, likely through self-reference keepalive (see
below) work OK
[*K] boils down to [*3], unless QB_LOG_INIT_DATA used on both client
and interlib side, which makes it, likely through self-reference
keepalive (see below) work OK (it's expected that this a mere
composite of situations [*I] and [*J] with consequences as stated)
[*L] boils down to [*3], unless QB_LOG_INIT_DATA used on interlib side
(sufficient?), which makes it, likely through self-reference
keepalive (see below) boil down just to [*1]
* * *
Note: as observed with [*D] case (libqb linked with ld.bfd < 2.29
whereas interlib and its client linked with ld.bfd = 2.29), the exact
availability of a working logging doesn't depend solely on the linkers
in question, but generally (further investigation out of scope) the
conclusion is that when 2.29 ld.bfd is involved somewhere in the chain
of logging-related discrete compilation units, also (self-)referencing
of the section's boundary denoting symbols is a deciding factor whether
particular logging source will be honored. This may be a result of
some internal linkage garbage collection mechanisms involved.
Anyway, it is supposed that the fix to broken-by-linkage logging can be
proclaimed complete once all combinations pass barring QB_LOG_INIT_DATA
usage (incurring the mentioned active referential use of the symbols),
along with a spin using it everywhere for good measure.
For another level of the analysis depth, one can further play with
combinations of -n{sc,cl,il} options (explained upon -h switch) to
log_test_mock.sh (taking an oracle, this is added mostly to justify
the upcoming self-check test change because linker-script-based
workaround for newer linkers will cause the section boundary symbols
to be present regardless if that section is utilized, leading to
a self-inflicted breakage due to these empty section symbols suddenly
winning in the symbol resolution mechanism).
Signed-off-by: Jan Pokorný <jpokorny@redhat.com>
Beside the fact that libqb.so file delivered with that package is indeed
referring to arch-preserving binary library (present in the same,
arch-specific path as the libqb.so happens to reside), it's also
a matter of being disciplined per what distros reasonably require:
https://fedoraproject.org/wiki/Packaging:Guidelines#Requiring_Base_Package
The syntactic provision at hand was introduced in rpm 4.6.0
(8+ years ago): http://rpm.org/user_doc/arch_dependencies.html
Signed-off-by: Jan Pokorný <jpokorny@redhat.com>
The intention behind enabling the syslog tests on demand (642f74d) was
to tread cautiously as libtool used to alert that something controversial
is going on:
$ ./autogen.sh && ./configure --enable-syslog-tests && make check
> ...
> *** Warning: Linking the executable log.test against the loadable module
> *** _syslog_override.so is not portable!
> ...
owing to the fact that _syslog_override.so is being linked (through
libtool) with LDFLAGS=-module.
In fact, the issue did go away with a fix to the "make install" process
(ebcff54) for which _syslog_override.so* files were being picked
undesirably prior to the fix, which manifested itself also on
"make rpm" (hence the respective commit message):
> RPM build errors:
> Installed (but unpackaged) file(s) found:
> /usr/lib64/_syslog_override.so
> /usr/lib64/_syslog_override.so.0
> /usr/lib64/_syslog_override.so.0.0.0
The explanation for the secondary positive effect on the mentioned
libtool's warning going away is rather simple:
"lib" prefix switches the expectations about the result as a library
(also due to "libdir" destination) rather than as an executable object.
Change like that ensures the result is what libtool's manual calls
"dynamic module that can be opened by lt_dlopen" rather than "runtime
library that cannot" in the context of Mac OS X, which was likely the
cause of the portability warning.
(https://www.gnu.org/software/libtool/manual/libtool.html#FOOT10)
And because the tests themselves are run through the libtool wrapper
scripts capable of relinking and other magic
What libtool manual has to say on this topic:
> Note that libtool modules don’t need to have a "lib" prefix. However,
> Automake 1.4 or higher is required to build such modules.
referring to version released 15+ years back, which is assumed anyway.
(https://www.gnu.org/software/libtool/manual/libtool.html#Modules-for-libltdl)
* * *
That being said, there's now no longer a reason to have "syslog-tests"
enablement conditionalized (no longer supposed intrusive), hence enable
them unconditionally along the other libcheck-based tests
-- whenever libcheck is detected.
This changeset also drops any trace of --enable-syslog-tests switch
in various places using that (spec file, Travis CI configuration)
making for a complete vaporizatio of this choice.
This is to prevent issues like the one being fixed with ebcff54
(https://github.com/ClusterLabs/libqb/pull/197).
Also, plain "make" invocation is dropped as it is an integral part
of "make rpm" (%build phase in libqb.spec).
This is to try and get a better balance in the amount
of processing between IPC and totem in corosync.
Signed-off-by: Angus Salkeld <asalkeld@redhat.com>
This ringbuffer is usable across processes.
the point is to use this for IPC to provide async
connections from client to server, but with inherient
flow control.
This still needs a bit of clean up, but committing now
for feedback and as it is quite functional.
Signed-off-by: Angus Salkeld <asalkeld@redhat.com>
