RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
Build: add multi-platform native build support (linux/arm64, darwin) (#19247)
xugangqiangb44e852e6bf3
diff --git a/build.sh b/build.shindex 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_versionort_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; docase "$(basename "$f")" in*cuda*|*tensorrt*|*coreml*|*dml*|*migraphx*) continue ;;esaccase "$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" ]; thenlocal availavail="$(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}" >&2echo " available: ${avail:-<none>}" >&2echo " 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" ]; thenlocal actualactual="$(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 1fi@@ -375,12 +493,12 @@ check_office_oxide_deps() {local found_versionfound_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); thenecho -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 1fi@@ -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 ;;esaclocal 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" ]; thennm "$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}"fielse- 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}"fiecho -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++"+ fiecho " 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)" indiff --git a/internal/development.md b/internal/development.mdindex e1e1df36d5..f5a599cb4d 100644--- a/internal/development.md+++ b/internal/development.md@@ -25,6 +25,34 @@ sudo ln -s /usr/bin/clang-20 /usr/bin/clangsudo 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 + clInstall `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 seedsdiff --git a/tools/scripts/download_dev_deps.py b/tools/scripts/download_dev_deps.pyindex 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 argparseimport hashlibimport os+import platformimport reimport shutilimport 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:continuestale = 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 aversion 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 Trueos.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 thesame-named re-issued archive actually refreshes the .a files instead ofbeing 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.pyindex 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.utilimport io@@ -28,28 +33,32 @@ import pytestimport 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_nameassert 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 Trueassert 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_nameassert 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 Falsedef 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 Truebefore = 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 Trueassert 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.fixturedef 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"