Homebrew

From HerzbubeWiki
Jump to navigation Jump to search

This document contains information about Homebrew, a project that packages software so that it can be built on Mac OS X using the "Developer Tools" (or "Xcode Tools") environment provided by Apple.

Homebrew is an alternative to MacPorts and Fink. I have not tested whether Homebrew can co-exist with its competitors on the same system.

On the new Silicon Macs Homebrew uses the prefix /opt/homebrew to install its stuff, while on Intel Macs it used the prefix /usr/local.


Documentation


Glossary

Homebrew uses a "fun" nomenclature that revolves around beer. Reading the man page for the first time is slightly surreal, and the fun usually goes away when you urgently fumble for a term that you just can't remember because you are not very familiar with Homebrew. That's when this glossary might come in handy. Also check out Homebrew's own glossary.

brew
The main command.
bottle
A precompiled binary for a formula.
cask
A Mac OS X GUI application installed via Homebrew-Cask (a separate project that extends Homebrew with the subcommand cask).
cellar
The folder where Homebrew places all of its files. The default is /opt/homebrew/Cellar. The files in /opt/homebrew are just symlinks that point to the cellar.
formula (pl. formulae)
A Homebrew package.
keg
A folder in the cellar that contains the files of a formula. As far as I understand, this refers to a version-specific folder, e.g. /opt/homebrew/Cellar/boost/1.55.0.
keg-only
A formula is installed only into the cellar, i.e. it is not linked into /opt/homebrew. A typical reason for this is that the formula's files would conflict with files already provided by the system. For instance, macOS already contains a version of Python, available at /usr/bin/python, so Homebrew does not provide a symlink /opt/homebrew/bin/python in order not to override the system-provided Python. If you need symlinks the command brew link is the solution - see below for an example.
pouring
The process of installing a bottle.
tap
A Git repository with formulae. Homebrew comes with a number of official taps (e.g. homebrew/core, homebrew/games), but it's also possible to add custom taps.


Installation

A prerequisite for installing Homebrew is that Xcode is present on the system. Homebrew will use the Xcode version that is currently configured with

xcode-select

Homebrew's installation process is started with a single command line. It can be found at the bottom of the Homebrew website. At the time of writing the command was this:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The script explains what it's going to do before it does it - very neat! On Intel Macs Homebrew used to install its stuff into the prefix /usr/local, but on the newer Silicon Macs Homebrew went the same way as MacPorts and Fink do and installs its stuff into a location that does not conflict with the rest of the system:

/opt/homebrew

To make Homebrew binaries available in the PATH place the following line in your ~/.zprofile:

eval "$(/opt/homebrew/bin/brew shellenv)"


Operation principles

sudo

Except at the very beginning, when Homebrew needs to get its foot into the system door to create /opt/homebrew, Homebrew does not require the use of sudo. The FAQ has an entry on why, but the basic reasoning is that running a makefile with sudo is dangerous because it might fiddle with stuff in /usr.


Binary vs. source packages

Homebrew attempts to install a pre-compiled binary package (a so-called "bottle") when you install a formula. If there is no bottle, it will compile the formula from source. Bottles are distributed via a SourceForge project and the SourceForge mirror system, Homebrew simply knows where to look.


The cellar

Homebrew installs packages into a prefix folder, the so-called "cellar". The default is

/opt/homebrew/Cellar

Files in /opt/homebrew/bin are merely symlinks that point to the cellar.

A formula can have multiple folders in the cellar, one for each version of the formula. These folders are called "kegs". For instance:

$ ls -l /opt/homebrew/Cellar/boost
total 0
drwxr-xr-x   5 admin  admin   170  3 Jan  2015 1.55.0
drwxr-xr-x   5 admin  admin   170 14 Mai 19:23 1.60.0_2


Taps

A so-called "tap" is a Git repository with formulae. Homebrew comes with a number of official taps (e.g. homebrew/core, homebrew/games), but it's also possible to add custom taps.


A tap is identified by a combination of

  • A user name
  • A repository name

This is tailored towards GitHub where the top-level entities are users (or organizations) and the second-level entities are Git repositories.


A tap is stored in this path:

/opt/homebrew/Homebrew/Library/Taps/<user-name>/<repository-name>


See the next section "Usage" for examples how to manage taps.


Usage

Update Homebrew and installed packages

brew update
brew upgrade

Check the system for potential problems (e.g. this lists files that were installed to /opt/homebrew without Homebrew):

brew doctor

List all formulae that Homebrew knows about:

brew search

Search for a given formula (only formulae names are searched):

brew search foo      # substring search
brew search /^foo/   # regex search

List formulae:

brew list              # list formulae installed by Homebrew
brew list --unbrewed   # list files installed by something else than Homebrew

Install/uninstall a formula:

brew install foo
brew uninstall foo

See the detailed description of a formula:

brew info foo

Find out which formulae a formula depends on:

brew deps foo

Find out which locally installed packages depend on a package:

brew uses --installed foo

The following examples show Git repositories with formulae, so-called "taps". See the section Taps further up on this page, or consult the man page for more details.

brew tap                   # taps that are currently installed
brew tap --list-official   # official taps (even if they are not installed)
brew tap --list-pinned     # pinned taps (i.e. taps that have higher priority than homebrew/homebrew-core when searching for formulae)
brew tap-info --installed  # more details on installed taps

Install/uninstall a tap:

# Install from GitHub. The repository URL is assumed to be
# https://github.com/<user-name>/homebrew-<repository-name>
brew tap user-name/repository-name

# Install from anywhere else. The URL can use any transport protocol
# that Git can handle. User and repository names must be specified to
# identify the tap locally, but are not used automatically in any way
# to modify the URL.
brew tap user-name/repository-name URL

# Uninstalling does not require an URL, merely the user and repository
# names that were used to install the tap.
brew untap user-name/repository-name

Pin/unpin an installed tap:

brew tap-pin user-name/repository-name
brew tap-unpin user-name/repository-name

A formula may be "keg-only", which means that Homebrew does not create symlinks in the standard subfolders of /opt/homebrew, such as /opt/homebrew/bin, /opt/homebrew/include and /opt/homebrew/lib. The effect is that most tools will not find the formula's files automatically. Formulas are keg-only for good reasons, the typical case being that the formula's files conflict with files already provided by the system. Homebrew does create a link in the non-standard /opt/homebrew/opt for every formula it installs, so you might be able to point your tools (e.g. a compiler) to take the necessary files from there. If all else fails, and you know what you're doing, you can force Homebrew to create the usual symlinks like this:

# Only list files that would be symlinked
brew link --dry-run foo

# Do the real thing
# The --force parameter is necessary for keg-only formulas
# The --overwrite parameter tells Homebrew to overwrite files that already exist
brew link --force foo

# Same pattern for unlinking/disabling a formula
brew unlink --dry-run foo
brew unlink foo