Branches

Apache Iceberg™ C++

Requirements

Required:

C++23 compliant compiler (GCC 14+, Clang 16+, MSVC 2022+)
CMake 3.25+ or Meson 1.5+
Ninja (recommended build backend)

Optional:

Python 3 and pre-commit (for linting)

Quick Start

git clone https://github.com/apache/iceberg-cpp.git
cd iceberg-cpp
cmake -S . -B build -G Ninja
cmake --build build
ctest --test-dir build --output-on-failure

Build with CMake

Build, Run Tests and Install Core Libraries

cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/path/to/install -DICEBERG_BUILD_STATIC=ON -DICEBERG_BUILD_SHARED=ON
cmake --build build
ctest --test-dir build --output-on-failure
cmake --install build

To run a specific test suite:

ctest --test-dir build -R schema_test --output-on-failure

Build and Install Iceberg Bundle Library

Vendored Apache Arrow (default)

cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/path/to/install -DICEBERG_BUILD_BUNDLE=ON
cmake --build build
ctest --test-dir build --output-on-failure
cmake --install build

Provided Apache Arrow

cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/path/to/install -DCMAKE_PREFIX_PATH=/path/to/arrow -DICEBERG_BUILD_BUNDLE=ON
cmake --build build
ctest --test-dir build --output-on-failure
cmake --install build

CMake Build Options

Option	Default	Description
`ICEBERG_BUILD_STATIC`	`ON`	Build static library
`ICEBERG_BUILD_SHARED`	`OFF`	Build shared library
`ICEBERG_BUILD_TESTS`	`ON`	Build tests
`ICEBERG_BUILD_BUNDLE`	`ON`	Build the battery-included library
`ICEBERG_BUILD_REST`	`ON`	Build REST catalog client
`ICEBERG_BUILD_REST_INTEGRATION_TESTS`	`OFF`	Build REST catalog integration tests
`ICEBERG_ENABLE_ASAN`	`OFF`	Enable Address Sanitizer
`ICEBERG_ENABLE_UBSAN`	`OFF`	Enable Undefined Behavior Sanitizer

Build with Meson

meson setup builddir
meson compile -C builddir
meson test -C builddir --timeout-multiplier 0

Meson provides built-in equivalents for several CMake options:

--default-library=<shared|static|both> instead of ICEBERG_BUILD_STATIC / ICEBERG_BUILD_SHARED
-Db_sanitize=address,undefined instead of ICEBERG_ENABLE_ASAN / ICEBERG_ENABLE_UBSAN
--libdir, --bindir, --includedir for install directories

Meson-specific options (configured via -D<option>=<value>):

Option	Default	Description
`rest`	`enabled`	Build REST catalog client
`rest_integration_test`	`disabled`	Build integration test for REST catalog
`tests`	`enabled`	Build tests

Build Examples

After installing the core libraries, you can build the examples:

cd example
cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH=/path/to/install
cmake --build build

If you are using provided Apache Arrow, include /path/to/arrow in CMAKE_PREFIX_PATH:

cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH="/path/to/install;/path/to/arrow"

Customizing Dependency URLs

If you experience network issues when downloading dependencies, you can customize the download URLs using environment variables:

ICEBERG_ARROW_URL: Apache Arrow tarball URL
ICEBERG_AVRO_URL: Apache Avro tarball URL
ICEBERG_AVRO_GIT_URL: Apache Avro git repository URL
ICEBERG_NANOARROW_URL: Nanoarrow tarball URL
ICEBERG_CROARING_URL: CRoaring tarball URL
ICEBERG_NLOHMANN_JSON_URL: nlohmann-json tarball URL
ICEBERG_CPR_URL: cpr tarball URL

Example:

export ICEBERG_ARROW_URL="https://your-mirror.com/apache-arrow-22.0.0.tar.gz"
cmake -S . -B build

Contribute

Apache Iceberg is an active open-source project, governed under the Apache Software Foundation (ASF). Iceberg-cpp is open to people who want to contribute to it. Here are some ways to get involved:

Submit Issues for bug report or feature requests.
Discuss at dev mailing list (subscribe / unsubscribe / archives)
Talk to the community directly at Slack #cpp channel.

The Apache Iceberg community is built on the principles described in the Apache Way and all who engage with the community are expected to be respectful, open, come with the best interests of the community in mind, and abide by the Apache Foundation Code of Conduct.

In addition, contributors using AI-assisted tools must follow the documented guidelines for AI-assisted contributions available on the Iceberg website: https://iceberg.apache.org/contribute/#guidelines-for-ai-assisted-contributions.

Linting

Install the python package pre-commit and run once pre-commit install.

pip install pre-commit
pre-commit install

This will setup a git pre-commit-hook that is executed on each commit and will report the linting problems. To run all hooks on all files use pre-commit run -a.

Dev Containers

We provide Dev Container configuration file templates.

To use a Dev Container as your development environment, follow the steps below, then select Dev Containers: Reopen in Container from VS Code's Command Palette.

cd .devcontainer
cp Dockerfile.template Dockerfile
cp devcontainer.json.template devcontainer.json

If you make improvements that could benefit all developers, please update the template files and submit a pull request.

License

Licensed under the Apache License, Version 2.0

Apache Iceberg C++