How to Create a Homebrew Formula

Homebrew formula Python tap distribution

3 min read | by Jordi Prats

Homebrew is a popular package manager for macOS (also available for Linux), allowing developers to distribute their software through simple brew install commands. We are going to use a Python project to create a Homebrew formula and distribuite it using a tap.

Creating a Homebrew formula

First we'll have to create a Homebrew formula, which is essentially a Ruby script that tells Homebrew how to install your software. It has the following structure:

class Awstools < Formula
  homepage "https://github.com/jordiprats/awstools"
  url "https://github.com/jordiprats/awstools/archive/refs/tags/1.0.tar.gz"
  sha256 "004d6fafabe0b84a2b147fcffa7eeb6abee896a5186a1c044df1fae44cd1873d"

  def install
    system "python3", "-m", "pip", "install", "-r", "requirements.txt"
    system "mkdir", "-p", "~/awstools"
    system "sh", "./helpers/macinstall.sh", "#{prefix}"
  end

  test do
    system "python3 awstools.py"
  end
end

We'll need to include:

  • homepage: The URL of the project, where users can find more information about the tool.
  • url: The URL of the tarball or zip file containing the source code in a tarball or zip file.
  • sha256: The SHA256 checksum of the tarball or zip file.
  • The install method is where we define the steps to install the software. In this case, we are using python3 to install the requirements and then running a shell script to install the software.
  • The test method is where we define the steps to test the software. The test should return a non-zero exit code if the test fails.

Distributing the formula

In order to distribute the formula, we need to create a tap. A tap is a collection of formulae that can be installed using Homebrew. We can create a tap by creating a new repository on GitHub with the prefix homebrew-. For example, the tap that contains the awstools formula would is called homebrew-awstools.

In the tab repository we can add as many formulae as we want. In this example we have only one formula, awstools.rb, which contains the formula for the awstools software.

Installing the formula

To install the tap we can use the brew tap followed by the URL of the tap repository. Since we are a GitHub repository, we can use the user/repo format. We can even omit the homebrew- prefix in the tap command:

$ brew tap jordiprats/awstools
==> Tapping jordiprats/awstools
Cloning into '/opt/homebrew/Library/Taps/jordiprats/homebrew-awstools'...
remote: Enumerating objects: 24, done.
remote: Counting objects: 100% (24/24), done.
remote: Compressing objects: 100% (22/22), done.
remote: Total 24 (delta 9), reused 0 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (24/24), 17.18 KiB | 977.00 KiB/s, done.
Resolving deltas: 100% (9/9), done.
Tapped 1 formula (15 files, 57.1KB).

Once the tap is installed, we can install the formula using the brew install command:

$ brew install jordiprats/awstools/awstools
==> Downloading https://github.com/jordiprats/awstools/archive/refs/tags/1.0.tar.gz
==> Downloading from https://codeload.github.com/jordiprats/awstools/tar.gz/refs/tags/1.0
######################################################################## 100.0%
==> Installing awstools from jordiprats/awstools
==> python3 -m pip install -r requirements.txt
==> mkdir -p ~/awstools
==> sh ./helpers/macinstall.sh /opt/homebrew/Cellar/awstools/1.0
🍺  /opt/homebrew/Cellar/awstools/1.0: 4 files, 98.4KB, built in 8 seconds
==> Running `brew cleanup awstools`...
Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP.
Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).

Posted on 06/09/2024

Categories