Tap formulae using Language::Python::Virtualenv: what is still missing to install qmk

[waynehoover]

I have been moving a Homebrew setup over to mise bootstrap, and qmk is the one formula that does not survive the trip. Chasing it end to end turned up four separate gaps rather than one, so this lays out the whole chain in order, with what I actually verified at each step. Two of the four already have PRs up. I would rather have the remaining work judged as a whole than send it one error at a time, because the last two steps interact and there is a real design choice between them.

Everything below was produced by running the two shims directly against the 253 tap formulae installed on this machine (macOS 15, arm64), and cross-checking against Homebrew's own Version.detect where version inference is involved.

The formula

qmk/homebrew-qmk, version 1.1.8. A Python CLI with 15 runtime dependencies, 2 build dependencies, and 22 PyPI resources:

class Qmk < Formula
  include Language::Python::Virtualenv
  ...
  def install
    virtualenv_install_with_resources
  end
end

Step 1: metadata evaluation aborts on line 2

Formula/qmk.rb:2:in '<class:Qmk>': uninitialized constant Qmk::Language (NameError)

include Language::Python::Virtualenv is a constant reference, not a method call, so neither shim's method_missing DSL fallback catches it. Evaluation dies while the class body is still being read, which means the url, version and depends_on lines below the include are never reached. The formula cannot be resolved at all.

Status: PR #13328. Defines brew's Language::* namespace as empty modules in both shims. Verified: qmk and apfel-mcp newly extract, 251 of 253 unchanged, 0 regressions.

Step 2: version inference, one case fixed and one still open

inferred_version in tap_formula_metadata.rb reads the URL basename only. Two distinct failures fall out of that.

The first is goku, whose release asset is goku-arm.zip and carries no version in the filename at all. PR #13327 ports Homebrew's GitHub releases URL parser and, following brew's own VERSION_PARSERS ordering, tries it ahead of the basename pattern. That ordering incidentally fixed 8 more formulae that were silently resolving to strings like 1.10.0-arm64-macos, because the basename pattern swallows the platform suffix.

The second is still open, and it is load-bearing for qmk specifically. hid_bootloader_cli is a direct qmk dependency, and it still fails after both PRs:

could not infer formula version; add an explicit version declaration

Its URL is https://github.com/abcminiuser/lufa/archive/refs/tags/LUFA-210130.tar.gz. Homebrew resolves this to 210130 via its trailing-number stem parser, roughly StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS})$/). mise gets nothing, so the dependency cannot be resolved and qmk is blocked even though qmk's own metadata is now fine.

Here is the full dependency tree as it resolves today with both PRs applied:

dependency	source	status
avrdude, bootloadhid, clang-format, dfu-programmer, dfu-util, hidapi, libusb, make, pillow, python, teensy_loader_cli, rust, pkg-config	homebrew/core	fine, uses the API path
mdloader	qmk tap	resolves, 1.0.7
osx-cross/arm/arm-none-eabi-gcc@8	osx-cross tap	resolves, 8.5.0
osx-cross/avr/avr-gcc@8	osx-cross tap	resolves, 8.5.0
hid_bootloader_cli	qmk tap	blocked, cannot infer version

Step 3: there is no bottle, so it must build from source

This one is deliberate rather than a bug, and I want to flag it rather than assume it should change. From tap.rs:

//! own Ruby shim. The resulting formula deliberately has no bottles: source
//! installation is the portable fallback and avoids duplicating Homebrew's
//! bottle URL construction rules.

The metadata shim discards bottle blocks (def bottle(*) = nil, and the emitted metadata carries "bottle" => {}), so every tap formula takes the source path even when the tap publishes bottles. Both qmk and hid_bootloader_cli do publish them, at ghcr.io/v2/qmk/qmk, including an arm64_sequoia bottle for hid_bootloader_cli.

I understand the reasoning, and duplicating brew's bottle URL rules is genuinely unappealing. It is worth naming the consequence, though: for this particular formula the bottle path would sidestep steps 4 and 5 entirely.

Step 4: virtualenv_install_with_resources is not implemented

After #13328 this now fails cleanly instead of with a NameError, which is the point of that PR, but it still fails:

Error: formula uses `virtualenv_install_with_resources (install-time helper)`, which mise's source-build shim does not support

The encouraging part is how much of the groundwork is already in shim.rb. Resource#stage already fetches, checksum-verifies and unpacks into a target directory, with explicit refusals for resource patches and non-default download strategies. prefix, bin, libexec, buildpath, resources and system all exist on the Formula instance.

So what is actually missing is the venv step itself: create a virtualenv under libexec using the resolved python dependency, pip install the 22 staged resource sdists into it, install the formula's own sdist, and link the resulting entry points into bin. Homebrew's real implementation lives in Library/Homebrew/language/python.rb and is not enormous.

This would benefit every Language::Python::Virtualenv formula in every tap, not just qmk. It is easily the most reusable piece of work on this list.

Step 5: the practical cost once the above lands

Worth stating honestly. Two of qmk's dependencies are arm-none-eabi-gcc@8 and avr-gcc@8. Building two GCC cross-compilers from source is a multi-hour operation, and both taps publish bottles that mise would currently ignore because of step 3. So even with steps 1, 2 and 4 all resolved, mise install brew:qmk/qmk/qmk would be a very long build rather than a quick one.

What I think the remaining work is

1. Port the trailing-number stem parser. Small and self-contained, in the same spirit as fix(brew): infer formula version from the GitHub release tag path #13327. Unblocks hid_bootloader_cli, and therefore qmk's dependency resolution.
2. Implement virtualenv_install_with_resources in shim.rb. Medium sized, highest reuse value, and most of the supporting machinery is already there.
3. Optionally, honor tap bottles. Largest, and a policy question rather than a technical one, given the comment in tap.rs is a deliberate choice. Would make qmk fast rather than merely possible.

There is also a fifth gap I hit in the same sweep but deliberately left out of scope, since it fails the same way as step 1 but needs more than empty modules: download strategy constants. uninitialized constant CurlDownloadStrategy affects acli and ecctl, and a tap doing its own require "download_strategy" fails with a LoadError.

Question

I am happy to implement 1 and 2, and would send them as separate PRs. Before I do, two things worth your call:

• For 2, would you rather the shim implement virtualenv properly, or keep refusing it and treat Python virtualenv formulae as out of scope for source builds?
• Is 3 firmly settled, or is honoring a tap's own bottle do block with an explicit root_url (which is the easy subset, no URL construction rules to duplicate) something you would consider?

Happy to be told that qmk is simply not a formula mise intends to support from source. That is a perfectly reasonable answer, and knowing it would save me sending PRs 1 and 2.