wehub-resource-sync
200 lines
5.0 KiB
Markdown
200 lines
5.0 KiB
Markdown
# Web Engines, Packaging, and Debugging
|
|
|
|
Use this when choosing system WebView vs Chromium, installing CEF, packaging, signing, running doctor, finding logs, or debugging runtime behavior.
|
|
|
|
## Web engine choice
|
|
|
|
Default:
|
|
|
|
```zig
|
|
.web_engine = "system",
|
|
```
|
|
|
|
System mode:
|
|
|
|
- Uses the OS web engine.
|
|
- macOS: WKWebView.
|
|
- Linux: WebKitGTK.
|
|
- Smallest app footprint.
|
|
- Fastest startup.
|
|
- Rendering depends on the user's OS.
|
|
|
|
Chromium mode:
|
|
|
|
```zig
|
|
.web_engine = "chromium",
|
|
.cef = .{ .dir = "third_party/cef/macos", .auto_install = false },
|
|
```
|
|
|
|
Chromium mode:
|
|
|
|
- Bundles CEF.
|
|
- Gives predictable Chromium behavior.
|
|
- Increases package size and startup cost.
|
|
- Requires matching CEF layout at build and package time.
|
|
|
|
Use Chromium when the product needs a pinned web platform, complex frontend rendering consistency, or Chromium-only behavior. Otherwise prefer `system`.
|
|
|
|
## CEF setup
|
|
|
|
Install the prepared runtime:
|
|
|
|
```bash
|
|
native cef install
|
|
native doctor --manifest app.zon
|
|
```
|
|
|
|
Pin CEF in app setup or CI when reproducibility matters:
|
|
|
|
```bash
|
|
native cef install --version <version>
|
|
```
|
|
|
|
Useful overrides:
|
|
|
|
```bash
|
|
zig build run -Dweb-engine=chromium -Dcef-dir=third_party/cef/macos
|
|
zig build run -Dweb-engine=chromium -Dcef-auto-install=true
|
|
native package --web-engine chromium --cef-dir third_party/cef/macos
|
|
```
|
|
|
|
Normal product configuration should live in `app.zon`; CLI/build flags are for temporary overrides.
|
|
|
|
## Packaging
|
|
|
|
Simple path:
|
|
|
|
```bash
|
|
zig build package
|
|
```
|
|
|
|
CLI path:
|
|
|
|
```bash
|
|
native package --target macos --manifest app.zon --binary zig-out/bin/MyApp
|
|
```
|
|
|
|
Important package manifest fields:
|
|
|
|
- `id`: bundle ID, desktop ID, log/state prefix.
|
|
- `display_name`: app/menu/window title fallback.
|
|
- `version`: package metadata.
|
|
- `icons`: copied into package resources.
|
|
- `platforms`: intended package targets.
|
|
- `frontend`: asset directory and entry file.
|
|
- `web_engine` and `cef`: engine and Chromium runtime config.
|
|
|
|
For frontend apps, package the built frontend assets. The build step usually wires this automatically. If using CLI directly, pass `--assets frontend/dist`.
|
|
|
|
## macOS packages
|
|
|
|
`zig build package` creates a `.app` bundle with:
|
|
|
|
- `Contents/MacOS/<binary>`
|
|
- `Contents/Resources/AppIcon.icns` (generated from the square `assets/icon.png`/`.svg` source in `.icons`; a prebuilt `.icns` ships untouched under its own name)
|
|
- `Contents/Info.plist`
|
|
- `Contents/Resources/dist/` when frontend assets are configured
|
|
- `Contents/Frameworks/Chromium Embedded Framework.framework` for Chromium apps
|
|
|
|
macOS minimum system version is 11.0.
|
|
|
|
Signing modes:
|
|
|
|
```bash
|
|
native package --target macos --signing none
|
|
native package --target macos --signing adhoc
|
|
native package --target macos --signing identity --identity "Developer ID Application: Your Name"
|
|
```
|
|
|
|
For Chromium apps, verify the CEF framework and resources are included and signed before notarization.
|
|
|
|
## Linux and Windows packages
|
|
|
|
Linux creates an install tree with:
|
|
|
|
- `bin/<name>`
|
|
- `share/applications/<name>.desktop`
|
|
- icons under `share/icons/hicolor/...`
|
|
|
|
Windows packaging is early support and creates a directory-based distributable layout.
|
|
|
|
Shortcut commands:
|
|
|
|
```bash
|
|
native package-linux --binary zig-out/bin/MyApp
|
|
native package-windows --binary zig-out/bin/MyApp.exe
|
|
```
|
|
|
|
## Doctor and validation
|
|
|
|
Validate manifest schema:
|
|
|
|
```bash
|
|
native validate app.zon
|
|
```
|
|
|
|
Check environment and package readiness:
|
|
|
|
```bash
|
|
native doctor
|
|
native doctor --manifest app.zon --strict
|
|
native doctor --manifest app.zon --web-engine chromium --cef-dir third_party/cef/macos
|
|
```
|
|
|
|
Doctor checks:
|
|
|
|
- host platform
|
|
- WebView availability
|
|
- manifest validity
|
|
- log directory writability
|
|
- CEF layout when Chromium is selected
|
|
- signing tools
|
|
|
|
Use `--strict` in CI or before release so warnings fail the command.
|
|
|
|
## Debugging
|
|
|
|
Trace modes:
|
|
|
|
- `off`
|
|
- `events`
|
|
- `runtime`
|
|
- `all`
|
|
|
|
Build/run flags commonly include:
|
|
|
|
```bash
|
|
zig build run -Dtrace=all
|
|
zig build run-webview -Ddebug-overlay=true
|
|
```
|
|
|
|
Log defaults:
|
|
|
|
- macOS: `~/Library/Logs/<bundle-id>/native-sdk.jsonl`
|
|
- Linux: `~/.local/state/<bundle-id>/logs/native-sdk.jsonl`
|
|
- Windows: `%LOCALAPPDATA%\<bundle-id>\Logs\native-sdk.jsonl`
|
|
|
|
Environment variables:
|
|
|
|
```bash
|
|
NATIVE_SDK_LOG_DIR=/tmp/my-logs zig build run
|
|
NATIVE_SDK_LOG_FORMAT=text zig build run
|
|
```
|
|
|
|
Panic capture:
|
|
|
|
```zig
|
|
pub const panic = std.debug.FullPanic(native_sdk.debug.capturePanic);
|
|
```
|
|
|
|
Generated runners usually install panic capture so crashes write `last-panic.txt` and append a fatal trace record.
|
|
|
|
## Common failures
|
|
|
|
- App window opens blank: check `WebViewSource`, `frontend.dist`, `frontend.entry`, and allowed origins.
|
|
- Dev server never loads: check `app.zon frontend.dev.url`, command, readiness path, and `NATIVE_SDK_FRONTEND_URL`.
|
|
- Bridge call rejects with `permission_denied`: check command origin and permissions in policy.
|
|
- Bridge call rejects with `unknown_command`: handler was not registered or command name differs.
|
|
- Chromium app fails at launch: check CEF layout, version mismatch, bundle Frameworks layout, and signing.
|
|
- Package misses frontend: check `frontend.dist`, frontend build step, and `--assets`.
|