Proposal to Restructure C++ Public Headers

[ColinLee <sh...@163.com>]

Hi everyone,

Our current C++ header organization and packaging approach is not ideal.

When TsFile is built and packaged, a large number of headers from the source directories are copied into the release package. 
As a result, users who install the C++ package need to install and include what is effectively a full development header package, including many internal implementation headers that are not required for normal API usage.

This creates several issues:

- Users need to install and manage many unnecessary internal headers.
- The boundary between the public API and internal implementation is unclear.
- Header dependencies are larger than necessary, which can increase compilation times.
- External projects may unintentionally depend on internal implementation details.
- Future internal refactoring becomes more difficult due to compatibility concerns.

Apache Arrow provides a good reference for addressing this problem. It separates public API headers from internal implementation headers, provides entry-point headers such as `api.h`, and only installs the headers intended for public use.

I propose that we restructure the TsFile C++ headers in a similar direction:

1. Create a dedicated public include directory, such as `include/tsfile/`.
2. Move stable APIs, including Reader, Writer, Schema, and Tablet interfaces, into this directory.
3. Keep implementation-specific headers, such as encoders, page writers, block readers, caches, and generated parser headers, under `src/`.
4. Add umbrella headers such as `tsfile/api.h` as the primary user entry points.
5. Update the CMake and packaging logic to install only public headers.
6. Add standalone compilation tests for each public header.
7. Provide a proper CMake package target that distinguishes build-time dependencies from installed consumer dependencies.

As a short-term step, we could stop recursively exporting all source headers and instead maintain an explicit list of public headers. The directory restructuring and API boundary cleanup can then be completed incrementally.

This change should reduce the size and complexity of the user-facing package, improve integration and compilation times, provide a clearer public API, and make future internal refactoring safer.

Please share your thoughts on this direction. We can follow up by defining the initial public header list and a phased migration plan.

Best regards,  
Colin