Feature Request: Move public API headers to include/librdkafka/

[stertingen]

Description

The examples have the following lines:

/* Typical include path would be <librdkafka/rdkafka.h>, but this program
 * is builtin from within the librdkafka source tree and thus differs. */
//#include <librdkafka/rdkafka.h>
#include "rdkafka.h"

I propose to move the public API headers into new directories at include/librdkafka and adjust the Makefiles and CMake-Files to add this as a new include directory.

If I want to use librdkafka in my project, there are to ways to do this:

1. Install the library somewhere on my system. The public API headers are at `<librdkafka/librdkafka.h>
2. Include the librdkafka source code in a subfolder and link static. The public API headers are not installed, they are available at <librdkafka.h> with src/ added to the include directories.

By moving rdkafka.h, rdkafka_mock.h and rdkafkacpp.h into include/librdkafka, I would add include/ to my include directories for the second case.

Checklist

IMPORTANT: We will close issues where the checklist has not been completed.

Please provide the following information:

• [x] librdkafka version (release number or git tag): v1.9.2
• [x] Apache Kafka version: (not relevant since this is a build issue)
• [x] librdkafka client configuration: (default configuration)
• [x] Operating system: Ubuntu 20.04 in WSL
• [x] Provide logs (with debug=.. as necessary) from librdkafka (not available since this is a build issue)
• [x] Provide broker log excerpts (not available since this is a build issue)
• [x] Critical issue: Not critical.

[edenhill]

I think your proposal makes sense, but it has implications on a lot of derived projects that package or bundle librdkafka in various ways - so it needs to be done with care and ample warning.

Could an interim solution be to create include/ and then symlink the public headers from their original src/ and src-cpp/ locations? Not sure how well that works on Windows though.

[stertingen]

I think your proposal makes sense, but it has implications on a lot of derived projects that package or bundle librdkafka in various ways - so it needs to be done with care and ample warning.

Could an interim solution be to create include/ and then symlink the public headers from their original src/ and src-cpp/ locations? Not sure how well that works on Windows though.

We could have compatibility headers in src/ and src-cpp/ with includes to <librdkafka/*.h> and maybe a deprecation warning. We should avoid recursive inclusion, though.

EDIT: Never mind, this solution would require to change the include paths anyway.

EDIT 2: The other way round should work. Have new headers at include/librdkafka/* including the old headers. New projects would have all include, src and src-cpp as include paths during a transition period (easily implemented in CMake). src/rdkafka.h and companions emit a deprecation warning when included directly.