Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

Build: add multi-platform native build support (linux/arm64, darwin) (#19247)

xugangqiangb44e852e6bf3
diff --git a/build.sh b/build.sh
index 01455d877f..160e5d58b7 100755
--- a/build.sh
+++ b/build.sh
@@ -55,6 +55,84 @@ PDF_OXIDE_VERSION="0.3.73"
# Downloaded by tools/scripts/download_dev_deps.py into onnxruntime/static_lib.
ONNXRUNTIME_STATIC_PREFIX="${HOME}/ragflow-native-libs/onnxruntime/static_lib"
+# ── target platform detection ──────────────────────────────────────────
+# Defaults to the build host (uname), overridable with RAGFLOW_TARGET_OS /
+# RAGFLOW_TARGET_ARCH for cross-baked dependency downloads. goos ∈ {linux,
+# darwin}; goarch ∈ {amd64, arm64}.
+TARGET_OS=""
+TARGET_ARCH=""
+detect_target_platform() {
+ TARGET_OS="${RAGFLOW_TARGET_OS:-$(uname -s)}"
+ TARGET_ARCH="${RAGFLOW_TARGET_ARCH:-$(uname -m)}"
+ case "$TARGET_OS" in
+ Linux) TARGET_OS="linux" ;;
+ Darwin) TARGET_OS="darwin" ;;
+ esac
+ case "$TARGET_ARCH" in
+ x86_64|amd64) TARGET_ARCH="amd64" ;;
+ arm64|aarch64) TARGET_ARCH="arm64" ;;
+ esac
+ export TARGET_OS TARGET_ARCH
+}
+
+# Map the target platform to the release asset filename for each native lib.
+# These mirror tools/scripts/download_dev_deps.py's *_ASSETS maps and the
+# verified upstream release assets.
+office_oxide_asset() {
+ case "${TARGET_OS}_${TARGET_ARCH}" in
+ linux_amd64) echo "native-linux-x86_64.tar.gz" ;;
+ linux_arm64) echo "native-linux-aarch64.tar.gz" ;;
+ darwin_amd64) echo "native-macos-x86_64.tar.gz" ;;
+ darwin_arm64) echo "native-macos-aarch64.tar.gz" ;;
+ esac
+}
+pdfium_asset() {
+ case "${TARGET_OS}_${TARGET_ARCH}" in
+ linux_amd64) echo "pdfium-linux-x64-static.tgz" ;;
+ linux_arm64) echo "pdfium-linux-arm64-static.tgz" ;;
+ darwin_amd64) echo "pdfium-mac-x64-static.tgz" ;;
+ darwin_arm64) echo "pdfium-mac-arm64-static.tgz" ;;
+ esac
+}
+pdf_oxide_asset() {
+ case "${TARGET_OS}_${TARGET_ARCH}" in
+ linux_amd64) echo "pdf_oxide-go-ffi-linux-amd64.tar.gz" ;;
+ linux_arm64) echo "pdf_oxide-go-ffi-linux-arm64.tar.gz" ;;
+ darwin_amd64) echo "pdf_oxide-go-ffi-darwin-amd64.tar.gz" ;;
+ darwin_arm64) echo "pdf_oxide-go-ffi-darwin-arm64.tar.gz" ;;
+ esac
+}
+# Release target token of the ONNX Runtime zip published under
+# infiniflow/ragflow-build tag onnxruntime-v{version}: linux-x86_64,
+# linux-aarch64, osx-arm64, osx-universal (no osx-x86_64 is published —
+# Intel Macs use the universal archive). Mirrors download_dev_deps.py's
+# ort_target().
+ort_release_target() {
+ case "${TARGET_OS}_${TARGET_ARCH}" in
+ linux_amd64) echo "linux-x86_64" ;;
+ linux_arm64) echo "linux-aarch64" ;;
+ darwin_amd64) echo "osx-universal" ;;
+ darwin_arm64) echo "osx-arm64" ;;
+ esac
+}
+# Top-level dir prefix of the extracted ONNX Runtime static lib under
+# $ONNXRUNTIME_STATIC_PREFIX, e.g. onnxruntime-linux-x64-static_lib-.
+# download_dev_deps.py renames each release zip's top-level dir to
+# onnxruntime-<os>-<arch>-static_lib-<version>[-glibc2_28] (see its
+# ort_normalized_dir), so this prefix — plus the DeepDocORTVersion parsed
+# below — pins the dir we link. Keeping it platform-specific stops a shared
+# cache from linking an ORT built for another OS/arch. The arch token is not
+# GOARCH: Linux uses x64/aarch64, and macOS uses arm64 or universal (Intel Macs
+# share the universal archive — ragflow-build publishes no osx-x86_64).
+ort_static_lib_prefix() {
+ case "${TARGET_OS}_${TARGET_ARCH}" in
+ linux_amd64) echo "onnxruntime-linux-x64-static_lib-" ;;
+ linux_arm64) echo "onnxruntime-linux-aarch64-static_lib-" ;;
+ darwin_amd64) echo "onnxruntime-osx-universal-static_lib-" ;;
+ darwin_arm64) echo "onnxruntime-osx-arm64-static_lib-" ;;
+ esac
+}
+
# Copy a dependency from the system pre-seed directory to the user cache.
# Returns 0 if the dep was copied or already exists in cache, 1 otherwise.
_seed_from_system() {
@@ -269,6 +347,16 @@ check_ort_version_consistency() {
# use). Devs who ran a download script have the zip under ragflow_deps/; CI
# seeds from /opt and has no zip, where the bake is authoritative.
check_onnxruntime_deps() {
+ # Ensure TARGET_OS/TARGET_ARCH are resolved. ort_static_lib_prefix below
+ # depends on them; without this guard an early call (before any other path
+ # triggers detect_target_platform) would resolve the archive glob against an
+ # empty prefix and could pick up an ORT built for the wrong platform from a
+ # shared cache. Idempotent: derive once, then reuse the result.
+ if [ -z "$_TARGET_PLATFORM_DETECTED" ]; then
+ detect_target_platform
+ _TARGET_PLATFORM_DETECTED=1
+ fi
+
local ort_version
ort_version="$(grep -m1 -E 'DeepDocORTVersion[[:space:]]*=[[:space:]]*"' \
"${PROJECT_ROOT}/internal/common/environments.go" \
@@ -285,12 +373,26 @@ check_onnxruntime_deps() {
ORT_A_FILES=""
local primary=""
local f
+ # Platform-specific top-level dir prefix (see ort_static_lib_prefix)
+ # plus the required version — a shared cache can hold ORT built for
+ # another OS/arch, and the Python side legitimately keeps another ORT
+ # version in the same prefix. Matching both is why coexisting version
+ # dirs need no separate fail-fast guard here.
+ local ort_dir_prefix
+ ort_dir_prefix="$(ort_static_lib_prefix)"
while IFS= read -r f; do
case "$(basename "$f")" in
*cuda*|*tensorrt*|*coreml*|*dml*|*migraphx*) continue ;;
esac
case "$f" in
- */onnxruntime-linux-x64-static_lib-"${ort_version}"*/lib/*.a)
+ # Only collect .a from the dir matching both the target
+ # platform and the required version: ${ort_dir_prefix} pins
+ # OS/arch (a shared cache can also hold ORT built for another
+ # platform), ${ort_version} pins DeepDocORTVersion (the Python
+ # side legitimately keeps another ORT version in the same
+ # prefix). Matching both is why coexisting version dirs no
+ # longer need a fail-fast guard here.
+ */${ort_dir_prefix}${ort_version}*/lib/*.a)
ORT_A_FILES="$ORT_A_FILES $f"
[ -z "$primary" ] && primary="$f"
case "$(basename "$f")" in
@@ -303,7 +405,7 @@ check_onnxruntime_deps() {
if [ -z "$ORT_A_FILES" ]; then
local avail
avail="$(find "$ONNXRUNTIME_STATIC_PREFIX" -maxdepth 1 -type d \
- -name 'onnxruntime-linux-x64-static_lib-*' -exec basename {} \; 2>/dev/null | tr '\n' ' ')"
+ -name "${ort_dir_prefix}*" -exec basename {} \; 2>/dev/null | tr '\n' ' ')"
echo -e "${RED}Error: no ONNX Runtime ${ort_version} static lib under $ONNXRUNTIME_STATIC_PREFIX${NC}" >&2
echo " available: ${avail:-<none>}" >&2
echo " DeepDocORTVersion=${ort_version}; fetch it with:" >&2
@@ -325,10 +427,26 @@ check_onnxruntime_deps() {
# tools/scripts/download_dev_deps.py still verifies against
# the published sidecar at download time, so a re-issued archive is picked
# up on the next download.
- local asset="onnxruntime-v${ort_version}-linux-x86_64.zip"
+ #
+ # The digest is per release target (see ort_release_target): comparing a
+ # macOS zip against the Linux digest would warn on every build, so an
+ # unknown target verifies nothing instead.
+ local asset="onnxruntime-v${ort_version}-$(ort_release_target).zip"
local zip_path="${PROJECT_ROOT}/ragflow_deps/${asset}"
- local expected="439308c93822d26cf04341cab3e77c595bbe88a12b54043210d14a0ca5574bd1"
- if [ -f "$zip_path" ]; then
+ local expected=""
+ case "$asset" in
+ onnxruntime-v*-linux-x86_64.zip)
+ expected="439308c93822d26cf04341cab3e77c595bbe88a12b54043210d14a0ca5574bd1" ;;
+ onnxruntime-v*-linux-aarch64.zip)
+ expected="59a30fc0754d2b3dafb2761f208610e9be962f6370a0e1223fbca39440fa02a0" ;;
+ onnxruntime-v*-osx-arm64.zip)
+ expected="e80f81e61750f7cfde8bada1f2175c5218d9d910a5ec61bc70dba4a1f7c950eb" ;;
+ onnxruntime-v*-osx-universal.zip)
+ expected="29e9ceeaa84eba4734bbc8b7a8473487e1deb8010a2b6bc1b1cd695a4d87e7f3" ;;
+ esac
+ if [ -z "$expected" ]; then
+ echo " (no pinned digest for ${asset}; skipping sha256 check)"
+ elif [ -f "$zip_path" ]; then
local actual
actual="$(sha256sum "$zip_path" | awk '{print $1}')"
if [ "$actual" != "$expected" ]; then
@@ -363,7 +481,7 @@ check_office_oxide_deps() {
echo -e "${RED}Error: office_oxide native library not found${NC}"
echo " Expected: ${lib_path}"
echo " Run: uv run tools/scripts/download_dev_deps.py"
- echo " Or manually download: https://github.com/yfedoseev/office_oxide/releases/download/v${OFFICE_OXIDE_VERSION}/native-linux-x86_64.tar.gz"
+ echo " Or manually download: https://github.com/yfedoseev/office_oxide/releases/download/v${OFFICE_OXIDE_VERSION}/$(office_oxide_asset)"
exit 1
fi
@@ -375,12 +493,12 @@ check_office_oxide_deps() {
local found_version
found_version=$(strings "$lib_path" 2>/dev/null | grep -E "^0\.[0-9]+\.[0-9]+$" | head -1)
echo -e "${YELLOW}office_oxide native lib version mismatch (required v${OFFICE_OXIDE_VERSION}; found: ${found_version:-unknown}); refreshing from download${NC}"
- rm -rf "${OFFICE_OXIDE_PREFIX}" "${PROJECT_ROOT}/office_oxide-linux-x86_64.tar.gz"
+ rm -rf "${OFFICE_OXIDE_PREFIX}" "${PROJECT_ROOT}/ragflow_deps/$(office_oxide_asset)"
if ! (cd "${PROJECT_ROOT}" && uv run tools/scripts/download_dev_deps.py); then
echo -e "${RED}Error: office_oxide native lib version mismatch${NC}"
echo " Required: v${OFFICE_OXIDE_VERSION}; found: ${found_version:-unknown}"
echo " A stale lib silently loses PPT97 (.ppt) slide content. Refresh:"
- echo " rm -rf ~/ragflow-native-libs/office_oxide ragflow_deps/office_oxide-linux-x86_64.tar.gz"
+ echo " rm -rf ~/ragflow-native-libs/office_oxide ragflow_deps/$(office_oxide_asset)"
echo " uv run tools/scripts/download_dev_deps.py"
exit 1
fi
@@ -415,7 +533,7 @@ check_pdfium_deps() {
echo " pdfium (static) not found"
echo " Expected: ${lib_path}"
echo " Run: uv run tools/scripts/download_dev_deps.py"
- echo " Or: curl -fsSL https://github.com/kognitos/pdfium-static/releases/download/chromium%2F${PDFIUM_STATIC_VERSION}/pdfium-linux-x64-static.tgz | tar xz -C ${PDFIUM_STATIC_PREFIX}"
+ echo " Or: curl -fsSL https://github.com/kognitos/pdfium-static/releases/download/chromium%2F${PDFIUM_STATIC_VERSION}/$(pdfium_asset) | tar xz -C ${PDFIUM_STATIC_PREFIX}"
return 1
}
@@ -463,24 +581,13 @@ pdf_oxide_validate_version() {
check_pdf_oxide_deps() {
_seed_from_system "pdf_oxide" || true
- # Map platform to tarball-internal subdirectory.
- local platform_subdir
- case "$(uname -s)" in
- Linux)
- case "$(uname -m)" in
- x86_64) platform_subdir="linux_amd64" ;;
- aarch64|arm64) platform_subdir="linux_arm64" ;;
- *) echo " pdf_oxide (static) → unsupported arch"; return 1 ;;
- esac
- ;;
- Darwin)
- case "$(uname -m)" in
- x86_64) platform_subdir="darwin_amd64" ;;
- arm64) platform_subdir="darwin_arm64" ;;
- *) echo " pdf_oxide (static) → unsupported arch"; return 1 ;;
- esac
- ;;
- *) echo " pdf_oxide (static) → unsupported OS"; return 1 ;;
+ # Map platform to tarball-internal subdirectory (lib/<os>_<arch>/). Reuses
+ # TARGET_OS/TARGET_ARCH set by detect_target_platform instead of re-deriving
+ # from uname, so it stays consistent with the other check_*_deps helpers.
+ local platform_subdir="${TARGET_OS}_${TARGET_ARCH}"
+ case "$platform_subdir" in
+ linux_amd64|linux_arm64|darwin_amd64|darwin_arm64) ;;
+ *) echo " pdf_oxide (static) → unsupported platform: $platform_subdir"; return 1 ;;
esac
local lib_path="${PDF_OXIDE_PREFIX}/lib/${platform_subdir}/libpdf_oxide.a"
@@ -519,7 +626,7 @@ check_pdf_oxide_deps() {
echo -e "${RED}Error: pdf_oxide native lib version mismatch${NC}"
echo " Required: v${PDF_OXIDE_VERSION}; found: ${found_version:-unknown}"
echo " A stale lib silently reverts PDF parsing fixes. Refresh:"
- echo " rm -rf ${PDF_OXIDE_PREFIX} ragflow_deps/pdf_oxide-go-ffi-linux-amd64.tar.gz"
+ echo " rm -rf ${PDF_OXIDE_PREFIX} ragflow_deps/$(pdf_oxide_asset)"
echo " uv run tools/scripts/download_dev_deps.py"
return 1
;;
@@ -529,7 +636,7 @@ check_pdf_oxide_deps() {
echo " pdf_oxide (static) not found"
echo " Expected: ${lib_path}"
echo " Run: uv run tools/scripts/download_dev_deps.py"
- echo " Or: curl -fsSL https://github.com/yfedoseev/pdf_oxide/releases/download/v${PDF_OXIDE_VERSION}/pdf_oxide-go-ffi-linux-amd64.tar.gz | tar xz -C ${PDF_OXIDE_PREFIX}"
+ echo " Or: curl -fsSL https://github.com/yfedoseev/pdf_oxide/releases/download/v${PDF_OXIDE_VERSION}/$(pdf_oxide_asset) | tar xz -C ${PDF_OXIDE_PREFIX}"
return 1
}
@@ -569,16 +676,24 @@ build_cpp() {
# onnxruntime keeps calling its own. Verified to eliminate the crash.
local tok_a="$BUILD_DIR/librag_tokenizer_c_api.a"
local rename_map="$BUILD_DIR/re2_rename.map"
+ # GNU objcopy is standard on Linux; on macOS it is provided by LLVM as
+ # llvm-objcopy (brew install llvm). Prefer whichever is available.
+ local objcopy_bin=""
if command -v objcopy >/dev/null 2>&1; then
+ objcopy_bin=objcopy
+ elif command -v llvm-objcopy >/dev/null 2>&1; then
+ objcopy_bin=llvm-objcopy
+ fi
+ if [ -n "$objcopy_bin" ]; then
nm "$tok_a" \
| awk '$2 ~ /^[TDBRWtdbrwiIVv]$/ && $3 ~ /^_ZN3re2|_ZNK3re2|_ZTVN3re2|_ZTIN3re2|_ZTSN3re2/ { print $3" ragtokre2_"$3 }' \
| sort -u > "$rename_map"
if [ -s "$rename_map" ]; then
- objcopy --redefine-syms="$rename_map" "$tok_a"
+ "$objcopy_bin" --redefine-syms="$rename_map" "$tok_a"
echo -e "${GREEN}✓ Renamed $(wc -l < "$rename_map") tokenizer re2 symbols into private namespace (ragtokre2_)${NC}"
fi
else
- echo -e "${YELLOW}Warning: objcopy not found, skipping re2 symbol rename (re2 collision with onnxruntime may cause SIGSEGV)${NC}"
+ echo -e "${YELLOW}Warning: objcopy/llvm-objcopy not found, skipping re2 symbol rename (re2 collision with onnxruntime may cause SIGSEGV)${NC}"
fi
echo -e "${GREEN}✓ C++ static library built successfully${NC}"
@@ -696,6 +811,8 @@ build_go() {
# Configure CGO flags for native libraries (office_oxide, pdfium, pdf_oxide).
# All three are statically linked — no LD_LIBRARY_PATH or -Wl,-rpath needed.
setup_cgo_env() {
+ detect_target_platform
+
# ── office_oxide ──────────────────────────────────────────────────
check_office_oxide_deps
@@ -744,23 +861,14 @@ setup_cgo_env() {
# ── pdf_oxide ─────────────────────────────────────────────────────
check_pdf_oxide_deps || return 1
- # The go-ffi tarball places the .a under lib/<platform_subdir>/.
- local pdf_oxide_subdir
- case "$(uname -s)" in
- Linux)
- case "$(uname -m)" in
- x86_64) pdf_oxide_subdir="linux_amd64" ;;
- aarch64|arm64) pdf_oxide_subdir="linux_arm64" ;;
- *) echo "pdf_oxide: unsupported arch"; return 1 ;;
- esac
- ;;
- Darwin)
- case "$(uname -m)" in
- x86_64) pdf_oxide_subdir="darwin_amd64" ;;
- arm64) pdf_oxide_subdir="darwin_arm64" ;;
- *) echo "pdf_oxide: unsupported arch"; return 1 ;;
- esac
- ;;
+ # The go-ffi tarball places the .a under lib/<platform_subdir>/. Reuses
+ # TARGET_OS/TARGET_ARCH set by detect_target_platform (instead of
+ # re-deriving from uname) so RAGFLOW_TARGET_OS/ARCH overrides apply here
+ # exactly as they do in check_pdf_oxide_deps.
+ local pdf_oxide_subdir="${TARGET_OS}_${TARGET_ARCH}"
+ case "$pdf_oxide_subdir" in
+ linux_amd64|linux_arm64|darwin_amd64|darwin_arm64) ;;
+ *) echo "pdf_oxide: unsupported platform: $pdf_oxide_subdir"; return 1 ;;
esac
# Version-stamp the archive path so an in-place .a upgrade invalidates
# Go's build cache. See the office_oxide block above for why the raw path
@@ -774,36 +882,30 @@ setup_cgo_env() {
export CGO_LDFLAGS="$CGO_LDFLAGS ${pdf_oxide_versioned_dir}/libpdf_oxide.a"
# ── onnxruntime (static, resolved via dlopen(NULL)) ────────────────
- # macOS native builds of the in-process DeepDoc backend are not supported:
- # ONNX Runtime is statically linked with GNU ld flags
- # (-Wl,--undefined=OrtGetApiBase + -Wl,--dynamic-list) and resolved at
- # runtime via dlopen(NULL); Apple's ld64 does not understand these flags.
- # Build on Linux or cross-compile there.
- case "$(uname -s)" in
- Darwin)
- echo "Error: macOS native build of the in-process DeepDoc backend is not supported." >&2
- echo " ONNX Runtime is linked with GNU ld flags (-Wl,--undefined=OrtGetApiBase + -Wl,--dynamic-list)" >&2
- echo " and resolved via dlopen(NULL); Apple's ld64 does not support them. Build on Linux." >&2
- return 1
- ;;
- esac
# Statically link libonnxruntime*.a into the binary. The org Go binding
# (onnxruntime_go, github.com/infiniflow/onnxruntime_go) resolves OrtGetApiBase
# with dlopen(NULL) + dlsym(handle, "OrtGetApiBase"), so the ONLY symbol that
- # must be visible in the process-global table is OrtGetApiBase.
+ # must be visible in the process-global table is OrtGetApiBase. No
+ # libonnxruntime.so/.dylib is required or supported at runtime; there is no
+ # dynamic fallback.
#
- # We therefore do NOT use --whole-archive: that flag force-pulls every .o in
- # the archive (including unregistered "dead" kernels we never call), which
- # is why every ORT size-trimming build flag had near-zero effect before.
- # Instead we link the archives normally and let GNU ld's archive-level GC
- # drop any kernel/EP object that nothing references. The onnxruntime_go
- # binding reaches ORT purely through the OrtApi function-pointer table
- # returned by OrtGetApiBase, and a minimal/reduced-ops build registers only
- # the operators the deepdoc models actually use, so the reachable closure is
- # small. --dynamic-list exports just OrtGetApiBase (the only symbol dlopen
- # needs) and leaves Go's runtime symbols untouched, unlike a "local: *"
- # version script which breaks PIE absolute relocations. No libonnxruntime.so
- # is required or supported at runtime; there is no dynamic .so fallback.
+ # The two linkers need different flags to get there (see the platform
+ # branch further down where CGO_LDFLAGS is assembled):
+ # Linux (GNU ld): force-pull just the archive member defining OrtGetApiBase
+ # and export exactly that symbol — no --whole-archive, so archive-level GC
+ # drops every ORT kernel/EP object nothing references (that flag is why
+ # every ORT size-trimming build flag had near-zero effect before). The
+ # binding reaches ORT purely through the OrtApi function-pointer table
+ # returned by OrtGetApiBase, and a minimal/reduced-ops build registers
+ # only the operators the deepdoc models actually use, so the reachable
+ # closure is small. --dynamic-list exports just OrtGetApiBase (the only
+ # symbol dlopen needs) and leaves Go's runtime symbols untouched, unlike
+ # a "local: *" version script which breaks PIE absolute relocations.
+ # macOS (ld64): no GNU ld flags exist, so pull the archives in with
+ # -force_load and export them with -export_dynamic. This path is written
+ # but NOT yet verified on real Apple-Silicon hardware — the dlopen(NULL)
+ # resolution of OrtGetApiBase under -export_dynamic must be confirmed
+ # there. (待 Mac 验证)
#
# Seed the static ORT archives from the system pre-bake (/opt, laid down
# by the CI runner image) into the user cache before the link check
@@ -831,36 +933,54 @@ setup_cgo_env() {
ort_a_versioned="$ort_a_versioned $ort_versioned_dir/$(basename "$f")"
done
- # Export exactly one symbol (OrtGetApiBase) for the binding's
- # dlopen(NULL)+dlsym lookup via --dynamic-list (NOT --version-script
- # with "local: *", which hides Go's runtime type symbols and breaks
- # the PIE absolute relocations). No --whole-archive, so GNU ld's
- # archive-level GC drops any ORT kernel/EP object nothing references.
- #
- # The dynamic list is written to a STABLE, project-scoped path (not
- # mktemp) so CGO_LDFLAGS is reproducible across builds and survives
- # across invocations; its content never changes, so overwriting is
- # safe and nothing leaks in /tmp. .cache/ is gitignored.
- local ort_dynamic_list="${PROJECT_ROOT}/.cache/ort_dynamic_list.txt"
- mkdir -p "$(dirname "$ort_dynamic_list")"
- printf '{\n OrtGetApiBase;\n};\n' > "$ort_dynamic_list"
- # --undefined=OrtGetApiBase force-pulls the archive member that
- # defines OrtGetApiBase (the Go binding reaches ORT only via
- # dlsym("OrtGetApiBase"), so nothing references it at link time and
- # it would otherwise be GC'd). From there the minimal build's CPU-EP
- # registration call chain pulls in the operators the models use.
- # The explicit space between $ort_dynamic_list and the versioned .a
- # list keeps the two as separate linker arguments regardless of the
- # list's leading space.
- export CGO_LDFLAGS="$CGO_LDFLAGS -Wl,--undefined=OrtGetApiBase -Wl,--dynamic-list=$ort_dynamic_list $ort_a_versioned -lstdc++"
+ if [ "$TARGET_OS" = "darwin" ]; then
+ # ld64 has no --undefined / --dynamic-list spelled the GNU way.
+ # Force-load each archive so ORT's lazily-registered execution
+ # providers are pulled in, and export the symbols so the runtime
+ # dlopen(NULL) can resolve OrtGetApiBase.
+ #
+ # NOTE: the macOS link path is NOT yet verified on a real Apple
+ # Silicon machine — the dlopen(NULL) symbol resolution of
+ # OrtGetApiBase under -export_dynamic must be confirmed there.
+ # (待 Mac 验证)
+ local ort_force=""
+ for f in $ort_a_versioned; do
+ ort_force="$ort_force -Wl,-force_load,$f"
+ done
+ export CGO_LDFLAGS="$CGO_LDFLAGS -Wl,-export_dynamic${ort_force} -lc++"
+ else
+ # Export exactly one symbol (OrtGetApiBase) for the binding's
+ # dlopen(NULL)+dlsym lookup via --dynamic-list (NOT --version-script
+ # with "local: *", which hides Go's runtime type symbols and breaks
+ # the PIE absolute relocations). No --whole-archive, so GNU ld's
+ # archive-level GC drops any ORT kernel/EP object nothing references.
+ #
+ # The dynamic list is written to a STABLE, project-scoped path (not
+ # mktemp) so CGO_LDFLAGS is reproducible across builds and survives
+ # across invocations; its content never changes, so overwriting is
+ # safe and nothing leaks in /tmp. .cache/ is gitignored.
+ local ort_dynamic_list="${PROJECT_ROOT}/.cache/ort_dynamic_list.txt"
+ mkdir -p "$(dirname "$ort_dynamic_list")"
+ printf '{\n OrtGetApiBase;\n};\n' > "$ort_dynamic_list"
+ # --undefined=OrtGetApiBase force-pulls the archive member that
+ # defines OrtGetApiBase (the Go binding reaches ORT only via
+ # dlsym("OrtGetApiBase"), so nothing references it at link time and
+ # it would otherwise be GC'd). From there the minimal build's CPU-EP
+ # registration call chain pulls in the operators the models use.
+ # The explicit space between $ort_dynamic_list and the versioned .a
+ # list keeps the two as separate linker arguments regardless of the
+ # list's leading space.
+ export CGO_LDFLAGS="$CGO_LDFLAGS -Wl,--undefined=OrtGetApiBase -Wl,--dynamic-list=$ort_dynamic_list $ort_a_versioned -lstdc++"
+ fi
echo " onnxruntime (static) → $ONNXRUNTIME_STATIC_PREFIX"
# The re2 regex-library collision between onnxruntime.a and
# librag_tokenizer_c_api.a is fixed at the .a level in build_cpp():
# the tokenizer's bundled re2 symbols are renamed into a private
# namespace (ragtokre2_) so the two re2 copies never share a symbol
- # name. --dynamic-list (above) exports OrtGetApiBase into the process
- # dynamic symbol table, which is what the binding's dlopen(NULL)+dlsym
- # lookup needs at runtime (no --export-dynamic required).
+ # name. OrtGetApiBase is exported into the process dynamic symbol
+ # table on Linux via --dynamic-list (above) — or, on macOS, via
+ # -export_dynamic — which is what the binding's dlopen(NULL)+dlsym
+ # lookup needs at runtime.
# ── platform-specific system libraries ────────────────────────────
case "$(uname -s)" in
diff --git a/internal/development.md b/internal/development.md
index e1e1df36d5..f5a599cb4d 100644
--- a/internal/development.md
+++ b/internal/development.md
@@ -25,6 +25,34 @@ sudo ln -s /usr/bin/clang-20 /usr/bin/clang
sudo ln -s /usr/bin/ld.lld-20 /usr/bin/ld.lld
```
+> **ARM64 (aarch64) build hosts need more than the above** (empirical minimum,
+> verified on a Snapdragon X Elite host with a trixie-based container):
+> - glibc ≥ 2.38 — the prebuilt native libs reference `__isoc23_*` symbols;
+> Debian bookworm (glibc 2.36) fails linking with
+> `undefined reference to __isoc23_strtoll`.
+> - GCC ≥ 13 (libstdc++ ≥ 13) — symbols like
+> `std::__cxx11::basic_string::_M_replace_cold` need GCC 13+; bookworm's
+> GCC 12 fails.
+> - `libsimde-dev` — SIMDe supplies the x86 SSE/AVX headers the C++ sources
+> include (`simde/x86/sse4.1.h`, …); without it `./build.sh --cpp` fails at
+> the include stage.
+> - cmake ≥ 4.0 — the DeepDoc C++ project requires cmake 4.x; Ubuntu 24.04's
+> default-repo cmake is older than that (§1.1's kitware route installs a
+> current one).
+> - lld ≥ 20 — **lld-18 is not enough**. With lld-18 the Go binaries link
+> successfully but then hang at startup: 100% CPU spin, zero output, before
+> any Go init runs (`GODEBUG=inittrace=1` prints nothing). Root cause:
+> build.sh's versioned-symlink cache-busting paths (e.g.
+> `office_oxide-v0.1.12/lib/liboffice_oxide.a`) make lld-18 pull in ~4 MB of
+> duplicate archive members, and the duplicated C++ static initializers spin
+> forever. The same flags with lld-20 produce a correct, smaller binary
+> (12.5 MB vs 16.7 MB).
+>
+> The `apt install clang-20 lld-20` above only works on distros that ship them
+> (e.g. Debian trixie); Ubuntu 24.04's default lld is 18. On 24.04 use a
+> trixie-based container or the LLVM apt repository — an ARM64 host that
+> silently keeps lld-18 hits the startup hang described above.
+
### 1.3 Install golang
```shell
@@ -44,7 +72,7 @@ uv run tools/scripts/download_dev_deps.py # local-dev one-stop: native .a + cl
Install `uv` before running the downloaders; it installs each script's declared Python dependencies.
-`download_dev_deps.py` is the local-dev one-stop: it provisions the Go native libraries under `~/ragflow-native-libs` AND the `.ort` weights, embedding tokenizer assets, and `cl100k_base.tiktoken` into `internal/rag/res/deepdoc/` and `ragflow_deps/huggingface.co/`. Run it once and the local environment is ready. The image-facing `ragflow_deps/download_deps.py` provisions the same runtime resources plus the stagehand driver (installed into the SDK's cache, using the SDK version from `go.mod`) and skips the native `.a`; run it only when building the dependency image or in CI. Native archives support Linux x86_64.
+`download_dev_deps.py` is the local-dev one-stop: it provisions the Go native libraries under `~/ragflow-native-libs` AND the `.ort` weights, embedding tokenizer assets, and `cl100k_base.tiktoken` into `internal/rag/res/deepdoc/` and `ragflow_deps/huggingface.co/`. Run it once and the local environment is ready. The image-facing `ragflow_deps/download_deps.py` provisions the same runtime resources plus the stagehand driver (installed into the SDK's cache, using the SDK version from `go.mod`) and skips the native `.a`; run it only when building the dependency image or in CI. Native archives are fetched per target platform (linux/darwin on amd64/arm64; override with `RAGFLOW_TARGET_OS` / `RAGFLOW_TARGET_ARCH`).
Build the Go resource image from `ragflow_deps/` after preparing these files:
@@ -59,28 +87,57 @@ The image contains Go DeepDoc weights, tokenizer assets, the BPE table, and stag
>
> ```bash
> RAGFLOW_DEPS="${HOME}/ragflow-native-libs" # created by download_dev_deps.py
-> PLATFORM="linux_amd64" # macOS (darwin_*) is temporarily unsupported; linux_arm64 is not a supported native build target
-> # NOTE: the ONNX Runtime static lib fetched by download_dev_deps.py is
-> # linux-x64 ONLY (onnxruntime-linux-x64-static_lib-*). On darwin_* / non-amd64
-> # PLATFORM values the production DeepDoc backend cannot be linked, so those
-> # PLATFORM examples cover office_oxide/pdfium/pdf_oxide only — ORT is a
-> # Linux-amd64 link dependency here. macOS is temporarily not supported by the
-> # Go backend; use a Linux x86-64 host for a supported native build.
+> PLATFORM="linux_amd64" # or darwin_amd64, linux_arm64, darwin_arm64
+> # Native libs are fetched for the *host* platform by download_dev_deps.py
+> # (override with RAGFLOW_TARGET_OS / RAGFLOW_TARGET_ARCH). ONNX Runtime static
+> # libs are published for linux-x86_64, linux-aarch64, osx-arm64 and
+> # osx-universal (Intel Macs use the universal archive — there is no osx-x86_64),
+> # so the production DeepDoc backend links on all four. On Linux the link force-pulls
+> # OrtGetApiBase and exports just it (--undefined=OrtGetApiBase + --dynamic-list,
+> # no --whole-archive) with -fuse-ld=lld + -lstdc++; on macOS (ld64) it uses
+> # -force_load + -export_dynamic + -lc++ instead, since ld64 has no GNU ld
+> # equivalents. The macOS path is written but NOT yet verified on real
+> # Apple-Silicon hardware — confirm the dlopen(NULL) resolution of OrtGetApiBase
+> # there. (待 Mac 验证)
>
> # Resolve the version-stamped ORT archive path FIRST, in its own unquoted
> # assignment: the shell does not expand `*` inside the double-quoted
> # CGO_LDFLAGS below. If this lists more than one match, delete the stale
> # version dir — build.sh refuses to link two ORT versions.
-> ORT_A="$(ls ${RAGFLOW_DEPS}/onnxruntime/static_lib/*/lib/libonnxruntime.a)"
+> # The glob must pin the target platform: the extracted dir is
+> # onnxruntime-<os>-<arch>-static_lib-<version> (see ort_static_lib_prefix in
+> # build.sh). A bare */ would also match ORT built for another OS/arch in a
+> # shared cache. For linux_amd64 the prefix is onnxruntime-linux-x64-static_lib-;
+> # for linux_arm64 use onnxruntime-linux-aarch64-static_lib-; for macOS use
+> # onnxruntime-osx-arm64-static_lib- (darwin_arm64) or
+> # onnxruntime-osx-universal-static_lib- (darwin_amd64, Intel Macs).
+> ORT_A="$(ls ${RAGFLOW_DEPS}/onnxruntime/static_lib/onnxruntime-linux-x64-static_lib-*/lib/libonnxruntime.a)"
>
-> # The binding reaches ORT with dlopen(NULL)+dlsym("OrtGetApiBase"), so
-> # OrtGetApiBase is the only symbol that must be visible process-wide. Export
-> # just it — not via a "local: *" version script, which hides Go's runtime type
-> # symbols and breaks PIE absolute relocations. There is deliberately no
-> # --whole-archive, so unreferenced kernels are dropped. Write the dynamic
-> # list to .cache/ (gitignored), matching build.sh.
-> mkdir -p .cache
-> printf '{\n OrtGetApiBase;\n};\n' > .cache/ort_dynamic_list.txt
+> # Link flags differ between Linux (GNU ld) and macOS (ld64). On macOS the
+> # path below is written but NOT yet verified on real Apple-Silicon hardware
+> # (see "待 Mac 验证" above) — prefer `build.sh` which derives the same flags.
+> if [ "$(uname -s)" = "Darwin" ]; then
+> ORT_LINK="-Wl,-export_dynamic"
+> for a in ${ORT_A}; do ORT_LINK="${ORT_LINK} -Wl,-force_load,${a}"; done
+> ORT_LINK="${ORT_LINK} -lc++"
+> # System libs mirror setup_cgo_env in build.sh for darwin: the frameworks are
+> # required by ONNX Runtime's Core ML / system integrations, and -liconv /
+> # -lresolv back the string/network code paths the static archive references.
+> SYS_LIBS="-framework CoreGraphics -framework CoreFoundation \
+> -framework Security -framework SystemConfiguration \
+> -liconv -lresolv -lm -lpthread -ldl -lutil -lc -lc++"
+> else
+> # The binding reaches ORT with dlopen(NULL)+dlsym("OrtGetApiBase"), so
+> # OrtGetApiBase is the only symbol that must be visible process-wide. Export
+> # just it via --dynamic-list — not a "local: *" version script, which hides
+> # Go's runtime type symbols and breaks PIE absolute relocations. There is
+> # deliberately no --whole-archive, so unreferenced kernels are dropped.
+> # The dynamic list lives in .cache/ (gitignored), matching build.sh.
+> mkdir -p .cache
+> printf '{\n OrtGetApiBase;\n};\n' > .cache/ort_dynamic_list.txt
+> ORT_LINK="-Wl,--undefined=OrtGetApiBase -Wl,--dynamic-list=.cache/ort_dynamic_list.txt ${ORT_A} -lstdc++"
+> SYS_LIBS="-fuse-ld=lld -lm -lpthread -ldl -lrt -lgcc_s -lutil -lc"
+> fi
>
> export CGO_CFLAGS="-I${RAGFLOW_DEPS}/office_oxide/include/office_oxide_c"
> export CGO_LDFLAGS="\
@@ -89,18 +146,21 @@ The image contains Go DeepDoc weights, tokenizer assets, the BPE table, and stag
> ${RAGFLOW_DEPS}/pdfium-static/lib/libc++.a \
> ${RAGFLOW_DEPS}/pdfium-static/lib/libc++abi.a \
> ${RAGFLOW_DEPS}/pdf_oxide/lib/${PLATFORM}/libpdf_oxide.a \
-> -Wl,--undefined=OrtGetApiBase -Wl,--dynamic-list=.cache/ort_dynamic_list.txt ${ORT_A} -lstdc++ \
-> -fuse-ld=lld \
-> -lm -lpthread -ldl -lrt -lgcc_s -lutil -lc"
+> ${ORT_LINK} \
+> ${SYS_LIBS}"
> ```
>
> All four native libraries are statically linked — no `LD_LIBRARY_PATH` or `-Wl,-rpath` needed.
>
> **ONNX Runtime is mandatory for the production binary.** The in-process (Go)
-> DeepDoc backend is statically linked against `libonnxruntime.a` (no
-> `--whole-archive`; `OrtGetApiBase` is force-pulled with
-> `-Wl,--undefined=OrtGetApiBase` and exported via `--dynamic-list`), and
-> `OrtGetApiBase` is resolved at runtime through `dlopen(NULL)`. The org
+> DeepDoc backend is statically linked against `libonnxruntime.a`. On Linux the
+> only symbol that must be visible process-wide is `OrtGetApiBase`: it is
+> force-pulled with `-Wl,--undefined=OrtGetApiBase` and exported via
+> `--dynamic-list` (no `--whole-archive`, so unreferenced kernels are dropped).
+> On macOS (ld64) the archives are instead pulled in with `-force_load` and
+> exported with `-export_dynamic`, since ld64 has no GNU ld equivalents; this
+> path is written but NOT yet verified on real Apple-Silicon hardware. In both
+> cases `OrtGetApiBase` is resolved at runtime through `dlopen(NULL)`. The org
> `onnxruntime_go` binding
> (github.com/infiniflow/onnxruntime_go, the mirror of yalue/onnxruntime_go) only
> needs `-ldl` to *compile*, so a binary built **without** ORT links
@@ -134,9 +194,10 @@ The image contains Go DeepDoc weights, tokenizer assets, the BPE table, and stag
> **Note**: `build.sh` also guards ONNX Runtime **archive integrity** and the
> **link cache**, because a silently-stale `.a` is easy to miss:
> - `check_onnxruntime_deps` compares the local release ZIP under `ragflow_deps/`
-> (`onnxruntime-v<ver>-linux-x86_64.zip`) against the SHA-256 digest pinned in
+> (`onnxruntime-v<ver>-<target>.zip`, e.g. `-linux-x86_64` / `-osx-arm64`)
+> against the SHA-256 digest pinned in
> `build.sh`, without a network request. The downloader separately checks the
-> published `onnxruntime-v<ver>-linux-x86_64.zip.sha256` sidecar. A local ZIP
+> published `onnxruntime-v<ver>-<target>.zip.sha256` sidecar. A local ZIP
> mismatch only emits a warning with the expected/actual SHA-256 and the
> refresh command (`rm -f <zip>` + `uv run tools/scripts/download_dev_deps.py`);
> the build continues checking and linking the extracted static libraries. CI seeds
diff --git a/tools/scripts/download_dev_deps.py b/tools/scripts/download_dev_deps.py
index a8c91a27a0..a67fea2eba 100755
--- a/tools/scripts/download_dev_deps.py
+++ b/tools/scripts/download_dev_deps.py
@@ -35,10 +35,28 @@
#
# Behind the GFW, route GitHub release downloads through a mirror with
# --china-mirrors (or export GH_PROXY=https://gh-proxy.com/).
+#
+# Platform support
+# ----------------
+# The native static libraries are downloaded for the *target* platform by
+# default. The target GOOS/GOARCH is detected from the host `uname`; override it
+# with RAGFLOW_TARGET_OS / RAGFLOW_TARGET_ARCH (or --target-os / --target-arch)
+# when baking a cross-platform environment or when the host's reported arch is
+# wrong.
+#
+# linux/amd64 -> native-linux-x86_64 / pdfium-linux-x64 / ... / onnxruntime-v{VER}-linux-x86_64
+# linux/arm64 -> native-linux-aarch64 / pdfium-linux-arm64 / ... / onnxruntime-v{VER}-linux-aarch64
+# darwin/amd64 -> native-macos-x86_64 / pdfium-mac-x64 / ... / onnxruntime-v{VER}-osx-universal
+# darwin/arm64 -> native-macos-aarch64 / pdfium-mac-arm64 / ... / onnxruntime-v{VER}-osx-arm64
+#
+# The in-process (Go) DeepDoc backend statically links ONNX Runtime; the
+# symlink-free `dlopen(NULL)` resolution means no `.so`/`.dylib` ships at
+# runtime.
import argparse
import hashlib
import os
+import platform
import re
import shutil
import sys
@@ -59,12 +77,12 @@ import requests
#
# Source of the native static archives: infiniflow/ragflow-build (our own
# ORT-only minimal build), NOT the third-party csukuangfj/onnxruntime-libs
-# account. The release tag is `onnxruntime-v{ORT_VERSION}` and the asset is
-# `onnxruntime-v{ORT_VERSION}-linux-x86_64.zip`. The archive is occasionally
-# re-issued under this SAME tag/asset name with patched content (e.g. the
-# build that exports SessionGetInitializer*); the downloader detects that via
-# a `{asset}.sha256` sidecar and re-downloads/re-extracts, so a stale local
-# copy never silently lingers.
+# account. The release tag is `onnxruntime-v{ORT_VERSION}` and it publishes one
+# asset per target: `onnxruntime-v{ORT_VERSION}-<target>.zip` (see ort_target).
+# The archive is occasionally re-issued under this SAME tag/asset name with
+# patched content (e.g. the build that exports SessionGetInitializer*); the
+# downloader detects that via a `{asset}.sha256` sidecar and
+# re-downloads/re-extracts, so a stale local copy never silently lingers.
ORT_VERSION = "1.29.0"
# pdf_oxide go-ffi release. Bare module version (the "v" is added by
@@ -78,6 +96,58 @@ PDF_OXIDE_VERSION = "0.3.73"
PDFIUM_VERSION = "7809"
+def host_platform(target_os=None, target_arch=None):
+ """Return (goos, goarch) for the build target.
+
+ Defaults to the host machine, overridable via the RAGFLOW_TARGET_OS /
+ RAGFLOW_TARGET_ARCH environment variables or the explicit arguments (the
+ --target-os / --target-arch CLI flags) so a cross-platform environment can
+ be baked for a foreign arch.
+ """
+ raw_os = target_os or os.environ.get("RAGFLOW_TARGET_OS")
+ raw_arch = target_arch or os.environ.get("RAGFLOW_TARGET_ARCH")
+ if not raw_os:
+ raw_os = platform.system() # "Linux" / "Darwin" / ...
+ if not raw_arch:
+ raw_arch = platform.machine().lower() # x86_64 / arm64 / aarch64 / ...
+
+ # Normalize the same aliases build.sh's detect_target_platform accepts, so
+ # `RAGFLOW_TARGET_OS=Linux RAGFLOW_TARGET_ARCH=x86_64` (valid for build.sh)
+ # does not raise KeyError when indexing the per-platform asset maps below.
+ goos = {"linux": "linux", "darwin": "darwin"}.get(raw_os.lower())
+ if goos is None:
+ raise SystemExit(f"Unsupported target OS={raw_os!r}; expected linux or darwin (aliases Linux/Darwin also accepted).")
+ goarch = {"amd64": "amd64", "x86_64": "amd64", "arm64": "arm64", "aarch64": "arm64"}.get(raw_arch.lower())
+ if goarch is None:
+ raise SystemExit(f"Unsupported target arch={raw_arch!r}; expected amd64 or arm64 (aliases x86_64/aarch64 also accepted).")
+ return goos, goarch
+
+
+# Per-(goos, goarch) release asset filenames. The tarballs extract flat into
+# `~/ragflow-native-libs/<lib>/` with a platform-independent internal layout
+# (office_oxide: lib/liboffice_oxide.a + include/office_oxide_c/; pdfium:
+# lib/libpdfium.a; pdf_oxide: lib/<platform_subdir>/libpdf_oxide.a +
+# include/), so build.sh resolves the same paths on every platform.
+OFFICE_OXIDE_ASSETS = {
+ ("linux", "amd64"): "native-linux-x86_64.tar.gz",
+ ("linux", "arm64"): "native-linux-aarch64.tar.gz",
+ ("darwin", "amd64"): "native-macos-x86_64.tar.gz",
+ ("darwin", "arm64"): "native-macos-aarch64.tar.gz",
+}
+PDFIUM_STATIC_ASSETS = {
+ ("linux", "amd64"): "pdfium-linux-x64-static.tgz",
+ ("linux", "arm64"): "pdfium-linux-arm64-static.tgz",
+ ("darwin", "amd64"): "pdfium-mac-x64-static.tgz",
+ ("darwin", "arm64"): "pdfium-mac-arm64-static.tgz",
+}
+PDF_OXIDE_ASSETS = {
+ ("linux", "amd64"): "pdf_oxide-go-ffi-linux-amd64.tar.gz",
+ ("linux", "arm64"): "pdf_oxide-go-ffi-linux-arm64.tar.gz",
+ ("darwin", "amd64"): "pdf_oxide-go-ffi-darwin-amd64.tar.gz",
+ ("darwin", "arm64"): "pdf_oxide-go-ffi-darwin-arm64.tar.gz",
+}
+
+
def gh_proxy() -> str:
"""GitHub release proxy prefix (gh-proxy.com behind the GFW), else empty."""
return os.environ.get("GH_PROXY") or ""
@@ -99,47 +169,71 @@ def go_module_version(module: str, repo_root: str) -> str:
# ── URL builders ──────────────────────────────────────────────────────────
# Every download URL is assembled from the constants above via one of these
-# helpers, so a version bump touches exactly one constant.
+# helpers, so a version bump touches exactly one constant. Each takes the target
+# (goos, goarch) and resolves the release asset filename from the per-platform
+# maps above.
-def pdf_oxide_url() -> str:
- """pdf_oxide go-ffi tarball."""
- return f"{gh_proxy()}https://github.com/yfedoseev/pdf_oxide/releases/download/v{PDF_OXIDE_VERSION}/pdf_oxide-go-ffi-linux-amd64.tar.gz"
+def pdf_oxide_url(goos: str, goarch: str) -> str:
+ """pdf_oxide go-ffi tarball for the target platform."""
+ return f"{gh_proxy()}https://github.com/yfedoseev/pdf_oxide/releases/download/v{PDF_OXIDE_VERSION}/{PDF_OXIDE_ASSETS[(goos, goarch)]}"
-def pdfium_url() -> str:
- """pdfium static library tarball."""
- return f"{gh_proxy()}https://github.com/kognitos/pdfium-static/releases/download/chromium%2F{PDFIUM_VERSION}/pdfium-linux-x64-static.tgz"
+def pdfium_url(goos: str, goarch: str) -> str:
+ """pdfium static library tarball for the target platform."""
+ return f"{gh_proxy()}https://github.com/kognitos/pdfium-static/releases/download/chromium%2F{PDFIUM_VERSION}/{PDFIUM_STATIC_ASSETS[(goos, goarch)]}"
-def office_oxide_url(repo_root: str) -> str:
- """office_oxide native tarball. The version is derived from go.mod so it
- always matches what the Go build actually links (no second hardcoded copy
- to drift)."""
+def office_oxide_url(repo_root: str, goos: str, goarch: str) -> str:
+ """office_oxide native tarball for the target platform. The version is
+ derived from go.mod so it always matches what the Go build actually links
+ (no second hardcoded copy to drift)."""
version = go_module_version("github.com/yfedoseev/office_oxide/go", repo_root)
- return f"{gh_proxy()}https://github.com/yfedoseev/office_oxide/releases/download/v{version}/native-linux-x86_64.tar.gz"
+ return f"{gh_proxy()}https://github.com/yfedoseev/office_oxide/releases/download/v{version}/{OFFICE_OXIDE_ASSETS[(goos, goarch)]}"
# ── ONNX Runtime release asset helpers ─────────────────────────────────────
-def ort_asset_name(version: str = ORT_VERSION) -> str:
+def ort_target(goos: str, goarch: str) -> str:
+ """infiniflow/ragflow-build release target for (goos, goarch).
+
+ The release publishes one zip per target: linux-x86_64, linux-aarch64,
+ osx-arm64 and osx-universal. There is no osx-x86_64 — Intel Macs use the
+ universal archive (x86_64 + arm64 in one .a).
+ """
+ if goos == "linux":
+ return "linux-x86_64" if goarch == "amd64" else "linux-aarch64"
+ return "osx-universal" if goarch == "amd64" else "osx-arm64"
+
+
+def ort_asset_name(version: str, target: str) -> str:
"""Release asset filename under infiniflow/ragflow-build tag onnxruntime-v{version}."""
- return f"onnxruntime-v{version}-linux-x86_64.zip"
+ return f"onnxruntime-v{version}-{target}.zip"
-def ort_url(version: str = ORT_VERSION) -> str:
- return f"{gh_proxy()}https://github.com/infiniflow/ragflow-build/releases/download/onnxruntime-v{version}/{ort_asset_name(version)}"
+def ort_url(version: str, target: str) -> str:
+ return f"{gh_proxy()}https://github.com/infiniflow/ragflow-build/releases/download/onnxruntime-v{version}/{ort_asset_name(version, target)}"
-def ort_extracted_dir(version: str = ORT_VERSION) -> str:
+def ort_extracted_dir(version: str, target: str) -> str:
"""Top-level directory name INSIDE the release zip (what extractall creates)."""
- return f"onnxruntime-v{version}-linux-x86_64"
+ return f"onnxruntime-v{version}-{target}"
-def ort_normalized_dir(version: str = ORT_VERSION) -> str:
- """Directory name build.sh's `find ... -name '*.a'` glob expects under static_lib."""
- return f"onnxruntime-linux-x64-static_lib-{version}-glibc2_28"
+def ort_normalized_dir(version: str, goos: str, goarch: str) -> str:
+ """Directory name build.sh's `find ... -name '*.a'` glob expects under static_lib.
+
+ Not the zip's own top-level dir: build.sh matches the onnxruntime release
+ layout (onnxruntime-<os>-<arch>-static_lib-<version>[-glibc2_28]), so
+ extract_onnxruntime() renames the extracted dir to this. The glibc suffix
+ exists on Linux only.
+ """
+ if goos == "linux":
+ arch_token = "x64" if goarch == "amd64" else "aarch64"
+ return f"onnxruntime-linux-{arch_token}-static_lib-{version}-glibc2_28"
+ arch_token = "universal" if goarch == "amd64" else "arm64"
+ return f"onnxruntime-osx-{arch_token}-static_lib-{version}"
def _repo_root() -> str:
@@ -210,7 +304,7 @@ def _valid_download(filename):
if filename.endswith((".tar.gz", ".tgz")):
if not tarfile.is_tarfile(filename):
return False
- if os.path.basename(filename) == "office_oxide-linux-x86_64.tar.gz":
+ if os.path.basename(filename) in OFFICE_OXIDE_ASSETS.values():
version = go_module_version("github.com/yfedoseev/office_oxide/go", REPO_ROOT)
with tarfile.open(filename) as archive:
try:
@@ -276,18 +370,18 @@ def _extract_native_archive(archive_path, target, required_files, version=None):
print(f" ✓ extracted {os.path.basename(archive_path)} to {target}")
-def prune_stale_onnxruntime(static_lib_dir, version):
+def prune_stale_onnxruntime(static_lib_dir, expected_dir):
"""Remove ONNX Runtime version dirs under static_lib that do NOT match
- `version`. Without this, a version bump leaves the stale dir next to
- the new one and build.sh's `find ... -name '*.a'` links BOTH (duplicate
- symbols / wrong version, silently)."""
+ `expected_dir`. Without this, a version bump (or a foreign-arch run on a
+ shared cache) leaves a stale dir next to the new one and build.sh's
+ `find ... -name '*.a'` links BOTH (duplicate symbols / wrong version,
+ silently)."""
if not os.path.isdir(static_lib_dir):
return
- expected = ort_normalized_dir(version)
for name in os.listdir(static_lib_dir):
- if not name.startswith("onnxruntime-linux-x64-static_lib-"):
+ if not name.startswith("onnxruntime-"):
continue
- if name == expected:
+ if name == expected_dir:
continue
stale = os.path.join(static_lib_dir, name)
print(f" Removing stale ONNX Runtime dir: {stale}")
@@ -299,39 +393,40 @@ def has_static_archives(directory):
return any(f.endswith(".a") for _, _, files in os.walk(directory) for f in files)
-def extract_onnxruntime(static_lib_dir, archive_path, version):
- """Ensure the ONNX Runtime static archives for `version` sit under
- `static_lib_dir`. Returns True when that version is available afterwards
+def extract_onnxruntime(static_lib_dir, archive_path, expected_dir):
+ """Ensure the ONNX Runtime static archives for `expected_dir` sit under
+ `static_lib_dir`. Returns True when that dir is available afterwards
(extracted now or already present), False when the archive is missing.
- The infiniflow/ragflow-build release zip carries a top-level dir named
- onnxruntime-v{version}-linux-x86_64, so a present
+ The zip wraps everything in a version-stamped top-level dir
+ (onnxruntime-v{version}-<target>/, see ort_extracted_dir), so a present
`static_lib_dir` is NOT evidence that THIS version is extracted: after a
version bump the stale dir is pruned and the new one must be extracted.
"""
if not os.path.isfile(archive_path):
print(f" Skipping extraction: {os.path.basename(archive_path)} not found")
return False
- prune_stale_onnxruntime(static_lib_dir, version)
- version_dir = os.path.join(static_lib_dir, ort_normalized_dir(version))
- if os.path.isdir(version_dir) and has_static_archives(version_dir):
- print(f" ✓ onnxruntime/static_lib ({version}) already extracted to {version_dir}")
+ prune_stale_onnxruntime(static_lib_dir, expected_dir)
+ expected_path = os.path.join(static_lib_dir, expected_dir)
+ if os.path.isdir(expected_path) and has_static_archives(expected_path):
+ print(f" ✓ onnxruntime/static_lib ({expected_dir}) already extracted to {expected_path}")
return True
os.makedirs(static_lib_dir, exist_ok=True)
print(f" Extracting {os.path.basename(archive_path)} → {static_lib_dir}")
with zipfile.ZipFile(archive_path) as zf:
zf.extractall(static_lib_dir)
- # The release zip's top-level dir is onnxruntime-v{version}-linux-x86_64, but
- # build.sh's glob and the stale checks above all expect
- # onnxruntime-linux-x64-static_lib-{version}-glibc2_28. Rename it so every
- # consumer shares one name convention (driven by ORT_VERSION).
- extracted = os.path.join(static_lib_dir, ort_extracted_dir(version))
- normalized = os.path.join(static_lib_dir, ort_normalized_dir(version))
- if os.path.isdir(extracted) and extracted != normalized:
- if os.path.exists(normalized):
- shutil.rmtree(normalized)
- print(f" Renaming {os.path.basename(extracted)} → {os.path.basename(normalized)}")
- os.rename(extracted, normalized)
+ top_level = {name.split("/", 1)[0] for name in zf.namelist() if name.strip("/")}
+ # The zip's top-level dir (onnxruntime-v{version}-<target>) is not the name
+ # build.sh's glob and the stale-dir check above expect, so rename it to
+ # `expected_dir` — every consumer then shares one name convention.
+ normalized = os.path.join(static_lib_dir, expected_dir)
+ if len(top_level) == 1:
+ extracted = os.path.join(static_lib_dir, top_level.pop())
+ if os.path.isdir(extracted) and extracted != normalized:
+ if os.path.exists(normalized):
+ shutil.rmtree(normalized)
+ print(f" Renaming {os.path.basename(extracted)} → {os.path.basename(normalized)}")
+ os.rename(extracted, normalized)
return True
@@ -352,14 +447,15 @@ def _fetch_ort_sidecar_sha(url):
return None
-def _download_ort_archive(archive_path):
+def _download_ort_archive(archive_path, goos, goarch):
"""Download the ORT release zip, verifying it against the published
.sha256 sidecar so a re-issued archive is always refreshed.
A (re-)download drops any previously extracted version dir, so the
same-named re-issued archive actually refreshes the .a files instead of
being masked by the extraction-time idempotence check."""
- url = ort_url()
+ target = ort_target(goos, goarch)
+ url = ort_url(ORT_VERSION, target)
expected_sha = _fetch_ort_sidecar_sha(url + ".sha256")
if os.path.isfile(archive_path) and os.path.getsize(archive_path) > 0:
if expected_sha is not None:
@@ -381,7 +477,7 @@ def _download_ort_archive(archive_path):
if not _valid_download(archive_path):
os.unlink(archive_path)
raise RuntimeError(f"Invalid downloaded dependency: {os.path.basename(archive_path)}")
- version_dir = os.path.join(NATIVE_LIBS_DIR, "onnxruntime", "static_lib", ort_normalized_dir())
+ version_dir = os.path.join(NATIVE_LIBS_DIR, "onnxruntime", "static_lib", ort_normalized_dir(ORT_VERSION, goos, goarch))
if os.path.isdir(version_dir):
print(f" Removing stale extracted ONNX Runtime dir: {version_dir}")
shutil.rmtree(version_dir)
@@ -571,20 +667,35 @@ def main():
build stage bakes into the binary)."""
parser = argparse.ArgumentParser(description="Download the native static libraries and runtime resources the local Go dev server needs")
parser.add_argument("--china-mirrors", action="store_true", help="Use China-accessible mirrors for downloads")
+ parser.add_argument(
+ "--target-os",
+ default=os.environ.get("RAGFLOW_TARGET_OS"),
+ help="Override the target GOOS (linux/darwin). Defaults to host.",
+ )
+ parser.add_argument(
+ "--target-arch",
+ default=os.environ.get("RAGFLOW_TARGET_ARCH"),
+ help="Override the target GOARCH (amd64/arm64). Defaults to host.",
+ )
args = parser.parse_args()
if args.china_mirrors:
os.environ["GH_PROXY"] = "https://gh-proxy.com/"
+ goos, goarch = host_platform(args.target_os, args.target_arch)
+ print(f"Target platform: {goos}/{goarch}")
+ ort_zip = ort_asset_name(ORT_VERSION, ort_target(goos, goarch))
+ ort_dir = ort_normalized_dir(ORT_VERSION, goos, goarch)
+
# Anchor the downloaded archives to ragflow_deps/ regardless of the
# caller's working directory (build.sh invokes this from the repo root).
os.chdir(RAGFLOW_DEPS_DIR)
# ONNX Runtime archive (+ checksum sidecar), then the other native archives.
- _download_ort_archive(os.path.join(RAGFLOW_DEPS_DIR, ort_asset_name()))
+ _download_ort_archive(os.path.join(RAGFLOW_DEPS_DIR, ort_zip), goos, goarch)
archives = [
- (pdfium_url(), "pdfium-linux-x64-static.tgz"),
- (pdf_oxide_url(), "pdf_oxide-go-ffi-linux-amd64.tar.gz"),
- (office_oxide_url(REPO_ROOT), "office_oxide-linux-x86_64.tar.gz"),
+ (pdfium_url(goos, goarch), PDFIUM_STATIC_ASSETS[(goos, goarch)]),
+ (pdf_oxide_url(goos, goarch), PDF_OXIDE_ASSETS[(goos, goarch)]),
+ (office_oxide_url(REPO_ROOT, goos, goarch), OFFICE_OXIDE_ASSETS[(goos, goarch)]),
]
for url, filename in archives:
print(f"Downloading {filename} from {url}...")
@@ -600,9 +711,9 @@ def main():
# Ensures build.sh can find them without network access.
office_version = go_module_version("github.com/yfedoseev/office_oxide/go", REPO_ROOT)
extractions = [
- ("pdfium-linux-x64-static.tgz", "pdfium-static", ["lib/libpdfium.a", "lib/libc++.a", "lib/libc++abi.a", "include/fpdfview.h"], None),
- ("pdf_oxide-go-ffi-linux-amd64.tar.gz", "pdf_oxide", ["lib/linux_amd64/libpdf_oxide.a", "include/pdf_oxide.h"], None),
- ("office_oxide-linux-x86_64.tar.gz", "office_oxide", ["lib/liboffice_oxide.a", "include/office_oxide_c/office_oxide.h"], office_version),
+ (PDFIUM_STATIC_ASSETS[(goos, goarch)], "pdfium-static", ["lib/libpdfium.a", "lib/libc++.a", "lib/libc++abi.a", "include/fpdfview.h"], None),
+ (PDF_OXIDE_ASSETS[(goos, goarch)], "pdf_oxide", [f"lib/{goos}_{goarch}/libpdf_oxide.a", "include/pdf_oxide.h"], None),
+ (OFFICE_OXIDE_ASSETS[(goos, goarch)], "office_oxide", ["lib/liboffice_oxide.a", "include/office_oxide_c/office_oxide.h"], office_version),
]
for archive, subdir, required_files, version in extractions:
@@ -619,15 +730,15 @@ def main():
if not extract_onnxruntime(
os.path.join(NATIVE_LIBS_DIR, "onnxruntime", "static_lib"),
- os.path.join(RAGFLOW_DEPS_DIR, ort_asset_name()),
- ORT_VERSION,
+ os.path.join(RAGFLOW_DEPS_DIR, ort_zip),
+ ort_dir,
):
# The archive was not downloaded or failed to extract, so no .a landed.
# Fail loud instead of exiting 0: build.sh's ORT guard would otherwise
# reject the build later with a less actionable message, and a missing
# .a left here is exactly the "silent green" this split must prevent.
print(
- f" ERROR: ONNX Runtime static archives for {ORT_VERSION} were not "
+ f" ERROR: ONNX Runtime static archives for {ort_dir} were not "
f"extracted to {os.path.join(NATIVE_LIBS_DIR, 'onnxruntime', 'static_lib')}. "
f"Check the download above; build.sh will refuse to link without them.",
file=sys.stderr,
diff --git a/tools/scripts/test_download_dev_deps.py b/tools/scripts/test_download_dev_deps.py
index 9c3047d415..a928c14708 100644
--- a/tools/scripts/test_download_dev_deps.py
+++ b/tools/scripts/test_download_dev_deps.py
@@ -8,11 +8,16 @@
# an ORT version bump, where the zip's version-stamped top-level dir changes but
# static_lib/ still exists from the previous run.
#
-# The release zip from infiniflow/ragflow-build carries a top-level dir named
-# onnxruntime-v{version}-linux-x86_64; extract_onnxruntime() must rename it to the
-# build.sh-expected onnxruntime-linux-x64-static_lib-{version}-glibc2_28 so every
-# consumer shares one name convention. These tests pin that rename, the stale-dir
-# pruning, the archive member sanitization, and the atomic download behaviour.
+# The release zip from infiniflow/ragflow-build wraps everything in a top-level
+# dir named onnxruntime-v{version}-{target}; extract_onnxruntime() must rename
+# it to the build.sh-expected onnxruntime-<os>-<arch>-static_lib-{version}... so
+# every consumer shares one name convention. These tests pin that rename, the
+# stale-dir pruning, the archive member sanitization, and the atomic download
+# behaviour.
+#
+# extract_onnxruntime() takes the *expected dir name* rather than just the
+# version string, because that name is platform-dependent (linux vs osx, amd64
+# vs arm64) and build.sh's stale-version guard keys on it.
import importlib.util
import io
@@ -28,28 +33,32 @@ import pytest
import requests
-def make_ort_zip(path, version):
+def make_ort_zip(path, dir_name):
"""Build a zip shaped like the infiniflow/ragflow-build ORT release: a
- top-level dir named onnxruntime-v{version}-linux-x86_64 holding
- lib/libonnxruntime.a. extract_onnxruntime() must rename it to the
- build.sh-expected onnxruntime-linux-x64-static_lib-{version}-glibc2_28."""
- member = f"{native.ort_extracted_dir(version)}/lib/libonnxruntime.a"
+ top-level dir holding lib/libonnxruntime.a. extract_onnxruntime() must
+ rename it to the build.sh-expected dir (see ort_normalized_dir)."""
with zipfile.ZipFile(path, "w") as zf:
- zf.writestr(member, b"!<arch>\nort-payload")
+ zf.writestr(f"{dir_name}/lib/libonnxruntime.a", b"!<arch>\nort-payload")
return path
+def ort_archive(tmp_path, goos="linux", goarch="amd64", version="1.29.0"):
+ """Return (zip_path, normalized_dir) for `goos/goarch` at `version`."""
+ target = native.ort_target(goos, goarch)
+ zip_path = tmp_path / native.ort_asset_name(version, target)
+ return make_ort_zip(zip_path, native.ort_extracted_dir(version, target)), native.ort_normalized_dir(version, goos, goarch)
+
+
def test_extracts_on_first_run(tmp_path):
# static_lib/ does not exist yet: the plain first-run path.
static_lib = tmp_path / "onnxruntime" / "static_lib"
- version = "1.29.0"
- archive = make_ort_zip(tmp_path / native.ort_asset_name(version), version)
+ archive, dir_name = ort_archive(tmp_path)
- assert native.extract_onnxruntime(str(static_lib), str(archive), version) is True
+ assert native.extract_onnxruntime(str(static_lib), str(archive), dir_name) is True
- extracted = static_lib / native.ort_extracted_dir(version)
+ extracted = static_lib / native.ort_extracted_dir("1.29.0", native.ort_target("linux", "amd64"))
assert not extracted.exists(), "release zip top-level dir must be renamed away"
- version_dir = static_lib / native.ort_normalized_dir(version)
+ version_dir = static_lib / dir_name
assert version_dir.is_dir()
assert native.has_static_archives(str(version_dir))
@@ -61,39 +70,154 @@ def test_extracts_after_version_bump_when_static_lib_exists(tmp_path):
build.sh's ORT guard rejects the build."""
static_lib = tmp_path / "onnxruntime" / "static_lib"
static_lib.mkdir(parents=True)
- stale = static_lib / native.ort_normalized_dir("1.28.0")
+ stale = static_lib / native.ort_normalized_dir("1.28.0", "linux", "amd64")
(stale / "lib").mkdir(parents=True)
(stale / "lib" / "libonnxruntime.a").write_bytes(b"old-ort")
- version = "1.29.0"
- archive = make_ort_zip(tmp_path / native.ort_asset_name(version), version)
+ archive, dir_name = ort_archive(tmp_path)
- assert native.extract_onnxruntime(str(static_lib), str(archive), version) is True
+ assert native.extract_onnxruntime(str(static_lib), str(archive), dir_name) is True
assert not stale.exists(), "stale ORT version should be pruned"
- extracted = static_lib / native.ort_extracted_dir(version)
+ extracted = static_lib / native.ort_extracted_dir("1.29.0", native.ort_target("linux", "amd64"))
assert not extracted.exists(), "release zip top-level dir must be renamed away"
- version_dir = static_lib / native.ort_normalized_dir(version)
+ version_dir = static_lib / dir_name
assert version_dir.is_dir(), "bumped ORT version was silently not extracted"
assert native.has_static_archives(str(version_dir)), "bumped ORT version landed no .a"
def test_skips_when_archive_missing(tmp_path):
static_lib = tmp_path / "onnxruntime" / "static_lib"
- assert native.extract_onnxruntime(str(static_lib), str(tmp_path / "missing.zip"), "1.29.0") is False
+ _, dir_name = ort_archive(tmp_path)
+ assert native.extract_onnxruntime(str(static_lib), str(tmp_path / "missing.zip"), dir_name) is False
def test_idempotent_when_matching_version_already_present(tmp_path):
static_lib = tmp_path / "onnxruntime" / "static_lib"
- version = "1.29.0"
- archive = make_ort_zip(tmp_path / native.ort_asset_name(version), version)
+ archive, dir_name = ort_archive(tmp_path)
- assert native.extract_onnxruntime(str(static_lib), str(archive), version) is True
+ assert native.extract_onnxruntime(str(static_lib), str(archive), dir_name) is True
before = sorted(os.listdir(static_lib))
- assert native.extract_onnxruntime(str(static_lib), str(archive), version) is True
+ # Same dir already present: should short-circuit, not re-extract.
+ assert native.extract_onnxruntime(str(static_lib), str(archive), dir_name) is True
assert sorted(os.listdir(static_lib)) == before
+def test_prunes_foreign_platform_dir(tmp_path):
+ """A dir from a different platform/version must be pruned so build.sh's
+ `find ... -name '*.a'` does not link two ORT builds."""
+ static_lib = tmp_path / "onnxruntime" / "static_lib"
+ static_lib.mkdir(parents=True)
+ foreign = static_lib / native.ort_normalized_dir("1.29.0", "darwin", "arm64")
+ (foreign / "lib").mkdir(parents=True)
+ (foreign / "lib" / "libonnxruntime.a").write_bytes(b"mac-ort")
+
+ archive, dir_name = ort_archive(tmp_path)
+
+ assert native.extract_onnxruntime(str(static_lib), str(archive), dir_name) is True
+ assert not foreign.exists(), "foreign-platform ORT dir should be pruned"
+ assert (static_lib / dir_name).is_dir()
+
+
+def test_ort_asset_names_match_upstream_layout():
+ # Spot-check the platform-specific asset/dir names so the download script and
+ # build.sh's stale-version guard stay aligned with the upstream release.
+ assert native.ort_asset_name("1.29.0", "linux-x86_64") == "onnxruntime-v1.29.0-linux-x86_64.zip"
+ assert native.ort_asset_name("1.29.0", "linux-aarch64") == "onnxruntime-v1.29.0-linux-aarch64.zip"
+ assert native.ort_asset_name("1.29.0", "osx-arm64") == "onnxruntime-v1.29.0-osx-arm64.zip"
+ # No osx-x86_64 asset is published; Intel Macs use the universal archive.
+ assert native.ort_asset_name("1.29.0", "osx-universal") == "onnxruntime-v1.29.0-osx-universal.zip"
+ assert native.ort_normalized_dir("1.29.0", "linux", "amd64") == "onnxruntime-linux-x64-static_lib-1.29.0-glibc2_28"
+ assert native.ort_normalized_dir("1.29.0", "linux", "arm64") == "onnxruntime-linux-aarch64-static_lib-1.29.0-glibc2_28"
+ assert native.ort_normalized_dir("1.29.0", "darwin", "arm64") == "onnxruntime-osx-arm64-static_lib-1.29.0"
+ assert native.ort_normalized_dir("1.29.0", "darwin", "amd64") == "onnxruntime-osx-universal-static_lib-1.29.0"
+ assert native.ort_target("linux", "amd64") == "linux-x86_64"
+ assert native.ort_target("linux", "arm64") == "linux-aarch64"
+ assert native.ort_target("darwin", "arm64") == "osx-arm64"
+ assert native.ort_target("darwin", "amd64") == "osx-universal"
+
+
+def test_extracts_darwin_archive(tmp_path):
+ # The macOS zip carries no glibc suffix in its normalized dir name; the
+ # rename step must still land it where build.sh expects.
+ static_lib = tmp_path / "onnxruntime" / "static_lib"
+ archive, dir_name = ort_archive(tmp_path, goos="darwin", goarch="arm64")
+
+ assert native.extract_onnxruntime(str(static_lib), str(archive), dir_name) is True
+ assert (static_lib / dir_name / "lib" / "libonnxruntime.a").is_file()
+
+
+def test_prunes_foreign_platform_dir_on_short_circuit(tmp_path):
+ """When the expected ORT dir is already extracted, the short-circuit return
+ must still prune a co-resident foreign-platform dir (defense-in-depth;
+ build.sh's ort_dir_prefix guard also filters by platform at link time)."""
+ static_lib = tmp_path / "onnxruntime" / "static_lib"
+ dir_name = native.ort_normalized_dir("1.29.0", "linux", "amd64")
+ expected = static_lib / dir_name
+ (expected / "lib").mkdir(parents=True)
+ (expected / "lib" / "libonnxruntime.a").write_bytes(b"linux-ort")
+ foreign = static_lib / native.ort_normalized_dir("1.29.0", "darwin", "arm64")
+ (foreign / "lib").mkdir(parents=True)
+ (foreign / "lib" / "libonnxruntime.a").write_bytes(b"mac-ort")
+
+ archive, _ = ort_archive(tmp_path)
+ assert native.extract_onnxruntime(str(static_lib), str(archive), dir_name) is True
+ assert not foreign.exists(), "foreign dir must be pruned even on short-circuit"
+ assert expected.is_dir()
+
+
+def test_host_platform_normalizes_aliases(monkeypatch):
+ # build.sh's detect_target_platform accepts Linux/Darwin + x86_64/amd64
+ # aliases; host_platform must normalize the same way or it KeyErrors when
+ # indexing the per-platform asset maps.
+ monkeypatch.setenv("RAGFLOW_TARGET_OS", "Linux")
+ monkeypatch.setenv("RAGFLOW_TARGET_ARCH", "x86_64")
+ assert native.host_platform() == ("linux", "amd64")
+ monkeypatch.setenv("RAGFLOW_TARGET_OS", "Darwin")
+ monkeypatch.setenv("RAGFLOW_TARGET_ARCH", "aarch64")
+ assert native.host_platform() == ("darwin", "arm64")
+
+
+def test_host_platform_normalizes_explicit_arguments():
+ # The --target-os / --target-arch flags must go through the same
+ # normalization as the environment variables, or an alias (e.g.
+ # --target-os Linux) KeyErrors on the per-platform asset maps.
+ assert native.host_platform("Linux", "x86_64") == ("linux", "amd64")
+ assert native.host_platform("Darwin", "aarch64") == ("darwin", "arm64")
+
+
+def test_host_platform_rejects_unsupported(monkeypatch):
+ monkeypatch.setenv("RAGFLOW_TARGET_OS", "windows")
+ with pytest.raises(SystemExit):
+ native.host_platform()
+ monkeypatch.setenv("RAGFLOW_TARGET_OS", "linux")
+ monkeypatch.setenv("RAGFLOW_TARGET_ARCH", "riscv64")
+ with pytest.raises(SystemExit):
+ native.host_platform()
+
+
+def test_url_builders_select_platform_assets(monkeypatch):
+ monkeypatch.delenv("GH_PROXY", raising=False)
+ assert native.pdfium_url("linux", "amd64").endswith("/pdfium-linux-x64-static.tgz")
+ assert native.pdfium_url("linux", "arm64").endswith("/pdfium-linux-arm64-static.tgz")
+ assert native.pdfium_url("darwin", "arm64").endswith("/pdfium-mac-arm64-static.tgz")
+ assert native.pdf_oxide_url("linux", "amd64").endswith("/pdf_oxide-go-ffi-linux-amd64.tar.gz")
+ assert native.pdf_oxide_url("darwin", "amd64").endswith("/pdf_oxide-go-ffi-darwin-amd64.tar.gz")
+ assert native.ort_url("1.29.0", native.ort_target("darwin", "amd64")).endswith("/onnxruntime-v1.29.0-osx-universal.zip")
+
+
+def test_office_oxide_url_selects_platform_asset(tmp_path):
+ (tmp_path / "go.mod").write_text("module fixture\n\nrequire github.com/yfedoseev/office_oxide/go v0.1.12\n")
+ assert native.office_oxide_url(str(tmp_path), "linux", "amd64").endswith("/v0.1.12/native-linux-x86_64.tar.gz")
+ assert native.office_oxide_url(str(tmp_path), "darwin", "arm64").endswith("/v0.1.12/native-macos-aarch64.tar.gz")
+
+
+def test_url_builders_honor_gh_proxy(monkeypatch):
+ monkeypatch.setenv("GH_PROXY", "https://gh-proxy.com/")
+ assert native.pdfium_url("linux", "amd64").startswith("https://gh-proxy.com/https://github.com/")
+ assert native.pdf_oxide_url("linux", "arm64").startswith("https://gh-proxy.com/https://github.com/")
+
+
@pytest.fixture
def download_server():
class Handler(BaseHTTPRequestHandler):
@@ -367,3 +491,57 @@ def test_image_script_does_not_handle_native_archives():
assert not hasattr(img, "extract_onnxruntime")
assert not hasattr(img, "_extract_native_archive")
assert "onnxruntime" not in (img.__doc__ or "").lower()
+
+
+# ── Documentation contract: ARM64 build-host minimums ─────────────────────
+# The ARM64 host requirements are empirical findings from real hardware
+# (glibc 2.38 __isoc23_* symbols, GCC 13 libstdc++, SIMDe headers, cmake 4.x,
+# lld 20 — where lld-18 LINKS but hangs at startup). They cost half a day to
+# diagnose, so a doc refactor must not silently drop them: these tests pin the
+# section and its failure signatures.
+
+
+def _arm64_docs_section():
+ """Return the ARM64 host-requirements block of internal/development.md.
+
+ Scoped to the section (anchor → next "###" heading) so the assertions
+ below check the requirements block itself, not unrelated version numbers
+ elsewhere in an 800-line document.
+ """
+ doc = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "internal", "development.md")
+ assert os.path.isfile(doc), f"development.md not found at {doc}"
+ with open(doc, encoding="utf-8") as file:
+ text = file.read()
+ start = text.find("ARM64 (aarch64) build hosts")
+ assert start != -1, "development.md no longer has an ARM64 build-hosts section"
+ end = text.find("\n### ", start)
+ return text[start:] if end == -1 else text[start:end]
+
+
+def test_development_docs_document_arm64_host_requirements():
+ section = _arm64_docs_section()
+ # Each minimum, with its concrete failure signature, must stay documented.
+ for token in (
+ "glibc",
+ "2.38",
+ "__isoc23_strtoll",
+ "GCC",
+ "13",
+ "libsimde-dev",
+ "simde/x86/sse4.1.h",
+ "cmake",
+ "4.0",
+ "lld",
+ "20",
+ "inittrace",
+ ):
+ assert token in section, f"development.md ARM64 section lost requirement token {token!r}"
+
+
+def test_arm64_docs_section_warns_that_lld18_links_but_hangs():
+ # The subtle failure mode: lld-18 produces a binary that links fine and
+ # then spins at startup. Drop this warning and an ARM64 host silently
+ # keeping the distro-default lld hits an undebuggable hang.
+ section = _arm64_docs_section()
+ assert "lld-18" in section, "lld-18 is no longer called out as insufficient"
+ assert "hang" in section.lower() or "spin" in section.lower(), "lld-18 startup-hang failure mode missing"