Fixing a broken formula

[james-caresnap]

Output of brew config

HOMEBREW_VERSION: 4.3.17-21-g2a5eb02
ORIGIN: https://github.com/Homebrew/brew
HEAD: 2a5eb025f1d36e41667bb22a564ce03cb1eceb48
Last commit: 23 minutes ago
Core tap HEAD: 4b89cd986cfb9988f962cd2ea7fc8dc330f20314
Core tap last commit: 24 minutes ago
Core tap JSON: 19 Aug 15:40 UTC
Core cask tap JSON: 19 Aug 15:40 UTC
HOMEBREW_PREFIX: /opt/homebrew
HOMEBREW_CASK_OPTS: []
HOMEBREW_EDITOR: emacsclient --no-wait
HOMEBREW_GITHUB_API_TOKEN: set
HOMEBREW_MAKE_JOBS: 8
HOMEBREW_SORBET_RUNTIME: set
Homebrew Ruby: 3.3.4 => /opt/homebrew/Library/Homebrew/vendor/portable-ruby/3.3.4_1/bin/ruby
CPU: octa-core 64-bit arm_blizzard_avalanche
Clang: 15.0.0 build 1500
Git: 2.46.0 => /opt/homebrew/bin/git
Curl: 8.7.1 => /usr/bin/curl
macOS: 14.6.1-arm64
CLT: 15.3.0.0.1.1708646388
Xcode: 15.4 => /Applications/Xcode-15.4.0.app/Contents/Developer
Rosetta 2: false

Output of brew doctor

Warning: Some installed formulae are deprecated or disabled.
You should find replacements for the following formulae:
  openssl@1.1
  packer
  terraform

Description of issue

This version bump broke the mailcatcher formula back in June:
Homebrew/homebrew-core#173471

An attempt was made to fix the issue by the maintainer of the mailcatcher project (@sj26), but the pull request wasn't quite finished and was automatically closed:
Homebrew/homebrew-core#174319

I'm interested in helping to get this PR back up and running, and getting this formula fixed.

I'm wondering about the approach being used in this formula. It's building the package from source, but the whole thing could be drastically simplified by just pulling the pre-built gem(s) from rubygems. That should correctly support all platforms, and eliminate the need to download and install all of these build-only dependencies. Is there a philosophical reason why it must be built from source when all of the dependencies are just pulled from rubygems, too?

The meat of the formula could be reduced to:

  resource "mailcatcher" do
    url "https://rubygems.org/downloads/mailcatcher-0.10.0.gem"
    sha256 "f59b6fe184687bdad2b3a4532b79bb331b35830f1d0dccf20750de4663d5030d"
  end
  
  // declare the rest of the gem dependencies

Also, this formula is on the autobump list. I don't quite grok what all is needed for "autobump" to work, but since it looks like homebrew wants all the gem dependencies to be explicitly declared I'm not sure how you autobump without regenerating the formula by walking the new dependency graph. Seems likely that more is needed than just updating the source tar url.

I primarily use homebrew for this package since it installs the gems into a private directory, and it creates a service to start/stop/keepalive the daemon.

[SMillerDev]

I'm interested in helping to get this PR back up and running, and getting this formula fixed.

Looking forward to the pull request

I'm wondering about the approach being used in this formula. It's building the package from source, but the whole thing could be drastically simplified by just pulling the pre-built gem(s) from rubygems. That should correctly support all platforms, and eliminate the need to download and install all of these build-only dependencies. Is there a philosophical reason why it must be built from source when all of the dependencies are just pulled from rubygems, too?

https://docs.brew.sh/Acceptable-Formulae#we-dont-like-binary-formulae

Also, this formula is on the autobump list. I don't quite grok what all is needed for "autobump" to work, but since it looks like homebrew wants all the gem dependencies to be explicitly declared I'm not sure how you autobump without regenerating the formula by walking the new dependency graph. Seems likely that more is needed than just updating the source tar url.

It'll just update the URL, but then someone else can help fix it further.

[james-caresnap]

@SMillerDev thanks, that's very clear and helpful.

The usage of the term 'binary formula' here is a little fuzzy for this project. Many rubygems are interpreted ruby code with bindings to C code. For example, many of the gems enumerated in resource blocks in the current version of the mailcatcher formula (and at least the previous version, too) are gems with ruby bindings to native code. It's likely been this way for the whole of the formula's existence.

If it's deemed that this is actually a binary formula, to bring it into compliance with https://docs.brew.sh/Acceptable-Formulae#we-dont-like-binary-formulae would require quite a large effort, since every dependency with compiled code would have to be converted to a formula as well. This seems kind of silly since rubygems already handles fetching and installing for the entire universe of supported ruby platforms.

It seems like this formula might be better suited to a cask, but I did a quick search through the cask repository and didn't see anything like it in there. This bullet on the Rejected Cask FAQ seems to suggest it might be rejected:

App is both open-source and CLI-only (i.e. it only uses the binary artifact). In that case, and in the spirit of deduplication, submit it first to homebrew/core as a formula that builds from source. If it is rejected, you may then try again as a cask (link to the issue from your pull request so we can see the discussion and reasoning for rejection).

The binary does, in fact, have a UI, but it's a web-based UI. Does that count? The package is almost entirely interacted with through the web-based UI. In spirit, mailcatcher is really an application.

If this is an acceptable candidate for a cask, what's the process for moving the package from core to cask?

[cho-m]

For Ruby-based formulae, our preference is for upstream to use Gemfile.lock - https://docs.brew.sh/Formula-Cookbook#ruby-gem-dependencies

However, if there is no Gemfile.lock, then we need to use resources to keep reproducible behavior with versioned & checksumed downloads. This is similar to use case in Python and Perl formulae, but sadly only Python has an easy way of updating these.

If you want to simplify the formula, then easiest way is to get upstream to upload their Gemfile.lock

---

The gem resources usually would not be classified as binaries. It would have to be something like precompiled native gem, which would include platform in the name, e.g. nokogiri-*-arm64-darwin.gem.

The gem is essentially just an archival format (can be unpacked with tar). As long as it is a source distribution inside the gem, then it is acceptable. If it contains binaries (e.g. in example of nokogiri, then nokogiri.bundle) then it would be unacceptable.

---

From quick glance, I don't think mailcatcher would be accepted as a Cask.

[p-linnane]

As @cho-m stated: if upstream adds a Gemfile.lock, we can use bundler to set everything up. May be worth discussing with the upstream author.