Index of every page on this site: llms.txt
All skills
Run it yourself

Use this skill when building, running, launching, or debugging an engine-first egui application across runtime targets: the native desktop app (eframe/wgpu), headless CLI and batch runner, authenticated JSON TCP control channel and MCP server, offscreen egui visual snapshots, or WebAssembly browser builds (via Trunk or Docker). Also use when configuring GPU backend fallbacks or single-instance locks.

  • 2 files
  • 9.1 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/domesticmouse/skills/egui-app-runner

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesruntime-flags-and-debugging.md

≈909 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Runtime Flags, Environment Variables & Debugging Reference

1. Recommended CLI Flags (Desktop eframe Binary)

Flag Purpose
<files>... Open files on startup (forwards to existing instance unless isolated)
--new-instance Bypass single-instance forwarding and open a separate process
--safe-gpu Start with software/fallback adapter for this launch
--control <port> Start the loopback JSON control server on 127.0.0.1:<port>
--control-token-file <path> Read (or generate) the 64-hex bearer token file for --control
--automation-read-root <dir> Directory from which automation/control commands are allowed to read
--automation-write-root <dir> Directory to which automation/control commands are allowed to write
--present-mode <mode> Override swapchain present mode: fifo, autovsync, or novsync (immediate/mailbox)
--frame-latency <1..3> Maximum queued swapchain frames for latency testing
--in-window-menus Force in-window egui menu bar instead of native OS menu bar

2. Environment Variables

Variable Effect
RUST_LOG Controls log verbosity on stderr and log files (e.g., RUST_LOG=debug, RUST_LOG=info,eframe=debug).
WGPU_BACKEND Override wgpu backend (metal, vulkan, dx12, gl).
APP_CONFIG_DIR Override the per-user settings/recovery/log directory (also isolates the single-instance lock).
APP_NEW_INSTANCE=1 Equivalent to --new-instance.
APP_LOCALE=<tag> Override UI language for one launch (e.g., ja, de, fr).
APP_THEME_FILE=tokens.json Debug builds only: live-reload egui design token overrides (theme::Tokens) on save without recompiling.

3. Single-Instance Lock & Forwarding Pattern

  • By default, the first desktop instance can acquire instance.lock and write instance.json in the config directory (or $XDG_RUNTIME_DIR/app/<app-id>/instance.sock on Linux).
  • Subsequent launches without isolation flags pass their file arguments to the running window so they open as new tabs, then exit.
  • When running via cargo run while another instance is open: pass --new-instance or override the config directory so cargo run does not hand off to the existing binary and exit.
  • Launches with --control, --safe-gpu, --present-mode, --frame-latency, --in-window-menus, or --automation-*-root should automatically run as separate instances.

4. GPU Startup Marker & Crash Recovery Pattern

  • Startup marker (gpu-starting.json): Written and locked before creating the wgpu device, then cleared after the first frames render. If a launch crashes inside the graphics driver, the next launch detects the unlocked marker and steps down to the next safer backend:
    • macOS: Metal $\to$ CPU/Fallback
    • Windows: Vulkan $\to$ DX12 $\to$ Fallback
    • Linux: Vulkan $\to$ GL $\to$ Fallback
  • Document crash recovery (RecoveryStore): Unsaved documents can autosave in the background using content-addressed state (crates/format). If the app crashes or loses the GPU device, autosaves are flushed and automatically reopened on the next launch.

5. Log Files & Rotation

Desktop logs can be written both to stderr and to logs/<app>.log inside the OS-appropriate application support/config directory:

  • macOS: ~/Library/Application Support/<App>/logs/<app>.log
  • Linux: ~/.config/<app>/logs/<app>.log
  • Windows: %APPDATA%\<App>\logs\<app>.log

Rotate the previous log on startup (.1.log, .2.log) so crash logs survive a restart.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 606a5d5. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago

README badge

README badge for domesticmouse/skills/egui-app-runner