Getting Started¶

Requirements¶

Required:

C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+)
CMake 3.25+
Ninja (recommended build backend)

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¶

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

Bundle Library (with vendored dependencies)¶

cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/path/to/install -DICEBERG_BUILD_BUNDLE=ON
cmake --build build
cmake --install build

Bundle Library (with 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
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_BUILD_HIVE`	`OFF`	Build Hive (HMS) catalog client
`ICEBERG_BUILD_SQL_CATALOG`	`OFF`	Build SQL catalog client
`ICEBERG_SQL_SQLITE`	`OFF`	Build the SQLite connector for the SQL catalog
`ICEBERG_SQL_POSTGRESQL`	`OFF`	Build the PostgreSQL connector for the SQL catalog
`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

Running Tests¶

Run all tests:

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

Run a specific test suite:

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

Build Examples¶

After installing the core libraries:

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

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 default to C++23.

Using the Library from C++20¶

To use iceberg-cpp from a C++20 application, build the library with ICEBERG_CXX20_COMPAT=ON. The library itself still requires C++23. Run these commands from the repository root:

cmake -S . -B build-compat -G Ninja -DICEBERG_CXX20_COMPAT=ON -DCMAKE_INSTALL_PREFIX=/path/to/compat-install
cmake --build build-compat
cmake --install build-compat

Then build the example against that installation:

cmake -S example -B example/build -G Ninja -DCMAKE_PREFIX_PATH=/path/to/compat-install -DICEBERG_EXAMPLE_CXX_STANDARD=20
cmake --build example/build

Your toolchain must support C++20 library features such as std::format. In this mode, base setters return base-class references, so call derived-specific methods separately instead of chaining them. Use matching headers and libraries; do not mix the default and compatibility packages in one program.

See Contributing for implementation and testing details.

Customizing Dependency URLs¶

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

Variable	Dependency
`ICEBERG_ARROW_URL`	Apache Arrow tarball
`ICEBERG_AVRO_URL`	Apache Avro tarball
`ICEBERG_AVRO_GIT_URL`	Apache Avro git repository
`ICEBERG_NANOARROW_URL`	Nanoarrow tarball
`ICEBERG_CROARING_URL`	CRoaring tarball
`ICEBERG_UTF8PROC_URL`	utf8proc tarball
`ICEBERG_NLOHMANN_JSON_URL`	nlohmann-json tarball
`ICEBERG_CPR_URL`	cpr tarball

Example:

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