How we built Ballerina Homebrew Formula
Create Your Own Homebrew Package
For those who haven’t heard about Homebrew; It’s a well-known package manager for the Mac OS users.
With this article, you will learn on how to contribute your own package to the Homebrew system. Thought it’s worthwhile to understand insides-out of the Homebrew before we jump into the hacking. Enlighten yourself !
1. Why We Don’t Get Built-in Package Managers for OSX?
Not sure if it’s only for me, below are the words that came across my mind; when I hear Homebrew for the first time.
If Debian has pre-shipped apt-get, RedHat has rpm, FreeBSD has portsnap, NetBSD has pkgsrc then Why onearth OSX has 3rd party package managers like Homebrew, MacPorts?
Let’s Answer That First! It’s loud and clear. Apple OSX is commercial software and has a tiny interest in investing in package managers but promotes App Stores. On the other hand, package managers are born through the UNIX-like OSs out of the necessity of keeping track of shared dependencies between the packages(or libraries). Well, that’s deep. In the abstract, package managers make the developer’s life a lot easier with a bunch of simplified APIs and managing the dependency hell. The takeaway is that you don’t get a built-in package manager for the Mac OSX.
This is the reason why Homebrew promotes themselves as “The missing package manager for macOS”.
2. The Homebrew Ecosystem
The Homebrew itself, is standing on the shoulders of technologies; Git VCS and Ruby language. Another noticeable catch is that most of the concepts and terms of the Homebrew are based on its literal meaning; homemade-beer. With homebrew terminology, a Package is called a Formula. Thus, hereafter we’ll use the term formulae for the packages.
How Does Homebrew Work?
Spare few seconds to go through the below image. It explains how we get all the formulae into our machine.
The Homebrew installation process starts with the taps. Taps are the repositories that contribute formulae. Every time you run the brew update, it does a git pull. For example; if you try brew install ballerina; first Homebrew will sync its local taps with the git pulls. Then it searches all local taps for the formulae with the name; “ballerina”. if the formula is found; it will execute the code defined in that Ruby file.
Exactly! for instance, below is the ballerina.rb, it is a package definition written in Ruby. These formulae are Ruby files that describe the software they install and contain instructions to install and test it.
Let’s look how `brew install ballerina` works;
- Homebrew fetches the URL (here that’s https://product-dist.ballerina.io/downloads/0.990.2/ballerina-0.990.2.zip) using curl and stores the archive in a cache directory to make sure you don’t download it twice.
- It computes the checksum against the checksum that the formula provides to ensure you have downloaded the correct file(without corruption).
- Verifying ballerina-0.990.2.zip checksum: sha256 (612ecebfb1c68908cb2ec25ed3d4f13ad35a6fb137aea49909fe40992f682642)
- Need java8 before installing ballerina
- Execute other steps in ballerina.rb
3. Writing Your Own Formula
Below steps explains how you can create a Formula from the scratch.
a. Creating Your New Formula
You can always start your formula with brew create <URLOfTheDistribution>. Then enter the name of the formula; Homebrew will open the new formula in the default text editor for you.
What about SHA256? Don’t worry about that. Just fill the rest and issue a brew install. Homebrew will shout the actual and expected one. Now you can change the hash with the expected one using brew edit.
b. Installing Your New Formula
Since you got the <NewFormula>.rb in your local taps; now you can issue brew install <NewFormula>.
c. Debugging Your New Formula
If you encounter any issues in the installation process you can try brew install --debug <NewFormula>. This will open a debugging shell.
d. Sharing Your New Formula
Option 1: Contribute Homebrew-Core
If you think your new formula should be a part of the Homebrew-core; you can submit a Git PR for the Homebrew/homebrew-core repository. You may read Formula Cookbook for all instructions.
# Run audits for following homebrew guidelines
brew audit --strict <NewFormula># Navigate into Homebrew Repository
cd $(brew --repo homebrew/core)# Create a new git branch for your formula so your pull request
# is easy to modify if any changes come up during review.
git checkout -b <new-branch-name> origin/master
git add Formula/<NewFormula>.rb
git commit
Option 2: Create and Maintain Your Own Tap
Another option is to have your own tap repo; just like homebrew-nginx. The downside of having a separate formulae repo is that users first need to add your repo using the command brew tap <username>/<repo>. Read more about maintaining taps here.
Would Like To Read More?
TL; DR — Summary
You can create your own formula with brew create <URL>. Try installing it; brew install <NewFormula>. If it needs to go into the Homebrew/homebrew-core, You can either submit a PR referring Formula Cookbook or have your own git repo (such as username/homebrew-<tapname>) that users can add the tap with brew tap username/<tapname>.
