Below are a few notes regarding the best ways that I’ve found regarding how to go about updating homebrew formula. Now, there are many good resources out there including the official formula cookbook, formula documentation, and how to make a homebrew PR. By no means are these notes meant to replace them. Simply put, they provide an abridged approach to updating or tweaking an existing formula since homebrew docs are a bit of a jungle to navigate.
a scalable machine learning library, written in C++, that aims to provide fast, extensible implementations of cutting-edge machine learning algorithms.
Since the formula is housed in a tap instead of the main brew repo, there is a slightly different contributing guide to be aware of.
Fork the repository
From there, let’s add a remote and create a branch to hold the experiment.
Before continuing, make sure to update homebrew twice and then upgrade:
Note: This was done once before in the prior
Check for formula changes
Before modifying the formula, it is highly advisable to see if there are any issues with the present formula. Issues can arise simply because of a style shift or an update to brew internals.
Make a note of any errors that come to light.
Access the formula
To edit a brew formula use:
This will open the formula in your preferred editor. By default,
Updating software links or revision information
The next step involves replacing versioning information. If the aim is
to update the software version, e.g. v1.1 -> v2.0, update the
url and delete
revision (if it exists). We will have to add the
back in later.
Save and close the formula. Under
vim this is done by pressing
Two ways to find the
sha256 hash of the file. The first way uses
in method for obtain the SHA256 hash. The second assumes you already have the
source archive from the above URL.
Option 1: Using brew to extract the sha256 hash
Highlight and copy the SHA256 string, e.g.
Option 2: Extracting hash from downloaded file
Or, if you have previously downloaded the source, use:
Highlight and copy the SHA256 string, e.g. the string on the left
Open up the formula again and include the
sha256 hash for the new version.
Note on revision
Now, only add
revision back if you did not change the software version.
revision flag simply indicates that the formula updated but the software
did not change. Hence, the clients should redownload it.
Fix errors or include new features
If there were any errors that initially came up with formula during the first, now is an ideal time to make the fixes. Alternatively, you could improve the formula by adding in additional options:
Build the formula
Begin the process of installing the new version of the formula.
--verboseflag gives you a copious amount of information regarding what is happening behind the scenes.
--debugflag provides the ability to open a shell to debug where the error occurred.
There is one of flag that may be useful,
by default when a new
sha256 hash is present this should automatically be
Run built-in tests
Many pre-existing formulas have tests. As a result, its often a good idea to see if the tests still function after installing the new formula:
Re-run the strict audit with the new version information.
It is very important that all is well. If a new issue arise, go back into the formula and try to correct it.
Now, the world of brew is ready to be bombarded with the potential contribution.
To contribute, the change must go through version control system (VCS) named
There is a specific formulation of how commit messages must be framed.
In particular, we have the following guidance:
- the first line is a commit summary of 50 characters or less
- two (2) newlines, then
- explain the commit thoroughly
The first lines take the following statues:
- Version upgrades are only titled by version:
- mlpack 2.1.1
- sphynx 0.5.0 (new formula)
- For slight changes, we have:
- foo: add test
- bar: make X11 optional
Next, push the local changes to the fork:
Then, open up a pull request:
Select the appropriate branch from the forked repo to compare to.
Fill out the template and make sure to tick the correct boxes.
Wait for a response. If changes are required, then make the changes. Otherwise, if the PR is closed, learn from the maintainers feedback and try again a later day if it was advised.
Cleanup or I’ve maded a terrible mistake
Once the PR is merged in or if everything has gone down the tube, revert back to the main build.
In short, the above guide pulls out useful factoids from the official documentation. The objective behind this guide is to provide quick reference guide as to how to update homebrew. The guide is not sufficient for developing new formula or making substantial modifications.