mirror of
https://github.com/YuanDevTeam/Vole.git
synced 2026-11-07 00:05:27 +00:00
yiguodev
f870ffe454
Add provider generations, automatic proxy groups, richer routing rules and live Controller configuration. Extend encrypted DNS, persistent fake-IP mappings and GeoData support. Add HTTP CONNECT, WireGuard, TrustTunnel, Mieru and MASQUE outbounds; expand TLS/ECH and transport compatibility. Add separately configured H1/H2 MITM and URL, header and body rewriting. Improve UDP association reuse, TCP delivery and H2/H3 scheduling while keeping memory bounded. Add Linux TUN route and system DNS management, MPTCP and TCP Brutal. Replace vendored dependencies with upstream libraries, update and pin Boring 5.4.0, and fix cross-platform builds and CI feature checks.
107 lines
6.7 KiB
Markdown
107 lines
6.7 KiB
Markdown
# 编译与发布
|
||
|
||
在 Vole 根目录执行。需要 Rust、uv、Git、C/C++、CMake、Perl 和 libclang，以及对应平台工具链。
|
||
Linux 自动准备原生依赖还需要 curl、zip、unzip 和 tar。
|
||
|
||
```sh
|
||
uv run --project scripts --locked vole-scripts build cli
|
||
uv run --project scripts --locked vole-scripts build cli --profile debug
|
||
uv run --project scripts --locked vole-scripts build cli --target aarch64-apple-darwin
|
||
uv run --project scripts --locked vole-scripts build apple
|
||
uv run --project scripts --locked vole-scripts build android
|
||
uv run --project scripts --locked vole-scripts build linux
|
||
uv run --project scripts --locked vole-scripts build windows --backend wintun
|
||
uv run --project scripts --locked vole-scripts build windows --backend uwp
|
||
```
|
||
|
||
CLI 默认构建当前宿主的 Release，Windows 固定 Wintun；Windows FFI 默认 UWP。
|
||
脚本输出产物路径，编译失败直接返回失败。
|
||
Windows 的构建和验证只允许宿主原生架构：x64 使用 x64 Python、MSVC 与产物，
|
||
ARM64 使用 ARM64 Python、MSVC 与产物，不跨架构编译或通过模拟运行验证。
|
||
Windows 需先安装本架构的 Python 并加入 `PATH`；为上述 `uv run` 增加 `--python python`
|
||
可明确使用该解释器。脚本拒绝非原生 Python 和不同架构的 Windows 目标。
|
||
|
||
| 目标 | 工具链与输出 |
|
||
| --- | --- |
|
||
| CLI | Linux/macOS/Windows amd64、arm64；`target/<triple>/<profile>/vole[.exe]` |
|
||
| Apple FFI | macOS/Xcode；`dist/apple/LibVole.xcframework`，iOS/tvOS ARM64 真机及模拟器、macOS universal 共五切片 |
|
||
| Android FFI | macOS/Linux + NDK 30；`dist/android/<abi>`，ARM64、x86_64 的 `libvole.so` 与匹配的 `libc++_shared.so` |
|
||
| Linux FFI | 原生 GNU 工具链；`dist/linux/<architecture>` 的静态库、动态库和头文件 |
|
||
| Windows FFI | 原生 Visual Studio C++；`dist/windows/<architecture>/<backend>` 的 DLL/import library 和头文件；UWP 另含两个 host 程序 |
|
||
|
||
Apple 最低版本为 iOS 13、macOS 10.15、tvOS 17；ARM64 iOS 模拟器/macOS 分别至少
|
||
14/11。原生消费者需链接 libc++，module map 已声明。Windows ARM64 还需要 LLVM 与 Ninja。
|
||
Android 优先使用 `ANDROID_NDK_HOME`，否则在 `ANDROID_HOME/ndk` 中选择 NDK 30 的最新已安装正式版。
|
||
`VOLE_ANDROID_NDK_VERSION` 可指定版本，`VOLE_ANDROID_API` 默认 24。
|
||
`CARGO_TARGET_DIR` 按 Cargo 约定覆盖中间产物目录；其余本地覆盖见 `builds.py`。
|
||
|
||
所有编译入口自动准备官方 BLAKE3 1.8.7 C 静态库。依赖通过
|
||
`native/blake3/vcpkg.json` 锁定正式 vcpkg registry/port，正常 bootstrap 和 install
|
||
使用宿主网络及用户缓存；首次构建需要联网。默认缓存位于 macOS 的
|
||
`~/Library/Caches/vole/native`、Linux 的 `$XDG_CACHE_HOME/vole/native`
|
||
（未设置时为 `~/.cache/vole/native`）、Windows 的 `%LOCALAPPDATA%/vole/native`，
|
||
可用 `VOLE_NATIVE_CACHE_DIR` 覆盖。第三方源、工具、头文件和静态库留在依赖缓存，
|
||
不加入仓库或发布归档。自有 triplet 为 C 符号设置 `vole_c_` 编译宏；官方 port 和源码不改。
|
||
Apple 使用对应 SDK 和上述最低版本，Android 使用同一 NDK/API，Windows 区分
|
||
Windows/WindowsStore；Wintun 使用静态 CRT，UWP 的 Rust、BoringSSL 和 BLAKE3
|
||
统一使用动态 CRT，BLAKE3 本身仍为静态库。UWP 宿主安装包负责声明并部署对应架构的
|
||
Visual C++ Runtime 依赖；各目标安装目录独立。
|
||
|
||
直接执行 Cargo 时可先准备宿主依赖：
|
||
|
||
```sh
|
||
uv run --project scripts --locked vole-scripts deps
|
||
```
|
||
|
||
该命令打印两个目标后缀环境变量；在当前 shell 中设置后执行 Cargo。
|
||
Windows UWP 使用 `deps --backend uwp`，还需设置输出的 `CARGO_ENCODED_RUSTFLAGS`，
|
||
使 Rust 和原生依赖使用相同的动态 CRT。
|
||
CI 使用 `deps --github-env "$GITHUB_ENV"` 自动传给后续步骤。
|
||
显式提供 `VOLE_BLAKE3_INCLUDE_DIR_<TARGET>` 与 `VOLE_BLAKE3_LIB_DIR_<TARGET>`
|
||
可复用已准备的同目标 namespaced 静态包；`<TARGET>` 为大写 Rust target，连字符改成下划线。
|
||
无后缀的两变量仅在宿主原生构建有效。缺少一项或路径无效直接失败，不回退到其他架构。
|
||
平台构建命令本身不需要手工设置这些变量。
|
||
|
||
## 发布
|
||
|
||
[Release workflow](../.github/workflows/release.yml) 在 `vX.Y.Z` tag push 时构建并发布，
|
||
tag 必须匹配 Cargo 版本。PR 使用同一构建矩阵，全部构建成功后汇总十四个归档。
|
||
CI 中的 Python 均由 `actions/setup-python` 安装，选择最新稳定 Python 3；uv 仅使用系统解释器，
|
||
禁止自动下载 Python，不使用脚本安装或特定解释器发行版请求。
|
||
CLI 构建后执行 `-h/-v/-t` 检查。Windows CLI、Wintun FFI、UWP FFI 分别使用独立的
|
||
x64/ARM64 job，每个 job 的 runner、Python、工具链和验证产物必须同架构；
|
||
UWP 的 COM 回归只加载当前 job 构建的 DLL。ARM64 MSVC 使用原生 `vcvarsall arm64`，
|
||
不使用 `amd64_arm64` 交叉工具链。
|
||
Apple FFI 的六个 Rust 目标分别在独立 job 并行编译并缓存；`FFI Apple` 等待全部目标
|
||
成功后合并 macOS 双架构、生成五切片 XCFramework 并打包。
|
||
CI 的依赖来源检查见 [TLS 依赖](../docs/tls-dependencies.md)。
|
||
|
||
| 归档 | 内容 |
|
||
| --- | --- |
|
||
| `vole-{linux,darwin}-{amd64,arm64}.gz` | 单个 CLI 可执行文件 |
|
||
| `vole-windows-{amd64,arm64}.zip` | `vole.exe`，Wintun 后端 |
|
||
| `vole-ffi-apple.tar.gz` | XCFramework，含 headers/module maps |
|
||
| `vole-ffi-android.tar.gz` | 两种 ABI 的核心库、C++ runtime 和 C 头文件 |
|
||
| `vole-ffi-linux-{amd64,arm64}.tar.gz` | `libvole.so`、`libvole.a` 和 C 头文件 |
|
||
| `vole-ffi-windows-{wintun,uwp}-{amd64,arm64}.zip` | `vole.dll`、`vole.dll.lib` 和 C 头文件；UWP 另含 Provider Host、Session Host |
|
||
|
||
公共 C 接口由 `vole.h` 提供；UWP 另附 `vole_windows_uwp.h`，声明 Windows 安装包桥接接口。
|
||
文件名不带版本号，不附带 checksums 或 `wintun.dll`。
|
||
发布脚本不收集许可证；CLI、FFI、XCFramework 与归档不额外内嵌或打包许可证内容。
|
||
|
||
Linux/macOS 的 CLI 使用 gzip 单文件归档，解压后需设置执行权限。下载匹配系统与架构的
|
||
归档后执行（以 Linux amd64 为例）：
|
||
|
||
```sh
|
||
gzip -dc vole-linux-amd64.gz > vole
|
||
chmod +x vole
|
||
./vole -v
|
||
```
|
||
|
||
发布入口为 `python -m vole_scripts.release`，参数见 `--help`；
|
||
`build-apple-target` 构建单个 Apple 静态库，`assemble-apple --inputs <目录> --output <目录>`
|
||
从 `<inputs>/<Rust target>/libvole.a` 汇总六个目标并打包，不重复编译。
|
||
省略 `--tag` 可在本地验证打包。`builds.py` 负责平台编译，`release.py` 负责打包与汇总。
|
||
|
||
CLI 参数见 [CLI](../docs/cli.md)，测试命令见 [tests](../tests/README.md)。
|