feat: Support macOS builds with AppleClang and Homebrew Clang by suxiaogang223 · Pull Request #279 · alibaba/paimon-cpp

suxiaogang223 · 2026-05-13T06:26:46Z

Summary

enable macOS builds by handling Darwin-specific linker flags, library output behavior, and logging compatibility
adjust bundled dependency configuration for macOS, including Arrow/ORC-related build fixes and static/shared target handling
support Homebrew LLVM clang on macOS by using Apple SDK libc++ headers for upstream Clang builds
document verified macOS build flows for AppleClang and Homebrew clang

Related Issue

Part of #260.

Motivation

paimon-cpp could not be built cleanly on macOS with the bundled dependency path. The failures came from a mix of Linux-specific linker options, macOS dynamic library naming/runtime differences, bundled third-party build assumptions, and compiler/header compatibility issues.

This PR first makes the project build with AppleClang from Xcode Command Line Tools. It then extends the CMake setup so developers can also use Homebrew LLVM clang without manually patching bundled third-party sources. For upstream Clang on macOS, CMake defaults to Apple SDK libc++ headers to avoid current incompatibilities in bundled fmt and Arrow's bundled thrift when using the newest Homebrew libc++ headers.

Validation

AppleClang release build:
- cmake -S . -B build-macos-fix3 -DPAIMON_DEPENDENCY_SOURCE=BUNDLED -DPAIMON_BUILD_TESTS=OFF
- cmake --build build-macos-fix3 -j8
Homebrew LLVM clang 22 release build:
- cmake -S . -B build-macos-homebrew-clang22-cmake-auto -DPAIMON_DEPENDENCY_SOURCE=BUNDLED -DPAIMON_BUILD_TESTS=OFF -DCMAKE_C_COMPILER=/opt/homebrew/opt/llvm/bin/clang -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++
- cmake --build build-macos-homebrew-clang22-cmake-auto -j8

suxiaogang223 · 2026-05-15T08:55:06Z

Hi @zjw1111 , could you please help take a look at this PR when you have time?

This change adds macOS build support for both AppleClang and Homebrew Clang. I think this would be useful for local development because many contributors use macOS as their daily environment, and being able to configure, build, and run checks locally makes it easier to validate changes before opening PRs.

It should also help reduce the feedback cycle for dependency/CMake related work: developers can reproduce more issues locally instead of relying only on Linux CI, while keeping the existing Linux build paths unchanged.

Thanks!

Copilot

Pull request overview

Enables building paimon-cpp on macOS (AppleClang and Homebrew LLVM Clang) by adjusting platform-specific CMake/linking behavior, improving third-party bundled dependency configuration, and updating build documentation to include verified macOS flows.

Changes:

Add macOS-aware handling for GNU-specific linker flags, dl linking, and gLog initialization program-name retrieval.
Adjust bundled third-party build configuration (notably Protobuf/Zlib, ORC rpath handling, and imported target properties for Arrow/TBB).
Document verified macOS build commands for AppleClang and Homebrew Clang, including a new Clang/libc++ headers option.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/paimon/common/logging/logging.cpp	Makes gLog initialization portable by using an OS-specific program-name source.
src/paimon/CMakeLists.txt	Avoids linking `dl` on macOS by conditionally appending it only on non-Apple platforms.
README.md	Updates the “verified builds” statement to include macOS arm64.
docs/source/building.rst	Adds macOS build instructions for AppleClang and Homebrew Clang; updates general build examples.
CMakeLists.txt	Adds a macOS Clang/libc++ headers option and disables version-script flags on Apple.
cmake_modules/ThirdpartyToolchain.cmake	Tweaks bundled dependency builds (Protobuf Zlib args, ORC rpath flags, Arrow/TBB imported target properties).
cmake_modules/SetupCxxFlags.cmake	Adds logic to use Apple SDK libc++ headers when building with upstream Clang on macOS.
cmake_modules/BuildUtils.cmake	Guards GNU-ld-specific shared-library linker options on non-Apple platforms only.
cmake_modules/arrow.diff	Updates Arrow patching to accept macOS `libtool` version-string variants and adds CMake policy compatibility.
build_support/run_clang_tidy.py	Updates shebang to `python3`.
build_support/run_clang_format.py	Updates shebang to `python3`.
build_support/iwyu/iwyu.sh	Uses `${PYTHON:-python3}` instead of `python`.
build_support/iwyu/iwyu_tool.py	Updates shebang and usage example to `python3`.
build_support/asan_symbolize.py	Updates shebang to `python3`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

zjw1111

Great work, and thanks for the improvement!

I have a quick question: is this intended to be an intermediate version that supports building on macOS?

I noticed that the current codebase can now build successfully on macOS in the default configuration. However, if -DPAIMON_BUILD_TESTS=ON is enabled, there still seem to be some build issues. For example, a few linker flags such as --whole-archive and --no-as-needed are ELF-specific and are not supported by the macOS toolchain.

So I’m wondering whether:

full macOS support is planned in follow-up changes, or
we only intend to make the main build pass on macOS

Thanks again for the work!

suxiaogang223 · 2026-05-19T03:10:06Z

Great work, and thanks for the improvement!

I have a quick question: is this intended to be an intermediate version that supports building on macOS?

I noticed that the current codebase can now build successfully on macOS in the default configuration. However, if -DPAIMON_BUILD_TESTS=ON is enabled, there still seem to be some build issues. For example, a few linker flags such as --whole-archive and --no-as-needed are ELF-specific and are not supported by the macOS toolchain.

So I’m wondering whether:

full macOS support is planned in follow-up changes, or

we only intend to make the main build pass on macOS

Thanks again for the work!

My goal is to support macOS builds as fully as possible, not just the default build configuration.

For example, making -DPAIMON_BUILD_TESTS=ON work on macOS is very helpful for developers, because it allows them to build and validate tests locally before submitting changes. I’ve updated the test-linking path to avoid ELF-specific linker flags on macOS while keeping the existing Linux behavior unchanged.

suxiaogang223 · 2026-05-19T05:09:04Z

This pr rely on #282, it will be rebased after pr#282 merged

mrdrivingduck · 2026-05-19T06:37:27Z

@suxiaogang223 Amazing work!

suxiaogang223 · 2026-05-22T17:05:56Z

@zjw1111 Thanks for the suggestions on improving the CMake structure and making the linking logic cleaner. I have updated the code following your direction :)

zjw1111 · 2026-05-25T10:06:13Z

I re-tested the latest PR head on macOS with tests enabled:

cmake -S . -B build-pr279-tests -DPAIMON_DEPENDENCY_SOURCE=BUNDLED -DPAIMON_BUILD_TESTS=ON
cmake --build build-pr279-tests -- -j4

The configure step succeeds, and Arrow/Brotli now use the bundled path correctly, but the build still fails while linking paimon-orc-format-test:

Undefined symbols for architecture arm64:
  "paimon::Literal::Literal<long>(long const&)", referenced from:
      paimon::orc::test::PredicateConverterTest_TestSimple_Test::TestBody()
      paimon::orc::test::PredicateConverterTest_TestCompound_Test::TestBody()
      paimon::orc::test::PredicatePushdownTest_...
ld: symbol(s) not found for architecture arm64

The immediate cause appears to be calls such as Literal(5l) / Literal(10l) in the ORC predicate tests. On macOS, the l suffix instantiates Literal<long>, while literal.cpp only explicitly instantiates the constructor for int64_t; on this platform int64_t is long long, not long.

Could you please make the BIGINT test literals platform-independent, for example by using Literal(static_cast<int64_t>(5)). After that, PAIMON_BUILD_TESTS=ON should be re-run on macOS to verify the test targets link successfully.

suxiaogang223 · 2026-05-26T16:57:56Z

I re-tested the latest PR head on macOS with tests enabled:
cmake -S . -B build-pr279-tests -DPAIMON_DEPENDENCY_SOURCE=BUNDLED -DPAIMON_BUILD_TESTS=ON
cmake --build build-pr279-tests -- -j4
The configure step succeeds, and Arrow/Brotli now use the bundled path correctly, but the build still fails while linking paimon-orc-format-test:
Undefined symbols for architecture arm64:
  "paimon::Literal::Literal<long>(long const&)", referenced from:
      paimon::orc::test::PredicateConverterTest_TestSimple_Test::TestBody()
      paimon::orc::test::PredicateConverterTest_TestCompound_Test::TestBody()
      paimon::orc::test::PredicatePushdownTest_...
ld: symbol(s) not found for architecture arm64
The immediate cause appears to be calls such as Literal(5l) / Literal(10l) in the ORC predicate tests. On macOS, the l suffix instantiates Literal<long>, while literal.cpp only explicitly instantiates the constructor for int64_t; on this platform int64_t is long long, not long.

Could you please make the BIGINT test literals platform-independent, for example by using Literal(static_cast<int64_t>(5)). After that, PAIMON_BUILD_TESTS=ON should be re-run on macOS to verify the test targets link successfully.

Thank you for your review:) I didn't consider all CMake compilation options during my local verification. Perhaps we should add a corresponding macOS verification CI pipeline after this pr merged to ensure compilation stability on macOS.

zjw1111 · 2026-05-27T04:01:44Z

LGTM! Could you take a review? @lucasfang

zjw1111 · 2026-05-27T05:26:27Z

Thank you for your review:) I didn't consider all CMake compilation options during my local verification. Perhaps we should add a corresponding macOS verification CI pipeline after this pr merged to ensure compilation stability on macOS.

Thanks for the suggestion. I agree that adding macOS verification would help keep the build stable.

We plan to add a macOS compilation CI pipeline after the Apache migrate is completed, so future changes can be verified on macOS more consistently.

lucasfang · 2026-05-27T08:20:40Z

LGTM！

LGTM! Could you take a review? @lucasfang

LGTM！

lucasfang

+1

suxiaogang223 changed the title ~~[codex] Support macOS builds~~ [codex] Support macOS builds with AppleClang and Homebrew Clang May 13, 2026

suxiaogang223 changed the title ~~[codex] Support macOS builds with AppleClang and Homebrew Clang~~ build: Support macOS builds with AppleClang and Homebrew Clang May 13, 2026

suxiaogang223 marked this pull request as ready for review May 13, 2026 06:31

suxiaogang223 changed the title ~~build: Support macOS builds with AppleClang and Homebrew Clang~~ feat: Support macOS builds with AppleClang and Homebrew Clang May 13, 2026

zjw1111 requested a review from Copilot May 15, 2026 13:41

Copilot started reviewing on behalf of zjw1111 May 15, 2026 13:41 View session

Copilot AI reviewed May 15, 2026

View reviewed changes

Comment thread cmake_modules/ThirdpartyToolchain.cmake Outdated

Comment thread docs/source/building.rst

zjw1111 reviewed May 18, 2026

View reviewed changes

Comment thread src/paimon/CMakeLists.txt Outdated

suxiaogang223 added 13 commits May 21, 2026 14:25

Support macOS build with AppleClang

af45f40

Support Homebrew Clang on macOS

20f58c1

Format macOS build changes

c8c4634

Use default build directory in docs

e03a8c9

Align macOS build docs

495155c

Fix bundled Arrow dependency linkage

1540899

Use python3 for build support scripts

30785ef

Address Copilot review comments

d7df513

Format CMake changes

f420029

fix: make macOS test linking portable

cd5865f

fix: clean up macOS CMake options

709fcaf

style: apply cmake format

d63e961

fix: reuse managed deps in bundled Arrow build

ec4fbab

suxiaogang223 force-pushed the codex/macos-build-support branch from 8d5b93b to ec4fbab Compare May 21, 2026 06:26

zjw1111 reviewed May 22, 2026

View reviewed changes

Comment thread CMakeLists.txt Outdated

Comment thread CMakeLists.txt Outdated

Comment thread CMakeLists.txt Outdated

Comment thread src/paimon/CMakeLists.txt Outdated

Comment thread src/paimon/CMakeLists.txt Outdated

fix: refine test plugin link helpers

7ef9dd7

fix: improve macos orc test portability

6ce819e

zjw1111 added 2 commits May 27, 2026 10:43

Merge branch 'main' into codex/macos-build-support

52cac3c

Merge branch 'main' into codex/macos-build-support

d26f7df

lucasfang approved these changes May 27, 2026

View reviewed changes

lucasfang merged commit 6dffe8a into alibaba:main May 27, 2026
9 checks passed

Conversation

suxiaogang223 commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Motivation

Validation

Uh oh!

suxiaogang223 commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

zjw1111 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

suxiaogang223 commented May 19, 2026

Uh oh!

suxiaogang223 commented May 19, 2026

Uh oh!

mrdrivingduck commented May 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

suxiaogang223 commented May 22, 2026

Uh oh!

zjw1111 commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

suxiaogang223 commented May 26, 2026

Uh oh!

zjw1111 commented May 27, 2026

Uh oh!

zjw1111 commented May 27, 2026

Uh oh!

lucasfang commented May 27, 2026

Uh oh!

lucasfang left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

suxiaogang223 commented May 13, 2026 •

edited

Loading

suxiaogang223 commented May 15, 2026 •

edited

Loading

zjw1111 left a comment •

edited

Loading

zjw1111 commented May 25, 2026 •

edited

Loading