oceanbase · dengfuping · Jan 28, 2026 · Jan 29, 2026 · Jan 28, 2026 · Jan 28, 2026
diff --git a/.github/workflows/build-libseekdb.yml b/.github/workflows/build-libseekdb.yml
diff --git a/.gitignore b/.gitignore
@@ -385,6 +385,9 @@ tools/ob-configserver/bin/*
 tools/ob-configserver/tests/*.log
 tools/ob-configserver/tests/*.out
 
+############# package/libseekdb #############
+package/libseekdb/libseekdb-*.zip
+
 ############# deps #############
 deps/oblib/src/common/storage/ob_io_selector.h
 deps/3rd

diff --git a/build.sh b/build.sh
@@ -6,13 +6,11 @@ BUILD_SH=$TOPDIR/build.sh
 DEP_DIR=${TOPDIR}/deps/3rd/usr/local/oceanbase/deps/devel
 TOOLS_DIR=${TOPDIR}/deps/3rd/usr/local/oceanbase/devtools
 
-# Get CPU cores and CMAKE command, compatible with macOS and Linux
+# Get CPU cores; cmake path is resolved in do_build() (Linux may use host cmake before deps devtools exist)
 if [[ "$(uname -s)" == "Darwin" ]]; then
-  CMAKE_COMMAND="cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1"
   CPU_CORES=$(sysctl -n hw.ncpu)
   KERNEL_RELEASE=""
 else
-  CMAKE_COMMAND="${TOOLS_DIR}/bin/cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1"
   CPU_CORES=$(grep -c ^processor /proc/cpuinfo)
   KERNEL_RELEASE=$(grep -Po 'release [0-9]{1}' /etc/issue 2>/dev/null)
 fi
@@ -166,22 +164,25 @@ function do_init
 # make build directory && cmake && make (if need)
 function do_build
 {
-    # Check if cmake exists, compatible with macOS and Linux
+    # Resolve cmake: prefer OceanBase devtools on Linux; else Homebrew/common paths; else PATH (e.g. apt cmake on CI)
     CMAKE_PATH=""
     if [[ "$(uname -s)" == "Darwin" ]]; then
-      # macOS: cmake may be at /opt/homebrew/bin/cmake or /usr/local/bin/cmake
       if [ -f /opt/homebrew/bin/cmake ]; then
         CMAKE_PATH="/opt/homebrew/bin/cmake"
       elif [ -f /usr/local/bin/cmake ]; then
         CMAKE_PATH="/usr/local/bin/cmake"
       fi
     else
-      # Linux
-      CMAKE_PATH="${TOOLS_DIR}/bin/cmake"
+      if [[ -x "${TOOLS_DIR}/bin/cmake" ]]; then
+        CMAKE_PATH="${TOOLS_DIR}/bin/cmake"
+      fi
+    fi
+    if [[ -z "$CMAKE_PATH" ]] && command -v cmake >/dev/null 2>&1; then
+      CMAKE_PATH="$(command -v cmake)"
     fi
 
     if [ -z "$CMAKE_PATH" ]; then
-      echo_log "[NOTICE] Your workspace has not initialized dependencies, please append '--init' args to initialize dependencies"
+      echo_log "[NOTICE] cmake not found. On Linux install cmake (e.g. apt install cmake) or run --init so ${TOOLS_DIR}/bin/cmake exists"
       exit 1
     fi
 
@@ -200,7 +201,7 @@ function do_build
       echo_log "Android NDK: $ANDROID_NDK_HOME"
     fi
 
-    ${CMAKE_COMMAND} ${TOPDIR} ${ANDROID_CMAKE_ARGS} "$@"
+    "${CMAKE_PATH}" -DCMAKE_EXPORT_COMPILE_COMMANDS=1 ${TOPDIR} ${ANDROID_CMAKE_ARGS} "$@"
     if [ $? -ne 0 ]; then
       echo_err "Failed to generate Makefile"
       exit 1

diff --git a/cmake/Env.cmake b/cmake/Env.cmake
@@ -190,9 +190,15 @@ if(OB_ANDROID)
   # and Env.cmake runs before project() which would set ANDROID.
   set(OB_CLANG_BIN "clang")
   set(OB_CLANGXX_BIN "clang++")
-  # NDK toolchain bin dir (derive from ANDROID_NDK_HOME or CMAKE_TOOLCHAIN_FILE)
+  # NDK toolchain bin dir (derive from ANDROID_NDK_HOME or CMAKE_TOOLCHAIN_FILE).
+  # GLOB prebuilt/*/bin so Linux hosts (e.g. CI) resolve linux-x86_64, macOS resolves darwin-x86_64.
   if(DEFINED ENV{ANDROID_NDK_HOME})
-    set(_NDK_TOOLCHAIN_BIN "$ENV{ANDROID_NDK_HOME}/toolchains/llvm/prebuilt/darwin-x86_64/bin")
+    file(GLOB _NDK_TOOLCHAIN_BIN "$ENV{ANDROID_NDK_HOME}/toolchains/llvm/prebuilt/*/bin")
+    list(LENGTH _NDK_TOOLCHAIN_BIN _ndk_bin_n)
+    if(_ndk_bin_n LESS 1)
+      message(FATAL_ERROR "ANDROID_NDK_HOME: no toolchains/llvm/prebuilt/*/bin under $ENV{ANDROID_NDK_HOME}")
+    endif()
+    list(GET _NDK_TOOLCHAIN_BIN 0 _NDK_TOOLCHAIN_BIN)
   else()
     # Derive from toolchain file path: .../build/cmake/android.toolchain.cmake -> .../toolchains/llvm/prebuilt/*/bin
     get_filename_component(_NDK_ROOT "${CMAKE_TOOLCHAIN_FILE}" DIRECTORY)
@@ -237,9 +243,14 @@ endif()
 
 ob_define(OB_USE_CCACHE OFF)
 if (OB_USE_CCACHE)
+  # Prefer devtools (from deps); dep_create may wipe deps/3rd before a symlink is recreated,
+  # and Android deps do not ship obdevtools-ccache — fall back to ccache on PATH.
   find_program(OB_CCACHE ccache PATHS "${DEVTOOLS_DIR}/bin" NO_DEFAULT_PATH)
   if (NOT OB_CCACHE)
-    message(FATAL_ERROR "cannot find ccache.")
+    find_program(OB_CCACHE ccache)
+  endif()
+  if (NOT OB_CCACHE)
+    message(FATAL_ERROR "cannot find ccache. Install ccache (e.g. apt install ccache) or place it under ${DEVTOOLS_DIR}/bin.")
   else()
     set(CMAKE_C_COMPILER_LAUNCHER ${OB_CCACHE})
     set(CMAKE_CXX_COMPILER_LAUNCHER ${OB_CCACHE})

diff --git a/deps/init/dep_create.sh b/deps/init/dep_create.sh
@@ -72,6 +72,17 @@ function echo_err() {
   echo -e "[dep_create.sh][ERROR] $@" 1>&2
 }
 
+# GNU tar: archives built on macOS may contain PAX extended headers (e.g. LIBARCHIVE.xattr.com.apple.provenance);
+# extracting on Linux otherwise prints harmless "Ignoring unknown extended header keyword" noise.
+function extract_tar_gz_strip1() {
+  local dir="$1" archive="$2"
+  if tar --version 2>/dev/null | head -n1 | grep -q 'GNU tar'; then
+    (cd "$dir" && tar --warning=no-unknown-keyword -xzf "$archive" --strip-components=1)
+  else
+    (cd "$dir" && tar -xzf "$archive" --strip-components=1)
+  fi
+}
+
 function get_os_release() {
   if [[ "${ANDROID_BUILD}" == "true" ]]; then
     OS_RELEASE="android"
@@ -461,7 +472,7 @@ do
         fi
         echo_log "unpack package <${pkg}>... \c"
         if [[ "${IS_TAR_PLATFORM}" == "true" ]]; then
-          (cd ${TARGET_DIR_3RD} && tar -xzf "${TARGET_DIR_3RD}/pkg/${pkg}" --strip-components=1)
+          extract_tar_gz_strip1 "${TARGET_DIR_3RD}" "${TARGET_DIR_3RD}/pkg/${pkg}"
         elif [[ "$ID" = "arch" || "$ID" = "garuda" ]]; then
           (cd ${TARGET_DIR_3RD} && rpmextract.sh "${TARGET_DIR_3RD}/pkg/${pkg}")
         else

diff --git a/deps/oblib/src/lib/cpu/ob_cpu_topology.cpp b/deps/oblib/src/lib/cpu/ob_cpu_topology.cpp
@@ -93,7 +93,12 @@ int CpuFlagSet::init_from_os(uint64_t& flags)
 {
   int ret = OB_SUCCESS;
   flags = 0;
-#if defined(__linux__)
+#if defined(__ANDROID__)
+  // Android defines __linux__ as well, but app processes are sandboxed and shelling
+  // out to grep /proc/cpuinfo via system()/posix_spawn() is unsafe during startup.
+  // Rely on direct CPU probing instead.
+  init_from_cpu(flags);
+#elif defined(__linux__)
   const char* const CPU_FLAG_CMDS[(int)CpuFlag::MAX] = {"grep -E ' sse4_2( |$)' /proc/cpuinfo > /dev/null 2>&1",
       "grep -E ' avx( |$)' /proc/cpuinfo > /dev/null 2>&1",
       "grep -E ' avx2( |$)' /proc/cpuinfo > /dev/null 2>&1",
@@ -113,8 +118,8 @@ int CpuFlagSet::init_from_os(uint64_t& flags)
       flags |= (1 << i);
     }
   }
-#elif defined(__APPLE__) || defined(__ANDROID__)
-  // On macOS/Android, /proc/cpuinfo doesn't exist or SSE/AVX features are irrelevant.
+#elif defined(__APPLE__)
+  // On macOS, /proc/cpuinfo doesn't exist or SSE/AVX features are irrelevant.
   // We can use sysctl to check for features, but for now we rely on init_from_cpu
   // and just return success here with flags set to a reasonable default or
   // matched with cpu flags to avoid mismatch error in constructor.

diff --git a/deps/oblib/src/lib/signal/ob_signal_handlers.cpp b/deps/oblib/src/lib/signal/ob_signal_handlers.cpp
@@ -87,6 +87,13 @@ static inline void handler(int sig, siginfo_t *s, void *p)
 int install_ob_signal_handler()
 {
   int ret = OB_SUCCESS;
+#ifdef __ANDROID__
+  // ART/libsigchain owns fatal signal dispatch for app processes. Installing
+  // OceanBase's process-wide crash handlers here interferes with JNI/runtime
+  // fault handling and can turn startup failures into opaque instrumentation
+  // crashes.
+  return ret;
+#else
   struct sigaction sa;
   sa.sa_flags = SA_SIGINFO | SA_RESTART | SA_NODEFER | SA_ONSTACK;
   sa.sa_sigaction = handler;
@@ -102,6 +109,7 @@ int install_ob_signal_handler()
     }
   }
   return ret;
+#endif
 }
 
 bool g_redirect_handler = false;

diff --git a/docs/developer-guide/en/android.md b/docs/developer-guide/en/android.md
@@ -5,7 +5,7 @@ Cross-compile seekdb for Android arm64-v8a on macOS using the NDK toolchain, the
 ## Prerequisites
 
 - macOS host (this guide is written for macOS)
-- Android NDK 27.x installed (default: `~/Library/Android/sdk/ndk/27.3.13750724`)
+- Android NDK installed (**27.x is recommended** to match pre-built dependencies; other major versions are untested). Default path example: `~/Library/Android/sdk/ndk/27.3.13750724`
 - Android emulator running arm64-v8a (API 28+), or a physical device
 - Dependencies built via [ob-deps](https://github.com/oceanbase/ob-deps/tree/android_arm64-v8a) `ndk/build_all.sh`
 - `adb` available on PATH
@@ -31,13 +31,34 @@ This runs `deps/init/dep_create.sh` in Android mode, which downloads and extract
 pre-built NDK dependency tarballs into `deps/3rd/`.
 
 ### 2. Configure and build
+
 To build only the observer binary:
 
 ```bash
 cd build_android_release
 make seekdb -j$(nproc)
 ```
 
+### Build libseekdb (FFI shared library)
+
+In the same Android build directory, build the C API shared library (CMake target `libseekdb`, output `libseekdb.so`):
+
+```bash
+cd build_android_release
+make libseekdb -j$(nproc)
+```
+
+The artifact is usually `build_android_release/src/include/libseekdb.so` (relative to the repo root). The public header is `src/include/seekdb.h` in the source tree.
+
+To reduce size, strip ELF with the NDK `llvm-strip` (not the host `strip`). On macOS or Linux hosts the toolchain lives under `toolchains/llvm/prebuilt/<host>/bin/`, for example:
+
+```bash
+NDK_STRIP=$(echo "$ANDROID_NDK_HOME"/toolchains/llvm/prebuilt/*/bin/llvm-strip)
+$NDK_STRIP -o /tmp/libseekdb.stripped build_android_release/src/include/libseekdb.so
+```
+
+You can also pack `seekdb.h` and `libseekdb.so` into **`libseekdb-android-arm64-v8a.zip`** with [`package/libseekdb/libseekdb-build.sh`](../../../package/libseekdb/libseekdb-build.sh) (**arm64-v8a only**). From `package/libseekdb/` run `./libseekdb-build.sh --android` (builds if needed), or `./libseekdb-build.sh <path/to/build_android_*/src/include>` to pack an existing tree. On macOS, a tree that only contains the NDK-built `libseekdb.so` still gets that naming (not `darwin-*`).
+
 ### 3. Build unit tests (optional)
 
 A combined `all_tests` binary includes all unit tests in a single executable:
@@ -50,8 +71,9 @@ make all_tests
 ## Deploy to Emulator
 
 ### Strip debug symbols
+
 ```bash
-NDK_STRIP=$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-strip
+NDK_STRIP=$(echo "$ANDROID_NDK_HOME"/toolchains/llvm/prebuilt/*/bin/llvm-strip)
 
 $NDK_STRIP -o /tmp/seekdb build_android_release/src/observer/seekdb
 ```
@@ -114,4 +136,4 @@ adb shell "tail -100 /data/local/tmp/seekdb_data/log/seekdb.log"
 
 ```bash
 adb shell "kill \$(pidof seekdb)"
-```
+```
diff --git a/docs/developer-guide/zh/android.md b/docs/developer-guide/zh/android.md
@@ -5,7 +5,7 @@
 ## 前置条件
 
 - macOS 主机（本文档基于 macOS 环境编写）
-- 已安装 Android NDK 27.x（默认路径：`~/Library/Android/sdk/ndk/27.3.13750724`）
+- 已安装 Android NDK（**推荐 27.x**，与预构建依赖一致；其它主版本需自行验证。默认路径示例：`~/Library/Android/sdk/ndk/27.3.13750724`）
 - 运行 arm64-v8a（API 28+）的 Android 模拟器，或物理设备
 - 通过 [ob-deps](https://github.com/oceanbase/ob-deps/tree/android_arm64-v8a) 的 `ndk/build_all.sh` 构建依赖
 - 已安装 `adb` 并加入 PATH
@@ -38,6 +38,26 @@ cd build_android_release
 make seekdb -j$(nproc)
 ```
 
+### 构建 libseekdb（FFI 共享库）
+
+在相同 Android 构建目录下编译 C API 共享库（CMake 目标名 `libseekdb`，产物为 `libseekdb.so`）：
+
+```bash
+cd build_android_release
+make libseekdb -j$(nproc)
+```
+
+产物路径一般为仓库根目录下的 `build_android_release/src/include/libseekdb.so`，头文件为源码树中的 `src/include/seekdb.h`。
+
+若需缩小体积，请使用 NDK 自带的 `llvm-strip` 处理 ELF（不要用 macOS 自带的 `strip`）。在 macOS / Linux 主机上，工具链位于 `toolchains/llvm/prebuilt/<宿主>/bin/`，例如：
+
+```bash
+NDK_STRIP=$(echo "$ANDROID_NDK_HOME"/toolchains/llvm/prebuilt/*/bin/llvm-strip)
+$NDK_STRIP -o /tmp/libseekdb.stripped build_android_release/src/include/libseekdb.so
+```
+
+也可在仓库内使用 [`package/libseekdb/libseekdb-build.sh`](../../../package/libseekdb/libseekdb-build.sh) 打包 `seekdb.h` 与 `libseekdb.so` 为 **`libseekdb-android-arm64-v8a.zip`**（仅支持 **arm64-v8a**）。在 `package/libseekdb/` 下执行 `./libseekdb-build.sh --android`（会先按需构建），或 `./libseekdb-build.sh <path/to/build_android_*/src/include>` 仅打包已有产物；在 macOS 上仅含 NDK 产出的 `libseekdb.so` 时也会使用该命名，避免误用 `darwin-*`。
+
 ### 3. 构建单元测试（可选）
 
 `all_tests` 会将所有单元测试合并到一个可执行文件中：
@@ -52,7 +72,7 @@ make all_tests
 ### 移除调试符号
 
 ```bash
-NDK_STRIP=$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-strip
+NDK_STRIP=$(echo "$ANDROID_NDK_HOME"/toolchains/llvm/prebuilt/*/bin/llvm-strip)
 
 $NDK_STRIP -o /tmp/seekdb build_android_release/src/observer/seekdb
 ```

diff --git a/package/libseekdb/README.md b/package/libseekdb/README.md
@@ -0,0 +1,76 @@
+# libseekdb package
+
+Portable C library build of libseekdb for Linux (x64/arm64) and macOS (arm64). Output is a zip containing `seekdb.h` and `libseekdb.so` (Linux) or `libseekdb.dylib` (macOS), suitable for standalone use.
+
+## Build
+
+```bash
+./libseekdb-build.sh
+```
+
+Output: `libseekdb-<os>-<arch>.zip` is created in this directory. Arch is `x64` (for x86_64) or `arm64`, e.g. `libseekdb-linux-x64.zip`, `libseekdb-linux-arm64.zip`, `libseekdb-darwin-arm64.zip`.
+
+### Reference build environments (CI)
+
+The supported systems and environments are defined by the GitHub Actions workflow [`.github/workflows/build-libseekdb.yml`](../../.github/workflows/build-libseekdb.yml). The workflow builds on push/PR and optionally uploads zips to S3 when **DESTINATION_TARGET_PATH** (e.g. `s3://bucket/libseekdb/<sha>`) or **AWS_S3_BUCKET** and AWS credentials are configured.
+
+| Platform    | Zip name                   | Runner / container                                   | Deps profile              |
+| ----------- | -------------------------- | ---------------------------------------------------- | ------------------------- |
+| Linux x64   | libseekdb-linux-x64.zip    | ubuntu-22.04 + quay.io/pypa/manylinux2014_x86_64     | oceanbase.el7.x86_64.deps |
+| Linux arm64 | libseekdb-linux-arm64.zip  | ubuntu-22.04-arm + quay.io/pypa/manylinux2014_aarch64 | oceanbase.el7.aarch64.deps |
+| macOS arm64 | libseekdb-darwin-arm64.zip | macos-14 (native)                                    | oceanbase.macos.arm64.deps |
+
+Use these systems and deps as the standard when building or consuming libseekdb.
+
+### Linux glibc compatibility
+
+CI Linux builds use **pypa/manylinux2014** (CentOS 7–based), which ships **glibc 2.17**. The prebuilt `libseekdb.so` therefore requires **GLIBC_2.17** or newer on the target system, **including CentOS 7**.
+
+- **Supported (glibc ≥ 2.17)**: CentOS 7 / RHEL 7, CentOS 8 / RHEL 8, AlmaLinux 7/8, Rocky Linux 8/9, Ubuntu 18.04+, Debian 10+, Fedora 25+, and most distros from about 2014 onward. This covers current and legacy Linux environments, including CentOS 7.
+- **Not supported (glibc &lt; 2.17)**: CentOS 6 (2.12) and older distros. For these, build libseekdb locally on the target system.
+
+To check your system: `ldd --version` or `getconf GNU_LIBC_VERSION`.
+
+### macOS compatibility
+
+CI macOS builds use **macOS 14** runners and set **CMAKE_OSX_DEPLOYMENT_TARGET=11.0**, so the prebuilt `libseekdb.dylib` runs on **macOS 11 (Big Sur) and later** (12, 13, 14, 15). Setting the deployment target to 11.0 allows use on most current and recent macOS versions.
+
+## Package contents and standalone distribution
+
+Zip layout:
+
+```
+seekdb.h           # C API header
+libseekdb.dylib    # Main library (macOS) or libseekdb.so (Linux)
+libs/              # Dependency dylibs (macOS only; collected by dylibbundler)
+  *.dylib
+```
+
+- **Standalone distribution**: After extraction, the package can be used by other projects without this repo or the build environment.
+- **macOS**: The main library and its dependencies use relative paths (`@loader_path/libs`). Unzip to any directory and keep the main library and `libs/` at the same level so they load correctly.
+- **Linux**: Usually has no extra dependencies or relies on system libraries; unzip and use as-is.
+
+### How to use (standalone)
+
+1. Unzip to a target directory, e.g. `/opt/seekdb-sdk/`:
+   ```
+   /opt/seekdb-sdk/
+     seekdb.h
+     libseekdb.dylib
+     libs/
+       libfoo.dylib
+       ...
+   ```
+
+2. Point your build at the header and library, e.g.:
+   ```bash
+   gcc -I/opt/seekdb-sdk -L/opt/seekdb-sdk -lseekdb ...
+   ```
+   At runtime on macOS, the main library loads dependencies from `libs/` in the same directory; you do not need to set `DYLD_LIBRARY_PATH`.
+
+3. If the main library and the executable are in different directories (e.g. executable in `bin/`, library in `lib/`), ensure `libs/` exists next to the main library, or put the dependencies where the system can find them and set `DYLD_LIBRARY_PATH` (not recommended; prefer keeping the zip layout).
+
+### Notes
+
+- **OS and architecture**: The zip name reflects the build OS and CPU: `darwin-arm64`, `linux-x64`, `linux-arm64` (x64 = x86_64). Use the matching zip for the target environment. On Linux, the prebuilt .so requires glibc ≥ 2.17 (see [Linux glibc compatibility](#linux-glibc-compatibility)), including CentOS 7; on macOS, the prebuilt dylib is built on **macOS 14** with **minimum deployment target 11.0**, so it runs on **macOS 11 (Big Sur) and later** (12, 13, 14, 15).
+- **Rebuilding**: After changing loader path or dependencies, run `libseekdb-build.sh` again to produce a new zip.