Skip to content

Commit 06e029e

Browse files
wgtmacwgtmac
committed
docs: restructure and improve documentation website
1 parent 36b5887 commit 06e029e

10 files changed

Lines changed: 624 additions & 315 deletions

File tree

‎README.md‎

Lines changed: 79 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -21,49 +21,51 @@
2121

2222
[![Slack](https://img.shields.io/badge/chat-on%20Slack-brightgreen.svg)](https://apache-iceberg.slack.com/)
2323
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/apache/iceberg-cpp)
24+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
2425

2526
# Apache Iceberg™ C++
2627

2728
C++ implementation of [Apache Iceberg™](https://iceberg.apache.org/).
2829

2930
## Requirements
3031

31-
- CMake 3.25 or higher
32+
**Required:**
33+
3234
- C++23 compliant compiler (GCC 14+, Clang 16+, MSVC 2022+)
35+
- CMake 3.25+ or Meson 1.5+
36+
- [Ninja](https://ninja-build.org/) (recommended build backend)
3337

34-
## Customizing Dependency URLs
38+
**Optional:**
3539

36-
If you experience network issues when downloading dependencies, you can customize the download URLs using environment variables.
40+
- Python 3 and [pre-commit](https://pre-commit.com/) (for linting)
3741

38-
The following environment variables can be set to customize dependency URLs:
39-
40-
- `ICEBERG_ARROW_URL`: Apache Arrow tarball URL
41-
- `ICEBERG_AVRO_URL`: Apache Avro tarball URL
42-
- `ICEBERG_AVRO_GIT_URL`: Apache Avro git repository URL
43-
- `ICEBERG_NANOARROW_URL`: Nanoarrow tarball URL
44-
- `ICEBERG_CROARING_URL`: CRoaring tarball URL
45-
- `ICEBERG_NLOHMANN_JSON_URL`: nlohmann-json tarball URL
46-
- `ICEBERG_CPR_URL`: cpr tarball URL
47-
48-
Example usage:
42+
## Quick Start
4943

5044
```bash
51-
export ICEBERG_ARROW_URL="https://your-mirror.com/apache-arrow-22.0.0.tar.gz"
52-
cmake -S . -B build
45+
git clone https://github.com/apache/iceberg-cpp.git
46+
cd iceberg-cpp
47+
cmake -S . -B build -G Ninja
48+
cmake --build build
49+
ctest --test-dir build --output-on-failure
5350
```
5451

55-
## Build
52+
## Build with CMake
5653

57-
### Build, Run Test and Install Core Libraries
54+
### Build, Run Tests and Install Core Libraries
5855

5956
```bash
60-
cd iceberg-cpp
6157
cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/path/to/install -DICEBERG_BUILD_STATIC=ON -DICEBERG_BUILD_SHARED=ON
6258
cmake --build build
6359
ctest --test-dir build --output-on-failure
6460
cmake --install build
6561
```
6662

63+
To run a specific test suite:
64+
65+
```bash
66+
ctest --test-dir build -R schema_test --output-on-failure
67+
```
68+
6769
### Build and Install Iceberg Bundle Library
6870

6971
#### Vendored Apache Arrow (default)
@@ -84,22 +86,76 @@ ctest --test-dir build --output-on-failure
8486
cmake --install build
8587
```
8688

89+
### CMake Build Options
90+
91+
| Option | Default | Description |
92+
|--------|---------|-------------|
93+
| `ICEBERG_BUILD_STATIC` | `ON` | Build static library |
94+
| `ICEBERG_BUILD_SHARED` | `OFF` | Build shared library |
95+
| `ICEBERG_BUILD_TESTS` | `ON` | Build tests |
96+
| `ICEBERG_BUILD_BUNDLE` | `ON` | Build the battery-included library |
97+
| `ICEBERG_BUILD_REST` | `ON` | Build REST catalog client |
98+
| `ICEBERG_BUILD_REST_INTEGRATION_TESTS` | `OFF` | Build REST catalog integration tests |
99+
| `ICEBERG_ENABLE_ASAN` | `OFF` | Enable Address Sanitizer |
100+
| `ICEBERG_ENABLE_UBSAN` | `OFF` | Enable Undefined Behavior Sanitizer |
101+
102+
## Build with Meson
103+
104+
```bash
105+
meson setup builddir
106+
meson compile -C builddir
107+
meson test -C builddir --timeout-multiplier 0
108+
```
109+
110+
Meson provides built-in equivalents for several CMake options:
111+
112+
- `--default-library=<shared|static|both>` instead of `ICEBERG_BUILD_STATIC` / `ICEBERG_BUILD_SHARED`
113+
- `-Db_sanitize=address,undefined` instead of `ICEBERG_ENABLE_ASAN` / `ICEBERG_ENABLE_UBSAN`
114+
- `--libdir`, `--bindir`, `--includedir` for install directories
115+
116+
Meson-specific options (configured via `-D<option>=<value>`):
117+
118+
| Option | Default | Description |
119+
|--------|---------|-------------|
120+
| `rest` | `enabled` | Build REST catalog client |
121+
| `rest_integration_test` | `disabled` | Build integration test for REST catalog |
122+
| `tests` | `enabled` | Build tests |
123+
87124
### Build Examples
88125

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

91128
```bash
92-
cd iceberg-cpp/example
129+
cd example
93130
cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH=/path/to/install
94131
cmake --build build
95132
```
96133

97-
If you are using provided Apache Arrow, you need to include `/path/to/arrow` in `CMAKE_PREFIX_PATH` as below.
134+
If you are using provided Apache Arrow, include `/path/to/arrow` in `CMAKE_PREFIX_PATH`:
98135

99136
```bash
100137
cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH="/path/to/install;/path/to/arrow"
101138
```
102139

140+
## Customizing Dependency URLs
141+
142+
If you experience network issues when downloading dependencies, you can customize the download URLs using environment variables:
143+
144+
- `ICEBERG_ARROW_URL`: Apache Arrow tarball URL
145+
- `ICEBERG_AVRO_URL`: Apache Avro tarball URL
146+
- `ICEBERG_AVRO_GIT_URL`: Apache Avro git repository URL
147+
- `ICEBERG_NANOARROW_URL`: Nanoarrow tarball URL
148+
- `ICEBERG_CROARING_URL`: CRoaring tarball URL
149+
- `ICEBERG_NLOHMANN_JSON_URL`: nlohmann-json tarball URL
150+
- `ICEBERG_CPR_URL`: cpr tarball URL
151+
152+
Example:
153+
154+
```bash
155+
export ICEBERG_ARROW_URL="https://your-mirror.com/apache-arrow-22.0.0.tar.gz"
156+
cmake -S . -B build
157+
```
158+
103159
## Contribute
104160

105161
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:
@@ -116,7 +172,7 @@ In addition, contributors using AI-assisted tools must follow the documented gui
116172

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

119-
```
175+
```bash
120176
pip install pre-commit
121177
pre-commit install
122178
```
@@ -129,7 +185,7 @@ We provide Dev Container configuration file templates.
129185

130186
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.
131187

132-
```
188+
```bash
133189
cd .devcontainer
134190
cp Dockerfile.template Dockerfile
135191
cp devcontainer.json.template devcontainer.json

‎mkdocs/README.md‎

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,32 @@
1919

2020
# Documentation
2121

22-
To build the documentation:
22+
The website is built with [MkDocs](https://www.mkdocs.org/) (Material theme) and [Doxygen](https://www.doxygen.nl/) for API docs, hosted at https://cpp.iceberg.apache.org/.
2323

24-
1. Install [Doxygen](https://www.doxygen.nl/).
25-
2. From this directory, run `doxygen`.
24+
## Prerequisites
2625

27-
The output will be in `./build/html`.
26+
- Python 3 with pip
27+
- [Doxygen](https://www.doxygen.nl/)
28+
29+
## Build
30+
31+
From the project root:
32+
33+
```bash
34+
make install-deps # Install Python dependencies
35+
make build-api-docs # Generate API docs with Doxygen
36+
make build-docs # Build MkDocs site
37+
make all # Build everything
38+
```
39+
40+
## Local Preview
41+
42+
```bash
43+
make serve-docs # Serve at http://127.0.0.1:8000
44+
```
45+
46+
## Clean
47+
48+
```bash
49+
make clean-docs # Remove generated files
50+
```

mkdocs/docs/assert/iceberg-logo-icon.png renamed to mkdocs/docs/assets/iceberg-logo-icon.png

File renamed without changes.

‎mkdocs/docs/contributing.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
<!--
2+
~ Licensed to the Apache Software Foundation (ASF) under one
3+
~ or more contributor license agreements. See the NOTICE file
4+
~ distributed with this work for additional information
5+
~ regarding copyright ownership. The ASF licenses this file
6+
~ to you under the Apache License, Version 2.0 (the
7+
~ "License"); you may not use this file except in compliance
8+
~ with the License. You may obtain a copy of the License at
9+
~
10+
~ http://www.apache.org/licenses/LICENSE-2.0
11+
~
12+
~ Unless required by applicable law or agreed to in writing,
13+
~ software distributed under the License is distributed on an
14+
~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
~ KIND, either express or implied. See the License for the
16+
~ specific language governing permissions and limitations
17+
~ under the License.
18+
-->
19+
20+
# Contributing
21+
22+
We welcome contributions to Apache Iceberg C++. For general Iceberg contribution guidelines, see the [official guide](https://iceberg.apache.org/contribute/). Contributors using AI-assisted tools must follow the [AI-assisted contribution guidelines](https://iceberg.apache.org/contribute/#guidelines-for-ai-assisted-contributions).
23+
24+
For build and installation instructions, see [Getting Started](getting-started.md).
25+
26+
## Coding Standard
27+
28+
The project follows the same coding standard as [Apache Arrow](https://arrow.apache.org/docs/developers/cpp/development.html#code-style-linting-and-ci) (a variant of the Google’s C++ Style Guide)
29+
30+
### Naming Conventions
31+
32+
| Element | Style | Examples |
33+
|---------|-------|----------|
34+
| Classes / Structs | `PascalCase` | `TableScanBuilder`, `PartitionSpec` |
35+
| Factory methods | `PascalCase` | `CreateNamespace()`, `ExtractYear()` |
36+
| Accessors / Getters | `snake_case` | `name()`, `type_id()`, `partition_spec()` |
37+
| Variables | `snake_case` | `file_io`, `schema_id` |
38+
| Constants | `k` + `PascalCase` | `kHeaderContentType`, `kMaxPrecision` |
39+
40+
### General Practices
41+
42+
- Prefer smart pointers (`std::unique_ptr`, `std::shared_ptr`) for memory management
43+
- Use `Result<T>` for error propagation
44+
- Write Doxygen-style comments (`/// \brief ...`) for all public APIs
45+
- Do not remove public methods without a deprecation cycle:
46+
47+
```cpp
48+
[[deprecated("Use new_method() instead. Will be removed in a future release.")]]
49+
void old_method();
50+
```
51+
52+
## Development Environment
53+
54+
### Code Formatting
55+
56+
Formatting is enforced via `.clang-format` (Google base, `ColumnLimit: 90`). Set up `pre-commit` to run it automatically:
57+
58+
```bash
59+
pip install pre-commit
60+
pre-commit install
61+
```
62+
63+
To run all hooks manually on the entire codebase:
64+
65+
```bash
66+
pre-commit run -a
67+
```
68+
69+
### Dev Containers
70+
71+
We provide Dev Container templates for VS Code:
72+
73+
```bash
74+
cd .devcontainer
75+
cp Dockerfile.template Dockerfile
76+
cp devcontainer.json.template devcontainer.json
77+
```
78+
79+
Then select `Dev Containers: Reopen in Container` from the Command Palette.
80+
81+
## Submitting Changes
82+
83+
### Workflow
84+
85+
1. Fork the repository on GitHub
86+
2. Create a feature branch from `main`:
87+
```bash
88+
git checkout -b feature/your-feature-name
89+
```
90+
3. Make your changes following the coding standards
91+
4. Add or update tests for any behavioral changes
92+
5. Ensure all tests pass and `pre-commit run -a` is clean
93+
6. Push to your fork and open a Pull Request
94+
95+
### Commit Messages
96+
97+
Follow [Conventional Commits](https://www.conventionalcommits.org/):
98+
99+
```
100+
feat: add support for S3 file system
101+
fix: resolve memory leak in table reader
102+
docs: update API documentation
103+
test: add unit tests for schema validation
104+
refactor(rest): simplify auth token handling
105+
```
106+
107+
### Pull Request Checklist
108+
109+
- Clear problem/solution description
110+
- Linked issue(s) when applicable
111+
- Tests for behavioral changes
112+
- Passing CI checks (tests, pre-commit, license header, sanitizers)
113+
114+
## Getting Help
115+
116+
- **GitHub Issues** — [Report bugs or request features](https://github.com/apache/iceberg-cpp/issues/new)
117+
- **Good First Issues** — [Browse here](https://github.com/apache/iceberg-cpp/labels/good%20first%20issue)
118+
- **Mailing List** — [dev@iceberg.apache.org](mailto:dev@iceberg.apache.org) ([subscribe](mailto:dev-subscribe@iceberg.apache.org?subject=(send%20this%20email%20to%20subscribe)) / [unsubscribe](mailto:dev-unsubscribe@iceberg.apache.org?subject=(send%20this%20email%20to%20unsubscribe)) / [archives](https://lists.apache.org/list.html?dev@iceberg.apache.org))
119+
- **Slack** — [#cpp channel](https://join.slack.com/t/apache-iceberg/shared_invite/zt-1zbov3k6e-KtJfoaxp97YfX6dPz1Bk7A)
120+
121+
The Apache Iceberg community follows the [Apache Way](https://www.apache.org/theapacheway/index.html) and the Apache Foundation [Code of Conduct](https://www.apache.org/foundation/policies/conduct.html).

0 commit comments

Comments
 (0)