alibaba / alibaba/paimon-cpp

Improve paimon-cpp CMake structure toward modern best practices

Open
#260 2 comments 4 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.