feat: make the public headers consumable as C++20

.github/.licenserc.yaml

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

.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'

.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/.*(\.(h)|CMakeLists\.txt)$
+        pass_filenames: false

LICENSE

@@ -230,6 +230,34 @@ License: https://www.apache.org/licenses/LICENSE-2.0
 
 --------------------------------------------------------------------------------
 
+This product includes code from zeus-cpp/expected.
+
+* src/iceberg/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,20 @@ C++ implementation of [Apache Iceberg™](https://iceberg.apache.org/).
 
 - Python 3 and [pre-commit](https://pre-commit.com/) (for linting)
 
+## C++20 Compatibility
+
+iceberg-cpp is built as C++23, but its installed public headers are also usable
+from C++20. Applications that consume iceberg-cpp can therefore be compiled as
+C++20 or later; C++20 is the minimum standard supported for the public headers.
+
+This contract is checked in two ways: `cpp20_compatibility_test` compiles every
+public header as C++20 as part of the regular test suite, and CI builds the
+[example](example) against the installed headers as both C++20 and C++23 (see
+`ICEBERG_EXAMPLE_CXX_STANDARD` in [Build Examples](#build-examples)). The test's
+header list, `src/iceberg/cpp20_compatibility_internal.h`, is generated by
+`ci/scripts/generate_public_headers.py`; a pre-commit hook fails whenever it is
+out of date, so new public headers cannot be missed.
+
 ## Quick Start
 
 ```bash
@@ -121,6 +135,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 .

ci/scripts/generate_public_headers.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Regenerate src/iceberg/cpp20_compatibility_internal.h.
+
+The generated header includes every public header, i.e. every header that
+iceberg_install_all_headers() installs: *.h files in a directory whose
+CMakeLists.txt calls it, except those with "internal" in their name. This script
+applies the same rule, so the list never has to be maintained by hand. The
+generate-public-headers pre-commit hook runs it and fails when the checked-in
+header is out of date.
+
+Headers of optional components are wrapped in a macro that
+cpp20_compatibility_test defines only when that component is built.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+SRC = ROOT / "src"
+OUTPUT = SRC / "iceberg" / "cpp20_compatibility_internal.h"
+
+# Install path prefix -> macro guarding it. The first match wins, so list more
+# specific prefixes first. Anything unmatched is always built.
+OPTIONAL_COMPONENTS = [
+    ("iceberg/catalog/hive", "ICEBERG_PUBLIC_HEADERS_HIVE"),
+    ("iceberg/catalog/rest", "ICEBERG_PUBLIC_HEADERS_REST"),
+    ("iceberg/catalog/sql", "ICEBERG_PUBLIC_HEADERS_SQL_CATALOG"),
+    ("iceberg/arrow", "ICEBERG_PUBLIC_HEADERS_BUNDLE"),
+    ("iceberg/avro", "ICEBERG_PUBLIC_HEADERS_BUNDLE"),
+    ("iceberg/parquet", "ICEBERG_PUBLIC_HEADERS_BUNDLE"),
+]
+
+INSTALL_CALL = re.compile(r"iceberg_install_all_headers\(\s*([^\s)]+)")
+
+LICENSE = """\
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+"""
+
+
+def component_of(install_path: str) -> str | None:
+    for prefix, macro in OPTIONAL_COMPONENTS:
+        if install_path == prefix or install_path.startswith(prefix + "/"):
+            return macro
+    return None
+
+
+def collect_public_headers() -> dict[str | None, list[str]]:
+    headers: dict[str | None, list[str]] = {}
+    for cmake_file in sorted(SRC.rglob("CMakeLists.txt")):
+        for install_path in INSTALL_CALL.findall(cmake_file.read_text()):
+            for header in cmake_file.parent.iterdir():
+                if header.suffix != ".h" or "internal" in header.name:
+                    continue
+                headers.setdefault(component_of(install_path), []).append(
+                    f"{install_path}/{header.name}"
+                )
+    return headers
+
+
+def render(headers: dict[str | None, list[str]]) -> str:
+    lines = [
+        LICENSE,
+        "// Generated by ci/scripts/generate_public_headers.py; do not edit by hand.",
+        "//",
+        "// Includes every public (installed) header. cpp20_compatibility_test compiles",
+        "// it as C++20 to keep the public headers usable from C++20.",
+        "",
+        "#pragma once",
+        "",
+    ]
+    lines += [f'#include "{h}"' for h in sorted(headers.get(None, []))]
+    for macro in sorted({m for _, m in OPTIONAL_COMPONENTS}):
+        if macro not in headers:
+            continue
+        lines += ["", f"#ifdef {macro}"]
+        lines += [f'#  include "{h}"' for h in sorted(headers[macro])]
+        lines += [f"#endif  // {macro}"]
+    return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+    content = render(collect_public_headers())
+    if OUTPUT.exists() and OUTPUT.read_text() == content:
+        return 0
+    OUTPUT.write_text(content)
+    print(f"Regenerated {OUTPUT.relative_to(ROOT)}; commit the updated file.")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

example/CMakeLists.txt

@@ -20,13 +20,75 @@ cmake_minimum_required(VERSION 3.25)
 
 project(example)
 
-set(CMAKE_CXX_STANDARD 23)
+# 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 a
+# newer standard (e.g. 23) to check the headers from a newer consumer as well.
+set(ICEBERG_EXAMPLE_CXX_STANDARD
+    20
+    CACHE STRING "C++ standard used to build the example (20 or newer)")
+if(ICEBERG_EXAMPLE_CXX_STANDARD MATCHES "^(98|11|14|17)$")
+  message(FATAL_ERROR "ICEBERG_EXAMPLE_CXX_STANDARD must be 20 or newer, 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)
 
+if(TARGET iceberg::iceberg_bundle_shared)
+  set(ICEBERG_BUNDLE_TARGET iceberg::iceberg_bundle_shared)
+else()
+  set(ICEBERG_BUNDLE_TARGET iceberg::iceberg_bundle_static)
+endif()
+
+if(TARGET iceberg::iceberg_rest_shared)
+  set(ICEBERG_REST_TARGET iceberg::iceberg_rest_shared)
+else()
+  set(ICEBERG_REST_TARGET iceberg::iceberg_rest_static)
+endif()
+
 add_executable(demo_example demo_example.cc)
 
-target_link_libraries(demo_example
-                      PRIVATE "$<IF:$<TARGET_EXISTS:iceberg::iceberg_bundle_shared>,iceberg::iceberg_bundle_shared,iceberg::iceberg_bundle_static>"
-                              "$<IF:$<TARGET_EXISTS:iceberg::iceberg_rest_shared>,iceberg::iceberg_rest_shared,iceberg::iceberg_rest_static>"
-)
+target_link_libraries(demo_example PRIVATE ${ICEBERG_BUNDLE_TARGET}
+                                           ${ICEBERG_REST_TARGET})
+
+# 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}
+                    INTERFACE_INCLUDE_DIRECTORIES)
+foreach(ICEBERG_INCLUDE_DIR IN LISTS ICEBERG_BUNDLE_INCLUDE_DIRS)
+  if(EXISTS "${ICEBERG_INCLUDE_DIR}/iceberg")
+    set(ICEBERG_PUBLIC_INCLUDE_DIR "${ICEBERG_INCLUDE_DIR}")
+    break()
+  endif()
+endforeach()
+
+if(NOT ICEBERG_PUBLIC_INCLUDE_DIR)
+  message(FATAL_ERROR "Could not locate iceberg's installed public headers")
+endif()
+
+file(GLOB_RECURSE ICEBERG_PUBLIC_HEADERS CONFIGURE_DEPENDS
+     "${ICEBERG_PUBLIC_INCLUDE_DIR}/iceberg/*.h")
+list(SORT ICEBERG_PUBLIC_HEADERS)
+
+set(ICEBERG_PUBLIC_HEADER_CHECK_SOURCE
+    "// Generated from iceberg's installed public headers.\n")
+foreach(ICEBERG_PUBLIC_HEADER IN LISTS ICEBERG_PUBLIC_HEADERS)
+  file(RELATIVE_PATH ICEBERG_PUBLIC_HEADER_RELATIVE_PATH "${ICEBERG_PUBLIC_INCLUDE_DIR}"
+       "${ICEBERG_PUBLIC_HEADER}")
+  string(APPEND ICEBERG_PUBLIC_HEADER_CHECK_SOURCE
+         "#include <${ICEBERG_PUBLIC_HEADER_RELATIVE_PATH}>\n")
+endforeach()
+string(APPEND ICEBERG_PUBLIC_HEADER_CHECK_SOURCE "\nint main() { return 0; }\n")
+
+file(GENERATE
+     OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/public_headers_check.cc"
+     CONTENT "${ICEBERG_PUBLIC_HEADER_CHECK_SOURCE}")
+
+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})