Improve paimon-cpp CMake structure toward modern best practices
- Dominant language
- C++
- Stars
- 131
- Forks
- 49
- PR merge metrics
- No merged PRs in 30d
Description
## Motivation
The current paimon-cpp CMake build works, but it has accumulated a number of legacy patterns that make the build harder to maintain, less portable, and harder for downstream users to consume.
This is related to the dependency-management work in #103 / #259, but the broader CMake modernization should be tracked separately. The goal of this issue is to move paimon-cpp toward modern, target-based CMake best practices in incremental PRs.
## Current Problems
Some notable issues in the current build structure:
- `PaimonConfig.cmake.in` manually creates imported targets with hardcoded library paths.
- It hardcodes `.so`, which is not portable.
- It uses install-time absolute paths, making packages less relocatable.
- It does not use `install(EXPORT ...)` / generated `PaimonTargets.cmake`.
- It does not declare transitive dependencies with `find_dependency(...)`.
- It does not provide a namespaced public target such as `Paimon::paimon`.
- The root CMake files still use many directory-scope commands:
- `add_definitions(...)`
- `include_directories(...)`
- `link_directories(...)`
These make dependency propagation harder to reason about and can leak flags/includes into unrelated targets or external builds.
- Some linker flags are GNU ld specific:
- `--exclude-libs`
- `--version-script`
- `-Bsymbolic`
- `-z,defs`
- `--gc-sections`
These should be guarded or expressed in a portable way.
- C and C++ compile flags are mixed through global variables instead of target usage requirements and language-specific generator expressions.
- Third-party build helpers are mostly implemented as `macro()` and rely on variable leakage. This makes system/bundled dependency switching fragile.
- Target naming is inconsistent. Some dependencies use namespaced targets, while others use plain target names.
## Proposed Direction
This should be done incrementally. Possible steps:
1. Replace the handwritten `PaimonConfig.cmake.in` with standard package export support.
- Use `install(EXPORT ...)`.
- Generate `PaimonTargets.cmake`.
- Introduce namespaced public targets such as `Paimon::paimon`.
- Use `CMakeFindDependencyMacro` and `find_dependency(...)`.
2. Move compile options and definitions to target-based interface libraries.
- Introduce something like `paimon_compile_options`.
- Use `target_compile_features(...)`.
- Use `target_compile_definitions(...)`.
- Use `$` generator expressions where needed.
3. Reduce directory-scope side effects.
- Gradually remove global `include_directories(...)`, `add_definitions(...)`, and `link_directories(...)`.
- Prefer `target_include_directories(...)`, `target_link_libraries(...)`, and `target_link_options(...)`.
4. Improve portability of linker and shell commands.
- Guard platform-specific linker flags.
- Replace shell-specific commands with `${CMAKE_COMMAND} -E ...` where possible.
5. Gradually make third-party dependency handling more target-based.
- Avoid relying on leaked include/library variables.
- Prefer imported targets and explicit usage requirements.
- Consider converting selected `build_*` macros to functions where practical.
6. Discuss a longer-term dependency strategy separately.
- Package-manager-specific integration and dependency version policy should be evaluated independently from the initial CMake structure cleanup.
## Expected Outcome
After these changes, paimon-cpp should be easier to:
- consume via `find_package(Paimon CONFIG REQUIRED)`;
- build across different platforms;
- maintain as dependency options grow;
- reason about through target-based CMake usage requirements;
- package and relocate after installation.
## Scope
This issue is intended as a tracking issue for CMake modernization. It does not need to be solved in one PR. Smaller focused PRs are preferred.
Contributor guide
Research direction
Start with PaimonConfig.cmake.in and the root CMake files to map the existing package export, directory-scope settings, and target definitions. Choose one focused modernization step from the proposed direction; done should be a scoped change that improves target-based usage or portability without attempting the entire tracking issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cmake, cpp
- Domain
- build-system
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100