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.
Case Study: mlpack
In this case, we’ll opt to use the mlpack
formula in homebrew/science
.
In short, the objective of mlpack
is to be:
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
The main git
repo is hosted by GitHub, so one will also need to setup an account there. Once there, fork the repository:
- Fork
homebrew/science
(mlpack is found here) - Fork
homebrew/core
From there, let’s add a remote and create a branch to hold the experiment.
cd $(brew --repo homebrew/science) # cd $(brew --repo homebrew/core) # if in core
# GH_USERNAME is your github username
git remote add <GH_USERNAME> https://github.com/<GH_USERNAME>/homebrew-science.git # homebrew-core # if core
git checkout master # Checkout master branch
brew update # Update brew
brew update # Twice.
brew upgrade # Then upgrade brew
git checkout -b <BRANCH_NAME> origin/master # Create a branch to house contribution
Update brew
Before continuing, make sure to update homebrew twice and then upgrade:
brew update
brew update
brew 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.
brew audit --strict --online <FORMULA>
Make a note of any errors that come to light.
Access the formula
To edit a brew formula use:
brew edit <FORMULA>
This will open the formula in your preferred editor. By default, brew
will
use vim
.
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
both the sha256
and revision
(if it exists). We will have to add the sha256
back in later.
Original:
url "http://www.mlpack.org/files/mlpack-2.0.1.tar.gz"
sha256 "87305f7003e060d3c93d60ce1365c4ec0fa7e827c356e857be316b0e54114f22"
revision 3
New:
url "http://www.mlpack.org/files/mlpack-2.1.1.tar.gz"
Save and close the formula. Under vim
this is done by pressing Esc
+ :wq
Two ways to find the sha256
hash of the file. The first way uses brew
’s built
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
brew fetch <FORMULA> --build-from-source
Output:
==> Fetching mlpack from homebrew/science
==> Downloading http://www.mlpack.org/files/mlpack-2.1.1.tar.gz
######################################################################## 100.0%
Downloaded to: /Users/agentxyz/Library/Caches/Homebrew/mlpack-2.1.1.tar.gz
SHA256: c2249bbab5686bb8658300ebcf814b81ac7b8050a10f1a517ba5530c58dbac31
Warning: Cannot verify integrity of mlpack-2.1.1.tar.gz
A checksum was not provided for this resource
For your reference the SHA256 is: c2249bbab5686bb8658300ebcf814b81ac7b8050a10f1a517ba5530c58dbac31
Highlight and copy the SHA256 string, e.g. c2249bbab5686bb8658300ebcf814b81ac7b8050a10f1a517ba5530c58dbac31
Option 2: Extracting hash from downloaded file
Or, if you have previously downloaded the source, use:
shasum -a 256 <path/to/download/source>
e.g.
shasum -a 256 ~/Downloads/mlpack-2.1.1.tar.gz
Output
c2249bbab5686bb8658300ebcf814b81ac7b8050a10f1a517ba5530c58dbac31 ~/Downloads/mlpack-2.1.1.tar.gz
Highlight and copy the SHA256 string, e.g. the string on the left c2249bbab5686bb8658300ebcf814b81ac7b8050a10f1a517ba5530c58dbac31
.
Combine
Open up the formula again and include the sha256
hash for the new version.
url "http://www.mlpack.org/files/mlpack-2.1.1.tar.gz"
sha256 "c2249bbab5686bb8658300ebcf814b81ac7b8050a10f1a517ba5530c58dbac31"
Note on revision
Now, only add revision
back if you did not change the software version.
The 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:
# Add new options
option "with-toad", "Enable toad" # Opt-in build with, default is to build without.
option "without-mope", "Disable mope" # Opt-in build without, default is to build with.
# Remove options
deprecated_option "with-check" => "with-test" # Redirect old option
option "with-test", "Run build-time tests" # Must supply new option
# Use of options
if build.with? "ham" # No "with-" necessary
# Do something if option was set
end
if build.without? "ham" # No "without-" needed
# Do something if option was set
end
Specifying other formulae as dependencies
# New software requirements
depends_on "pkg-config" => :run # Permenantly available
depends_on "pkg-config" => :build # Available only during build not availabled if formula is installed by bottle!
depends_on "pkg-config" => :recommended # Enabled by default, user can disable with --without-pkg-config
depends_on "pkg-config" => :optional # Automatically generates --with-pkg-config option
Build the formula
Begin the process of installing the new version of the formula.
brew install --verbose --debug <FORMULA>
- The
--verbose
flag gives you a copious amount of information regarding what is happening behind the scenes. - The
--debug
flag provides the ability to open a shell to debug where the error occurred.
There is one of flag that may be useful, --build-from-source
, however
by default when a new sha256
hash is present this should automatically be
triggered.
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:
brew test <FORMULA>
Re-run audit
Re-run the strict audit with the new version information.
brew audit --strict --online <FORMULA>
It is very important that all is well. If a new issue arise, go back into the formula and try to correct it.
Commit change
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 git
.
git add <FORMULA>.rb # Formula/<FORMULA>.rb # if in core
git commit # Commit changes...
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
Push
Next, push the local changes to the fork:
git push --set-upstream <GH_USERNAME> <BRANCH_NAME>
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.
git checkout -f master
git reset --hard origin/master
Fin
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.