Installing Pestle via. Homebrew

Last week I woke up and discovered that Fabrizio Balliano had taken my open source project pestle (a command line framework and Magento code generation tool) and created a homebrew package for it, which will make installing the program much easier for MacOS folks who may not know what a PHP .phar file is.

This also provides me with an opportunity to spin out a few articles about software package management systems. Today we’re going to take a quick tour of what homebrew is and how it works.

What is Homebrew

Homebrew is a software repository system originally built to install and distribute open source software on MacOS (then known as OS X). While MacOS is a proper unix, it’s not based on linux. MacOS’s unix systems come from [an Apple project named darwin](https://en.wikipedia.org/wiki/Darwin_(operating_system). Darwin traces its unix roots back to the BSD family of operating systems. This means there’s many subtle differences between MacOS unix and linux unix — especially when you’re compiling and installing software.

Homebrew helps smooth over these differences by collecting compilation/installation recipes for software and offering direct, precompiled binary installation of many popular packages. The project’s been so successful that it has grown beyond its MacOS origins and is available for linux systems as well.

If you didn’t follow that — don’t worry — the point of homebrew is you don’t need to understand where the software comes from, all you need to do is type a simple command

$ brew install package-name

and homebrew will install your software. Managing these packages over time does require getting to know a few more brew commands and learning about the structure of the /usr/local/Cellar folder where homebrew puts things, but of all the systems that let you install open source software on MacOS (MacPorts, fink, etc.), I’ve found brew to be the most stable and consistent for the past decade.

What is a “tap”

Fabrizio’s project has a README.md that says

Install the Tap (repository) with …

Out of the box, if you install homebrew, you have access to the main homebrew software repository. This repository contains a huge list of popular open source software. The default repository is maintained and curated by the homebrew project maintainers. The project maintainers may not work on every recipe, but they decide what gets in, and what stays out.

You are not, however, limited to this default software repository. Anyone can setup their own homebrew repository, and homebrew users can tell their homebrew system to install software from these third party repositories. In homebrew’s terminology, these third party repositories are known as “taps” — t(hird)-p(arty) repositories. We’re not sure where the a went either — Homebrew’s metaphors are based around beer — homebrew as in home brewing. A little silly, but we were all young once.

What Fabrizio has done is setup a third party homebrew repository and written recipes for pestle and both version of n98-magenrun. Instead of a user needing to download these .phar files manually, figuring out where to put them (/usr/local/bin? ~/bin? somewhere else?), and ensuring they can be executed from the command line (permissions? is the previous folder in your unix $PATH?) — Fabrizio and homebrew will take care of this for you.

When you type

$ brew tap fballiano/mageutils

you’re telling the brew command that, in the future, it should also search the fballiano/magutils repository for packages. While it’s beyond the scope of this article, tap repositories are just github repos — the homebrew docs have more information if you’re curious about creating one of your own.

Looking at the pestle Recipe

So what happens when you install pestle via homebrew?

$ brew install pestle

Homebrew will find pestle’s formula in the fballiano/mageutils repository. A homebrew formula is a ruby class that contains all the information homebrew will need to install a software package. The brew program (also written in ruby) will use this class to create an object, and then use the data and methods in this object to install the package.

At the time of this writing, the pestle formula looks like this

class Pestle < Formula
  desc "A collection of command line scripts for Magento 2 code generation, and a PHP module system for organizing command line scripts."
  homepage "https://github.com/astorm/pestle"
  url "https://fabrizioballiano.com/pestle/pestle-1.5.0.phar"
  sha256 "ca4e57ceef400cd5b7a5674f3df3db14cdd79d51ab94e83f834668d23f23b310"

  bottle :unneeded

  def install
    bin.install "pestle-1.5.0.phar" => "pestle"
  end

  test do
    system "#{bin}/pestle", "list"
  end
end

This is a relatively simple formula. While I’m far from a ruby or homebrew expert, I believe the url property tells homebrew is should download the configured file (https://fabrizioballiano.com/pestle/pestle-1.5.0.phar) and validate it using the listed sha256 hash. If you’ve never validated something use a sha hash, all that means is running the following command

$ openssl sha -sha256 pestle.phar

and then confirming that the returned string is the same as the one configured (ca4e57ceef400cd5b7a5674f3df3db14cdd79d51ab94e83f834668d23f23b310). Hashing functions allow you to take any computer file and reduce it down to a unique string. (Or, for the math nerds who are screaming, hashing functions let you take any large number and reduce it down to a smaller number that is near certain to be unique).

Hash validation lets you know you’re getting the file you expect — if a malicious-hacker wanted to replace the .phar file with another, that other file would have a different hash string and it would fail the validation check. Hackers would need to replace both the .phar, and the hash in the recipe in order to execute an attack.

The install method is where the main work of installing a homebrew package happens. In pestle‘s case this is relatively simple —

  def install
    bin.install "pestle-1.5.0.phar" => "pestle"
  end

The install method uses homebrew’s bin.install convenience tool to place the downloaded .phar file into the package’s bin directory — i.e. after installing this package you’ll find a file named pestle at

/usr/local/Cellar/pestle/1.5.0/bin/pestle

As things go, this is a relatively straightforward formula. If you’re interested in learning more, homebrew’s docs on formulas are a good place to start if you get stuck reading through a recipie’s formula. If you want to see what a more complicated formula for a compiled software package looks like, the formula for installing PHP is an interesting read.

What am I Installing?

There’s one thing to cover in this recipe. Let’s take another look at the formula URL

  url "https://fabrizioballiano.com/pestle/pestle-1.5.0.phar"

We can see that it downloads pestle from Fabrizio’s website, and not pestle’s official distribution URL

http://pestle.pulsestorm.net/pestle.phar

There’s nothing unreasonable about this — a recipe maintainer might want to make sure the .phar is downloaded from a source they know will be there in the future, or one that had versioned URLs (which is the case with Fabrizio), or perhaps they want to make sure it’s downloaded from an HTTPS URL (which I have mixed feelings about for non-sensitive content, and don’t provide for pestle).

While this is reasonable, it does mean that when you instal pestle via homebrew, you’re extending your circle of trust to the homebrew authors, and the formula maintainer. Even before Fabrizio did me the kindness of packaging up some open source software I wrote I’ve been thinking about this, and other social costs of software package repositories and that, schedule willing, is what we’ll talk about next time.