Making a formula is easy. Just `brew create URL` and then `brew install $FORMULA` (perhaps with `--debug --verbose`). Basically, a formula is a Ruby file. You can place it anywhere you want (local or remote) and install it by pointing to the file or URL.
We want your formula to be awesome, and the cookbook will tell you how.
_More general: `brew --prefix` and `brew --repository` instead of `/usr/local` but lets KISS._
## An Introduction
Did you see `/usr/local/.git`? Homebrew is built on Git. This means you can just do your work in `/usr/local` and merge in upstream changes as you go.
Homebrew installs to the `Cellar`, it then symlinks some of the installation into `/usr/local` so that other programs can see what's going on. We suggest you `brew ls` a few of the kegs in your Cellar to see how it is all arranged.
Packages are installed according to their formulae, which live in `$(brew --repository)/Library/Formula`. Check some out. You can view any formula at anytime; e.g. `brew edit wget`.
# Basic Instructions
Make sure you run `brew update` before you start. This turns your Homebrew installation into a Git repository.
Before contributing, make sure your package:
* meets all our [Acceptable Formulae](Acceptable-Formulae.md) requirements
* isn't already in Homebrew (check `brew search $FORMULA`)
* isn't in another [Homebrew tap](https://github.com/Homebrew)
* has a stable, tagged version (i.e. not just a GitHub repository with no versions). See [Interesting-Taps-&-Branches](Interesting-Taps-&-Branches.md) for where pre-release and head-only versions belong.
And then [Git](https://github.com/Homebrew/homebrew/tree/master/Library/Formula/git.rb) and [flac](https://github.com/Homebrew/homebrew/tree/master/Library/Formula/flac.rb) show more advanced functionality.
A more complete example-formula [cheat-sheet](https://github.com/Homebrew/homebrew/blob/master/Library/Contributions/example-formula.rb) shows almost all the stuff you can use in a Formula.
**Note:** If `brew` said `Warning: Version cannot be determined from URL` when doing the `create` step, you’ll need to explicitly add the correct version to the formula with `version "foo"`**and then save the formula**. `brew install` should then proceed without any trouble.
**Note:** If `brew` said `No formula found for "php54-timezonedb". Searching open pull requests...` and you are writing a Tap, you should run `brew tap --repair`.
## Fill in the Homepage
**We don’t accept formulae without homepages!**
Homebrew doesn’t have a description field because the homepage is always up to date, and Homebrew is not. That’s way less maintenance for us. Try `brew home qt`.
## Check the build system
brew install -i foo
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 (i.e. if 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:
*`libexpat`
*`libGL`
*`libiconv`
*`libpcap`
*`libxml2`
*`Python`
*`Ruby`
There are plenty of others. Check `/usr/lib` to see.
We try to not duplicate libraries and complicated tools in core Homebrew. We dupe some common tools though. But generally, we avoid dupes because it’s one of Homebrew’s foundations. (And it causes build and usage problems!)
The one special exception is OpenSSL. Anything that uses OpenSSL *should* be built using Homebrew’s shipped OpenSSL and our test bot's post-install audit will warn of this when it is detected. (*Of course, there are exceptions to the exception. Not everything can be forced onto our OpenSSL)*.
Because Homebrew’s OpenSSL is `keg_only` to avoid conflicting with the system sometimes formulae need to have environmental variables set or special configuration flags passed to locate our preferred OpenSSL; you can see this mechanism in the [clamav](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/clamav.rb#L28) formula. Usually this is unnecessary because when OpenSSL is specified as a dependency Homebrew temporarily prepends the $PATH with that prefix.
Homebrew maintains a special [tap that provides other useful dupes](https://github.com/Homebrew/homebrew-dupes).
*Important:* Since the introduction of `superenv`, `brew --prefix`/bin is NOT on the `$PATH` during formula installation. If you have dependencies at build time, you must specify them and brew will add them to the `$PATH`. You can test around this with `--env=std`.
Sometimes there’s hard conflict between formulae, and it can’t be avoided or circumvented with `keg_only`.
PolarSSL is a good [example](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/polarssl.rb#L36-L37) formula for minor conflict.
PolarSSL ship GNU’s Hello, and compiles a `hello` binary. This is obviously non-essential to PolarSSL’s functionality, and conflict with the `hello` formula would be overkill, so we just remove it.
However, also in the PolarSSL formulae is a [firm conflict](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/polarssl.rb#L19) with `md5sha1sum`, because both `md5sha1sum` and `polarssl` compile identically-named binaries that *are* important for core functionality.
As a general rule, `conflicts_with` should be a last-resort option. It’s a fairly blunt instrument.
The syntax for conflict that can’t be worked around is
```ruby
conflicts_with "blueduck", :because => "yellowduck also ships a duck binary"
In Homebrew we sometimes accept formulae updates that don’t include a version bump. These include homepage changes, resource updates, new patches or fixing a security issue with a formula.
Occasionally, these updates require a forced-recompile of the formula itself or its dependents to either ensure formulae continue to function as expected or to close a security issue. This forced-recompile is known as a `revision` and inserted underneath the homepage/url/sha block.
Where a dependent of a formula fails against a new version of that dependency it must receive a `revision`. An example of such failure can be seen [here](https://github.com/Homebrew/homebrew/issues/31195) and the fix [here](https://github.com/Homebrew/homebrew/pull/31207).
`Revisions` are also used for formulae that move from the system OpenSSL to the Homebrew-shipped OpenSSL without any other changes to that formula. This ensures users aren’t left exposed to the potential security issues of the outdated OpenSSL. An example of this can be seen in [this commit](https://github.com/Homebrew/homebrew/commit/6b9d60d474d72b1848304297d91adc6120ea6f96).
See [jrnl](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/jrnl.rb) for an example of a formula that does this well. The end-result means the user doesn't have to faff with `pip` or Python and can just run `jrnl`.
[This script](https://raw.githubusercontent.com/tdsmith/labmisc/master/mkpydeps) can help you generate resource stanzas for the dependencies of your Python application.
If your formula needs a gem or python module and it can't be made into a resource you’ll need to check for these external dependencies:
```ruby
class Foo <Formula
depends_on "mg" => :ruby
depends_on "json" => :python
depends_on "Authen::NTLM" => :perl
end
```
Note that we probably won't accept the formulae in this case; it's a far worse user experience than vendoring libraries with resources.
## Test the formula
Exit out of the interactive shell.
brew install --verbose --debug foo
Debug will ask you to open an interactive shell when the build fails so you can try to figure out what went wrong.
Check the top of the `./configure` output (if applicable)! Some configure scripts do not recognize `--disable-debug`. If you see a warning about it, remove the option from the formula.
## Add a test to the formula
Please add a `test do` block to the formula. This will be run by `brew test foo` and the [Brew Test Bot](Brew-Test-Bot.md).
The `test do` block automatically creates and changes to a temporary directory which is deleted after run. You can access this Pathname with the `testpath` function.
We want tests that don't require any user input and test the basic functionality of the application. For example `foo build-foo input.foo` is a good test and (despite their widespread use) `foo --version` and `foo --help` are bad tests. However, a bad test is better than no test at all.
See [cmake](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/cmake.rb) for an example of a formula with a good test. A basic `CMakeLists.txt` file is written CMake uses it to generate Makefiles. This test checks that CMake doesn't e.g. segfault during basic operation.
## Manuals
Homebrew expects to find man pages in `[prefix]/share/man/...`, and not in `[prefix]/man/...`.
Some software installs to man instead of `share/man`, so check the output and add a `"--mandir=#{man}"` to the `./configure` line if needed.
## A Quick Word on Naming
**THE NAME IS VERY IMPORTANT!**
Name the formula like the project markets the product. So it’s `pkg-config`, not `pkgconfig`; `sdl_mixer`, not `sdl-mixer` or `sdlmixer`.
The only exception is stuff like “Apache Ant”. Apache sticks “Apache” in front of everything, but we use the formula name `ant`. We only include the prefix in cases like *GNUplot* (because it’s part of the name) and *GNU Go* (because everyone calls it “GNU go”—nobody just calls it “Go”). The word “Go” is too common and there are too many implementations of it.
If you’re not sure about the name check the homepage, and check the Wikipedia page.
Where Homebrew already has a formula called `foo` we typically do not accept requests to replace that formula with something else also named `foo`. This is to avoid both confusing and surprising users’ expectation.
When two formulae share an upstream name, e.g. [`AESCrypt`](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/aescrypt.rb) and [`AESCrypt`](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/aescrypt-packetizer.rb) the newer formula must typically adapt the name to avoid conflict with the current formula.
If you’re *still* not sure, just commit. We’ll apply some arbitrary rule and make a decision ;)
When importing classes, Homebrew will require the formula and then create an instance of the class. It does this by assuming the formula name can be directly converted to the class name using a `regexp`. The rules are simple:
*`foo-bar.rb` => `FooBar`
*`foobar.rb` => `Foobar`
Thus, if you change the name of the class, you must also rename the file. Filenames should be all lowercase.
Add aliases by creating symlinks in `Library/Aliases`.
## Audit the formula
You can run `brew audit` to test formulae for adherence to Homebrew house style. This includes warnings for trailing whitespace, preferred URLs for certain source hosts, and a lot of other style issues. Fixing these warnings before committing will make the process a lot smoother for us.
## Commit
Everything is built on Git, so contribution is easy:
brew install git # if you already have git installed, skip this command
brew update # required in more ways than you think (initializes the brew git repository if you don't already have it)
cd `brew --repository`
# Create a new git branch for your formula so your pull request is easy to
# modify if any changes come up during review.
git checkout -b <some-descriptive-name>
git add Library/Formula/foo.rb
git commit
The established standard for Git commit messages is:
* the first line is a commit summary of *50 characters or less*, then
* two (2) newlines, then
* explain the commit throughly
At Homebrew, we like to put the name of the formula upfront like so "foobar 7.3 (new formula)".
This may seem crazy short, but you’ll find that forcing yourself to summarise the commit encourages you to be atomic and concise. If you can’t summarise it in 50-80 characters, you’re probably trying to commit two commits as one. For a more thorough explanation, please read Tim Pope’s excellent blog post, [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
The preferred commit message format for simple version updates is "foobar 7.3".
Ensure you reference any relevant GitHub issue `#12345` in the commit message. Homebrew’s history is the first thing future contributors will look to when trying to understand the current state of formulae they’re interested in.
If a commit touches multiple files, or isn’t one logical bug fix, or a file is touched in multiple commits, we’ll probably ask you to `rebase` and `squash` your commits. For this reason, you should avoid pushing to your `master` branch. Note, after rebase and/or squash, you'll need to push with `--force` to your remote.
# Overview of the Formula Install Process
<!-- TODO rewrite this. It is outdated, there are more layers now, and the implementation details discussed here are not relevant or useful to most users anyway. -->
* The result of `Formula.download_strategy` is instantiated.
*`DownloadStrategy.fetch` is called (downloads tarball, checks out git repository, etc.)
You’ll see stuff like that in other formulae. This installs the file foo into the Formula’s `bin` directory (`/usr/local/Cellar/pkg/0.1/bin`) and makes it executable (`chmod 0555 foo`).
A convenience function that can edit files in-place. For example:
`inreplace "path", before, after`
`before` and `after` can be strings or regexps. You can also use the block form:
```ruby
inreplace "path" do |s|
s.gsub! /foo/, "bar"
end
```
Make sure you modify `s`! This block ignores the returned value.
`inreplace` should be used instead of patches when it is patching something that will never be accepted upstream e.g. make the software’s build system respect Homebrew’s installation hierarchy. If it's Homebrew and MacPorts or OS X specific it should be turned into a patch instead.
If you need modify variables in a Makefile, rather than using `inreplace`, pass them as arguments to make:
```rb
system "make", "target", "VAR2=value1", "VAR2=value2", "VAR3=values can have spaces"
```
```rb
args = %W[
CC=#{ENV.cc}
PREFIX=#{prefix}
]
system "make", *args
```
Note that values *can* contain unescaped spaces if you use the multiple-argument form of `system`.
## Patches
While patches should generally be avoided, sometimes they are necessary.
When patching (i.e. fixing header file inclusion, fixing compiler warnings, etc.) the first thing to do is check whether or not the upstream project is aware of the issue. If not, file a bug report and/or submit your patch for inclusion. We may sometimes still accept your patch before it was submitted upstream but by getting the ball rolling on fixing the upstream issue you reduce the length of time we have to carry the patch around.
*Always, always, always justify a patch with a code comment!* Otherwise, nobody will know when it is safe to remove the patch, or safe to leave it in when updating the formula. The comment should include a link to the relevant upstream issue(s).
External patches can be declared using resource-style blocks:
```rb
patch do
url "https://example.com/example_patch.diff"
sha1 "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
end
```
A strip level of -p1 is assumed. It can be overridden using a symbol argument:
```rb
patch :p0 do
url "https://example.com/example_patch.diff"
sha1 "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
end
```
Patches can be declared in stable, devel, and head blocks. NOTE: always use a block instead of a conditional, i.e. `stable do ... end` instead of `if build.stable? then ... end`.
```rb
stable do
# some other things...
patch do
url "https://example.com/example_patch.diff"
sha1 "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
end
end
```
Embedded (__END__) patches can be declared like so:
```rb
patch :DATA
patch :p0, :DATA
```
with the patch data included at the end of the file:
```
__END__
diff --git a/foo/showfigfonts b/foo/showfigfonts
index 643c60b..543379c 100644
--- a/foo/showfigfonts
+++ b/foo/showfigfonts
@@ -14,6 +14,7 @@
…
```
Patches can also be embedded by passing a string. This makes it possible to provide multiple embedded patches while making only some of them conditional.
```rb
patch :p0, "..."
```
In embedded patches, the string `HOMEBREW_PREFIX` is replaced with the value of the constant `HOMEBREW_PREFIX` before the patch is applied.
## Creating the diff
brew install --interactive --git foo
…
(make some edits)
…
git diff | pbcopy
brew edit foo
Now just paste into the formula after `__END__`.
Instead of `git diff | pbcopy`, for some editors `git diff >> path/to/your/formula/foo.rb` might help you that the diff is not touched (e.g. white space removal, indentation, etc.)
If anything isn’t clear, you can usually figure it out with some `grep` and the `Library/Formula` directory. Please amend this document if you think it will help!
Formulae can specify alternate downloads for the upstream project’s `devel` release (unstable but not `trunk`) or `HEAD` (`master/trunk`).
### HEAD
HEAD URLs (activated by passing `--HEAD`) build the development cutting edge. Specifying it is easy:
```ruby
class Foo <Formula
head "https://github.com/mxcl/lastfm-cocoa.git"
end
```
Homebrew understands `git`, `svn`, and `hg` URLs, and has a way to specify `cvs` repositories as a URL as well. You can test whether the `HEAD` is being built with `build.head?`.
To use a specific commit, tag, or branch from a repository, specify head with the `:revision`, `:tag`, or `:branch` option, like so:
```ruby
class Foo <Formula
head "https://github.com/some/package.git", :revision => "090930930295adslfknsdfsdaffnasd13"
# or :branch => "develop"
# or :tag => "1_0_release"
end
```
Formulae that only have `head` versions should be submitted to [homebrew/headonly](https://github.com/Homebrew/homebrew-headonly) instead of Homebrew/homebrew.
### devel
The "devel" spec (activated by passing `--devel`) is used for a project’s unstable releases. It is specified in a block:
```ruby
devel do
url "https://foo.com/foo-0.1.tar.gz"
sha1 "deadbeefdeadbeefdeadbeafdeadbeefdeadbeef"
end
```
You can test if the "devel" spec is in use with `build.devel?`.
## Compiler selection
Sometimes a package fails to build when using a certain compiler. Since recent XCode no longer includes a GCC compiler, we cannot simply force the use of GCC. Instead, the correct way to declare this is the `fails_with` DSL method. A properly constructed `fails_with` block documents the latest compiler build version known to cause compilation to fail, and the cause of the failure. For example:
```ruby
fails_with :llvm do
build 2335
cause <<-EOS.undent
The "cause" field should include a short summary of the error. Include
the URLs of any relevant information, such as upstream bug reports. Wrap
the text at a sensible boundary (~72-80 characters), but do not break
URLs over multiple lines.
EOS
end
```
`build` takes a Fixnum (you can find this number in your `brew --config` output). `cause` takes a string, and the use of heredocs is encouraged to improve readability and allow for more comprehensive documentation.
`fails_with` declarations can be used with any of `:gcc`, `:llvm`, and `:clang`. Homebrew will use this information to select a working compiler (if one is available).
## Specifying the Download Strategy explicitly
To use one of Homebrew’s built-in download strategies, specify the `:using =>` flag on a `url` or `head`. For example:
If you need more control over the way files are downloaded and staged, you can create a custom download strategy and specify it using the `url` method's `:using` option:
```ruby
class MyDownloadStrategy <SomeHomebrewDownloadStrategy
# Does something cool
end
class Foo <Formula
url "something", :using => MyDownloadStrategy
end
```
Specifying download strategies can be useful when used with a local repo, where a plain URL would not let you specify how to access it. For example:
```ruby
class Bar <Formula
head "/users/abc/src/git.git", :using => :git
end
```
## Just copying some files
When your code in the install function is run, the current working directory is set to the extracted tarball.
So it is easy to just copy some files:
```ruby
prefix.install "file1", "file2"
```
Or everything:
```ruby
prefix.install Dir["output/*"]
```
Generally we'd rather you were specific about what files or directories need to be installed rather than installing everything.
Option names should be prefixed with one of the words `with`, `without`, `no`, or a verb in the imperative tense describing the action to be taken. For example, an option to run a test suite should be named `--with-test` or `--with-check` rather than `--test`, and an option to enable a shared library should be named `--enable-shared` rather than `--shared`.
Note that options that aren’t ` build.with? ` or ` build.without? ` should be actively deprecated where possible. See [wget](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/wget.rb#L27-L31) for an example.
See the [graphviz](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/graphviz.rb) formula for an example.
## File level operations
You can use the file utilities provided by Ruby (`FileUtils`). These are included in the `Formula` class, so you do not need the `FileUtils.` prefix to use them. They are documented [here](http://www.ruby-doc.org/stdlib/libdoc/fileutils/rdoc/index.html).
When creating symlinks, take special care to ensure they are *relative* symlinks. This makes it easier to create a relocatable bottle. For example, to create a symlink in `bin` to an executable in `libexec`, use
```rb
bin.install_symlink libexec/"name"
```
*not*
```rb
ln_s libexec/"name", bin
```
The symlinks created by `install_symlink` are guaranteed to be relative. `ln_s` will only produce a relative symlink when given a relative path.
## Handling files that should persist over formula upgrades
For example, Ruby 1.9’s gems should be installed to `var/lib/ruby/` so that gems don’t need to be reinstalled when upgrading Ruby. You can usually do this with symlink trickery, or *better* a configure option.
### launchd plist files
Homebrew provides two Formula methods for launchd plist files. `plist_name` will return `homebrew.mxcl.<formula>`, and `plist_path` will return, for example, `/usr/local/Cellar/foo/0.1/homebrew.mxcl.foo.plist`.
Eventually a new version of the software will be released. In this case you should update the `url` and `sha1`/`sha256`. Please leave the `bottle do ... end` block as-is; our CI system will update it when we pull your change.
Check if the formula you are updating is a dependency for any other formulae by running `brew uses UPDATED_FORMULA`. If it is a dependency please `brew reinstall` all the dependencies after it is installed and verify they work correctly.
# Style guide
Homebrew wants to maintain a consistent Ruby style across all formulae based on [Ruby Style Guide](https://github.com/styleguide/ruby). Other formulae may not have been updated to match this guide yet but all new ones should. Also:
* The order of methods in a formula should be consistent with other formulae (e.g.: `def patches` goes before `def install`)
* An empty line is required before the `__END__` line
# Troubleshooting for people writing new formulae
### Version detection fails
Homebrew tries to automatically determine the version from the URL in order to save on duplication. If the tarball has a funny name though, you may have to assign the version number:
```ruby
class Foobar
version "0.7"
end
```
## Bad Makefiles
Not all projects have makefiles that will run in parallel so try to deparallelize:
brew edit foo
Add all this to the formula (so there will already be a class line, don’t add another or change that, and there’s already an install function, don't add another one, add the lines in the install function below to the top of the problem formula’s install function).
```ruby
class Foo <Formula
skip_clean :all
def install
ENV.deparallelize
ENV.no_optimization
system "make" # separate make and make install steps
`superenv` is a "super" environment that tries to improve reliability for the general case. But it does make making formula harder.
To not use `superenv`, install with `--env=std`.
Superenv isolates builds by removing `/usr/local/bin` and all user-PATHs that are not determined to be essential to the build. It does this because other PATHs are full of stuff that breaks builds. (We have 15,000 tickets as testament!)
`superenv` tries to remove bad-flags from the commands passed to `clang`/`gcc` and injects others (for example all `keg_only` dependencies are added to the `-I` and `-L` flags. If superenv troubles you, try to `brew install --env=std` and report to us if that fixes it.
# Fortran
Some software requires a Fortran compiler. This can be declared by adding `depends_on :fortran` to a formula. `:fortran` is a special dependency that does several things.
First, it looks to see if you have set the `FC` environment variable. If it is set, Homebrew will use this value during compilation. If it is not set, it will check to see if `gfortran` is found in `PATH`. If it is, Homebrew will use its location as the value of `FC`. Otherwise, the `gcc` formula will be treated as a dependency and installed prior to compilation.
If you have set `FC` to a custom Fortran compiler, you may additionally set `FCFLAGS` and `FFLAGS`. Alternatively, you can pass `--default-fortran-flags` to `brew install` to use Homebrew's standard `CFLAGS`.
When using Homebrew's own gfortran compiler, the standard `CFLAGS` are used and user-supplied values of `FCFLAGS` and `FFLAGS` are ignored for consistency and reproducibility reasons.
# How to start over (reset to `master`)?
Have you created a real mess in git which paralyzes you to create the commit you just want to push?
Then you might consider start from scratch.
Your changes will be discarded in favour of the `master` branch:
