@next2d/builder 0.1.6 → 0.1.7

package/README.md

@@ -48,9 +48,13 @@ On other platforms the builder scaffolds the host project and stages assets only
 See the generated `xbox/README.md` for full build steps.
 
 ```bat
-npx @next2d/builder --platform xbox --env prd --v8-root C:\path\to\v8
+npx @next2d/builder --platform xbox --env prd
 ```
 
+The prebuilt V8 engine is downloaded automatically on the first Xbox build
+(published from the `build-v8` workflow). To use your own build, pass
+`--v8-root C:\path\to\v8`.
+
 ### Scheduled introduction
 
 | platform        | 

package/dist/index.js

@@ -2,6 +2,7 @@
 "use strict";
 import pc from "picocolors";
 import fs from "fs";
+import os from "os";
 import path from "path";
 import { fileURLToPath } from "url";
 import cp from "child_process";
@@ -76,8 +77,9 @@ const echoHelp = () => {
     console.log("For preview example:");
     console.log("npx @next2d/builder --preview --platform web --env prd");
     console.log();
-    console.log("For Xbox build example (prebuilt V8 monolith path):");
-    console.log("npx @next2d/builder --platform xbox --env prd --v8-root C:\\path\\to\\v8");
+    console.log("For Xbox build example (prebuilt V8 is downloaded automatically):");
+    console.log("npx @next2d/builder --platform xbox --env prd");
+    console.log("To use your own V8 build: --v8-root C:\\path\\to\\v8");
     console.log();
     process.exit(1);
 };
@@ -469,6 +471,17 @@ const getTemplateDir = (name) => {
  * @constant
  */
 const XBOX_CONFIG_NAME = "MicrosoftGame.config";
+/**
+ * @description 自動ダウンロードする prebuilt V8 のバージョン。
+ *              `.github/workflows/build-v8.yml` で発行した Releases のタグと、
+ *              `xbox-host-ci.yml` の V8_TAG に一致させること。
+ *              The prebuilt V8 version to auto-download. Must match the release tag
+ *              published by `build-v8.yml` and V8_TAG in `xbox-host-ci.yml`.
+ *
+ * @type {string}
+ * @constant
+ */
+const XBOX_V8_VERSION = "13.6.233.17";
 /**
  * @description ゲーム側の `xbox/` へスキャフォールドしないテンプレート内ファイル。
  *              - MicrosoftGame.config : ゲーム固有設定 (injectGameConfig が注入)
@@ -580,6 +593,59 @@ const copyXboxResources = () => {
         }
     });
 };
+/**
+ * @description Xbox ビルドに使う V8 のパスを解決する。優先順:
+ *              1. `--v8-root` 引数
+ *              2. 環境変数 `V8_ROOT`
+ *              3. キャッシュ済みの prebuilt (%LOCALAPPDATA%/next2d/v8/<version>)
+ *              4. GitHub Releases (build-v8.yml が発行) から自動ダウンロード
+ *              3・4 により、通常は何も指定せずに `--platform xbox` だけでビルドできる。
+ *              Resolve the V8 path for the Xbox build. With the cached/auto-downloaded
+ *              prebuilt, no flag or env var is required in the common case.
+ *
+ * @return {Promise<string>}
+ * @method
+ * @public
+ */
+const resolveXboxV8Root = async () => {
+    // 1. --v8-root 引数
+    if (v8Root) {
+        return path.resolve(process.cwd(), v8Root);
+    }
+    // 2. 環境変数 V8_ROOT
+    if (process.env.V8_ROOT) {
+        return process.env.V8_ROOT;
+    }
+    // 3. キャッシュ済み prebuilt
+    const cacheBase = process.env.LOCALAPPDATA
+        ? `${process.env.LOCALAPPDATA}/next2d`
+        : `${os.homedir()}/.cache/next2d`;
+    const cacheDir = `${cacheBase}/v8/${XBOX_V8_VERSION}`;
+    if (fs.existsSync(`${cacheDir}/include/v8.h`)) {
+        return cacheDir;
+    }
+    // 4. GitHub Releases から自動ダウンロード (マシンごとに初回のみ)
+    const assetName = `v8-monolith-${XBOX_V8_VERSION}-windows-x64.zip`;
+    const url = `https://github.com/Next2D/builder/releases/download/v8-${XBOX_V8_VERSION}-windows-x64/${assetName}`;
+    console.log(pc.green(`Downloading prebuilt V8 ${XBOX_V8_VERSION} (first time only) ...`));
+    console.log(url);
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`download failed: HTTP ${response.status}`);
+    }
+    fs.mkdirSync(cacheDir, { "recursive": true });
+    const zipPath = `${cacheDir}/${assetName}.tmp`;
+    fs.writeFileSync(zipPath, Buffer.from(await response.arrayBuffer()));
+    // Windows 10+ 標準の tar (bsdtar) は zip も展開できる
+    const extract = cp.spawnSync("tar", ["-xf", zipPath, "-C", cacheDir], { "stdio": "inherit" });
+    fs.rmSync(zipPath, { "force": true });
+    if (extract.status !== 0 || !fs.existsSync(`${cacheDir}/include/v8.h`)) {
+        fs.rmSync(cacheDir, { "recursive": true, "force": true });
+        throw new Error("failed to extract the prebuilt V8 archive");
+    }
+    console.log(pc.green(`Prebuilt V8 cached at: ${cacheDir}`));
+    return cacheDir;
+};
 /**
  * @description Xbox(GDKネイティブ)用アプリの書き出し関数。
  *              V8にNext2DのJSを載せ、Dawn(WebGPU/D3D12)で描画するC++ホストをビルドする。
@@ -619,18 +685,20 @@ const buildXbox = async () => {
     const gdkArch = process.env.NEXT2D_XBOX_ARCH || "Gaming.Xbox.Scarlett.x64";
     const cmakeBuildDir = `${process.cwd()}/${$outDir}/${platformDir}/build`;
     /**
-     * prebuilt V8 monolith のパス。優先順: `--v8-root` 引数 > 環境変数 V8_ROOT。
-     * どちらも無い場合は CMake (FindV8.cmake) が明確なエラーで停止するため、
-     * ここでは事前に分かりやすく案内だけする。
+     * prebuilt V8 のパスを解決する (--v8-root > V8_ROOT > キャッシュ > 自動ダウンロード)。
+     * 通常は何も指定せずにビルドできる。
      */
-    const resolvedV8Root = v8Root
-        ? path.resolve(process.cwd(), v8Root)
-        : process.env.V8_ROOT || "";
-    if (!resolvedV8Root) {
-        console.log(pc.red("V8 path is not specified."));
-        console.log(pc.red("Pass `--v8-root <path>` (or set the V8_ROOT environment variable):"));
-        console.log(pc.red("  npx @next2d/builder --platform xbox --env prd --v8-root C:\\path\\to\\v8"));
-        console.log(pc.red(`The path must contain \`include/v8.h\` and \`lib/v8_monolith.lib\`. See ${XBOX_DIR_NAME}/README.md.`));
+    let resolvedV8Root = "";
+    try {
+        resolvedV8Root = await resolveXboxV8Root();
+    }
+    catch (error) {
+        console.log(pc.red(`Failed to prepare the prebuilt V8: ${error}`));
+        console.log(pc.red("Fallbacks:"));
+        console.log(pc.red("  1) Retry later (the download may have failed temporarily)."));
+        console.log(pc.red("  2) Build V8 yourself and pass `--v8-root <path>`:"));
+        console.log(pc.red("     npx @next2d/builder --platform xbox --env prd --v8-root C:\\path\\to\\v8"));
+        console.log(pc.red(`     See ${XBOX_DIR_NAME}/README.md ("V8 の用意") for the build steps.`));
         return;
     }
     if (!fs.existsSync(`${resolvedV8Root}/include/v8.h`)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next2d/builder",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Multi-platform builder for Next2d Framework, supporting export to various platforms such as macOS, Windows, iOS, Android and Web(HTML)",
   "author": "Toshiyuki Ienaga <ienaga@next2d.app>",
   "license": "MIT",

package/templates/xbox/CMakeLists.txt

@@ -92,10 +92,13 @@ else()
     target_compile_definitions(Next2DXboxHost PRIVATE NEXT2D_XBOX_CONSOLE=0)
 endif()
 
-# V8 のプラットフォーム要件
+# V8 のプラットフォーム要件。
+# prebuilt V8 (build-v8.yml) のビルドフラグと一致させること:
+#   V8_COMPRESS_POINTERS <-> v8_enable_pointer_compression=true
+#   sandbox は無効 (libc++ ハードニング必須のため use_custom_libcxx=false と両立しない)
+#   → V8_ENABLE_SANDBOX は定義しない
 target_compile_definitions(Next2DXboxHost PRIVATE
     V8_COMPRESS_POINTERS
-    V8_ENABLE_SANDBOX
     NOMINMAX
     WIN32_LEAN_AND_MEAN
     UNICODE

package/templates/xbox/README.md

@@ -75,7 +75,7 @@ C++ 実行ファイルをビルドします。Electron や WebView は使用し
 | IDE | Visual Studio 2022 (v143, C++ Game development workload) |
 | GDK | Microsoft GDK (June 2024 以降) — ID@Xbox 登録が必要 |
 | CMake | 3.26 以降 |
-| V8 | prebuilt monolith (`v8_monolith.lib` + `include/`) |
+| V8 | 不要 (builder が prebuilt を自動ダウンロード)。自前ビルドは `--v8-root` で指定可 |
 | Dawn | CMake の FetchContent で自動取得(ネットワーク必須) |
 | devkit | Xbox 開発機(実機検証用) |
 
@@ -83,25 +83,72 @@ C++ 実行ファイルをビルドします。Electron や WebView は使用し
 
 ## V8 の用意
 
-V8 はソースビルドが非常に重いため prebuilt monolith を使います。自前ビルド例:
+**通常は何も必要ありません。** builder が Next2D の GitHub Releases から
+prebuilt V8 monolith を自動ダウンロードし、`%LOCALAPPDATA%\next2d\v8\<version>` に
+キャッシュします (マシンごとに初回のみ、以後は再利用)。
+
+自動ダウンロードを使わない場合の優先順:
+
+1. `--v8-root <path>` 引数
+2. 環境変数 `V8_ROOT`
+3. キャッシュ済み prebuilt
+4. GitHub Releases から自動ダウンロード
+
+> prebuilt は builder リポジトリの `build-v8.yml` ワークフロー (windows-latest) で
+> ビルドして Releases に発行しています。バージョンは builder の `XBOX_V8_VERSION` に固定。
+
+### 自前ビルドする場合 (任意)
+
+コンソール実機向け (GDK ツールチェーン) や V8 バージョンを変えたい場合のみ。
+**マシンごとに 1 回だけ**の作業で、以後は `--v8-root` で使い回せます。
+
+事前準備 (V8 ビルド用):
+
+| 項目 | 内容 |
+|------|------|
+| ディスク | 約 40GB (ソース + ビルド生成物) |
+| 時間 | 初回 fetch 30〜60 分 + ビルド 1〜3 時間 |
+| Git | インストール済みであること |
+| depot_tools | [取得手順](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up)に従い展開し、**PATH の先頭**に追加 |
+| 環境変数 | `DEPOT_TOOLS_WIN_TOOLCHAIN=0` (Google 社内ツールチェーンを使わない指定。未設定だと fetch が失敗する) |
+| Windows SDK | Visual Studio Installer で「Windows 11 SDK」と「Windows 用デバッグツール」を含めること (GN が要求する) |
+
+ビルド手順:
 
 ```bat
-:: depot_tools 導入後
+set DEPOT_TOOLS_WIN_TOOLCHAIN=0
 fetch v8
 cd v8
-gn gen out\x64.release --args="v8_monolithic=true v8_use_external_startup_data=false is_component_build=false target_cpu=\"x64\" is_debug=false v8_enable_pointer_compression=true v8_enable_sandbox=true"
+:: CI のコンパイル検証と同じバージョンに固定 (xbox-host-ci.yml の V8_TAG)
+git checkout 13.6.233.17
+gclient sync
+gn gen out\x64.release --args="v8_monolithic=true v8_use_external_startup_data=false is_component_build=false use_custom_libcxx=false icu_use_data_file=false treat_warnings_as_errors=false v8_jitless=true v8_enable_turbofan=false v8_enable_webassembly=false target_cpu=\"x64\" is_debug=false v8_enable_pointer_compression=true v8_enable_sandbox=false"
 ninja -C out\x64.release v8_monolith
 ```
 
 生成物を次の構成で配置し、builder の `--v8-root` 引数 (または環境変数 `V8_ROOT`) で指すこと:
 
 ```
-<V8_ROOT>/include/v8.h ...
-<V8_ROOT>/lib/v8_monolith.lib
+<V8_ROOT>/include/v8.h ...      (v8/include を丸ごとコピー)
+<V8_ROOT>/lib/v8_monolith.lib   (v8/out/x64.release/obj/v8_monolith.lib)
 ```
 
-> V8 のビルドフラグ(pointer compression / sandbox)は `CMakeLists.txt` の
-> `V8_COMPRESS_POINTERS` / `V8_ENABLE_SANDBOX` と一致させてください。不一致は ABI 崩れの原因になります。
+> - `use_custom_libcxx=false` は必須。V8 は clang でビルドされるため、これを外すと
+>   V8 同梱の libc++ が使われ、MSVC (MS STL) でビルドする本ホストとリンクできません。
+> - `v8_enable_sandbox=false` は必須。sandbox は libc++ ハードニング(=V8 同梱 libc++)を
+>   要求するため `use_custom_libcxx=false` と両立しません (BUILD.gn の assert で停止)。
+>   本ホストは自明に信頼済みのゲーム JS のみ実行するため無効で問題ありません。
+> - `icu_use_data_file=false` を推奨。外すと実行時に `icudtl.dat` の同梱が必要になります。
+> - `treat_warnings_as_errors=false` を推奨。`use_custom_libcxx=false` では MSVC STL の
+>   ヘッダ警告が -Werror で停止することがあります。**VS のバージョンは VS2022 (v143) を推奨**
+>   (新しすぎる STL は V8 の clang が警告/エラーを出しやすい)。
+> - `v8_jitless=true` + `v8_enable_turbofan=false` + `v8_enable_webassembly=false` を推奨。
+>   ホストは実行時 `--jitless` で動かすため (Xbox は JIT 禁止)、JIT/wasm をビルドから
+>   外すのが正しい構成です (BUILD.gn の assert もこの組み合わせを要求)。ビルドも大幅に速くなります。
+> - pointer compression は `CMakeLists.txt` の `V8_COMPRESS_POINTERS` と一致させてください
+>   (sandbox 無効に合わせ `V8_ENABLE_SANDBOX` は定義しません)。不一致は ABI 崩れの原因になります。
+> - 上記は PC (`Gaming.Desktop.x64`) 用。コンソール実機 (`Gaming.Xbox.*`) 向けは
+>   GDK ツールチェーンでの再ビルドが必要です (devkit 入手後の作業)。
 
 ---
 
@@ -110,7 +157,13 @@ ninja -C out\x64.release v8_monolith
 builder 経由(推奨):
 
 ```bat
-:: プロジェクトルートで。V8 は --v8-root で指定する (環境変数 V8_ROOT でも可)
+:: プロジェクトルートで。V8 は初回に自動ダウンロードされる (指定不要)
+npx @next2d/builder --platform xbox --env prd
+```
+
+自前の V8 を使う場合のみ `--v8-root` を指定:
+
+```bat
 npx @next2d/builder --platform xbox --env prd --v8-root C:\path\to\v8
 ```
 

package/templates/xbox/cmake/FindV8.cmake

@@ -10,10 +10,16 @@
 #            v8_monolithic=true
 #            v8_use_external_startup_data=false
 #            is_component_build=false
+#            use_custom_libcxx=false
+#            icu_use_data_file=false
+#            treat_warnings_as_errors=false
+#            v8_jitless=true
+#            v8_enable_turbofan=false
+#            v8_enable_webassembly=false
 #            target_cpu="x64"
 #            is_debug=false
 #            v8_enable_pointer_compression=true
-#            v8_enable_sandbox=true'
+#            v8_enable_sandbox=false'
 #        ninja -C out/x64.release v8_monolith
 #
 #   2. 配布物 (v8_monolith.lib + include/) を取得

package/templates/xbox/src/v8/V8Runtime.cpp

@@ -44,8 +44,9 @@ void V8Runtime::InitializeProcess(const char* exec_path)
 {
     // Xbox(GDK) / Nintendo Switch のリテール環境は動的コード生成(JIT)を禁止する。
     // V8 を jitless (Ignition インタプリタのみ・TurboFan/Sparkplug/RWXページ無し) で動かす。
-    // WebAssembly も JIT を要するため無効化する。
-    v8::V8::SetFlagsFromString("--jitless --no-expose-wasm --no-opt");
+    // prebuilt V8 (build-v8.yml) は v8_jitless=true + turbofan/wasm 無効でビルドされる。
+    // wasm/opt 系フラグはそのビルドに存在しないため渡さない (未知フラグ警告を避ける)。
+    v8::V8::SetFlagsFromString("--jitless");
 
     v8::V8::InitializeICUDefaultLocation(exec_path);
     v8::V8::InitializeExternalStartupData(exec_path);

package/templates/xbox/tests/check_local.sh

@@ -49,7 +49,7 @@ FILES=(
 )
 for f in "${FILES[@]}"; do
     c++ -fsyntax-only -std=c++20 -Isrc -isystem "${V8INC}" \
-        -DV8_COMPRESS_POINTERS -DV8_ENABLE_SANDBOX "$f"
+        -DV8_COMPRESS_POINTERS "$f"
     echo "OK   $f"
 done