xap_helper_cxx: detect libxapian version changes

As with libgit2, Xapian can be upgraded and break linkage
with the xap_helper binary.  For now, save the result of
`pkg-config --modversion xapian-core' to a file and
compare it with the current output.

Perhaps portable some make(1) can be used for this...

gcf2: detect libgit2 version changes

We need to force Inline::C to rebuild if libgit2 is updated;
otherwise dynamic linking can be broken.  Adding the output
from the `--modversion' of pkg-config(1) along with the existing
`--libs' and `--cflags' output seems appropriate for this task.

To force Inline::C into a rebuild, neither CFLAGSEX nor CPPFLAGS
changes are enough.  Modifying the source string and adding
comments seems like the most obvious way to force a rebuild.

The `-print-file-name=LIBRARY' feature from gcc+clang could also
be used, but that requires parsing the library name from
`pkg-config --libs' output into a library basename appropriate
for `-print-file-name='.  IOW, we'd need to transform:
`-lgit2' => `libgit2.so'; and possibly deal with platforms
which deal with static libraries in the future.

So just use pkg-config, since `pkg-config --modversion' is
roughly 2-3x as fast as `gcc-10 -print-file-name=', and
10-20x faster than clang-11.

Revert "dspoll: switch to the documented IO::Poll API"

This reverts commit 831ac641e8c23e3c87931b902527d7f5600fd80a.

provide select(2) backend for PublicInbox::DS

This is safer than relying on an internal API of IO::Poll
and doesn't create extra references to IO globs like the
public one.

spawn: do not block ABRT/BUS/ILL/SEGV signals

SIGABRT, SIGBUS, SIGILL, and SIGSEGV may all happen if we
introduce bugs in the section where signals are blocked.

We can delay handling of SIGFPE, SIGXCPU and SIGXFSZ since
there's no floating point operations; while SIGXCPU and
SIGXFSZ are safe to delay, especially in the absence of
threads in our current code paths.

ds: use constants for @UNBLOCKABLE list

There's no need for for a complicated map {} block here.  All
these unblockable signals are POSIX since 2001 at the latest, so
there's no reason any platform would lack them.

dspoll: switch to the documented IO::Poll API

IO::Poll::_poll has always been an undocumented API.  While it's
remained working so far (since the early 2000s with Danga::Socket),
I'm uncomfortable continuing with it moving forward since it's
not documented (the leading underscore typically means it's
not meant to be used by 3rd-parties).

So switch to the documented API and just learn to live with some
redundant object references and awkwardness in the API.

favor poll(2) for most daemons

public-inbox-watch, lei-daemon, the master process of
public-inbox-(netd|httpd|imapd|nntpd|pop3d),
and the (mostly) Perl implementation of XapHelper do not
have many FDs to watch so epoll|kqueue end up being overkill.

Of course, *BSDs already have separate kqueue FDs emulating
signalfd and/or inotify, even.

In other words, only the worker processes of
public-inbox-(netd|httpd|imapd|nntpd|pop3d) are expected
to see C10K (or C100K) types of traffic where epoll|kqueue
shine.

Perhaps lei could benefit from epoll/kqueue on some virtual users
IMAP/JMAP system one day; as could -watch with many IMAP IDLE
folders; but we'll probably add a knob if/when it comes to that.

ds: use object-oriented API for epoll

This allows us to cut down on imports and reduce code.
This also makes it easier (in the next commit) to provide an option
to disable epoll/kqueue when saving an FD is valued over scalability.

daemon: depend on DS event_loop in master process, too

The awaitpid API turns out to be quite handy for managing
long-lived worker processes.  This allows us to ensure all our
uses of signalfd (and kevent emulation) are non-blocking.

tests: map CLOFORK->FD_CLOEXEC temporarily for `tail -f'

This fixes `TAIL="tail -F" prove -bvw t/lei-refresh-mail-sync.t'
since that test relies on lacking FD_CLOEXEC to detect dead
lei-daemons, but we still want FD_CLOEXEC when when relying
on tail(1) to check -imapd output.

treewide: favor Xapian (SWIG binding) over Search::Xapian

The Xapian SWIG bindings are favored by Xapian upstream for
ease-of-maintenance compared to the XS version.  While Debian
lags on this front, the SWIG bindings are widely available
on all *BSDs.

xap_helper: relicense C++ implementation to GPL-2.0+

This will allow us to incorporate approxidate time/date parsing
from git.git without needing to relicense git code.

ci/profiles: strip everything after the `-' in utsname.release

This fixes the script under FreeBSD (tested 13.2) FreeBSD 13.2
has `13.2-RELEASE-p3' in its uname(2) utsname.release.  While
the `.2' component is a welcome addition over the old script,
Perl parses the `-' as a subtraction operation, which isn't
what we want.

xap_helper: clamp workers to USHRT_MAX

This allows us to avoid any integer overflow problems while
having enough room to grow for some future hardware, though it
looks like having hundreds of cores isn't ever going to make
it to typical servers nor workstations.

xap_helper: use _OPENBSD_SOURCE on NetBSD for reallocarray

NetBSD prefers reallocarr(3) for predictable zero-sized
allocation behavior; but no other OS seems to have reallocarr(3).
reallocarray(3) appears in by OpenBSD, FreeBSD, glibc, and musl,
so continue to go with that.

xap_helper: note __cleanup__ works with C++ exceptions

In case somebody reviewing this code gets curious.

update CI helper scripts for NetBSD and `pkgin'

ci/profiles: rewrite in Perl

Reading os-release(5) is a bit more painful, now; and still
requires using the shell.  However, sharing code between *BSDs
and being able to use v-strings for version comparisons is much
easier.

Test profiles for *BSDs are also trimmed down and more focused
on portability stuff.

ci/run.sh: parameterize BUILD_JOBS TEST_JOBS and TEST_TARGET

Parallezing BUILD_JOBS is usually harmless, but TEST_JOBS can
be problematic when tracking down problems on new platforms.
TEST_TARGET can be `check' or `check-run' for performance.

ipc: define _SC_NPROCESSORS_ONLN for NetBSD

We'll reorganize this into a hash table for ease-of-reading.

Makefile.PL: check `getconf NPROCESSORS_ONLN', too

NetBSD and OpenBSD getconf(1) don't accept a leading underscore,
while glibc getconf(1) only accepts the leading underscore
(`_NPROCESSORS_ONLN').  FreeBSD getconf(1) accepts both variants.

pop3d: support fcntl locks on NetBSD and OpenBSD

MboxLock already supported it since it locked the whole file,
but POP3D requires more fine-grained locking at file offsets.

I wonder if "struct flock" is old enough for it to be the same
across all the BSDs, it certainly seems so.

I originally considered using C11 `_Generic' support for the
struct offset/type dumping as I have in other projects, but
I am not ready to depend on C11 for this project, yet.

While we're modifying devel/sysdefs-list, add some Linux-only
structs to verify our `pack' templates are correct and remain
so when we encounter new architectures.

imapd: lazy-load IMAPsearchqp for Parse::RecDescent

This enables the t/pop3d.t test to pass when Parse::RecDescent
is not available.

fix some tests when `curl' is missing

Debian-based distros allow uninstalling the `curl' CLI tool
independently of libcurl* packages which git depends on.

ci/deps: redo and fix essential package handling

git depends on p5-TimeDate on FreeBSD, too, so ensure git
doesn't get uninstalled on FreeBSD.  Instead of making
@precious a separate array, we can actually stuff dependencies
into the $non_auto map and save us some code.

We can also eliminate some duplication in $non_auto by
populating the Perl standard library packages in a loop.

ci: updates for OpenBSD

Still a work-in-progress, but OpenBSD's pkg_add/pkg_delete seem
to be working somewhat.  The dependency system seems to need some
extra help to ensure leaf packages with their own dependencies
(e.g.  `xapian-bindings-perl') get uninstalled before their
dependencies (`xapian-core').

Deduplicating the command-line is also required since both
pkg_add and pkg_delete will repeat the installation/removal if
a package is specified multiple times in the same invocation.

ci/deps: drop unnecessary mappings and add Inline

The automatic mapping can work for more packages, so redundant
entries in $non_auto are just clutter.

Unfortunately, `Inline::C' is part of `Inline' on CentOS 7.x and
OpenBSD 7.3, so we'll add $non_auto mappings for those.

We'll also depend on `IO::Compress' to simplify mappings since
that's the CPAN distribution which holds both IO::Compress::Gzip
and IO::Compress::Gunzip and I'm not aware of any packagers who
split them.

ci/deps: add IMAP-related optional packages

Mail::IMAPClient and Parse::RecDescent are widely available in
all relevant OS package/ports systems.

update docs + tests for xapian-delve use

Since -cindex uses the xapian-delve(1) command for `--prune'
functionality, we'll rename our `xapian-compact' dependency to
the Debian package name (xapian-tools) since `xapian-delve' is
in the same package.

fake_inotify: increase directory ctime adjustment window

It actually needs to be bigger than the polling interval.
I suspect I missed this due to parallel tests on a loaded
VM, but running t/dir_idle.t on an unloaded machine reproduces
the problem when neither IO::KQueue nor Linux::Inotify2 are
present.

watch: reset HUP + USR1 signal handlers in children

Child processes handling IMAP/NNTP aren't going to want
to handle config reloads nor forced rescans, those are
exclusively for the parent.  We'll leave a note that
QUIT/TERM/INT can safely use the same callback for both
parent and children, as I nearly made the mistake of
resetting those to their default values in the child.

watch: set %SIG for non-signalfd/kqueue

We need to ensure there isn't a window where we lose $SIG{CHLD}
handling.  This is the second part in getting t/imapd.t to pass
the reload-after-setting-imap.pollInterval test

That said, I'm not entirely happy with the way -watch jumps
in and out of the event loop.  It's historical baggage from
the pre-event_loop days.

ds: fix signals unblock for non-signalfd/kqueue

Using the sigset result of allowset() isn't appropriate for
SIG_UNBLOCK.  We must generate a new signal set off of the $sig
dispatch map for use with SIG_UNBLOCK to actually unblock the
signals.

This is the first part in getting t/imapd.t to pass the
reload-after-setting--imap.pollInterval-test when neither
signalfd nor kqueue are usable.

tail_notify: explicitly detect self deletion

This allows t/tail_notify.t to pass more reliably using
FreeBSD with IO::KQueue.

fake_inotify + kqnotify: rewrite and combine code

KQNotify is now a subclass of FakeInotify since they're both
faking a subset of inotify; and both require directory scanning
via readdir() to detect new/deleted files.

ctime is no longer used with per-file stat to detect new files
with kevent.  That proved too unreliable either due to low
time resolution of the NetBSD/OpenBSD VFS and/or
Time::HiRes::stat being constrained by floating point to
represent `struct timespec', so instead we fuzz the time a bit
if the ctime is recent and merely compare filenames off readdir.

This fixes t/fake_inotify.t and t/kqnotify.t failures under NetBSD
and also removes workarounds for OpenBSD in t/kqnotify.t.  It
also allows us to to remove delays in tests by being more
aggressive in picking up new/deleted files in watch directories
by adjusting the time to scan if the ctime is recent.

This ought to may improve real-world reliability on all *BSDs
regardless of whether IO::KQueue is installed.

xap_helper: fix fcntl() argument order

*sigh*  I only noticed this when running `make check-run' under
OpenBSD.

t/search.t: tweak dir group semantics for all *BSDs

NetBSD shares semantics with FreeBSD and OpenBSD, at least;
and presumably all their *BSD cousins behave the same way.

t/cmd_ipc.t: allow EMSGSIZE send error for NetBSD

NetBSD sendmsg can error out with EMSGSIZE instead of EAGAIN or
ETOOMANYREFS when a socket is non-blocking and the reader isn't
keeping up.

tail_notify: reinstate watch on reopen

This fixes t/tail_notify.t on NetBSD 9.3 where the log file
is deleted and later recreated.

t/watch_filter_rubylang.t: DS->Reset to avoid segfault

Object destruction order needs to be managed manually here to
avoid an occasional segfault at _rthread_mutex_timedlock() with
the following callstack:

XS_DBI_dispatch()
XS_DBD__SQLite__st_DESTROY()
sqlite_st_destroy()
sqlite3_finalize()
_rthread_mutex_timedlock()

...on OpenBSD 7.3 (Perl 5.36, DBD::SQLite 1.70v0, DBI 1.643p0,
sqlite 3.41.0).  I'm not sure exactly where the bug is, but I
suspect it's something inherent in Perl's unpredictable
destruction order at process teardown (something I've had to
workaround in the past when dealing with XS extensions).

There's no downloadable debug-* OpenBSD packages to ease
debugging for these components, either.

dskqxs: get rid of needless confess check

Destruction order is unpredictable at process teardown,
so confessing or warning here is unnecessary, just break
out of the sub since it's for to delete an entry, anyways.

xap_helper: allow non-standard file description flags

pipe2(.., O_CLOEXEC) on NetBSD sets the O_CLOEXEC file description
flag along with the FD_CLOEXEC file descriptor flag, so we must
not attempt to do exact matches on the file description flags.

xap_helper: use rpath for libxapian on NetBSD

While rpath is frowned upon by Debian and other distro packagers; it
appears embraced by in the world of NetBSD ports and packages.  This is
because ldconfig(8) on NetBSD doesn't put /usr/pkg/lib in its search
path by default.  This behavior differs from the ports and packaging
systems of FreeBSD and OpenBSD which do search library paths of
pkg*-installed packages (and presumably ports).

test_common: start_script: set default signals

We need to ensure signal handlers in the child process aren't
inherited from the parent.  This change was originally intended
to block signals all the way until PublicInbox::Daemon and
PublicInbox::Watch were fully ready to handle them (preferably
via EVFILT_SIGNAL or signalfd); but that proved unrealistic.
Now, all signal handlers are restored to their default values
before signals are unblocked.

Drop a redundant DS->Reset while we're at it.

tests: add `+SCM_RIGHTS' as a require_mods target

We'll also ensure the existing `lei' target expands to depend on
`+SCM_RIGHTS', and use require_mods in t/lei-import-nntp.t and
t/lei.t so they can be skipped when Inline::C and Socket::MsgHdr
are missing on OpenBSD.

xap_helper.h: include signal.h for sig* functions

This is documented by all sig* manpages of FreeBSD and Linux,
but only OpenBSD fails to build without this header.

xap_helper: support SIGTTIN+SIGTTOU worker adjustments

Being able to tune worker process counts on-the-fly when
xap_helper gets used with -{netd,httpd,imapd} will be useful
for tuning new setups.

watch: ensure children can use signal handlers

Blindly using the signal set inherited from the parent process
is wrong, since the parent (or grandparent) could've blocked all
signals.  Ensure children can process signals in the event loop
when sig handlers have to use standard Perl facilities.

daemon: workaround pre-EVFILT_SIGNAL signals

FreeBSD and OpenBSD kqueue EVFILT_SIGNAL isn't able to handle
blocked signals which were sent before the filter is created.
This behavior differs from Linux signalfd, which can process
blocked signals that were sent before the signalfd existed.

update devel/syscall-list to devel/sysdefs-list

We use it to dump SIGWINCH and _SC_NPROCESSORS_ONLN, so
"sysdefs" is a more appropriate list for *BSD users.

t/sigfd: better checks related to SIGWINCH

Check to ensure there's a numeric value of SIGWINCH defined for
the given platform.  SIGWINCH may also fire while the test is
running due to a user resizing their terminal, so a boolean test
to ensure it fired rather than an exact value check is more
correct.

t/sigfd: test EVFILT_SIGNAL vs signalfd differences

Verify that observed OpenBSD and FreeBSD EVFILT_SIGNAL behavior
works differently than what Linux signalfd does to ease upcoming
changes to PublicInbox::DS.

ds: don't block important signals we don't use

Don't block SIGABRT, SIGBUS, SIGFPE, SIGILL nor SIGSEGV since
blocking them can hide real bugs in our code or 3rd-party
libraries and executables.

We'll also leave SIGXCPU and SIGXFSZ unblocked since users
may've setup RLIMIT_CPU and RLIMIT_FSIZE, respectively.

Clarify Inline::C dependency (optional on Linux, required elsewhere)

Link: https://public-inbox.org/meta/20230901110903.M876537@dcvr/
Link: https://public-inbox.org/meta/20230902194407.M464597@dcvr/
Fixes: 88c7c7c26b44 ("lei: wire up pure Perl sendmsg/recvmsg for Linux users")
Fixes: acefd91b302d ("syscall: implement sendmsg+recvmsg in pure Perl")

xap_helper: deal with Xapian::DocNotFoundError

It's possible for a long mset streaming operation to hit missing
documents after a database reopen if deletes hit the DB.

xap_helper.h: fix double-free on OpenBSD hdestroy

hdestroy on OpenBSD assumes each key in the table can be freed,
so use strdup to fulfil that requirement.

This behavior differs from tested behavior on glibc and FreeBSD,
as well as what I can see from reading the musl and NetBSD
source code.  OpenBSD may be the only relevant OS which requires
this workaround.

xap_helper.h: limit stderr assignment to glibc+FreeBSD

This fixes the C++ xap_helper compilation on OpenBSD.
Assignable `FILE *' pointers appear to only be supported on
FreeBSD and glibc.  Based on my reading of musl and NetBSD
source code, this should also fix builds on those platforms.

xap_helper.h: don't compress debug sections on OpenBSD

ld(1) on OpenBSD 7.3 doesn't appear to support zlib-compressed
debug sections out-of-the-box.  Oh well, being able to build
this C++ bit at all is required to get acceptable performance
with -cindex --associate.

t/kqnotify: improve test reliability on OpenBSD

Unlike FreeBSD, OpenBSD (tested 7.3) kevent doesn't document
EVFILT_VNODE behavior when directories are being watched.

Regardless, FreeBSD semantics appear to be mostly (if not
unreliably) supported.  Detecting rename(2) isn't reliable
at all and events seem to get lost and the test needs to
retry the rename(2) to succeed.  Fortunately, rename(2)
isn't recommended for Maildirs anyways since it can clobber
existing files.

link(2) detection appears to be merely delayed on OpenBSD,
so the test merely needs an occasional delay.

Makefile.PL: depend on autodie, at least for tests

While using autodie everywhere is not appropriate[*], many of
our tests and FS access code can be easier-to-write and more
readable using autodie as we've started doing in XapHelperCxx.pm
and xap_helper.t

[*] - EAGAIN on non-blocking I/O shouldn't die, nor should
      certain cases of opening maybe-missing files for reading

Makefile.PL: fix syntax for ASan and valgrind targets

Mixing various quoting and escaping rules between shell, make,
and Perl got confusing in Makefile.PL :x  This hopefully sorts
out my confusion.

We'll also fix and use TEST_XH_CXX_ONLY=1 to avoid needlessly
running the tests on the XS||SWIG implementation when we're
checking for memory errors.

Fixes: 2312ca26023fcbe3 (makefile: add targets for ASan and valgrind)

treewide: drop MSG_EOR with AF_UNIX+SOCK_SEQPACKET

It's apparently not needed for AF_UNIX + SOCK_SEQPACKET as our
receivers never check for MSG_EOR in "struct msghdr".msg_flags
anyways.  I don't believe POSIX is clear on the exact semantics
of MSG_EOR on this socket type.  This works around truncation
problems on OpenBSD recvmsg when MSG_EOR is used by the sender.

Link: https://marc.info/?i=20230826020759.M335788@dcvr

t/spawn.t: workaround OpenBSD RLIMIT_CPU delays

RLIMIT_CPU on OpenBSD doesn't work reliably with few syscalls or
on mostly idle systems.  Even at its most accurate, it takes an
extra second to fire compared to FreeBSD or Linux due to
internal accounting differences, but worst case even the SIGKILL
can be 50s delayed.

So rewrite the CPU burner script in Perl where we can unblock
SIGXCPU and reliably use more syscalls.

Link: https://marc.info/?i=20230829010110.M269767@dcvr

public-inbox-init: honor umask when creating config file

Creating config 0600 disregarding umask breaks scenarios where daemons
run with credentials different from config owner (but need to read the
config).

File::Temp defaults to 0600, which is unsuitable for the
recommended/typical scenario of daemons running unprivileged and with
UID different from $PI_CONFIG owner, as the deamons need to read
$PI_CONFIG.

Respecting umask might end up creating world-unreadable config, too,
but for people who use such umask that's expected behavior.

doc: daemon: clarify TLS and well-known ports

Reported-by: Štěpán Němec <stepnem@smrk.net>

Fix some typos/grammar/errors in docs and comments

spawn: remove distracting empty line

If anything, it should have been before the $rlim declaration, not
after, but the immediately preceding similar block has no empty line,
either.

spawn: remove stray variable $ndc_err

Code that could be setting it was removed in 14fa0abdcc7b.
Likewise for the double assignment to $err.

Fixes: 14fa0abdcc7b ("rewrite Linux nodatacow use in pure Perl w/o system")

watch: remove unused variable

ci/profiles.sh: fix case matching logic

'-' could never match, remove that alternative (it might have been a
typo of '--', but that is already covered by '*--|--*' ('*' matches
the null string)).

Replace '*--*' with the equivalent '*' ('--' is always present).

It would seem clearer to just replace the whole case command with
something like '[ "$ID" -a "$VERSION_ID" ] && break' (or the
POSIX-non-deprecated equivalent '[ "$ID" ] && [ "$VERSION_ID" ]' ); I
assume a preference of using case here (e.g., to avoid syscall
overhead in case [ is not implemented as a shell builtin (which seems
far-fetched given the context, though)).

t/xap_helper: skip test if missing SCM_RIGHTS support

xap_helper currently relies on FDs passed via SCM_RIGHTS for
robustness against $TMPDIR failures and over-eager FS cleanup
tasks.  This depends on stable syscall numbers (Linux) or
Inline::C||Socket::MsgHdr being available, though, as Perl5
itself doesn't support SCM_RIGHTS.

We could probably add FIFO support to xap_helper for portability
to systems where neither Inline::C nor Socket::MsgHdr are available,
but that's for another day.

cindex: make prune work without SCM_RIGHTS support

We don't have to create extra pipes to pass around, actually.
Sending records via send/sendmsg isn't noticeably more expensive
than writing to a pipe.

xap_helper: fix C++-specific warnings

While initialization of zeroed structs in C is done via `{0}',
I've just learned from g++(1) that C++ uses `{}'.  I can't seem
to get use of a single designated initializer to compile without
warnings in C++, either, so we'll just initialize them as zero
and assign them ASAP for __cleanup__ functions.

This fixes compilation warnings under -Wextra in g++ (Debian 10.2.1-6)
which adds -Wmissing-field-initializers.  This also fixes compilation
warnings under -Wall in clang (FreeBSD 13.0.0) from -Wmissing.

cindex: document pipelines created for prune

This ought to make things easier-to-understand for people
reading the code for the first time (or rereading it for the
first time in a few days :x)

makefile: add targets for ASan and valgrind

I would never consider working on C++ code without at least one
one of these tools present.

t/psgi_scan_all: reduce use_ok statements

This can save a handful of cycles to avoid testing things which
are already implicit from other tests.

doc: INSTALL: note OpenBSD xapian-bindings-perl package

The `xapian-bindings-perl' package contains the Xapian.pm
SWIG bindings, but doesn't adhere to the existing convention
of naming system packages after the Perl package name itself
using: "p5-${\($Perl_package_name =~ s/::/-/gr)}".

Reported-by: Štěpán Němec <stepnem@smrk.net>
Link: https://public-inbox.org/meta/20230824132323+0200.507058-stepnem@smrk.net/

cindex: dump cidx shards before inboxes

Since cidx shards used for associations are typically bigger
than individual inboxes, we'll dump them first to get better
work scheduling for xap_helper processes.

This gives roughly a 5% performance improvement with doing
a full associate on (git+lore).kernel.org

t/cindex: avoid reading default PI_CONFIG

I sometimes test on a machine with a broken
~/.public-inbox/config to detect inadvertant accesses in tests

drop unused CidxRecvIbx.pm

This is no longer needed since xap_helper performs its
functionality while having an optional C++ implementation
which is being significantly faster.

xap_helper: reopen+retry in MSetIterator loops

It's possible to hit a DatabaseModifiedError while iterating
through an MSet.  We'll retry in these cases and cleanup some
code in both the Perl and C++ implementations.

cindex: implement dump_roots in C++

It's now just `dump_roots' instead of `dump_shard_roots', since
this doesn't need to be tied to the concept of shards.  I'm
still shaky with C++, but intend to keep using stuff like
hsearch(3) to make life easier for C hackers :P

cindex: fix sorting and uniqueness

We can't rely on combining the `-u' and `-k1,1' switches of POSIX
sort(1) to do what we want.  So only rely on `sort -k1,1' while
introducing a small Perl helper to fold identical prefixes into
one line.  In other words, input such as:

  deadbeef 0
  deadbeef 1
  deadbeef 2

Was getting deduplicated into a single line:

  deadbeef 0

... with `sort -u -k1,1'
This makes puts the output into a more optimal form for eventual
(not-fully-implemented-yet) parsing:

  deadbeef 0,1,2

ORS is current the comma (`,') for inbox IDs, but it'll be a
space (` ') for coderepo root IDs.  This implementation also
combines identical IDs in the 2nd column.  Thus:

  deadbeef 0
  deadbeef 0

Becomes a single `deadbeef 0' line thanks to the use of
XS List::Util::uniq (which beats a pure Perl hash).

I attempted to implement this in awk but Perl is close enough to
gawk in performance while being shorter and easier-to-understand
due to List::Util::uniq.  mawk was faster, but still not enough
to matter as the bottleneck is from iterating through Xapian
MSets.

introduce optional C++ xap_helper

This allows us to perform the expensive "dump_ibx" operations in
native C++ code using the Xapian C++ library.  This provides the
majority of the speedup with the -cindex --associate switch.

Eventually this may be expanded to cover all uses of Xapian
within the project to ensure we have access to Xapian APIs which
aren't available in XS|SWIG bindings; and also for
ease-of-installation on systems which don't provide
pre-packaged Perl Xapian bindings (e.g. OpenBSD 7.3) but
do provide Xapian development libraries.

Most of the C++ code is still C, as I'm not remotely familiar
with C++ compared to C.  I suspect many users and potential
hackers being from git, Linux kernel, and glibc world are in the
same boat.

cindex: add --show-roots switch

This aids in development, but I'm not sure it's going to stay
or be moved into another interface.

cindex: read-only association dump

This will eventually allow associating coderepos with inboxes
and vice-versa; avoiding the need for manual configuration via
tedious publicinbox.*.coderepo directives.

I'm not sure how this should be stored for WWW, yet, but it's
required since it takes about 8 hours to do this fully across
lore and git.kernel.org.

search: hoist out shards_dir for future use

This will be useful for internal tooling and APIs.

ipc: support _SC_NPROCESSORS_ONLN on OpenBSD

Tested on both amd64 and i386, and these constants tend to be
architecture-independent.

isearch: avoid hex string for Xapian sortable_serialise

While a string representing a integer in hex is fine for DBI and
SQLite, Xapian's sortable_serialise requires a Perl integer value.
So just retrieve the last Xapian DB document ID in this rare
code path because we can't use 64-bit integer literals in some
32-bit Perl builds (e.g. OpenBSD on i386)

Fixes: be2a0a353d60 ("isearch: support 64-bit article numbers for SQLite query")

t/nntp.t: attempt to quiet spurious uninitialized warnings

When running via t/run.perl ("make check-run") to reduce test
startup time, t/nntp.t occasionally hits uninitialized variable
warnings in the quote_str sub.  I can't reproduce these
reliably, but scoping subs in tests reduces the chance of
conflict when we reuse interpreters.

search: all_terms: remove needless prefix check

The ->allterms_{begin,end} methods of Xapian::Database already
filter match on prefix natively.   Thus there's no need to do
filtering ourselves (unlike per-document ->termlist_{begin/end})

doc: extindex: note the use of `newsgroup' entries

We'll also be using this for -cindex for associating inboxes
to coderepos.

doc: *index: fix misuse of apostrophe in `its'

Reported-by: Kyle Meyer <kyle@kyleam.com>
Link: https://public-inbox.org/meta/87leeovmig.fsf@kyleam.com/

doc: clone: add a note about git 2.41+ and fetch.hideRefs

It's unusable for large mirrors, otherwise.

doc: add manpage for -cindex

It's similar to a combination of -index and -extindex but
perhaps more refined this time around...

clone: allow running without DBI / DBD::SQLite

Due to historic reasons, LeiQuery.pm gets loaded with LEI.pm and
-clone depends on LEI.  So delay loading any DBI-dependent
modules until querying is actually required.

Makefile.pl: *.cols: account for non-UTF-8-aware awk

When checking line length limits, the `length()' function of
mawk doesn't count non-ASCII characters properly in UTF-8
locales.  Force the man(1) output to use C locale and use normal
`-' instead of multi-byte dash characters.

tail_notify: cleanups and wakeup avoidance

Avoid adding redundant watches at initialization, and avoid
unnecessarily wake ups when no timeout is specified.

tests: t/run.perl: fix invocations with <10 tests

We must account for the maximum index of an array to avoid
filling unused slots with `undef' from out-of-bounds reads.
This is needed to avoid undefined entry errors in workers when
fewer than 10 tests are run.  We'll also silence the message
when a single test is run.

While I was diagnosing this, I also noticed a small
simplification and optimization in our generation of $todo_buf
since I initially thought that was the cause of undefined
entry errors in the $todo arrayref.