diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 2b5f01b6..50f46beb 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -217,26 +217,37 @@ jobs: with: path: artifacts - - name: Pack Godot addon + - name: Pack full and Asset Store addons env: RUSTC_WRAPPER: sccache run: | - # Use staging directory to avoid deleting source addon files - mise exec -- cargo xtask pack \ - --artifacts artifacts \ - --output dist/addons/godot_cef \ - --addon-src addons/godot_cef - mise exec -- cargo xtask validate --addon dist/addons/godot_cef - # Use dist as ZIP root so Asset Library installs into res://addons/godot_cef. - zip -r godot_cef.zip dist - - - name: Upload packed addon + # Stage each variant independently; both ZIPs retain the existing dist/addons layout. + for variant in full store; do + mise exec -- cargo xtask pack \ + --artifacts artifacts \ + --output staging/$variant/dist/addons/godot_cef \ + --addon-src addons/godot_cef \ + --variant "$variant" + mise exec -- cargo xtask validate \ + --addon staging/$variant/dist/addons/godot_cef --variant "$variant" + done + (cd staging/full && zip -r ../../godot_cef.zip dist) + (cd staging/store && zip -r ../../godot_cef-store.zip dist) + + - name: Upload full addon uses: actions/upload-artifact@v7 with: name: godot_cef-addon path: godot_cef.zip retention-days: 30 + - name: Upload Asset Store addon + uses: actions/upload-artifact@v7 + with: + name: godot_cef-store-addon + path: godot_cef-store.zip + retention-days: 30 + release: needs: [pack] runs-on: ubuntu-latest @@ -253,8 +264,16 @@ jobs: name: godot_cef-addon path: . - - name: Rename addon with version - run: mv godot_cef.zip godot_cef-${{ github.ref_name }}.zip + - name: Download Asset Store addon + uses: actions/download-artifact@v8 + with: + name: godot_cef-store-addon + path: . + + - name: Rename addons with version + run: | + mv godot_cef.zip godot_cef-${{ github.ref_name }}.zip + mv godot_cef-store.zip godot_cef-store-${{ github.ref_name }}.zip - name: Create GitHub Release uses: softprops/action-gh-release@v3 @@ -263,4 +282,6 @@ jobs: draft: true # release is draft until it is manually published prerelease: ${{ contains(github.ref_name, '-') }} generate_release_notes: true - files: godot_cef-${{ github.ref_name }}.zip + files: | + godot_cef-${{ github.ref_name }}.zip + godot_cef-store-${{ github.ref_name }}.zip diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f7e1b2d4..999642f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -295,6 +295,26 @@ For release or packaging changes, also run `cargo xtask pack` with the platform artifacts you changed and then `cargo xtask validate --addon` against the staged addon directory. +### Distribution variants + +`cargo xtask pack` defaults to the full addon, preserving all five platform +artifacts. For release packaging, stage and validate each variant independently: + +```bash +cargo xtask pack --artifacts artifacts --output staging/full/dist/addons/godot_cef --variant full +cargo xtask validate --addon staging/full/dist/addons/godot_cef --variant full +cargo xtask pack --artifacts artifacts --output staging/store/dist/addons/godot_cef --variant store +cargo xtask validate --addon staging/store/dist/addons/godot_cef --variant store +``` + +Variant validation requires every selected target and rejects excluded target +directories. Omit `--variant` for the existing partial-addon validation behavior. +The Store packer derives its descriptor from the full source manifest by removing +Windows/Linux ARM64 entries; do not install both descriptors in one Godot project. +See [Distribution variants](docs/api/distribution-variants.md) for archive layout, +architecture coverage, and manual ARM64 builds. CI builds all architectures and +publishes both package artifacts; this PR does not itself publish a release. + ### Lifecycle Cleanup Checklist When changing browser lifecycle code, preserve these cleanup invariants for `CefTexture`: diff --git a/README.md b/README.md index 53606d6d..410e5361 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,14 @@ For comprehensive API documentation, examples, and guides, visit the [full docum ## Platform Support +The default/full GitHub Release addon includes Windows x86_64/ARM64, Linux +x86_64/ARM64, and macOS universal (x86_64/ARM64). A separate **Asset Store** addon +includes Windows x86_64, Linux x86_64, and the same macOS universal framework to +reduce download size. Both packages install as `addons/godot_cef`; choose one. +ARM64 Windows/Linux users should use the full package. See +[Distribution variants](https://godotcef.org/api/distribution-variants.html) for +package names, local packaging commands and source-build instructions. + | Platform | DirectX 12 | Metal | Vulkan | Software Rendering | |----------|------------|-------|--------|-------------------| | **Windows** | ✅ (Note 1) | n.a. | ✅ (Note 2) | ✅ | diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index f7a839ac..d15bc06f 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -51,6 +51,7 @@ export default withMermaid(defineConfig({ { text: '拖放', link: '/zh_CN/api/drag-and-drop' }, { text: '下载', link: '/zh_CN/api/downloads' }, { text: 'Vulkan 支持', link: '/zh_CN/api/vulkan-support' }, + { text: '分发版本与源码构建', link: '/zh_CN/api/distribution-variants' }, { text: 'GPU 设备绑定', link: '/zh_CN/api/gpu-device-pinning' } ] } @@ -99,6 +100,7 @@ export default withMermaid(defineConfig({ { text: 'Drag and Drop', link: '/api/drag-and-drop' }, { text: 'Downloads', link: '/api/downloads' }, { text: 'Vulkan Support', link: '/api/vulkan-support' }, + { text: 'Distribution Variants', link: '/api/distribution-variants' }, { text: 'GPU Device Pinning', link: '/api/gpu-device-pinning' } ] } diff --git a/docs/api/compatibility-matrix.md b/docs/api/compatibility-matrix.md index a5f7d6bb..829fd437 100644 --- a/docs/api/compatibility-matrix.md +++ b/docs/api/compatibility-matrix.md @@ -2,6 +2,10 @@ This matrix summarizes the expected rendering mode behavior for each platform/backend combination. +This page covers architectures in the full GitHub Release addon. The smaller +Asset Store addon omits Windows/Linux ARM64; use the full package for those +targets. See [Distribution variants](./distribution-variants). + ## Version Baseline Current builds are based on the Rust `cef` / `cef-dll-sys` crates resolved as `152.3.0+152.0.6` in `Cargo.lock`. The matching CEF runtime version is pinned as `CEF_VERSION` in `mise.toml`; use it when installing CEF binaries manually: diff --git a/docs/api/distribution-variants.md b/docs/api/distribution-variants.md new file mode 100644 index 00000000..4b6f79c4 --- /dev/null +++ b/docs/api/distribution-variants.md @@ -0,0 +1,178 @@ +--- +title: Distribution Variants +description: Choose the full GitHub Release or smaller Asset Store addon and build custom ARM64 binaries. +--- + +# Distribution variants + +Godot CEF builds every supported architecture and produces two distribution +packages to address the Asset Store size limit. The full package continues to +provide Windows/Linux ARM64 binaries. This approach preserves platform support +and the default full-package behavior. See [#238](https://github.com/dsh0416/godot-cef/issues/238) +and [#239](https://github.com/dsh0416/godot-cef/pull/239) for the discussion. + +| Package | Release filename | Platform directories | +|---|---|---| +| Full (default) | `godot_cef-v.zip` | Windows x86_64/ARM64, Linux x86_64/ARM64, macOS universal | +| Asset Store | `godot_cef-store-v.zip` | Windows x86_64, Linux x86_64, macOS universal | + +macOS universal always includes x86_64 and ARM64. CI uploads separate ZIP +artifacts named `godot_cef-addon` and `godot_cef-store-addon`. The tag release +workflow attaches both to a draft release; PR builds do not publish releases. + +## Choose or switch packages + +Use the **full package** for native Windows/Linux ARM64 Godot editors or exports. +The Store package has no registrations for those architectures, so native ARM64 +processes cannot load the extension from it. Windows x86_64 emulation is not a +replacement validated by this change. + +Both ZIPs preserve the existing `dist/addons/godot_cef/` archive layout and install +as `addons/godot_cef/` in the project. Each package contains one +`godot_cef.gdextension` descriptor whose registrations match its binaries. +Back up local changes and **replace the whole addon directory** when switching +packages instead of extracting over an older installation. Do not install both +addon copies or descriptors together, as they register the same extension classes. + +The full descriptor comes from `addons/godot_cef/godot_cef.gdextension` in the +repository. The Store packer automatically removes Windows/Linux ARM64 library +entries and dependency dictionaries and does not copy those architecture +artifacts. Both packages share a version and API; architecture coverage differs. +Measure the final ZIP size from the actual build: a smaller target set does not +by itself confirm compliance with the Asset Store's exact byte limit. + +## Generate both packages locally + +Inputs use `artifacts/gdcef-/`, containing the extension, helper and CEF +runtime assets for that target. `cargo xtask pack` defaults to `full`, preserving +existing behavior; the Store variant is explicit. From the repository root with +the mise environment active: + +```bash +cargo xtask pack --artifacts artifacts --output staging/full/dist/addons/godot_cef --variant full +cargo xtask validate --addon staging/full/dist/addons/godot_cef --variant full +cargo xtask pack --artifacts artifacts --output staging/store/dist/addons/godot_cef --variant store +cargo xtask validate --addon staging/store/dist/addons/godot_cef --variant store +(cd staging/full && zip -r ../../godot_cef.zip dist) +(cd staging/store && zip -r ../../godot_cef-store.zip dist) +``` + +The input targets are `universal-apple-darwin`, `x86_64-pc-windows-msvc`, +`aarch64-pc-windows-msvc`, `x86_64-unknown-linux-gnu`, and +`aarch64-unknown-linux-gnu`. `validate --variant` requires every selected target +and rejects excluded target directories. Omitting `--variant` preserves the +existing partial-addon validation behavior. Packing recreates the output +folder; stage separately and do not use the source addon directory as output. + +## Custom ARM64 source builds + +Most users can choose the full prebuilt package. If you need to maintain your own +build, the existing source entry points are shown below. These commands were +reviewed against current build inputs and runtime layout; local verification did +not compile ARM64 binaries or run an ARM64 editor/rendering/export. Full platform +builds are checked by PR CI. You must still verify compiler/runtime availability +and compatibility with the destination system. + +## Common prerequisites + +Use a clean checkout of the exact tag or commit you intend to maintain. Install +Git and mise, then run commands from the repository root. `mise install` provides +the Rust nightly and `export-cef-dir` pinned by `mise.toml`. Use that checkout's +`CEF_VERSION`, not an arbitrary newer CEF runtime. A C++ compiler, CMake, and +Godot 4.5+ for the target OS/architecture are also required. Builds can consume +substantial disk space and memory. + +`cargo xtask bundle` dispatches by the **host OS**: use Windows for Windows +builds and Linux for Linux builds. Passing a Windows/Linux target on macOS does +not provide a cross-OS build path. + +## Windows ARM64 from a Windows x64 host + +Install Visual Studio 2022 Build Tools with Desktop development with C++, the +MSVC ARM64 build tools and a Windows SDK. Use a Developer Command Prompt configured +for x64-host/ARM64-target (`amd64_arm64`). For example, in `cmd.exe`, replace the +installation path with your actual Visual Studio location, then launch PowerShell +from that configured prompt so it inherits the compiler environment: + +```bat +call "\VC\Auxiliary\Build\vcvarsall.bat" amd64_arm64 +pwsh -NoProfile +``` + +Install CMake and PowerShell 7 (`pwsh`) and make them available on `PATH`. Run: + +```powershell +mise trust +mise install +mise exec -- pwsh -NoProfile +# The following commands run inside this mise environment. +$env:CEF_PATH = "$env:USERPROFILE/.local/share/cef_windows_arm64" +export-cef-dir --version $env:CEF_VERSION --target aarch64-pc-windows-msvc --force $env:CEF_PATH +rustup target add aarch64-pc-windows-msvc +cargo xtask bundle --release --target aarch64-pc-windows-msvc +``` + +Do not point `CEF_PATH` at an x64 runtime. The bundled output includes the helper, +DLLs, locales and CEF resources, and is deployed to +`addons/godot_cef/bin/aarch64-pc-windows-msvc/`. Cargo's target build output is +`target/aarch64-pc-windows-msvc/release/` with the default target directory. +A native Windows ARM64 host requires an ARM64-host/ARM64-target developer +environment and matching native tools; that host setup is not validated here. + +## Linux ARM64 from a Linux x64 host + +For a Debian/Ubuntu-style host, install the ordinary build dependencies and the +ARM64 cross compiler/binutils: + +```bash +sudo apt-get update +sudo apt-get install -y build-essential cmake libgtk-3-dev libnss3-dev \ + libatk1.0-dev libatk-bridge2.0-dev libcups2-dev libdrm-dev \ + libxkbcommon-dev libxcomposite-dev libxdamage-dev libxrandr-dev \ + libgbm-dev libpango1.0-dev libasound2-dev \ + gcc-aarch64-linux-gnu g++-aarch64-linux-gnu binutils-aarch64-linux-gnu +mise trust +mise install +mise exec -- bash +# The following commands run inside this mise environment. +export CEF_PATH="$HOME/.local/share/cef_linux_arm64" +export CC_aarch64_unknown_linux_gnu=aarch64-linux-gnu-gcc +export CXX_aarch64_unknown_linux_gnu=aarch64-linux-gnu-g++ +export-cef-dir --version "$CEF_VERSION" --target aarch64-unknown-linux-gnu --force "$CEF_PATH" +rustup target add aarch64-unknown-linux-gnu +cargo xtask bundle --release --target aarch64-unknown-linux-gnu +``` + +The repository's `.cargo/config.toml` selects `aarch64-linux-gnu-gcc` and permits +unresolved dependencies from `libcef.so` during cross linking. Those libraries +must still exist on the target system. Host development packages alone do not +supply an ARM64 runtime/sysroot; install target-architecture dependencies or +configure a compatible ARM64 sysroot if required by the compiler or CEF build. +Check the CEF runtime's glibc/system-library requirements against the destination. + +The Linux bundler uses `aarch64-linux-gnu-strip`, copies runtime assets and deploys +to `addons/godot_cef/bin/aarch64-unknown-linux-gnu/`. Cargo's default target output +is `target/aarch64-unknown-linux-gnu/release/`. A native Linux ARM64 build is also +accepted, but the current linker/strip configuration still requires the named +`aarch64-linux-gnu-*` tools; adjust your local toolchain if your distribution uses +other names. No native ARM64 host setup is validated here. + +## Install and validate a custom build + +`cargo xtask bundle` deploys the complete runtime to the repository's +`addons/godot_cef/bin//`. Copy the whole `addons/godot_cef/` into the project, +or copy the target directory into a full addon from the same commit. The full +repository descriptor already registers Windows/Linux ARM64; no manual manifest +entries are needed. If you previously used a Store package, switch to the full +descriptor and ensure its referenced target files match your deployed contents. +Do not copy only the extension DLL/SO without dependencies, or enable two +`.gdextension` descriptors together. Preserve Linux helper and `chrome-sandbox` +executable permissions. + +On the ARM64 destination, verify native Godot editor and exported-game extension +loading, helper startup, page rendering/input and exported runtime dependencies. +On Linux, run `ldd` on `libgdcef.so`, `gdcef_helper` and `libcef.so` on that +ARM64 system. Windows needs the matching MSVC runtime and CEF dependencies. +Cross-compilation success does not guarantee editor/export runtime compatibility. +Windows/Linux Vulkan hook acceleration still requires x86_64; start ARM64 runtime +validation with software rendering; see [Vulkan support](./vulkan-support). diff --git a/docs/api/vulkan-support.md b/docs/api/vulkan-support.md index 096a0c62..6df3565a 100644 --- a/docs/api/vulkan-support.md +++ b/docs/api/vulkan-support.md @@ -2,6 +2,10 @@ This page documents how Godot CEF enables GPU-accelerated rendering on Vulkan backends through runtime function hooking, and the limitations of this approach. +This page covers architectures in the full GitHub Release addon. The smaller +Asset Store addon omits Windows/Linux ARM64; use the full package for those +targets. See [Distribution variants](./distribution-variants). + ## Background GPU-accelerated offscreen rendering (OSR) in CEF requires sharing textures between the CEF renderer process and the host application (Godot). This is achieved through platform-specific external memory APIs: @@ -103,7 +107,7 @@ Vulkan hook-based acceleration is **only available on x86_64 (64-bit x86) archit The hooking mechanism relies on the [retour](https://github.com/darfink/retour-rs) library for runtime function detouring. This library currently does not support ARM64 architecture, which means: - **Windows ARM64** — Vulkan hooks not available -- **Linux ARM64** — Vulkan hooks not available +- **Linux ARM64** — Vulkan hooks not available - **macOS (Apple Silicon)** — Vulkan hooks not available On unsupported architectures, the extension automatically falls back to software rendering. diff --git a/docs/zh_CN/api/compatibility-matrix.md b/docs/zh_CN/api/compatibility-matrix.md index cfd31ab3..228b8f79 100644 --- a/docs/zh_CN/api/compatibility-matrix.md +++ b/docs/zh_CN/api/compatibility-matrix.md @@ -2,6 +2,9 @@ 该矩阵用于总结不同平台与渲染后端下，Godot CEF 的预期渲染行为。 +本页包含完整 GitHub Release 包支持的架构。精简的 Asset Store 包不含 Windows/Linux ARM64； +需要这些架构时请选择完整包。详见[分发版本](./distribution-variants)。 + ## 版本基线 当前构建基于 `Cargo.lock` 中解析到的 Rust `cef` / `cef-dll-sys` crate 版本：`152.3.0+152.0.6`。匹配的 CEF 运行时版本已在 `mise.toml` 中固定为 `CEF_VERSION`；手动安装 CEF 二进制文件时请使用它： diff --git a/docs/zh_CN/api/distribution-variants.md b/docs/zh_CN/api/distribution-variants.md new file mode 100644 index 00000000..8cfa9ce9 --- /dev/null +++ b/docs/zh_CN/api/distribution-variants.md @@ -0,0 +1,149 @@ +--- +title: 分发版本与源码构建 +description: 选择完整 GitHub Release 或精简 Asset Store 插件，并构建自定义 ARM64 二进制。 +--- + +# 分发版本与源码构建 + +Godot CEF 构建全部受支持的架构，同时生成两个分发包，以应对 Asset Store 的版本大小限制。 +完整包继续提供 Windows/Linux ARM64 二进制。此方案不移除这些平台的支持，也不会改变完整包的默认行为。 +背景讨论见 [#238](https://github.com/dsh0416/godot-cef/issues/238) 和 [#239](https://github.com/dsh0416/godot-cef/pull/239)。 + +| 分发包 | Release 文件名 | 平台目录 | +|---|---|---| +| 完整包（默认） | `godot_cef-v.zip` | Windows x86_64/ARM64、Linux x86_64/ARM64、macOS universal | +| Asset Store 精简包 | `godot_cef-store-v.zip` | Windows x86_64、Linux x86_64、macOS universal | + +macOS universal 始终同时包含 x86_64 和 ARM64。CI 将两个 ZIP 作为独立构件上传，分别命名为 +`godot_cef-addon` 和 `godot_cef-store-addon`。标签的 release 流程会把两者附加到草稿 release； +构建 PR 不会发布 release。 + +## 选择与切换 + +需要 Windows/Linux ARM64 原生 Godot 编辑器或导出时，请下载**完整包**。 +Store 包不注册这两种架构，原生 ARM64 进程不能从中加载扩展。 +Windows x86_64 模拟运行不是经本次改动验证的替代方案。 + +两个 ZIP 都保持原有 `dist/addons/godot_cef/` 布局，并安装为项目中的 `addons/godot_cef/`。 +每个包只有一个名为 `godot_cef.gdextension` 的清单，其注册与包内二进制相符。 +切换版本时先备份本地修改，然后**替换整个插件目录**，不要叠加解压到旧目录。 +不要同时安装两个插件副本或清单，以免重复注册扩展类。 + +完整清单来自仓库 `addons/godot_cef/godot_cef.gdextension`。 +Store 打包器自动移除其中 Windows/Linux ARM64 库条目和依赖块，也不复制这两种架构的构件。 +两个分发包共享版本和 API；区别在于包含的架构。最终 ZIP 大小以实际构建测量为准， +更小的目标集合不代表已经确认满足 Asset Store 的精确字节限制。 + +## 在本地生成两种分发包 + +构件输入布局为 `artifacts/gdcef-/`，其中包含该目标的扩展、helper 和 CEF 运行时资源。 +`cargo xtask pack` 默认选择 `full`，保持此前行为；Store 版本需显式指定。 +在仓库根目录运行以下命令（已启用 mise 环境）： + +```bash +cargo xtask pack --artifacts artifacts --output staging/full/dist/addons/godot_cef --variant full +cargo xtask validate --addon staging/full/dist/addons/godot_cef --variant full +cargo xtask pack --artifacts artifacts --output staging/store/dist/addons/godot_cef --variant store +cargo xtask validate --addon staging/store/dist/addons/godot_cef --variant store +(cd staging/full && zip -r ../../godot_cef.zip dist) +(cd staging/store && zip -r ../../godot_cef-store.zip dist) +``` + +输入目标为 `universal-apple-darwin`、`x86_64-pc-windows-msvc`、`aarch64-pc-windows-msvc`、 +`x86_64-unknown-linux-gnu` 和 `aarch64-unknown-linux-gnu`。 +使用 `validate --variant` 时，必须存在所选版本的全部目标，且不得包含被排除的目标目录。 +不传 `--variant` 则保留原有的部分插件验证行为。 +打包输出目录会被重建；请使用独立暂存目录，不要将源码插件目录作为输出。 + +## 自定义 ARM64 源码构建 + +通常直接使用完整的预编译包即可。需要自行维护构建时，可使用以下现有源码入口。 +命令按当前构建输入和资源布局整理；本地验证未执行 ARM64 编译、编辑器启动、渲染或导出， +完整平台构建由 PR CI 验证。编译器、CEF 可用性和目标系统运行时兼容性仍需自行确认。 + +## 通用前提 + +使用需要自行维护的确切 tag 或提交的干净 checkout。安装 Git 和 mise，并在仓库根目录运行命令。 +`mise install` 安装 `mise.toml` 固定的 Rust nightly 和 `export-cef-dir`。 +使用该 checkout 的 `CEF_VERSION`，不要随意换用较新的 CEF 运行时。 +还需要 C++ 编译器、CMake，以及目标系统/架构的 Godot 4.5+。构建可能占用较多磁盘和内存。 + +`cargo xtask bundle` 按**宿主操作系统**选择打包器：Windows 构建应在 Windows 上运行， +Linux 构建应在 Linux 上运行。在 macOS 上传入 Windows/Linux 目标并不能跨系统构建。 + +## 在 Windows x64 宿主上构建 Windows ARM64 + +安装 Visual Studio 2022 Build Tools 的“使用 C++ 的桌面开发”、MSVC ARM64 工具和 Windows SDK。 +使用配置为 x64 宿主、ARM64 目标（`amd64_arm64`）的开发者命令提示符。 +例如，在 `cmd.exe` 中将路径替换为实际 Visual Studio 安装位置，然后从该环境启动 PowerShell，继承编译器环境： + +```bat +call "\VC\Auxiliary\Build\vcvarsall.bat" amd64_arm64 +pwsh -NoProfile +``` + +安装 CMake 和 PowerShell 7（`pwsh`），确保位于 `PATH`，然后运行： + +```powershell +mise trust +mise install +mise exec -- pwsh -NoProfile +# The following commands run inside this mise environment. +$env:CEF_PATH = "$env:USERPROFILE/.local/share/cef_windows_arm64" +export-cef-dir --version $env:CEF_VERSION --target aarch64-pc-windows-msvc --force $env:CEF_PATH +rustup target add aarch64-pc-windows-msvc +cargo xtask bundle --release --target aarch64-pc-windows-msvc +``` + +不要让 `CEF_PATH` 指向 x64 运行时。打包器将扩展、helper、DLL、locales 和 CEF 资源复制到 +`addons/godot_cef/bin/aarch64-pc-windows-msvc/`。 +默认 Cargo 产物位于 `target/aarch64-pc-windows-msvc/release/`。 +在 Windows ARM64 原生宿主上构建需要 ARM64 宿主/ARM64 目标的开发环境及对应工具；本页未验证该宿主配置。 + +## 在 Linux x64 宿主上构建 Linux ARM64 + +以 Debian/Ubuntu 类宿主为例，安装常规依赖以及 ARM64 交叉编译器和 binutils： + +```bash +sudo apt-get update +sudo apt-get install -y build-essential cmake libgtk-3-dev libnss3-dev \ + libatk1.0-dev libatk-bridge2.0-dev libcups2-dev libdrm-dev \ + libxkbcommon-dev libxcomposite-dev libxdamage-dev libxrandr-dev \ + libgbm-dev libpango1.0-dev libasound2-dev \ + gcc-aarch64-linux-gnu g++-aarch64-linux-gnu binutils-aarch64-linux-gnu +mise trust +mise install +mise exec -- bash +# The following commands run inside this mise environment. +export CEF_PATH="$HOME/.local/share/cef_linux_arm64" +export CC_aarch64_unknown_linux_gnu=aarch64-linux-gnu-gcc +export CXX_aarch64_unknown_linux_gnu=aarch64-linux-gnu-g++ +export-cef-dir --version "$CEF_VERSION" --target aarch64-unknown-linux-gnu --force "$CEF_PATH" +rustup target add aarch64-unknown-linux-gnu +cargo xtask bundle --release --target aarch64-unknown-linux-gnu +``` + +仓库 `.cargo/config.toml` 选择 `aarch64-linux-gnu-gcc`，并允许交叉链接时 `libcef.so` +存在未解析的依赖。这些共享库仍必须在目标系统上可用。 +宿主开发包不等于 ARM64 运行时/sysroot；编译器或 CEF 构建需要时，请安装目标架构依赖， +或配置兼容的 ARM64 sysroot。核对目标系统是否满足 CEF 的 glibc 和系统库要求。 + +Linux 打包器使用 `aarch64-linux-gnu-strip`，将运行时资源部署到 +`addons/godot_cef/bin/aarch64-unknown-linux-gnu/`。 +默认 Cargo 产物位于 `target/aarch64-unknown-linux-gnu/release/`。 +打包器也接受 Linux ARM64 原生构建，但当前 linker/strip 配置仍要求上述 +`aarch64-linux-gnu-*` 工具名；发行版命名不同时需自行调整本地工具链。本页未验证原生 ARM64 宿主配置。 + +## 安装与验证自编译插件 + +`cargo xtask bundle` 将完整资源部署到仓库 `addons/godot_cef/bin//`。 +复制整个 `addons/godot_cef/` 到项目，或将目标目录复制到同一提交的完整插件。 +仓库的完整 `.gdextension` 已注册 Windows/Linux ARM64，无需手工添加清单条目。 +如果项目此前使用 Store 包，应切换为完整包的清单，并确保其引用的目标文件与实际部署相符。 +不要复制缺少依赖的扩展 DLL/SO，也不要同时启用两个 `.gdextension`。 +保留 Linux helper 和 `chrome-sandbox` 的可执行权限。 + +在目标系统上验证原生 ARM64 Godot 编辑器及导出游戏的扩展加载、helper 启动、网页渲染/输入、 +以及导出资源。Linux 可在 ARM64 目标系统上对 `libgdcef.so`、`gdcef_helper`、`libcef.so` 运行 `ldd`。 +Windows 需要匹配的 MSVC 运行时与 CEF 依赖。交叉编译成功不保证编辑器/导出运行时兼容。 +Windows/Linux 的 Vulkan Hook 加速仍要求 x86_64；ARM64 先用软件渲染验证，见 [Vulkan 支持](./vulkan-support)。 diff --git a/docs/zh_CN/api/vulkan-support.md b/docs/zh_CN/api/vulkan-support.md index 824a1fbc..df24b579 100644 --- a/docs/zh_CN/api/vulkan-support.md +++ b/docs/zh_CN/api/vulkan-support.md @@ -2,6 +2,9 @@ 本页面介绍 Godot CEF 如何通过运行时函数钩子在 Vulkan 后端启用 GPU 加速渲染，以及该方案的限制与注意事项。 +本页包含完整 GitHub Release 包支持的架构。精简的 Asset Store 包不含 Windows/Linux ARM64； +需要这些架构时请选择完整包。详见[分发版本](./distribution-variants)。 + ## 背景 CEF 中的 GPU 加速离屏渲染（OSR）需要在 CEF 渲染器进程和宿主应用程序（Godot）之间共享纹理。这通过平台特定的外部内存 API 实现： diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 0be1496f..629f025a 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -3,7 +3,7 @@ //! Usage: //! cargo xtask bundle [--release] [--target ] # Bundle for current platform and deploy to addons/ //! cargo xtask bundle-framework [--release] # Bundle framework (macOS only) -//! cargo xtask pack # Pack CI artifacts into distributable addon +//! cargo xtask pack --artifacts --output [--variant full|store] # Pack CI artifacts into distributable addon //! cargo xtask validate --addon # Validate addon artifact completeness //! cargo xtask validate-versions # Validate workspace/toolchain version pins @@ -22,6 +22,7 @@ mod validate; mod validate_versions; use clap::{Parser, Subcommand}; +use platform::PackageVariant; use std::path::PathBuf; #[derive(Parser)] @@ -73,6 +74,10 @@ enum Commands { /// Path to addon source files (gdextension, icons) #[arg(long)] addon_src: Option, + + /// Distribution variant (full includes every supported architecture) + #[arg(long, value_enum, default_value_t = PackageVariant::Full)] + variant: PackageVariant, }, /// Validate addon artifact completeness @@ -80,6 +85,10 @@ enum Commands { /// Path to addon directory containing bin/ outputs #[arg(long)] addon: PathBuf, + + /// Require all targets for this variant and reject excluded targets + #[arg(long, value_enum)] + variant: Option, }, /// Validate version and toolchain pins across workspace files @@ -132,11 +141,12 @@ fn main() -> Result<(), Box> { artifacts, output, addon_src, + variant, } => { - pack::run(&artifacts, &output, addon_src.as_deref())?; + pack::run(&artifacts, &output, addon_src.as_deref(), variant)?; } - Commands::Validate { addon } => { - validate::run(&addon)?; + Commands::Validate { addon, variant } => { + validate::run(&addon, variant)?; } Commands::ValidateVersions => { validate_versions::run()?; diff --git a/xtask/src/pack.rs b/xtask/src/pack.rs index 7b1c334e..0487da89 100644 --- a/xtask/src/pack.rs +++ b/xtask/src/pack.rs @@ -1,7 +1,7 @@ //! Pack command - assembles all platform artifacts into a single Godot addon use crate::bundle_common::{copy_directory, validate_required_paths}; -use crate::platform::{PLATFORM_SPECS, PlatformSpec}; +use crate::platform::{PLATFORM_SPECS, PackageVariant, PlatformSpec}; use std::fs; use std::path::Path; @@ -32,10 +32,48 @@ fn copy_platform_artifacts( Ok(true) } -fn copy_addon_files(addon_src: &Path, output_dir: &Path) -> Result<(), Box> { +fn manifest_for_variant( + manifest: &str, + variant: PackageVariant, +) -> Result> { + if variant == PackageVariant::Full { + return Ok(manifest.to_owned()); + } + + let mut result = String::new(); + let mut skipping_dictionary = false; + for line in manifest.split_inclusive('\n') { + let trimmed = line.trim(); + if skipping_dictionary { + if trimmed == "}" { + skipping_dictionary = false; + } + continue; + } + if let Some((key, value)) = trimmed.split_once('=') + && ["windows.arm64", "linux.arm64"].contains(&key.trim()) + { + // The source descriptor uses one-line library paths and multiline dependency dictionaries. + skipping_dictionary = value.trim() == "{"; + continue; + } + result.push_str(line); + } + if skipping_dictionary { + return Err("unterminated ARM64 dependency dictionary in GDExtension manifest".into()); + } + Ok(result) +} + +fn copy_addon_files( + addon_src: &Path, + output_dir: &Path, + variant: PackageVariant, +) -> Result<(), Box> { let gdext_src = addon_src.join("godot_cef.gdextension"); if gdext_src.exists() { - fs::copy(&gdext_src, output_dir.join("godot_cef.gdextension"))?; + let manifest = manifest_for_variant(&fs::read_to_string(&gdext_src)?, variant)?; + fs::write(output_dir.join("godot_cef.gdextension"), manifest)?; println!(" Copied: godot_cef.gdextension"); } @@ -56,8 +94,10 @@ pub fn run( artifacts_dir: &Path, output_dir: &Path, addon_src: Option<&Path>, + variant: PackageVariant, ) -> Result<(), Box> { println!("Packing Godot addon from artifacts..."); + println!(" Variant: {variant:?}"); println!(" Artifacts: {}", artifacts_dir.display()); println!(" Output: {}", output_dir.display()); @@ -68,7 +108,7 @@ pub fn run( fs::create_dir_all(&bin_dir)?; if let Some(addon_path) = addon_src { - copy_addon_files(addon_path, output_dir)?; + copy_addon_files(addon_path, output_dir, variant)?; } else { let workspace_addon = Path::new(env!("CARGO_MANIFEST_DIR")) .parent() @@ -78,12 +118,15 @@ pub fn run( ) .join("addons/godot_cef"); if workspace_addon.exists() { - copy_addon_files(&workspace_addon, output_dir)?; + copy_addon_files(&workspace_addon, output_dir, variant)?; } } let mut platforms_found = 0; for platform in PLATFORM_SPECS { + if !variant.includes(platform.target) { + continue; + } if copy_platform_artifacts(artifacts_dir, &bin_dir, platform)? { platforms_found += 1; } diff --git a/xtask/src/platform.rs b/xtask/src/platform.rs index 2a00aa43..9633f4e2 100644 --- a/xtask/src/platform.rs +++ b/xtask/src/platform.rs @@ -1,3 +1,5 @@ +use clap::ValueEnum; + pub struct PlatformSpec { pub target: &'static str, pub artifact_name: &'static str, @@ -13,6 +15,20 @@ pub struct RuntimeAssetSpec { pub deploy_dirs: &'static [&'static str], } +/// Full releases preserve every supported target; the Store bundle omits Windows/Linux ARM64. +#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, ValueEnum)] +pub enum PackageVariant { + #[default] + Full, + Store, +} + +impl PackageVariant { + pub fn includes(self, target: &str) -> bool { + self == Self::Full || ![WINDOWS_ARM64_TARGET, LINUX_ARM64_TARGET].contains(&target) + } +} + pub const MACOS_UNIVERSAL_TARGET: &str = "universal-apple-darwin"; pub const WINDOWS_X64_TARGET: &str = "x86_64-pc-windows-msvc"; pub const WINDOWS_ARM64_TARGET: &str = "aarch64-pc-windows-msvc"; diff --git a/xtask/src/validate.rs b/xtask/src/validate.rs index 5c3ae145..ed80063e 100644 --- a/xtask/src/validate.rs +++ b/xtask/src/validate.rs @@ -1,10 +1,13 @@ //! Validation command - checks packaged addon layout and required artifacts use crate::bundle_common::validate_required_paths; -use crate::platform::PLATFORM_SPECS; +use crate::platform::{PLATFORM_SPECS, PackageVariant}; use std::path::Path; -pub fn run(addon_dir: &Path) -> Result<(), Box> { +pub fn run( + addon_dir: &Path, + variant: Option, +) -> Result<(), Box> { let bin_dir = addon_dir.join("bin"); if !bin_dir.exists() { return Err(format!( @@ -14,9 +17,41 @@ pub fn run(addon_dir: &Path) -> Result<(), Box> { .into()); } + if let Some(variant) = variant { + let manifest = std::fs::read_to_string(addon_dir.join("godot_cef.gdextension"))?; + for platform in PLATFORM_SPECS { + if manifest.contains(platform.target) != variant.includes(platform.target) { + return Err(format!( + "GDExtension manifest does not match {variant:?} target selection: {}", + platform.target + ) + .into()); + } + } + } + let mut validated = 0usize; for platform in PLATFORM_SPECS { let platform_dir = bin_dir.join(platform.target); + if let Some(variant) = variant { + if !variant.includes(platform.target) { + if platform_dir.exists() { + return Err(format!( + "excluded target present in {variant:?} addon: {}", + platform.target + ) + .into()); + } + continue; + } + if !platform_dir.exists() { + return Err(format!( + "missing required {variant:?} addon target: {}", + platform.target + ) + .into()); + } + } if !platform_dir.exists() { println!("Skipping {} (not present)", platform.target); continue;