Burrito packaging: track upstream fixes for the known issues in the packaging guide

[ryanwinchester]

As of Burrito 1.6.0, Tuix apps do not work in Burrito binaries out of the box. The packaging guide and the examples/burrito project document the current state and workarounds. This issue tracks the upstream fixes so the docs can be updated (and the caveats removed) as they land.

Upstream issues

• burrito#234 — blocker. The launcher pipes the BEAM's stdout through the wrapper, so the VM never sees a TTY: ANSI detection fails, raw mode returns {:error, :enotsup}, and keyboard input is never delivered. No workaround short of patching Burrito's Zig wrapper.
• burrito#215 — Burrito's precompiled ERTS builds lack tty support, so raw mode fails even with correct stdio. Workaround: custom_erts pointing at a local OTP install root (wired up via BURRITO_CUSTOM_ERTS in the example).
• burrito#229 — the VM is halted by Elixir's CLI right after boot (no --no-halt). Worked around by running Tuix.run/2 synchronously inside Application.start/2; that pattern stays correct even after the upstream fix, so this only affects how strongly the guide has to insist on it.
• burrito#233 — -mode embedded is passed as a single argv string, so Burrito VMs boot in interactive mode. Non-fatal for Tuix: Tuix.Runtime.call_mount/2 now calls Code.ensure_loaded?/1 before function_exported?/3 (previously mount/2 was silently skipped in interactive-mode VMs — this bug was found while debugging the Burrito binary).

When fixes land

• #234 fixed: remove the "does not work out of the box" warnings from the guide's Known upstream issues section and the example README; bump the example's Burrito requirement to the fixed version.
• #215 fixed: drop the custom_erts / BURRITO_CUSTOM_ERTS workaround from the example mix.exs, guide, and example README.
• #229 fixed: soften the entry-point explanation (synchronous start/2 remains the recommended pattern).
• #233 fixed: no doc changes needed; the Code.ensure_loaded?/1 fix in Tuix stays regardless (it is correct for any lazy-loading VM).

Full write-up of the debugging that led to these reports lives in the linked upstream issues (probe tables, minimal repros, and suggested fixes).

[ryanwinchester]

Update: evaluated whether recommending Burrito 1.5 is a viable interim answer.

In favor:

• 1.5 predates both 1.6 regressions: its launcher never ran Elixir's CLI (no #229 halt) and did not pipe the BEAM's stdout (no #234), so 1.5 + the custom_erts workaround for #215 should work for TUI apps.
• Real-world precedent: Expert (the Elixir LSP) downgraded to 1.5 + Zig 0.15 over burrito#229 — expert-lsp/expert#844.

Against (verified locally):

• Burrito 1.5 requires Zig 0.15.2, which cannot link against the macOS 26 SDK. Builds fail with undefined symbols (_sysctlbyname, _waitpid for native aarch64-macos; __availability_version_check, _arc4random_buf, ... for cross-compiles) — any target, including Linux cross-builds, fails on a macOS 26 host. This matches the report in burrito#229.

Conclusion: no unconditional recommendation possible.

• Linux (or pre-26 macOS) build hosts: Burrito 1.5 + Zig 0.15.2 + custom_erts (#215) is the most workable combination today (TUI runtime path not verified by us — verification welcome).
• macOS 26+ build hosts: only 1.6 builds, and TUIs then require patching the wrapper for #234 (plus custom_erts for #215).

The packaging guide and examples/burrito README now include a "What about Burrito 1.5?" section documenting this.

[ryanwinchester]

Fix for burrito#234 submitted upstream: burrito#235 (inherit stdout when it is a TTY; pipe only when redirected). Verified against the examples/burrito smoke test end to end, plus redirected-output and EPIPE regressions.

[ryanwinchester]

Fix for burrito#233 also submitted upstream: burrito#236. Verified in a wrapped probe app: :code.get_mode() returns :embedded and :init.get_argument(:mode) parses (stock 1.6.0: :interactive / :error). Both upstream fixes are now pending: #235 (stdout tty) and #236 (embedded mode).

[ryanwinchester]

Root cause of burrito#215 (precompiled ERTS lacking tty support) has been traced and filed upstream in the build infrastructure: doawoo/beam-machine#6 — the published OTP builds are configured with --without-termcap on all platforms. Until fixed artifacts are republished, the custom_erts workaround remains necessary.