From 4c156ae4ff81d201b0ab5ec7c644cb8bd461032a Mon Sep 17 00:00:00 2001 From: yiguo Date: Fri, 14 Aug 2026 20:48:47 +0800 Subject: [PATCH 1/2] Document single Go runtime limitation --- README.md | 20 +++++++++++++++++++- readme/README.zh_CN.md | 17 ++++++++++++++++- 2 files changed, 35 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 29b38fb1..71f7d785 100644 --- a/README.md +++ b/README.md @@ -72,11 +72,29 @@ use [gomobile](https://github.com/golang/mobile) . ### iOS && macOS +> [!WARNING] +> **Use only one Go runtime per process.** Go does not support loading multiple +> independently built Go runtimes into one process. Both the cgo and gomobile +> Apple artifacts embed a Go runtime. Do not link `LibXray.xcframework` +> together with another independently built Go or gomobile framework into the +> same app or extension executable. Doing so can fail at link time or crash +> during runtime initialization, before application code or +> `NEPacketTunnelProvider` runs. +> If one process needs Go packages from several frameworks, include those +> packages in the same Go build or `gomobile bind` invocation and produce one +> framework so they share a runtime. Merely repackaging or merging independently +> built frameworks is not sufficient. The containing app and a Network +> Extension are separate processes, so apply this rule independently to each +> target. See [Go #18976](https://github.com/golang/go/issues/18976#issuecomment-308505600), +> [x/mobile #15956](https://github.com/golang/go/issues/15956#issuecomment-373709423), +> and [libXray #116](https://github.com/XTLS/libXray/issues/116). + #### 1. use gomobile Need "iOS Simulator Runtime". -This is the best choice for general scenarios and will not conflict with other frameworks. +This is the best choice for general scenarios. The single-runtime restriction +above still applies when linking other Go-based frameworks. Supports iOS, iOSSimulator, macOS, macCatalyst. diff --git a/readme/README.zh_CN.md b/readme/README.zh_CN.md index a859496e..23fb9545 100644 --- a/readme/README.zh_CN.md +++ b/readme/README.zh_CN.md @@ -40,11 +40,26 @@ python3 build/main.py windows local ### iOS && macOS +> [!WARNING] +> **每个进程只能使用一个 Go runtime。** Go 不支持在同一进程中加载多个独立构建的 +> Go runtime。cgo 和 gomobile 生成的 Apple 产物都会嵌入 Go runtime。不要在同一个 +> App 或 Extension 可执行文件中同时链接 `LibXray.xcframework` 与另一个独立构建的 +> Go 或 gomobile framework，否则可能在链接阶段失败，或在 runtime 初始化阶段崩溃， +> 甚至早于应用代码或 `NEPacketTunnelProvider` 执行。如果同一进程需要多个 +> framework 中的 Go package，应将这些 package 放入同一次 Go build 或 +> `gomobile bind` 并生成一个 framework， +> 使其共享一个 runtime。仅重新打包或合并已经独立构建的 frameworks 并不能解决问题。 +> 宿主 App 与 Network Extension 是不同进程，因此需要分别对每个 target 遵守这一限制。 +> 参见 [Go #18976](https://github.com/golang/go/issues/18976#issuecomment-308505600)、 +> [x/mobile #15956](https://github.com/golang/go/issues/15956#issuecomment-373709423) +> 和 [libXray #116](https://github.com/XTLS/libXray/issues/116)。 + #### 1. 使用 gomobile 需要 “iOS Simulator Runtime”。 -这是常规场景下的最佳选择，不会与其他 frameworks 冲突。 +这是常规场景下的最佳选择；与其他基于 Go 的 framework 同时集成时，仍须遵守上方的 +单 runtime 限制。 支持 iOS，iOSSimulator，macOS，macCatalyst。 From 833eb9da0160f000a25ca5672796cd97bb0eef9f Mon Sep 17 00:00:00 2001 From: yiguo Date: Fri, 14 Aug 2026 20:55:24 +0800 Subject: [PATCH 2/2] Generalize Go runtime warning across platforms --- README.md | 39 ++++++++++++++++++++------------------- readme/README.zh_CN.md | 30 +++++++++++++++--------------- 2 files changed, 35 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 71f7d785..e5fa0026 100644 --- a/README.md +++ b/README.md @@ -66,35 +66,36 @@ python3 build/main.py windows local ``` +> [!WARNING] +> **Use only one Go runtime per process.** Go does not support loading multiple +> independently built Go runtimes into one process. Every native libXray +> artifact embeds a Go runtime, whether it is produced through cgo or gomobile. +> Do not load libXray together with another independently built Go, cgo, or +> gomobile library in the same executable or process. Doing so can fail during +> build, link, or load, or crash during runtime initialization before +> application code runs. +> If one process needs Go packages from several libraries, include those +> packages in the same Go build or `gomobile bind` invocation and produce one +> native artifact so they share a runtime. Merely repackaging or merging +> independently built frameworks, archives, AARs, shared libraries, or DLLs is +> not sufficient. Separate OS processes may each load one Go runtime, so apply +> this rule independently to each process. See +> [Go #18976](https://github.com/golang/go/issues/18976#issuecomment-308505600), +> [golang/go#15956](https://github.com/golang/go/issues/15956#issuecomment-373709423), +> and [libXray #116](https://github.com/XTLS/libXray/issues/116). + ### Android use [gomobile](https://github.com/golang/mobile) . ### iOS && macOS -> [!WARNING] -> **Use only one Go runtime per process.** Go does not support loading multiple -> independently built Go runtimes into one process. Both the cgo and gomobile -> Apple artifacts embed a Go runtime. Do not link `LibXray.xcframework` -> together with another independently built Go or gomobile framework into the -> same app or extension executable. Doing so can fail at link time or crash -> during runtime initialization, before application code or -> `NEPacketTunnelProvider` runs. -> If one process needs Go packages from several frameworks, include those -> packages in the same Go build or `gomobile bind` invocation and produce one -> framework so they share a runtime. Merely repackaging or merging independently -> built frameworks is not sufficient. The containing app and a Network -> Extension are separate processes, so apply this rule independently to each -> target. See [Go #18976](https://github.com/golang/go/issues/18976#issuecomment-308505600), -> [x/mobile #15956](https://github.com/golang/go/issues/15956#issuecomment-373709423), -> and [libXray #116](https://github.com/XTLS/libXray/issues/116). - #### 1. use gomobile Need "iOS Simulator Runtime". -This is the best choice for general scenarios. The single-runtime restriction -above still applies when linking other Go-based frameworks. +This is the best choice for general scenarios. The cross-platform single-runtime +restriction above still applies when linking other Go-based libraries. Supports iOS, iOSSimulator, macOS, macCatalyst. diff --git a/readme/README.zh_CN.md b/readme/README.zh_CN.md index 23fb9545..87ca9e54 100644 --- a/readme/README.zh_CN.md +++ b/readme/README.zh_CN.md @@ -34,31 +34,31 @@ python3 build/main.py windows python3 build/main.py windows local ``` +> [!WARNING] +> **每个进程只能使用一个 Go runtime。** Go 不支持在同一进程中加载多个独立构建的 +> Go runtime。libXray 的所有原生产物都会嵌入 Go runtime，无论它们通过 cgo 还是 +> gomobile 生成。不要在同一个可执行文件或进程中同时加载 libXray 与另一个独立构建的 +> Go、cgo 或 gomobile 库，否则可能在构建、链接或加载阶段失败，也可能在应用代码执行前 +> 的 runtime 初始化阶段崩溃。 +> 如果同一进程需要多个库中的 Go package，应将这些 package 放入同一次 Go build 或 +> `gomobile bind` 并生成一个原生产物，使其共享一个 runtime。仅重新打包或合并已经独立 +> 构建的 framework、archive、AAR、shared library 或 DLL 并不能解决问题。不同的操作系统 +> 进程可以各自加载一个 Go runtime，因此需要分别对每个进程遵守这一限制。参见 +> [Go #18976](https://github.com/golang/go/issues/18976#issuecomment-308505600)、 +> [golang/go#15956](https://github.com/golang/go/issues/15956#issuecomment-373709423) +> 和 [libXray #116](https://github.com/XTLS/libXray/issues/116)。 + ### Android 使用 [gomobile](https://github.com/golang/mobile) 。 ### iOS && macOS -> [!WARNING] -> **每个进程只能使用一个 Go runtime。** Go 不支持在同一进程中加载多个独立构建的 -> Go runtime。cgo 和 gomobile 生成的 Apple 产物都会嵌入 Go runtime。不要在同一个 -> App 或 Extension 可执行文件中同时链接 `LibXray.xcframework` 与另一个独立构建的 -> Go 或 gomobile framework，否则可能在链接阶段失败，或在 runtime 初始化阶段崩溃， -> 甚至早于应用代码或 `NEPacketTunnelProvider` 执行。如果同一进程需要多个 -> framework 中的 Go package，应将这些 package 放入同一次 Go build 或 -> `gomobile bind` 并生成一个 framework， -> 使其共享一个 runtime。仅重新打包或合并已经独立构建的 frameworks 并不能解决问题。 -> 宿主 App 与 Network Extension 是不同进程，因此需要分别对每个 target 遵守这一限制。 -> 参见 [Go #18976](https://github.com/golang/go/issues/18976#issuecomment-308505600)、 -> [x/mobile #15956](https://github.com/golang/go/issues/15956#issuecomment-373709423) -> 和 [libXray #116](https://github.com/XTLS/libXray/issues/116)。 - #### 1. 使用 gomobile 需要 “iOS Simulator Runtime”。 -这是常规场景下的最佳选择；与其他基于 Go 的 framework 同时集成时，仍须遵守上方的 +这是常规场景下的最佳选择；与其他基于 Go 的库同时集成时，仍须遵守上方跨平台的 单 runtime 限制。 支持 iOS，iOSSimulator，macOS，macCatalyst。