feat(build): introduce build scripts and public API headers

.github/.rat-excludes

@@ -0,0 +1,14 @@
+build/*
+build-debug/*
+build-release/*
+test_data/*
+third_party/*
+build_support/*
+scripts/*
+cmake_modules/*
+.codespell_ignore
+.gitignore
+rat-report.txt
+requirements.txt
+.gitattributes
+.*\.svg$

.github/actions/setup-ccache/action.yml

@@ -0,0 +1,43 @@
+# 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.
+
+name: Setup ccache
+description: Install, configure and cache ccache for CI builds
+
+inputs:
+  cache-key-prefix:
+    description: Prefix for the cache key (e.g., ccache-gcc-test)
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Install ccache
+      shell: bash
+      run: sudo apt-get update && sudo apt-get install -y ccache
+
+    - name: Restore ccache
+      uses: actions/cache@v4
+      with:
+        path: ~/.ccache
+        key: ${{ inputs.cache-key-prefix }}-${{ runner.os }}-${{ github.ref_name }}-${{ hashFiles('**/CMakeLists.txt', '**/*.cmake') }}
+        restore-keys: |
+          ${{ inputs.cache-key-prefix }}-${{ runner.os }}-${{ github.ref_name }}-
+          ${{ inputs.cache-key-prefix }}-${{ runner.os }}-
+
+    - name: Configure ccache
+      shell: bash
+      run: ci/scripts/setup_ccache.sh

LICENSE

@@ -292,6 +292,7 @@ This product includes code from Apache Arrow.
     - include/paimon/status.h
     - include/paimon/string_builder.h
     - src/paimon/common/utils/status.cpp
+  * Arrow C Data Interface in include/paimon/arrow/abi.h
 * Build support utilities:
   * build_support/asan-suppressions.txt
   * build_support/get-upstream-commit.sh
@@ -314,6 +315,8 @@ This product includes code from Apache Arrow.
   * third-party toolchain and patches:
     - cmake_modules/ThirdpartyToolchain.cmake
     - cmake_modules/arrow.diff
+    - third_party/download_dependencies.sh
+    - third_party/versions.txt
 
 Copyright: 2016-2024 The Apache Software Foundation.
 Home page: https://arrow.apache.org/

PaimonConfig.cmake.in

@@ -0,0 +1,147 @@
+# 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.
+
+# Main library
+add_library(paimon_shared SHARED IMPORTED)
+set_target_properties(paimon_shared PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon.so"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+add_library(paimon_static STATIC IMPORTED)
+set_target_properties(paimon_static PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon.a"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+
+# paimon_parquet_file_format
+add_library(paimon_parquet_file_format_shared SHARED IMPORTED)
+set_target_properties(paimon_parquet_file_format_shared PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_parquet_file_format.so"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+add_library(paimon_parquet_file_format_static STATIC IMPORTED)
+set_target_properties(paimon_parquet_file_format_static PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_parquet_file_format.a"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+
+# paimon_orc_file_format
+add_library(paimon_orc_file_format_shared SHARED IMPORTED)
+set_target_properties(paimon_orc_file_format_shared PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_orc_file_format.so"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+add_library(paimon_orc_file_format_static STATIC IMPORTED)
+set_target_properties(paimon_orc_file_format_static PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_orc_file_format.a"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+
+# paimon_local_file_system
+add_library(paimon_local_file_system_shared SHARED IMPORTED)
+set_target_properties(paimon_local_file_system_shared PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_local_file_system.so"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+add_library(paimon_local_file_system_static STATIC IMPORTED)
+set_target_properties(paimon_local_file_system_static PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_local_file_system.a"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+
+# paimon_avro_file_format
+add_library(paimon_avro_file_format_shared SHARED IMPORTED)
+set_target_properties(paimon_avro_file_format_shared PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_avro_file_format.so"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+add_library(paimon_avro_file_format_static STATIC IMPORTED)
+set_target_properties(paimon_avro_file_format_static PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_avro_file_format.a"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+
+# paimon_blob_file_format
+add_library(paimon_blob_file_format_shared SHARED IMPORTED)
+set_target_properties(paimon_blob_file_format_shared PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_blob_file_format.so"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+add_library(paimon_blob_file_format_static STATIC IMPORTED)
+set_target_properties(paimon_blob_file_format_static PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_blob_file_format.a"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+
+# paimon_file_index
+add_library(paimon_file_index_shared SHARED IMPORTED)
+set_target_properties(paimon_file_index_shared PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_file_index.so"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+add_library(paimon_file_index_static STATIC IMPORTED)
+set_target_properties(paimon_file_index_static PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_file_index.a"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+
+# paimon_global_index
+add_library(paimon_global_index_shared SHARED IMPORTED)
+set_target_properties(paimon_global_index_shared PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_global_index.so"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+add_library(paimon_global_index_static STATIC IMPORTED)
+set_target_properties(paimon_global_index_static PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_global_index.a"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+
+# paimon_jindo_file_system
+add_library(paimon_jindo_file_system_shared SHARED IMPORTED)
+set_target_properties(paimon_jindo_file_system_shared PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_jindo_file_system.so"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+add_library(paimon_jindo_file_system_static STATIC IMPORTED)
+set_target_properties(paimon_jindo_file_system_static PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_jindo_file_system.a"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+
+# paimon_lance_file_format
+add_library(paimon_lance_file_format_shared SHARED IMPORTED)
+set_target_properties(paimon_lance_file_format_shared PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_lance_file_format.so"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+add_library(paimon_lance_file_format_static STATIC IMPORTED)
+set_target_properties(paimon_lance_file_format_static PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_lance_file_format.a"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+
+# paimon_lumina_index
+add_library(paimon_lumina_index_shared SHARED IMPORTED)
+set_target_properties(paimon_lumina_index_shared PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_lumina_index.so"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)
+add_library(paimon_lumina_index_static STATIC IMPORTED)
+set_target_properties(paimon_lumina_index_static PROPERTIES
+    IMPORTED_LOCATION "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/libpaimon_lumina_index.a"
+    INTERFACE_INCLUDE_DIRECTORIES "@CMAKE_INSTALL_PREFIX@/include"
+)

build_and_package.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# 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.
+
+set -euo pipefail
+
+SOURCE_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+OUTPUT_DIR="$SOURCE_ROOT/output"
+BUILD_TYPE="Release"
+BUILD_DIR="$SOURCE_ROOT/build-release"
+BUILD_NAME="paimon-cpp"
+MAKE_CLEAN=false
+PACKAGE=false
+CMAKE_OPTIONS=()
+JOBS=""
+
+show_help() {
+    cat << EOF
+Usage: $0 [options] [cmake_options...]
+
+Options:
+  -r, --release     Build release version (default)
+  -d, --debug       Build debug version
+  -c, --clean       Clean build directory before building
+  -p, --package     Package creation
+  -j, --jobs <num>  Number of parallel jobs for building (default: auto-detect)
+  -h, --help        Show this help message
+
+CMake Options:
+  Any unrecognized options will be passed directly to CMake.
+  You can specify multiple CMake options.
+
+Examples:
+  $0 -r -p -j 8 -DPAIMON_BUILD_SHARED=ON -DPAIMON_BUILD_STATIC=OFF
+  $0 --debug --clean --package --jobs 4
+
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -r|--release)
+            BUILD_TYPE="Release"
+            BUILD_DIR="$SOURCE_ROOT/build-release"
+            BUILD_NAME="paimon-cpp"
+            shift
+            ;;
+        -d|--debug)
+            BUILD_TYPE="Debug"
+            BUILD_DIR="$SOURCE_ROOT/build-debug"
+            BUILD_NAME="paimon-cpp-debug"
+            shift
+            ;;
+        -c|--clean)
+            MAKE_CLEAN=true
+            shift
+            ;;
+        -p|--package)
+            PACKAGE=true
+            shift
+            ;;
+        -j|--jobs)
+            shift
+            if [[ $# -gt 0 && $1 =~ ^[0-9]+$ ]]; then
+                JOBS="$1"
+                shift
+            else
+                echo "Error: -j/--jobs requires a numeric argument" >&2
+                exit 1
+            fi
+            ;;
+        -h|--help)
+            show_help
+            exit 0
+            ;;
+        *)
+            # All remaining parameters are CMake options
+            CMAKE_OPTIONS+=("$1")
+            shift
+            ;;
+    esac
+done
+
+echo "========== Build Configuration =========="
+echo "Build Type: $BUILD_TYPE"
+echo "Package Name: $BUILD_NAME"
+echo "Clean Build: $MAKE_CLEAN"
+echo "Package: $PACKAGE"
+if [ -n "$JOBS" ]; then
+    echo "Parallel Jobs: $JOBS"
+else
+    echo "Parallel Jobs: auto-detect"
+fi
+if [ ${#CMAKE_OPTIONS[@]} -gt 0 ]; then
+    echo "CMake Options: ${CMAKE_OPTIONS[*]}"
+else
+    echo "CMake Options: None"
+fi
+echo "========================================="
+
+echo "Step 1: Downloading dependencies..."
+"$SOURCE_ROOT"/third_party/download_dependencies.sh
+
+echo "Step 2: Building Paimon..."
+PACKAGE_DIR="$OUTPUT_DIR/$BUILD_NAME"
+
+if [ "$MAKE_CLEAN" = true ]; then
+    echo "Cleaning build directory: $BUILD_DIR"
+    rm -rf "$BUILD_DIR"
+fi
+mkdir -p "$BUILD_DIR"
+cd "$BUILD_DIR"
+
+CMAKE_ARGS=(
+    -G "Ninja"
+    -DCMAKE_BUILD_TYPE="$BUILD_TYPE"
+    -DCMAKE_INSTALL_PREFIX="$PACKAGE_DIR"
+)
+
+if [ ${#CMAKE_OPTIONS[@]} -gt 0 ]; then
+    CMAKE_ARGS+=("${CMAKE_OPTIONS[@]}")
+fi
+
+cmake "${CMAKE_ARGS[@]}" ..
+
+# Set default JOBS if not specified
+if [ -z "$JOBS" ]; then
+    JOBS=$(nproc 2>/dev/null || echo 4)
+fi
+
+ninja -j"$JOBS"
+
+if [ "$PACKAGE" = true ]; then
+    echo "Step 3: Packaging..."
+    mkdir -p "$OUTPUT_DIR"
+    cd "$BUILD_DIR"
+    ninja install
+    tar -czvf "$OUTPUT_DIR/$BUILD_NAME.tar.gz" -C "$OUTPUT_DIR" "$BUILD_NAME"
+    echo "Package created: $OUTPUT_DIR/$BUILD_NAME.tar.gz"
+else
+    echo "Step 3: Packaging skipped."
+fi