Skip to content

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

fix(build): adjust onnxruntime static link flags on Darwin arm64 (#21162)

Sanderhoff-alt819751a91527
diff --git a/build.sh b/build.sh
index f0b54f7df1..e924517ce0 100755
--- a/build.sh
+++ b/build.sh
@@ -925,11 +925,10 @@ setup_cgo_env() {
# 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 验证)
+ # macOS (ld64): ld64 uses -u _OrtGetApiBase to pull the OrtGetApiBase
+ # symbol from the static archive without -force_load (which would pull
+ # all unused objects and missing transitive dependencies), and exports
+ # it via -export_dynamic so runtime dlopen(NULL) resolves it.
#
# 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
@@ -958,20 +957,11 @@ setup_cgo_env() {
done
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++"
+ # ld64 uses -u _OrtGetApiBase (with leading underscore) to force-pull
+ # OrtGetApiBase without -force_load, avoiding dragging in unneeded
+ # objects from libonnxruntime.a. Export dynamic symbols so the runtime
+ # dlopen(NULL) resolves OrtGetApiBase.
+ export CGO_LDFLAGS="$CGO_LDFLAGS -Wl,-export_dynamic -Wl,-u,_OrtGetApiBase $ort_a_versioned -lc++"
else
# Export exactly one symbol (OrtGetApiBase) for the binding's
# dlopen(NULL)+dlsym lookup via --dynamic-list (NOT --version-script
@@ -1015,6 +1005,7 @@ setup_cgo_env() {
export CGO_LDFLAGS="$CGO_LDFLAGS \
-framework CoreGraphics -framework CoreFoundation \
-framework Security -framework SystemConfiguration \
+ -framework Foundation \
-liconv -lresolv -lc++"
;;
esac
diff --git a/internal/development.md b/internal/development.md
index 3174f120ff..36274c4df0 100644
--- a/internal/development.md
+++ b/internal/development.md
@@ -87,7 +87,6 @@ The image contains Go DeepDoc weights, tokenizer assets, and the BPE table. Deep
>
> ```bash
> RAGFLOW_DEPS="${HOME}/ragflow-native-libs" # created by download_dev_deps.py
-> 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
@@ -95,36 +94,44 @@ The image contains Go DeepDoc weights, tokenizer assets, and the BPE table. Deep
> # 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 验证)
+> # -u _OrtGetApiBase + -export_dynamic + -lc++ instead (using ld64's -u rather
+> # than -force_load to avoid pulling in unused objects from the static archive).
>
> # 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.
-> # 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)"
+> # Derive target platform and ORT prefix matching build.sh:
+> TARGET_OS="${RAGFLOW_TARGET_OS:-$(uname -s)}"
+> TARGET_ARCH="${RAGFLOW_TARGET_ARCH:-$(uname -m)}"
+> case "$TARGET_OS" in
+> Linux|linux) TARGET_OS="linux" ;;
+> Darwin|darwin) TARGET_OS="darwin" ;;
+> esac
+> case "$TARGET_ARCH" in
+> x86_64|amd64) TARGET_ARCH="amd64" ;;
+> arm64|aarch64) TARGET_ARCH="arm64" ;;
+> esac
+> PLATFORM="${TARGET_OS}_${TARGET_ARCH}"
+> case "$TARGET_OS-$TARGET_ARCH" in
+> linux-amd64) ORT_PREFIX="onnxruntime-linux-x64-static_lib-" ;;
+> linux-arm64) ORT_PREFIX="onnxruntime-linux-aarch64-static_lib-" ;;
+> darwin-arm64) ORT_PREFIX="onnxruntime-osx-arm64-static_lib-" ;;
+> darwin-amd64) ORT_PREFIX="onnxruntime-osx-universal-static_lib-" ;;
+> *) ORT_PREFIX="onnxruntime-*-static_lib-" ;;
+> esac
+> ORT_A="$(ls ${RAGFLOW_DEPS}/onnxruntime/static_lib/${ORT_PREFIX}*/lib/libonnxruntime.a)"
>
-> # 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++"
+> # Link flags differ between Linux (GNU ld) and macOS (ld64).
+> # Prefer `build.sh` which derives the same flags automatically.
+> if [ "$TARGET_OS" = "darwin" ]; then
+> ORT_LINK="-Wl,-export_dynamic -Wl,-u,_OrtGetApiBase ${ORT_A} -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 \
+> -framework Foundation \
> -liconv -lresolv -lm -lpthread -ldl -lutil -lc -lc++"
> else
> # The binding reaches ORT with dlopen(NULL)+dlsym("OrtGetApiBase"), so
@@ -157,9 +164,8 @@ The image contains Go DeepDoc weights, tokenizer assets, and the BPE table. Deep
> 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
+> On macOS (ld64) `OrtGetApiBase` is force-pulled with `-Wl,-u,_OrtGetApiBase`
+> and exported with `-export_dynamic`. 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