OneXray build scripts

September 11, 2026 · View on GitHub

English · 简体中文 · Русский

Release provenance / 发布溯源

  • Build resolves LIBXRAY_REF and VCORE_REF once in the metadata job. Every platform checks out those same full commit SHAs; the requested refs are stored separately. A local libXray commit is not assumed to exist in XTLS/libXray: publish the required dependency changes to the configured repository before selecting them for CI. This change does not push dependencies or start CI.
  • Each successful build writes ../output/provenance-<target>-<architecture>.json: App/libXray/VCore commits, source and effective App versions, run identity, actual tool versions, dependency-lock hashes, copied native/GeoData hashes, and package SHA-256. Commands that cannot report a version are explicitly marked unavailable, not replaced with stable or another requested version. sourceDirty records each checkout's initial tracked/untracked changes (ignored files excluded), before script-controlled source changes. It contains only booleans and does not prevent local development builds with uncommitted work.
  • Windows receipts additionally include windowsMode and use provenance-windows-<architecture>-<mode>.json, keeping EXE and MSIX builds separate.
  • Windows additionally requires VCore integration revision 3, the existing identity, architecture, file set, and hashes.
  • publish.yml and publish-microsoft-store.yml require release metadata and per-platform receipts, a successful matching Build run, clean recorded source checkouts before the build, and matching package hashes. A release tag must resolve to the recorded App commit. Missing metadata is never a manual-build exemption. Microsoft Store bundling additionally requires both architectures. If a failed run is retried, rerun the metadata job together with the platform jobs; receipts from different run attempts are intentionally not mixed.
  • GitHub publishing follows the Build's recorded target.txt: a single-platform build publishes only that platform, while all requires every GitHub release target. The verifier requires the matching receipts and all expected packages before emitting the exact list used for both asset replacement and upload. Linux requires ZIP and DEB for x64 and arm64. MAS PKG and Play AAB are not GitHub assets. Windows requires EXE and ZIP for x64 and arm64 for GitHub; MSIX continues through the separate Microsoft Store workflow, which accepts only MSIX-mode receipts.
  • These are provenance checks, not platform release acceptance. Tool versions remain recorded rather than all pinned; store deployment still happens inside the existing Apple/Android Fastlane commands. Do not run them as local tests.
  • WinGet updates run separately after a stable GitHub Release, using the published EXE assets rather than Build artifacts. See Windows builds for triggers, prerequisites, and the manifest PR workflow.

中文要点：依赖 ref 仅解析一次，*-sha.txt 只写真实提交；每个平台单独记录实际工具链、 依赖锁、原生库、GeoData 与包摘要。不能把本地未发布的提交写成上游可用版本。 发布入口拒绝缺失元数据、构建前源树未提交、来源不一致和摘要不一致； 这些检查不替代各平台实机/渠道验收。保持使用干净构建目录，避免混入之前构建的产物。

允许单平台发布，范围由该次 Build 的 target.txt 决定；all 必须具备全部 GitHub 发布目标的凭证和安装包。Linux 的两种架构都需要 ZIP 与 DEB，macOS 只发布 SE ZIP， Android 只发布通用 APK；商店 PKG/AAB 不要求出现在 GitHub 产物目录。Windows 在 GitHub 发布两种架构的 EXE 与 ZIP，MSIX 保留独立的 Microsoft Store 流程。Windows 凭证及其文件名 包含运行模式，EXE 凭证不能替代 MSIX 凭证。校验成功后输出精确文件清单，删除和上传均只使用该清单， 单平台发布不删除其他平台已有资产。verify_release.py 的标准输出为这份清单，失败时不输出。

无需构建或安装依赖的脚本验证（Python 3.12+）：

cd build_scripts
python -m unittest discover -s tests -p 'test_*.py'

English

The scripts in this directory run the standard libXray build, generate the Flutter FFI bindings, build the OneXray app, and package the platform-specific outputs. libXray resolves Xray-core from its Go module dependencies.

Workspace layout

OneXray and libXray must be sibling directories. Windows builds also require a VCore checkout; set VCORE_DIR when it is not at workspace/VCore. Build artifacts are written to the sibling output directory.

workspace/
├── OneXray/
├── libXray/
├── VCore/         # Windows only
└── output/        # created automatically

The scripts use the currently checked-out libXray and VCore revisions. VCore artifacts are copied only after their integration revision, architecture, identity, file set, and SHA-256 manifest pass. The Xray-core version is pinned by libXray's Go module; a sibling Xray-core checkout is not used.

Prerequisites

  • Python 3.12 or newer and uv. The scripts use only the Python standard library.
  • Flutter, Dart, and Go available on PATH; Windows also requires Rust and MSVC. EXE / ZIP packaging needs Fastforge, plus Inno Setup for EXE (INNO_SETUP_PATH may specify its installation directory); MSIX needs the Windows SDK makeappx/signtool tools.
  • A toolchain for the target operating system. Apple targets require macOS, Xcode, CocoaPods, and Fastlane; Android requires a JDK, Android SDK/NDK, and Fastlane; Linux packaging requires Fastforge.
  • Signing credentials and platform configuration required by the selected Fastlane lane.
  • A positive integer in the BUILD_NUMBER environment variable. It is added to the configured build_number.base (currently 400).

Create the Python environment with uv. Fastforge is needed for Linux and Windows EXE / ZIP packaging:

uv sync --project build_scripts
dart pub global activate fastforge

setup_flutter.sh can install a fresh stable Flutter checkout for CI-like builds. It deletes and recreates ONEXRAY_FLUTTER_ROOT, or $HOME/flutter/stable when the variable is not set, so do not point it at a Flutter checkout that must be preserved.

Run a build

Run the entry point from the OneXray repository root:

export BUILD_NUMBER=1
uv run --project build_scripts python build_scripts/main.py OneXray <system>

Windows PowerShell:

$env:BUILD_NUMBER = "1"
uv run --project build_scripts python build_scripts/main.py OneXray <system>

Use uv run --project build_scripts python build_scripts/main.py --help to display the CLI syntax.

Supported systems

systemBuild hostBehavior
iosmacOSFastlane build and TestFlight upload.
macosmacOSMac App Store build and upload.
macos_semacOSSigned and notarized Developer ID universal ZIP.
androidAndroid toolchainPlay internal AAB upload and universal APK.
windowsWindows x64 or ARM64EXE + ZIP by default; --windows-mode msix builds Microsoft Store MSIX.
linuxLinux x64 or ARM64ZIP and DEB for the host architecture.

For Windows, the architecture is detected from the host. CI can set ONEXRAY_WINDOWS_ARCH to x64 or arm64 when the matching Flutter, Go, Rust, and MSVC toolchains are configured. See the Windows build documentation for the local signing requirements.

--windows-mode exe|msix selects both packaging and the Flutter --dart-define=ONEXRAY_WINDOWS_MODE value. One Fastforge invocation builds and packages EXE and ZIP from the same bundle; MSIX is compiled separately without Fastforge. CMake always bundles the target MSVC runtime, Wintun, and VCore in a flat layout; runtime DLLs must exist and match the target architecture before packages are collected. The verified official Wintun archive is cached under workspace references/windows-build/; only the architecture-matched DLL is copied. Sources and distribution notes are linked on the documentation site.

Important behavior

  • The Apple and Android commands are deployment commands. They can sign, notarize, or upload builds to external stores. Verify credentials, version, and target before running them.
  • Use a clean or disposable worktree. The build updates pubspec.yaml, copies generated core libraries and data into the app tree, and may update platform-specific files.
  • macos_se replaces the local macos/ directory with the macos_se/ configuration before building. Preserve any uncommitted macOS changes first.
  • Android replaces the ##version_code## placeholder in android/fastlane/Fastfile and does not restore it. Start each Android build from a clean copy so a repeated build cannot reuse an old version code.
  • Outputs are collected in ../output relative to the OneXray repository.

简体中文

本目录中的脚本会执行 libXray 标准构建、生成 Flutter FFI 绑定、构建 OneXray App，并生成各平台对应的安装包。Xray-core 由 libXray 的 Go module 依赖解析。

工作区结构

OneXray 和 libXray 必须位于同一级目录。Windows 构建还需要 VCore；不在 workspace/VCore 时通过 VCORE_DIR 指定。构建产物写入同级 output 目录。

workspace/
├── OneXray/
├── libXray/
├── VCore/         # 仅 Windows
└── output/        # 自动创建

构建使用 libXray 和 VCore 当前检出的版本。VCore 产物只有在 integration revision、 架构、identity、文件集合和 SHA-256 manifest 全部通过后才复制。Xray-core 版本由 libXray 的 Go module 锁定，不使用同级目录下的 Xray-core checkout。

前置条件

  • Python 3.12 或更高版本，并安装 uv。脚本仅使用 Python 标准库。
  • PATH 中可以找到 Flutter、Dart 和 Go；Windows 还需要 Rust 与 MSVC。 EXE / ZIP 打包需要 Fastforge，EXE 还需要 Inno Setup（可用 INNO_SETUP_PATH 指定安装目录）；MSIX 需要 Windows SDK 的 makeappx、signtool。
  • 安装目标系统所需的工具链。Apple 平台需要 macOS、Xcode、CocoaPods 和 Fastlane；Android 需要 JDK、Android SDK/NDK 和 Fastlane；Linux 打包需要 Fastforge。
  • 准备所选 Fastlane lane 需要的签名证书、凭据和平台配置。
  • 设置正整数环境变量 BUILD_NUMBER。脚本会将它加到配置中的 build_number.base（当前为 400）上。

使用 uv 创建 Python 环境。Linux 和 Windows EXE / ZIP 打包需要 Fastforge：

uv sync --project build_scripts
dart pub global activate fastforge

setup_flutter.sh 可以安装一份全新的 Flutter stable，用于模拟 CI 环境。该脚本会删除并重新创建 ONEXRAY_FLUTTER_ROOT 指向的目录；未设置时 使用 $HOME/flutter/stable。不要将它指向需要保留的 Flutter 工作目录。

执行构建

在 OneXray 仓库根目录运行入口脚本：

export BUILD_NUMBER=1
uv run --project build_scripts python build_scripts/main.py OneXray <system>

Windows PowerShell：

$env:BUILD_NUMBER = "1"
uv run --project build_scripts python build_scripts/main.py OneXray <system>

可以运行 uv run --project build_scripts python build_scripts/main.py --help 查看命令格式。

支持的系统

system构建主机行为
iosmacOSFastlane 构建并上传到 TestFlight。
macosmacOS构建并上传 Mac App Store 版本。
macos_semacOS签名、公证并生成 Developer ID 通用 ZIP。
androidAndroid 工具链上传 Play internal AAB 并获取 universal APK。
windowsWindows x64 或 ARM64默认生成 EXE + ZIP；--windows-mode msix 生成 Microsoft Store MSIX。
linuxLinux x64 或 ARM64为主机架构生成 ZIP 和 DEB。

Windows 默认根据主机识别架构。CI 可以在对应 Flutter、Go、Rust 和 MSVC 工具链就绪时设置 ONEXRAY_WINDOWS_ARCH。本地签名要求以 Windows 构建文档 为准。

--windows-mode exe|msix 同时控制打包格式和 Flutter 的 --dart-define=ONEXRAY_WINDOWS_MODE。一次 Fastforge 调用完成 EXE / ZIP 的共同编译与打包， MSIX 单独编译，不使用 Fastforge； CMake 在两种模式下都平铺安装目标 MSVC runtime、Wintun 与 VCore；运行库 DLL 必须存在且架构匹配，才归集产物。官方 Wintun 压缩包校验摘要后缓存在 工作区 references/windows-build/，仅复制匹配架构的 DLL。来源与分发说明放在 文档站。

重要行为

  • Apple 和 Android 命令属于部署命令。 它们可能执行签名、公证或上传到 外部商店。运行前请确认凭据、版本和目标环境。
  • 建议使用干净或可丢弃的 worktree。构建会更新 pubspec.yaml，将生成的 Core 库和数据复制到 App 目录，并可能修改平台文件。
  • macos_se 会在构建前用 macos_se/ 配置替换本地 macos/ 目录。请先 保存所有尚未提交的 macOS 改动。
  • Android 构建会替换 android/fastlane/Fastfile 中的 ##version_code## 占位符，并且不会自动恢复。每次 Android 构建都应从 干净副本开始，避免重复构建沿用旧的 version code。
  • 所有产物集中在 OneXray 仓库同级的 ../output 目录。

Русский

Скрипты из этого каталога запускают стандартную сборку libXray, генерируют FFI-привязки Flutter, собирают приложение OneXray и создают пакеты для выбранной платформы. Версия Xray-core определяется зависимостями Go-модуля libXray.

Структура рабочего каталога

OneXray и libXray должны находиться в соседних каталогах. Для Windows также нужен VCore; если он находится не в workspace/VCore, задайте VCORE_DIR. Результаты записываются в соседний каталог output.

workspace/
├── OneXray/
├── libXray/
├── VCore/         # только Windows
└── output/        # создаётся автоматически

Сборка использует текущие версии libXray и VCore. Артефакты VCore копируются только после проверки integration revision, архитектуры, identity, набора файлов и SHA-256 manifest. Версия Xray-core закреплена Go-модулем libXray; соседний checkout Xray-core не используется.

Требования

  • Python 3.12 или новее и uv. Скрипты используют только стандартную библиотеку Python.
  • Flutter, Dart и Go через PATH; для Windows также нужны Rust и MSVC. Для EXE / ZIP нужен Fastforge, а для EXE дополнительно Inno Setup (каталог установки можно задать через INNO_SETUP_PATH); для MSIX — инструменты Windows SDK makeappx/signtool.
  • Инструменты для целевой системы. Для Apple требуются macOS, Xcode, CocoaPods и Fastlane; для Android — JDK, Android SDK/NDK и Fastlane; для упаковки под Linux требуется Fastforge.
  • Сертификаты, учётные данные и настройки платформы, необходимые выбранному lane Fastlane.
  • Положительное целое число в переменной окружения BUILD_NUMBER. Оно прибавляется к параметру build_number.base (сейчас 400).

Создайте среду Python с помощью uv. Fastforge требуется для упаковки Linux и Windows EXE / ZIP:

uv sync --project build_scripts
dart pub global activate fastforge

Скрипт setup_flutter.sh устанавливает свежую стабильную версию Flutter для сборки в окружении, похожем на CI. Он удаляет и заново создаёт каталог, указанный в ONEXRAY_FLUTTER_ROOT, либо $HOME/flutter/stable, если переменная не задана. Не указывайте каталог Flutter, который необходимо сохранить.

Запуск сборки

Запускайте основной скрипт из корня репозитория OneXray:

export BUILD_NUMBER=1
uv run --project build_scripts python build_scripts/main.py OneXray <system>

Windows PowerShell:

$env:BUILD_NUMBER = "1"
uv run --project build_scripts python build_scripts/main.py OneXray <system>

Команда uv run --project build_scripts python build_scripts/main.py --help выводит синтаксис CLI.

Поддерживаемые системы

systemСреда сборкиДействие
iosmacOSСборка Fastlane и загрузка в TestFlight.
macosmacOSСборка и загрузка версии Mac App Store.
macos_semacOSПодписанный и нотариализированный универсальный ZIP.
androidAndroid toolchainЗагрузка AAB в Play internal; universal APK.
windowsWindows x64 или ARM64По умолчанию EXE + ZIP; --windows-mode msix создаёт MSIX для Microsoft Store.
linuxLinux x64 или ARM64ZIP и DEB для архитектуры хоста.

В Windows архитектура определяется по системе. CI может задать ONEXRAY_WINDOWS_ARCH, когда настроены Flutter, Go, Rust и MSVC. Требования к локальной подписи см. в документации по сборке Windows.

--windows-mode exe|msix задаёт формат пакета и значение Flutter --dart-define=ONEXRAY_WINDOWS_MODE. Один вызов Fastforge собирает приложение и упаковывает EXE и ZIP; MSIX компилируется отдельно без Fastforge. CMake включает целевую среду выполнения MSVC, Wintun и VCore в обеих конфигурациях; перед сбором пакетов проверяются наличие и архитектура DLL. Проверенный официальный архив Wintun сохраняется в references/windows-build/ рабочего каталога; копируется только DLL нужной архитектуры. Сведения об источнике и распространении размещены на сайте документации.

Важные особенности

  • Команды Apple и Android выполняют развёртывание. Они могут подписывать, нотариализировать или загружать сборки во внешние магазины. Перед запуском проверьте учётные данные, версию и целевое окружение.
  • Используйте чистый или одноразовый worktree. Сборка изменяет pubspec.yaml, копирует сгенерированные библиотеки Core и данные в дерево приложения, а также может изменять платформенные файлы.
  • Перед сборкой macos_se локальный каталог macos/ заменяется конфигурацией из macos_se/. Сначала сохраните все незакоммиченные изменения macOS.
  • При сборке Android заменяется маркер ##version_code## в файле android/fastlane/Fastfile, и исходное значение не восстанавливается. Каждую сборку Android запускайте из чистой копии, чтобы повторный запуск не использовал старый version code.
  • Все результаты помещаются в соседний с репозиторием OneXray каталог ../output.