diff --git a/docs/en/setup/build.md b/docs/en/setup/build.md index 9db1858..bf63b07 100644 --- a/docs/en/setup/build.md +++ b/docs/en/setup/build.md @@ -127,6 +127,162 @@ These scripts do **not** fetch or build `libssruntime`, so [1. Prepare libssrunt > No batch release script is provided for the Linux custom module. Invoke `./scripts/build.sh platform=linux target=...` directly for each of `editor` / `template_debug` / `template_release`. +## Debugging the Custom Module + +If you want to debug the C++ code (`ss_player/`) of the plugin embedded as a custom module, follow these steps: + +1. **Verify the Debug Binary** + Godot binaries built with `target=editor` or `target=template_debug` contain debug symbols by default. + * **macOS:** `godot/Godot.app/Contents/MacOS/Godot` + * **Windows:** `godot/bin/godot.windows.editor.x86_64.exe` etc. + * **Linux:** `godot/bin/godot.linuxbsd.editor.x86_64` etc. + +2. **Attach Debugger and Launch Arguments** + Specify the above binary as the launch program in your debugger (e.g., VSCode, Visual Studio, Xcode, LLDB/GDB). + By passing the path to the target project as an argument (e.g., `--path examples/dev_module`), you can open the project directly without the project manager screen and start debugging. + +**VSCode (`launch.json`) Example (macOS / LLDB):** + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Debug Godot Custom Module", + "type": "lldb", + "request": "launch", + "program": "${workspaceFolder}/godot/Godot.app/Contents/MacOS/Godot", + "args": [ + "--path", + "${workspaceFolder}/examples/dev_module" + ], + "cwd": "${workspaceFolder}" + } + ] +} +``` + +## Export Testing and Debugging + +To verify and debug whether the custom module or GDExtension works correctly in the exported application, using the headless export from the CLI is convenient. + +The following is the flow for building/installing templates and exporting a sample project. (The example below uses macOS) + +1. **Build the runtime and templates** + Prepare `libssruntime` beforehand, then run the release script for the target platform. + ```bash + # Prepare the runtime in release build (if necessary) + ./scripts/build-runtime.sh build=release platform=macos + + # Build the export templates + ./scripts/release-macos.sh + ``` + +2. **Install templates** + Install the built templates into the local directory recognized by Godot. + **macOS / Linux:** + ```bash + ./scripts/install-template.sh macos + ``` + **Windows (PowerShell):** + ```powershell + .\scripts\install-template.ps1 windows + ``` + +3. **Run export from CLI** + Use the built Godot editor (in headless mode) to invoke the export process directly from the command line. + **macOS / Linux:** + ```bash + # Example: Export the dev_module project for macOS (outputs directly as .app) + ./godot/Godot.app/Contents/MacOS/Godot --path ./examples/dev_module/ --headless --export-debug "macOS" output.app + ``` + **Windows (PowerShell):** + ```powershell + .\godot\bin\godot.windows.editor.x86_64.exe --path .\examples\dev_module\ --headless --export-debug "Windows Desktop" output.exe + ``` + > **Note:** To run the export, the target project's `export_presets.cfg` must contain the preset for the specified platform name (e.g., `"macOS"`), and required identifiers (such as Bundle ID) must be properly configured. + +### Web Platform Export and Testing + +Exporting for the Web produces multiple files (e.g., `.html`, `.wasm`, `.pck`), so create a dedicated directory for the export. Additionally, a local server is required to bypass browser security restrictions. + +```bash +# 1. Create an output directory and export for Web +mkdir -p build_web +./godot/Godot.app/Contents/MacOS/Godot --path ./examples/dev_module/ --headless --export-debug "Web" ../../build_web/index.html + +# 2. Start a local HTTP server +cd build_web +python3 -m http.server 8000 +``` +After starting the server, access `http://localhost:8000` in your browser to verify it works. +(Since this plugin operates with `nothread` on the Web, it can be launched with a simple HTTP server without requiring special CORS headers.) + +### GDExtension Export and Testing + +For GDExtensions (e.g., `dev_gdextension`), **rebuilding the engine itself or installing custom templates is unnecessary**. You can export as-is using the standard Godot editor and official export templates distributed by Godot. + +1. **Release build of the GDExtension plugin** + Run the build script for the target platform beforehand to output the libraries (e.g., `.so`, `.xcframework`, `.dll`) into the project's `addons/` directory. + **macOS / Linux:** + ```bash + ./scripts/release-gdextension-macos.sh + ``` + **Windows (PowerShell):** + ```powershell + .\scripts\release-gdextension-windows.ps1 + ``` + +2. **Run export from CLI** + Export the project using the official Godot binary (or your own Godot command). + **macOS / Linux:** + ```bash + # * Here, "godot" refers to the official Godot editor executable in your path. + godot --path ./examples/dev_gdextension/ --headless --export-debug "macOS" output.app + ``` + **Windows (PowerShell):** + ```powershell + # * "godot.exe" refers to the official Godot executable. + godot.exe --path .\examples\dev_gdextension\ --headless --export-debug "Windows Desktop" output.exe + ``` + > During export, Godot will automatically bundle the plugin files (`.so`, `.framework`, `.dll`, etc.) into the exported artifacts. + +## Debugging the GDExtension + +You can debug the C++ code for GDExtensions using almost the same steps as a custom module. The only difference is that the launch program is the "official Godot editor". + +1. **Verify the GDExtension debug build** + The normal build scripts (like `build-extension.sh`) use `target=template_debug` by default, so the output libraries (`.dll`, `.dylib`) include debug symbols. + +2. **Attach Debugger and Launch Arguments** + Specify the **official Godot binary** as the launch program in your debugger (e.g., VSCode, Visual Studio), and pass the project path as an argument (`--path examples/dev_gdextension`). The breakpoint will be hit once Godot dynamically loads the plugin at startup. + +**VSCode (`launch.json`) Examples:** + +**macOS / Linux (LLDB):** +```json +{ + "name": "Debug GDExtension (macOS)", + "type": "lldb", + "request": "launch", + "program": "/Applications/Godot.app/Contents/MacOS/Godot", // Path to official binary + "args": [ "--path", "${workspaceFolder}/examples/dev_gdextension" ], + "cwd": "${workspaceFolder}" +} +``` + +**Windows (Visual Studio Debugger):** +```json +{ + "name": "Debug GDExtension (Windows)", + "type": "cppvsdbg", + "request": "launch", + "program": "C:\\path\\to\\Godot_v4.x-stable_win64.exe", // Path to official binary + "args": [ "--path", "${workspaceFolder}\\examples\\dev_gdextension" ], + "cwd": "${workspaceFolder}" +} +``` + ## For SpriteStudio-SDK Developers > The sections below are required **only when developing/customizing SpriteStudio-SDK itself in parallel with the Godot side**. General Godot builders using the SpriteStudio-SDK release artifacts can skip them. diff --git a/docs/ja/setup/build.md b/docs/ja/setup/build.md index 109db4c..37fd3e8 100644 --- a/docs/ja/setup/build.md +++ b/docs/ja/setup/build.md @@ -213,6 +213,71 @@ python3 -m http.server 8000 サーバー起動後、ブラウザで `http://localhost:8000` にアクセスすると動作確認ができます。 （本プラグインは Web においては `nothread` での動作となるため、特殊なCORSヘッダーなしの単純なHTTPサーバーで起動可能です） +### GDExtension のエクスポートと動作確認 + +GDExtension（例: `dev_gdextension`）の場合、**エンジン本体の再ビルドやカスタムテンプレートのインストールは不要**です。Godot公式が配布している標準のGodotエディタとエクスポートテンプレートを使用して、そのままエクスポートが可能です。 + +1. **GDExtension プラグインのリリースビルド** + 事前に対象プラットフォーム向けのビルドスクリプトを実行し、プロジェクトの `addons/` ディレクトリにライブラリ（`.so`, `.xcframework`, `.dll` 等）を出力しておきます。 + **macOS / Linux:** + ```bash + ./scripts/release-gdextension-macos.sh + ``` + **Windows (PowerShell):** + ```powershell + .\scripts\release-gdextension-windows.ps1 + ``` + +2. **CLIからのエクスポート実行** + 公式のGodotバイナリ（あるいは各自のGodotコマンド）を使って、プロジェクトをエクスポートします。 + **macOS / Linux:** + ```bash + # ※ ここでの "godot" は、パスが通っている公式のGodotエディタ実行ファイル等を指します + godot --path ./examples/dev_gdextension/ --headless --export-debug "macOS" output.app + ``` + **Windows (PowerShell):** + ```powershell + # ※ "godot.exe" は公式のGodot実行ファイル + godot.exe --path .\examples\dev_gdextension\ --headless --export-debug "Windows Desktop" output.exe + ``` + > 実行時に `.so`, `.framework`, `.dll` などのプラグインファイルは Godot が自動的にエクスポート成果物の中に同梱してくれます。 + +## GDExtension のデバッグ方法 + +GDExtension の場合も、カスタムモジュールとほぼ同じ手順でC++コードをデバッグできます。違いは起動するプログラムが「公式のGodotエディタ」になる点のみです。 + +1. **GDExtensionのデバッグビルド確認** + 通常のビルドスクリプト（`build-extension.sh` 等）はデフォルトで `target=template_debug` となっており、出力されるライブラリ（`.dll` や `.dylib`）にはデバッグシンボルが含まれています。 + +2. **デバッガのアタッチと起動引数** + VSCode や Visual Studio 等のデバッガから、**公式のGodotバイナリ** を起動プログラムとして指定し、引数でプロジェクトのパス（`--path examples/dev_gdextension`）を渡します。Godotが起動時にプラグインを動的ロードした時点でブレークポイントにヒットするようになります。 + +**VSCode (`launch.json`) の設定例:** + +**macOS / Linux (LLDBの場合):** +```json +{ + "name": "Debug GDExtension (macOS)", + "type": "lldb", + "request": "launch", + "program": "/Applications/Godot.app/Contents/MacOS/Godot", // 公式バイナリのパス + "args": [ "--path", "${workspaceFolder}/examples/dev_gdextension" ], + "cwd": "${workspaceFolder}" +} +``` + +**Windows (Visual Studio デバッガの場合):** +```json +{ + "name": "Debug GDExtension (Windows)", + "type": "cppvsdbg", + "request": "launch", + "program": "C:\\path\\to\\Godot_v4.x-stable_win64.exe", // 公式バイナリのパス + "args": [ "--path", "${workspaceFolder}\\examples\\dev_gdextension" ], + "cwd": "${workspaceFolder}" +} +``` + ## SpriteStudio-SDK 開発者向け > 以降のセクションは **SpriteStudio-SDK 自体を手元で開発・カスタマイズしながら Godot 側もビルドしたい場合のみ** 必要です。SpriteStudio-SDK のリリース成果物を使う一般的な Godot ビルダーは読み飛ばして構いません。