Skip to content

Document single Go runtime limitation #144

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yiguodev merged 2 commits into from
Aug 14, 2026
Merged

Document single Go runtime limitation #144

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4c156ae
Document single Go runtime limitation
Aug 14, 2026
833eb9d
Generalize Go runtime warning across platforms
Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Comment thread
yiguodev marked this conversation as resolved.
Resolved
> 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.

Expand Down
17 changes: 16 additions & 1 deletion readme/README.zh_CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Comment thread
yiguodev marked this conversation as resolved.
Resolved
> 和 [libXray #116](https://github.com/XTLS/libXray/issues/116)。

#### 1. 使用 gomobile

需要 “iOS Simulator Runtime”。

这是常规场景下的最佳选择，不会与其他 frameworks 冲突。
这是常规场景下的最佳选择；与其他基于 Go 的 framework 同时集成时，仍须遵守上方的
单 runtime 限制。

支持 iOS，iOSSimulator，macOS，macCatalyst。

Expand Down