Skip to content

[halidoscope] Add pip packaging via maturin - #9413

Open
alexreinking wants to merge 2 commits into
parkerziegler/halidoscopefrom
alexreinking/halidoscope-pip-packaging
Open

[halidoscope] Add pip packaging via maturin#9413
alexreinking wants to merge 2 commits into
parkerziegler/halidoscopefrom
alexreinking/halidoscope-pip-packaging

Conversation

@alexreinking

@alexreinking alexreinking commented Sep 1, 2026

Copy link
Copy Markdown
Member

Adds pip packaging for Halidoscope, stacked on #9356.

Packages the compiled Tauri binary (GUI + CLI) as a platform wheel using maturin's bin bindings, so pip install halidoscope puts the halidoscope executable on PATH.

The one non-obvious part: a plain cargo build --release (or maturin build without extra config) compiles fine, but the resulting binary always falls back to loading its UI from Tauri's dev server instead of embedding dist/, silently shipping a broken GUI. Enabling the tauri/custom-protocol Cargo feature (set in pyproject.toml) fixes this -- confirmed empirically by grepping the built binary for the compiled JS bundle's hash before/after.

Verified locally end-to-end: pnpm build -> maturin build --release -> fresh venv -> pip install the wheel -> halidoscope --version/--help both work, and the installed binary now contains the embedded frontend assets.

Halidoscope's version is kept in lockstep with Halide's release version via tbump (matching halide/halide-bin/halide-runtime), but it has no dependency on those packages -- it's a standalone companion tool.

Adds .github/workflows/pip-halidoscope.yml: builds and smoke-tests wheels on all four platforms, decoupled from pip.yml's existing publish job. This workflow is unverified in CI (can't run GitHub Actions locally) and deliberately does not wire into the nightly publish pipeline yet -- that's a follow-up once a real run has been checked.

Also relabels a handful of pre-existing usage examples in tools/halidoscope/README.md from bash to text code fences: they use <placeholder> notation that mdformat-shfmt was silently mis-parsing as shell redirection syntax and corrupting (confirmed directly with shfmt). No content changed, just the fence language.

Breaking changes

None.

Checklist

  • Tests added or updated (not required for docs, CI config, or typo fixes)
  • Documentation updated (if public API changed)
  • Python bindings updated (if public API changed)
  • Benchmarks are included here if the change is intended to affect performance.
  • Commits include AI attribution where applicable (see Code of Conduct)

@codecov

codecov Bot commented Sep 1, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (parkerziegler/halidoscope@8e4ba63). Learn more about missing BASE report.

Additional details and impacted files
@@                     Coverage Diff                      @@
##             parkerziegler/halidoscope    #9413   +/-   ##
============================================================
  Coverage                             ?   70.09%           
============================================================
  Files                                ?      261           
  Lines                                ?    79579           
  Branches                             ?    19399           
============================================================
  Hits                                 ?    55781           
  Misses                               ?    17895           
  Partials                             ?     5903           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@alexreinking

Copy link
Copy Markdown
Member Author

Follow-up worth tracking separately from this packaging PR: on Linux, halidoscope currently initializes tao's GTK-backed event loop unconditionally inside tauri::Builder::default().run(...) (src-tauri/src/lib.rs), and CLI subcommand dispatch happens inside the .setup() closure, which only runs after that event loop is constructed. That means on a headless Linux host (no X11/Wayland display -- e.g., a CI runner or container), every invocation panics with Failed to initialize GTK backend!, not just the interactive GUI. CI on this PR caught it directly: the manylinux_x86_64 job's smoke test failed running halidoscope --version with exactly that panic (worked around here with xvfb-run, see the workflow).

This undercuts the "non-interactive CLI" pitch for list/stats/dot/snapshot on Linux -- anyone wanting to run those in a headless pipeline needs a virtual display too. The real fix is parsing CLI args (via clap directly, ahead of constructing the tauri::Builder) before ever touching the windowing toolkit, so CLI-only invocations skip GTK entirely. That's a change to src-tauri/src/lib.rs's control flow in #9356, not something packaging can paper over, so I'm flagging it here rather than folding it into this PR.

alexreinking and others added 2 commits September 3, 2026 12:57
Packages the Tauri binary (GUI + CLI) as a platform wheel using maturin's
bin bindings, so `pip install halidoscope` puts it on PATH. The compiled
binary only embeds dist/ instead of falling back to Tauri's dev server
when built with the tauri/custom-protocol Cargo feature, which plain
`cargo build`/`maturin build` don't enable by default -- pyproject.toml
sets it explicitly.

Halidoscope's version is kept in lockstep with Halide's release version
via tbump, matching the other Python packages, but it has no dependency
on them: it's a standalone companion tool.

Adds a CI workflow that builds and smoke-tests wheels for all four
platforms; wiring it into pip.yml's nightly publish job is left for a
follow-up once this build has been verified in CI.

Also relabels a handful of pre-existing usage examples in README.md from
bash to text fences: they use <placeholder> notation that mdformat-shfmt
was silently mis-parsing as shell redirection syntax and corrupting.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
CI caught a real issue: tauri::Builder::run() initializes tao's
GTK-backed event loop before lib.rs's setup() closure ever dispatches to
a CLI subcommand, so on Linux even `halidoscope --version` panics with
no display attached ("Failed to initialize GTK backend"). This is true
of the compiled binary generally, not something packaging can paper
over -- it also means the README's claim that the CLI "works anywhere
the wheel installs" was wrong for headless Linux.

Runs the Linux smoke-test step under Xvfb (apt-installed alongside the
other Tauri system deps) and rewords the README to describe the actual
behavior instead of asserting the opposite. Unverified locally -- can't
reproduce the Linux GTK path on macOS -- so this is best-effort based on
reading the CI failure and the tao/tauri source.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@alexreinking
alexreinking force-pushed the alexreinking/halidoscope-pip-packaging branch from 612b2ab to 539691c Compare September 3, 2026 16:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant