installed headers don't compile

[elliefm]

Cyrus installs a bunch of its headers so that other software can compile against the various libcyrus* libraries. But if you try that it doesn't work, because of various problems in the headers that come of us assuming our code is always compiled from within the cyrus-imapd source tree.

This PR fixes some, but not all, of those issues. It also adds example source files for calling the working parts of the Cyrus libraries, and adds a LibCyrus test suite to Cassandane to make sure they do actually compile and link correctly.

There's a lot more to fix in this space, but nobody's really asking for it anymore, and I ran out of steam months ago. Here's a cleaned-up version of the former work in progress so we at least get some benefit from it, and future efforts to fix this stuff will already have test infrastructure ready to go.

Original description:
The Debian package maintainer privately reported a problem from the abi-compatibility-checker not being able to run due to the installed headers not compiling. This is part of Debian's work to switch to 64-bit time_t on some 32-bit platforms. Further details in https://cyrus.topicbox.com/groups/devel/T7b15dfc105949d4e-Meae606200efd965cc932318f

I'm using this PR to accumulate the fixes that we need to get the abi-compatibility-checker to actually run.

[dilyanpalauzov]

I thought your plan is to prefix in all #includes with a lib/, when appropriate. assert.h without lib/ can get very confusing and by tweaking CFLAGS replaced by assert from libc.

[elliefm]

That was my plan (#3044), but until now I hadn't properly considered if or how these headers work when they're installed for use by third-party software that wants to link against libcyrus, and it turns out that's been broken by some of my changes in this direction.

Hopefully, cleaning it up enough for the abi-compatibility-checker to work will shake out the issues, and reveal a clear path forward.

[dilyanpalauzov]

That was my plan (#3044), but until now I hadn't properly considered if or how these headers work when they're installed for use by third-party software that wants to link against libcyrus, and it turns out that's been broken by some of my changes in this direction.

Hopefully, cleaning it up enough for the abi-compatibility-checker to work will shake out the issues, and reveal a clear path forward.

I do not understand how installing or not a header somewhere under /usr/include/cyrus/ is related to the Binary Interface compatibility. How do third party software stop working correctly, if Cyrus installs a .h file?

[elliefm]

I do not understand how installing or not a header somewhere under /usr/include/cyrus/ is related to the Binary Interface compatibility.

It's not, really.

The Debian people needed to know whether the ABI would be compatible when they change some of their 32 bit platforms to use 64-bit time_t. They have a tool to check for this automatically, but it wants to compile the installed header files, which fails because some of them rely on stuff like config.h which isn't installed.

We've since established that the packages won't be ABI compatible, and so the Debian people will set their packages up to accommodate that. The tool no longer matters particularly... but the installed headers are still broken.

So it's not that the headers are a problem for ABI compatibility; they're a problem because they don't compile. It just so happens that it was the ABI compatibility checker that made us notice they don't compile.

[dilyanpalauzov]

My understanding now is, that cyrus-imap installs header files, which in some way depend on conifg.h.

[dilyanpalauzov]

How is this in xsha1.h supposed to work? Including xsha1.h either works nicely, when config.h is not available, or it fails. But it cannot work good with or without config.h, but still include config.h.

#if HAVE_CONFIG_H
#include <config.h>
#endif

My understaning is that this change is supposed to install only headers, which do not use config.h. util.h does use config.h, util.h is not installed. mappedfile.h, sqldb.h, imapurl.h, crc32.h, charset.h, rfc822tok.h are installed and do include util.h and thus depend on config.h. I addressed “util.h in charset.h” at #5108.

[elliefm]

xsha1.h needs config.h so we can check HAVE_SSL, which determines whether cyrus-imapd was configured to use openssl's sha1 implementation, or the internal libcyrus one.

If xsha1.h is being used outside the cyrus-imapd source tree, and therefore config.h is unavailable, the guards make sure we don't #include it. In this case, HAVE_SSL will also be undefined, so outside users of libcyrus will always get the libcyrus sha1 implementation, not the openssl one.

This goes hand in hand with the other change in this file, which makes sure the libcyrus sha1 implementation is always compiled into the library, even if cyrus-imapd is using the openssl one.