Skip to content

Formula Cookbook

Jump to bottom Edit New page
mxcl edited this page Sep 13, 2010 · 128 revisions

Terminology

Formula The package description /usr/local/Library/Formula/foo.rb
Keg The installation prefix of a Formula /usr/local/Cellar/foo/0.1
Cellar All kegs are installed in here /usr/local/Cellar

Basic Instructions

Before contributing, check that the package you are about to create isn’t waiting to be merged by doing a search at the issue tracker.

Naturally check it already isn’t in Homebrew with a search: brew search foo

Make sure you search thoroughly (all aliases!) We don’t want you to waste your time.

Formula we don’t accept

The mxcl fork doesn’t dupe stuff that comes with OS X or stuff that is provided by RubyGems, CPAN or PyPi. If you find such a dupe. It should be reported so that it can be removed (there are four exceptions: Ruby, Python, libxml2 and libpng).

We’re hoping other people will maintain forks that contain dupes. Currently AdamV is maintaining a duplicates branch.

Grab the URL

All you need to make a formula is a URL to the tarball.

brew create http://example.com/foo-0.1.tar.gz

This creates:

/usr/local/Library/Formula/foo.rb

And opens it in your $EDITOR. It’ll look like:

require 'formula'

class Foo <Formula
  url 'http://example.com/foo-0.1.tar.gz'
  homepage ''
  md5 ''

# depends_on 'cmake'

  def install
    system "./configure", "--prefix=#{prefix}", "--disable-debug", "--disable-dependency-tracking"
#   system "cmake . #{std_cmake_parameters}"
    system "make install"
  end
end

Fill in the Homepage

We don’t accept formula without homepages!

Homebrew doesn’t have a description field because the homepage is always up to date, and Homebrew is not. Thus it’s less maintenance for us. To satisfy the description we’re going to invent a new packaging microformat and persuade everyone to publish it on their homepage.

Fill in the MD5

 brew install -i foo

This downloads the formula and extracts it to a sandbox. Homebrew tells you the MD5 as it does this. Fill the formula in.

Check the build system

You’re now at new prompt with the tarball extracted to a temporary sandbox.

Check the package’s README. Does the package install with autotools, cmake or something else? Delete the commented out cmake lines if the package uses autotools (ie. it has a configure script).

Check for dependencies

The README probably tells you about dependencies. Homebrew or OS X probably already has them. You can check for Homebrew deps with brew search. These are the common deps that OS X comes with:

Freetype
libexpat
libGL
libiconv
libpcap
libpng
libxml2
Python
Ruby
X11

There are plenty of others. Check /usr/lib, /usr/X11/lib to see.

We try to never duplicate libraries and complicated tools. We dupe some common tools (eg scons). But generally we avoid dupes because it is a foundation of Homebrew, and because it causes build and usage problems.

We encourage you to maintain your own fork with dupes as you require them.

Specifying other formula as dependencies

class Foo < Formula
  depends_on 'jpeg'
end

Test the formula

Exit out of the interactive shell.

brew install -vd foo

The v is for verbose, the d debug. Debug mode dumps you to an interactive shell if the build fails so you can try to figure out what went wrong.

Submit to Homebrew

Everything is built on git, so contribution is easy:

brew install git
brew update  # required in more ways than you think
git add Library/Formula/foo.rb
git commit

Now you just need to push back to Github. If you haven’t forked Homebrew yet, then the easiest way to do that is with the github gem:

gem install github
github fork
git push myname master

Now create an issue so that one of the Homebrew collaborators can schedule a merge.

Overview of the Formula Install Process

  1. The result of Formula.download_strategy is instantiated.
  2. DownloadStrategy.fetch is called — eg. downloads tarball, checks out git repository, etc.
  3. A temporary sandbox is created in /tmp/homebrew
  4. DownloadStrategy.stage is called — eg. extracts tarball to above sandbox, exports git repository to sandbox, etc.
  5. Patches are applied
  6. Current directory is changed to the stage root (so when you system “Make”, it works)
  7. Formula.install is called
  8. Anything installed to the keg is cleaned (see later)
  9. The keg is symlinked into Homebrew’s prefix
  10. Caveats are displayed

Convenience Tools

bin.install(‘foo’)

You’ll see stuff like that in other formula. This installs the file foo into the Formula’s bin directory (`/usr/local/Cellar/pkg/0.1/bin`).

inreplace

A convenience function that can edit files in-place. Eg:

inreplace 'path', before, after

`before` and `after` can be strings or regexps. You can also use the block form:

inreplace 'path' do |contents| 
  contents.gsub! /foo/, 'bar'
end

Make sure you modify `contents` — this block ignores the returned value.

There are some special functions you can use inside the block that makes it easier to modify Makefiles:

inreplace 'Makefile' do |contents| 
  contents.remove_make_var! %w[CFLAGS LDFLAGS CC LD]
  contents.change_make_var! "CC", ENV.cc
end

Patches

Return an array or string from your re-implemented patches function:

def patches
  # fixes doc install on OS X 10.6
  "http://gist.github.com/623/my.patch/raw/"
end

Patches can gzipped or not. If the patches are not p1 return a Hash:

def patches
  # back ported fix for memory leak in drawing functions
  p0 => "http://gist.github.com/623/my.patch/raw/"
end

Small patches should be put in the formula:

class Foo < Formula
  def patches
    # fixes your mum (she was b0rked)
    p0 => DATA
  end
end

__END__
diff --git a/showfigfonts b/showfigfonts
index 643c60b..543379c 100644
--- a/showfigfonts
+++ b/showfigfonts
@@ -14,6 +14,7 @@
…

Always, always, always justify the patch with a comment! Otherwise nobody will ever know if it’s safe to remove the patch, or if it’s safe to leave it in when upgrading the formula.

Creating the diff

We use git for everything don’t you know?

AdamV came up with this ingenious method:

brew install -i foo
…
git init
git add -A
…
git diff | pbcopy
brew edit foo

Now just paste into the formula after __END__.

Advanced Formula Tricks

If anything isn’t clear you can usually figure it out with some grep and the Library/Formula directory. Please amend this wiki page if you think it will help!

HEAD formula

HEAD formula have an alternate URL that users can choose with --HEAD. This URL points to trunk/master/HEAD. It will build the development cutting edge. Specifying it is easy:

class Foo < Formula
  head 'git://github.com/mxcl/lastfm-cocoa.git'
end

Homebrew understands git, svn, cvs and hg URLs.

Specifying the Download Strategy explicitly

Override the Formula::download_strategy function. Return the class type. Eg:

class Foo < Formula
  def download_strategy
    GitDownloadStrategy
  end
end

This can be useful when used with a local repo, where specifying a url would not let you specify how to access it. For example:

class Bar < Formula
  def download_strategy; GitDownloadStrategy; end
  head '/users/abc/src/git.git'
end
Add a custom footer
Add a custom sidebar

Clone this wiki locally