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.
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
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,
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.
url "http://www.mlpack.org/files/mlpack-2.0.1.tar.gz" sha256 "87305f7003e060d3c93d60ce1365c4ec0fa7e827c356e857be316b0e54114f22" revision 3
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
brew fetch <FORMULA> --build-from-source
==> 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.
Option 2: Extracting hash from downloaded file
Or, if you have previously downloaded the source, use:
shasum -a 256 <path/to/download/source>
shasum -a 256 ~/Downloads/mlpack-2.1.1.tar.gz
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.
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.
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
# 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>
--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:
brew test <FORMULA>
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.
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 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
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
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.