expose ICEBERG_EXAMPLE_CXX_STANDARD and update docs to state C++20 as minimum standard for public headers

Author: PingLiuPing

.github/workflows/test.yml

@@ -78,12 +78,19 @@ jobs:
         with:
           key-prefix: sccache-test-ubuntu-${{ matrix.cmake_build_type }}
           job-status: ${{ job.status }}
-      - name: Build Example
+      - name: Build Example (C++20)
         shell: bash
         env:
           CC: gcc-14
           CXX: g++-14
         run: ci/scripts/build_example.sh $(pwd)/example
+      - name: Build Example (C++23)
+        shell: bash
+        env:
+          CC: gcc-14
+          CXX: g++-14
+          ICEBERG_EXAMPLE_CXX_STANDARD: 23
+        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
@@ -153,9 +160,14 @@ jobs:
         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 $(pwd)/example
+      - name: Build Example (C++23)
+        shell: bash
+        env:
+          ICEBERG_EXAMPLE_CXX_STANDARD: 23
+        run: ci/scripts/build_example.sh $(pwd)/example
   windows:
     if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
     name: AMD64 Windows 2025
@@ -199,8 +211,15 @@ jobs:
         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 $(pwd)/example'
+      - name: Build Example (C++23)
         shell: pwsh
+        env:
+          ICEBERG_EXAMPLE_CXX_STANDARD: 23
         run: |
           $ErrorActionPreference = "Stop"
           bash -lc 'ci/scripts/build_example.sh $(pwd)/example'

README.md

@@ -31,10 +31,14 @@ C++ implementation of [Apache Iceberg™](https://iceberg.apache.org/).
 
 **Required:**
 
-- C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+)
+- C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+) to build iceberg-cpp itself
 - CMake 3.25+
 - [Ninja](https://ninja-build.org/) (recommended build backend)
 
+**Using iceberg-cpp from your project:** the installed public headers require
+C++20 at minimum, so applications that link against iceberg-cpp can be
+compiled as C++20 or later. The library itself is still built as C++23.
+
 **Optional:**
 
 - Python 3 and [pre-commit](https://pre-commit.com/) (for linting)
@@ -121,6 +125,14 @@ 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 build as C++20 by default, which is the minimum standard supported
+by the public headers. Set `ICEBERG_EXAMPLE_CXX_STANDARD` to `23` to build them
+as C++23 instead:
+
+```bash
+cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH=/path/to/install -DICEBERG_EXAMPLE_CXX_STANDARD=23
+```
+
 ## Customizing Dependency URLs
 
 If you experience network issues when downloading dependencies, you can customize the download URLs using environment variables:

ci/scripts/build_example.sh

@@ -22,6 +22,7 @@ set -eux
 source_dir=${1}
 build_dir=${1}/build
 run_example=${ICEBERG_RUN_EXAMPLE:-OFF}
+cxx_standard=${ICEBERG_EXAMPLE_CXX_STANDARD:-20}
 
 # Clean up before configuring. If Windows still holds a just-built exe/dll
 # after the retries, let mkdir fail rather than reuse a half-deleted tree.
@@ -53,6 +54,7 @@ fi
 
 build_type="${ICEBERG_BUILD_TYPE:-Debug}"
 CMAKE_ARGS+=("-DCMAKE_BUILD_TYPE=${build_type}")
+CMAKE_ARGS+=("-DICEBERG_EXAMPLE_CXX_STANDARD=${cxx_standard}")
 
 cmake "${CMAKE_ARGS[@]}" ${source_dir}
 cmake --build .

example/CMakeLists.txt

@@ -20,7 +20,21 @@ cmake_minimum_required(VERSION 3.25)
 
 project(example)
 
-set(CMAKE_CXX_STANDARD 20)
+# C++20 is the minimum standard iceberg-cpp's public headers support, so the
+# example builds as C++20 by default to keep that contract exercised. Set this to
+# 23 to also check the headers from a C++23 consumer.
+set(ICEBERG_EXAMPLE_CXX_STANDARD
+    20
+    CACHE STRING "C++ standard used to build the example (20 or 23)")
+set_property(CACHE ICEBERG_EXAMPLE_CXX_STANDARD PROPERTY STRINGS 20 23)
+if(NOT ICEBERG_EXAMPLE_CXX_STANDARD MATCHES "^(20|23)$")
+  message(FATAL_ERROR "ICEBERG_EXAMPLE_CXX_STANDARD must be 20 or 23, got "
+                      "'${ICEBERG_EXAMPLE_CXX_STANDARD}'")
+endif()
+
+set(CMAKE_CXX_STANDARD ${ICEBERG_EXAMPLE_CXX_STANDARD})
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
 
 find_package(iceberg CONFIG REQUIRED COMPONENTS bundle rest)
 
@@ -41,7 +55,8 @@ add_executable(demo_example demo_example.cc)
 target_link_libraries(demo_example PRIVATE ${ICEBERG_BUNDLE_TARGET}
                                            ${ICEBERG_REST_TARGET})
 
-# Compile every installed public header as a C++20 consumer. The installed include
+# Compile every installed public header as a consumer using
+# ICEBERG_EXAMPLE_CXX_STANDARD. The installed include
 # tree is the public API contract: iceberg_install_all_headers excludes internal
 # headers before packaging them.
 get_target_property(ICEBERG_BUNDLE_INCLUDE_DIRS ${ICEBERG_BUNDLE_TARGET}
@@ -75,12 +90,9 @@ endforeach()
 string(APPEND ICEBERG_PUBLIC_HEADER_CHECK_SOURCE "\nint main() { return 0; }\n")
 
 file(GENERATE
-     OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/public_headers_cxx20.cc"
+     OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/public_headers_check.cc"
      CONTENT "${ICEBERG_PUBLIC_HEADER_CHECK_SOURCE}")
 
-add_executable(public_headers_cxx20 "${CMAKE_CURRENT_BINARY_DIR}/public_headers_cxx20.cc")
-set_target_properties(public_headers_cxx20
-                      PROPERTIES CXX_STANDARD 20 CXX_STANDARD_REQUIRED ON CXX_EXTENSIONS
-                                                                          OFF)
-target_link_libraries(public_headers_cxx20 PRIVATE ${ICEBERG_BUNDLE_TARGET}
+add_executable(public_headers_check "${CMAKE_CURRENT_BINARY_DIR}/public_headers_check.cc")
+target_link_libraries(public_headers_check PRIVATE ${ICEBERG_BUNDLE_TARGET}
                                                    ${ICEBERG_REST_TARGET})

mkdocs/docs/getting-started.md

@@ -23,10 +23,14 @@
 
 **Required:**
 
-- C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+)
+- C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+) to build iceberg-cpp itself
 - CMake 3.25+
 - [Ninja](https://ninja-build.org/) (recommended build backend)
 
+**Using iceberg-cpp from your project:** the installed public headers require
+C++20 at minimum, so applications that link against iceberg-cpp can be
+compiled as C++20 or later. The library itself is still built as C++23.
+
 ## Quick Start
 
 ```bash
@@ -112,6 +116,14 @@ If using provided Apache Arrow, include both paths:
 cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH="/path/to/install;/path/to/arrow"
 ```
 
+The examples build as C++20 by default, which is the minimum standard supported
+by the public headers. Set `ICEBERG_EXAMPLE_CXX_STANDARD` to `23` to build them
+as C++23 instead:
+
+```bash
+cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH=/path/to/install -DICEBERG_EXAMPLE_CXX_STANDARD=23
+```
+
 ## Customizing Dependency URLs
 
 If you experience network issues when downloading dependencies, you can override the download URLs using environment variables:

mkdocs/docs/index.md

@@ -25,7 +25,7 @@ iceberg-cpp is a C++ implementation of [Apache Iceberg™](https://iceberg.apach
 
 ## Key Features
 
-- **Modern C++23** — Built with ranges, concepts, `std::expected`, and other modern idioms
+- **Modern C++** — Built as C++23 with ranges, concepts, and other modern idioms; public headers require only C++20
 - **Cross-Platform** — Builds and runs on Linux, macOS, and Windows
 - **Spec Compliance** — Full table spec support today; Puffin, View, and UDF specs are on the roadmap
 - **Arrow-Native** — Uses the Arrow C Data Interface as the primary data API