feat: make public headers consumable as C++20 in compat mode (#936)

Enable C++20 consumers to include and use iceberg-cpp’s installed public headers when the library is built with ICEBERG_CXX20_COMPAT=ON, while keeping iceberg-cpp implementation code and internal workflows on C++23. C++23 remains the default public API.

Restore the vendored iceberg::expected backport — brings back src/iceberg/compat/expected.h from #40 (removed by [#139](#139)), with its test and LICENSE entry. unexpected's comparison operators now go through error().

cpp20_compatibility_test compiles all public headers as C++20, and the C++20 example links against an installed compatibility package.

Fix #928

Author: PingLiuPing

.github/.licenserc.yaml

@@ -29,6 +29,7 @@ header:
     - 'LICENSE'
     - 'NOTICE'
     - 'requirements.txt'
+    - 'src/iceberg/compat/expected.h'
     - 'src/iceberg/util/murmurhash3_internal.*'
     - 'src/iceberg/test/resources/**'
     - 'src/iceberg/catalog/hive/gen-cpp/**'

.github/workflows/aws_test.yml

@@ -126,7 +126,15 @@ jobs:
         shell: bash
         env:
           CMAKE_TOOLCHAIN_FILE: ${{ startsWith(matrix.runs-on, 'ubuntu') && matrix.bundle_awssdk == 'OFF' && '/usr/local/share/vcpkg/scripts/buildsystems/vcpkg.cmake' || '' }}
-        run: ci/scripts/build_iceberg.sh "$(pwd)" OFF ON ${{ matrix.s3 }} ${{ matrix.sigv4 }} ${{ matrix.bundle_awssdk }}
+        run: |
+          ci/scripts/build_iceberg.sh \
+            --source-dir "$(pwd)" \
+            --build-type Debug \
+            --sccache ON \
+            --rest-integration-tests OFF \
+            --s3 ${{ matrix.s3 }} \
+            --sigv4 ${{ matrix.sigv4 }} \
+            --bundle-awssdk ${{ matrix.bundle_awssdk }}
       - name: Save sccache
         if: always()
         uses: ./.github/actions/save-sccache

.github/workflows/cpp-linter.yml

@@ -103,6 +103,8 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         # need '-fno-builtin-std-forward_like', see https://github.com/llvm/llvm-project/issues/101614
+        # cpp20_compatibility_test.cc is ignored: it asserts it is compiled as C++20,
+        # which the global '-std=c++23' below would override. The build enforces it.
         run: |
           cpp-linter \
             --style='' \
@@ -111,7 +113,7 @@ jobs:
             --files-changed-only=true \
             --lines-changed-only=true \
             --thread-comments=true \
-            --ignore='build|cmake_modules|ci|src/iceberg/catalog/hive/gen-cpp' \
+            --ignore='build|cmake_modules|ci|src/iceberg/catalog/hive/gen-cpp|src/iceberg/test/cpp20_compatibility_test.cc' \
             --database=build \
             --verbosity=debug \
             --extra-arg='-std=c++23' \

.github/workflows/test.yml

@@ -45,15 +45,19 @@ env:
 jobs:
   ubuntu:
     if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
-    name: AMD64 Ubuntu 26.04 (${{ matrix.cmake_build_type }})
+    name: AMD64 Ubuntu 26.04 (${{ matrix.cmake_build_type }}, ${{ matrix.api_mode }})
     runs-on: ubuntu-26.04
     timeout-minutes: 60
     strategy:
       fail-fast: false
       matrix:
-        cmake_build_type:
-          - Debug
-          - RelWithDebInfo
+        include:
+          - cmake_build_type: Debug
+            extra_cmake_args: "-DICEBERG_CXX20_COMPAT=ON"
+            api_mode: C++20 Compat
+          - cmake_build_type: RelWithDebInfo
+            extra_cmake_args: ""
+            api_mode: C++23
     steps:
       - name: Checkout iceberg-cpp
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -71,22 +75,46 @@ jobs:
         env:
           CC: gcc-14
           CXX: g++-14
-        run: ci/scripts/build_iceberg.sh $(pwd) ON ON OFF OFF ON ${{ matrix.cmake_build_type }}
+          ICEBERG_EXTRA_CMAKE_ARGS: ${{ matrix.extra_cmake_args }}
+        run: |
+          ci/scripts/build_iceberg.sh \
+            --source-dir "$(pwd)" \
+            --build-type "${{ matrix.cmake_build_type }}" \
+            --sccache ON \
+            --rest-integration-tests ON \
+            --s3 OFF \
+            --sigv4 OFF \
+            --bundle-awssdk ON
+      - name: Build Example (C++20)
+        if: matrix.cmake_build_type == 'Debug'
+        shell: bash
+        env:
+          CC: gcc-14
+          CXX: g++-14
+        run: |
+          ci/scripts/build_example.sh \
+            --source-dir "$(pwd)/example" \
+            --build-type "${{ matrix.cmake_build_type }}" \
+            --cxx-standard 20
+      - name: Build Example (C++23)
+        shell: bash
+        env:
+          CC: gcc-14
+          CXX: g++-14
+        run: |
+          ci/scripts/build_example.sh \
+            --source-dir "$(pwd)/example" \
+            --build-type "${{ matrix.cmake_build_type }}" \
+            --cxx-standard 23
       - name: Save sccache
         if: always()
         uses: ./.github/actions/save-sccache
         with:
           key-prefix: sccache-test-ubuntu-${{ matrix.cmake_build_type }}
           job-status: ${{ job.status }}
-      - name: Build Example
-        shell: bash
-        env:
-          CC: gcc-14
-          CXX: g++-14
-        run: ci/scripts/build_example.sh $(pwd)/example
   hive:
     if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
-    name: AMD64 Ubuntu 26.04 Hive
+    name: AMD64 Ubuntu 26.04 Hive (C++23)
     runs-on: ubuntu-26.04
     timeout-minutes: 45
     strategy:
@@ -118,7 +146,11 @@ jobs:
         env:
           CC: gcc-14
           CXX: g++-14
-        run: ci/scripts/build_iceberg.sh $(pwd) OFF ON
+        run: |
+          ci/scripts/build_iceberg.sh \
+            --source-dir "$(pwd)" \
+            --build-type Debug \
+            --sccache ON
       - name: Show sccache stats
         shell: bash
         run: sccache --show-stats
@@ -130,7 +162,7 @@ jobs:
           key: sccache-test-hive-${{ github.run_id }}
   macos:
     if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
-    name: AArch64 macOS 26
+    name: AArch64 macOS 26 (C++20 Compat)
     runs-on: macos-26
     timeout-minutes: 30
     strategy:
@@ -146,19 +178,36 @@ jobs:
           key-prefix: sccache-test-macos
       - name: Build Iceberg
         shell: bash
-        run: ci/scripts/build_iceberg.sh $(pwd) OFF ON
+        env:
+          ICEBERG_EXTRA_CMAKE_ARGS: "-DICEBERG_CXX20_COMPAT=ON"
+        run: |
+          ci/scripts/build_iceberg.sh \
+            --source-dir "$(pwd)" \
+            --build-type Debug \
+            --sccache ON
       - name: Save sccache
         if: always()
         uses: ./.github/actions/save-sccache
         with:
           key-prefix: sccache-test-macos
           job-status: ${{ job.status }}
-      - name: Build Example
+      - name: Build Example (C++20)
+        shell: bash
+        run: |
+          ci/scripts/build_example.sh \
+            --source-dir "$(pwd)/example" \
+            --build-type Debug \
+            --cxx-standard 20
+      - name: Build Example (C++23)
         shell: bash
-        run: ci/scripts/build_example.sh $(pwd)/example
+        run: |
+          ci/scripts/build_example.sh \
+            --source-dir "$(pwd)/example" \
+            --build-type Debug \
+            --cxx-standard 23
   windows:
     if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
-    name: AMD64 Windows 2025
+    name: AMD64 Windows 2025 (C++20 Compat)
     runs-on: windows-2025
     timeout-minutes: 60
     strategy:
@@ -189,18 +238,40 @@ jobs:
           key-prefix: sccache-test-windows
       - name: Build Iceberg
         shell: pwsh
+        env:
+          ICEBERG_EXTRA_CMAKE_ARGS: "-DICEBERG_CXX20_COMPAT=ON"
         run: |
           $ErrorActionPreference = "Stop"
-          bash -lc 'ci/scripts/build_iceberg.sh $(pwd) OFF ON'
+          bash -lc '
+            ci/scripts/build_iceberg.sh \
+              --source-dir "$(pwd)" \
+              --build-type Debug \
+              --sccache ON
+          '
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
       - name: Save sccache
         if: always()
         uses: ./.github/actions/save-sccache
         with:
           key-prefix: sccache-test-windows
           job-status: ${{ job.status }}
-      - name: Build Example
+      - name: Build Example (C++20)
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          bash -lc '
+            ci/scripts/build_example.sh \
+              --source-dir "$(pwd)/example" \
+              --build-type Debug \
+              --cxx-standard 20
+          '
+      - name: Build Example (C++23)
         shell: pwsh
         run: |
           $ErrorActionPreference = "Stop"
-          bash -lc 'ci/scripts/build_example.sh $(pwd)/example'
+          bash -lc '
+            ci/scripts/build_example.sh \
+              --source-dir "$(pwd)/example" \
+              --build-type Debug \
+              --cxx-standard 23
+          '

.pre-commit-config.yaml

@@ -43,3 +43,12 @@ repos:
     rev: v0.6.10
     hooks:
       - id: cmake-format
+
+  - repo: local
+    hooks:
+      - id: generate-public-headers
+        name: check src/iceberg/cpp20_compatibility_internal.h is up to date
+        entry: python ci/scripts/generate_public_headers.py
+        language: python
+        files: ^(src/.*(\.hpp?|CMakeLists\.txt)|ci/scripts/generate_public_headers\.py)$
+        pass_filenames: false

CMakeLists.txt

@@ -36,6 +36,16 @@ set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+option(ICEBERG_CXX20_COMPAT "Expose the C++20-compatible public API" OFF)
+if(ICEBERG_CXX20_COMPAT)
+  set(ICEBERG_PUBLIC_CXX_STANDARD 20)
+  set(ICEBERG_CXX20_COMPAT_VALUE 1)
+else()
+  set(ICEBERG_PUBLIC_CXX_STANDARD 23)
+  set(ICEBERG_CXX20_COMPAT_VALUE 0)
+endif()
+configure_file("${PROJECT_SOURCE_DIR}/src/iceberg/compat/build_config.h.in"
+               "${PROJECT_BINARY_DIR}/src/iceberg/compat/build_config.h" @ONLY)
 option(ICEBERG_BUILD_STATIC "Build static library" ON)
 option(ICEBERG_BUILD_SHARED "Build shared library" OFF)
 option(ICEBERG_BUILD_TESTS "Build tests" ON)

LICENSE

@@ -230,6 +230,34 @@ License: https://www.apache.org/licenses/LICENSE-2.0
 
 --------------------------------------------------------------------------------
 
+This product includes code from zeus-cpp/expected.
+
+* src/iceberg/compat/expected.h is adapted from zeus-cpp/expected.
+
+Copyright: 2024 zeus-cpp.
+Home page: https://github.com/zeus-cpp/expected
+License: MIT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
 This product bundles utf8proc, which is available under the MIT License:
 
 utf8proc is a software package originally developed by Jan Behrens and the rest

README.md

@@ -39,6 +39,11 @@ C++ implementation of [Apache Iceberg™](https://iceberg.apache.org/).
 
 - Python 3 and [pre-commit](https://pre-commit.com/) (for linting)
 
+Building and developing iceberg-cpp requires C++23. Applications linking against
+an installation built with `ICEBERG_CXX20_COMPAT=ON` may also use C++20 through
+the public-header compatibility layer. See [Using the Library from C++20](mkdocs/docs/getting-started.md#using-the-library-from-c20)
+for its scope.
+
 ## Quick Start
 
 ```bash
@@ -104,6 +109,7 @@ cmake --install build
 | `ICEBERG_SQL_MYSQL` | `OFF` | Build the MySQL connector for the SQL catalog |
 | `ICEBERG_ENABLE_ASAN` | `OFF` | Enable Address Sanitizer |
 | `ICEBERG_ENABLE_UBSAN` | `OFF` | Enable Undefined Behavior Sanitizer |
+| `ICEBERG_CXX20_COMPAT` | `OFF` | Build a package with the C++20-compatible public API; library sources remain C++23 |
 
 ### Build Examples
 
@@ -121,6 +127,13 @@ If you are using provided Apache Arrow, include `/path/to/arrow` in `CMAKE_PREFI
 cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH="/path/to/install;/path/to/arrow"
 ```
 
+The examples default to C++23. To compile an application as C++20, use a library
+installation built with `ICEBERG_CXX20_COMPAT=ON` and set the example standard:
+
+```bash
+cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH=/path/to/compat-install -DICEBERG_EXAMPLE_CXX_STANDARD=20
+```
+
 ## Customizing Dependency URLs
 
 If you experience network issues when downloading dependencies, you can customize the download URLs using environment variables: