<commit_before># Formula Cookbook
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.

## Terminology - Homebrew speak

<table>
  <tbody>
    <tr>
      <th>Formula</th>
      <td>The package definition</td>
      <td><code>/usr/local/Library/Formula/foo.rb</code></td>
    </tr>
    <tr>
      <th>Keg</th>
      <td>The installation prefix of a Formula</td>
      <td><code>/usr/local/Cellar/foo/0.1</code></td>
    </tr>
    <tr>
      <th>opt prefix</th>
      <td>A symlink to the active version of a keg</td>
      <td><code>/usr/local/opt/foo</code></td>
    </tr>
    <tr>
      <th>Cellar</th>
      <td>All kegs are installed here</td>
      <td><code>/usr/local/Cellar</code></td>
    </tr>
    <tr>
      <th>Tap</th>
      <td>An optional repository (git) of Formulae</td>
      <td><code>/usr/local/Library/Taps</code></td>
    </tr>
    <tr>
      <th>Bottle</th>
      <td>Pre-built (binary) Keg that can be unpacked</td>
      <td><code>qt-4.8.4.mountain_lion.bottle.1.tar.gz</code></td>
    </tr>
  </tbody>
</table>

_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)
*   isn't already waiting to be merged (check the [issue tracker](https://github.com/Homebrew/homebrew/issues))
*   is still supported by upstream
*   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.

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

Be sure to look over the [contributing guidelines](https://github.com/Homebrew/homebrew/blob/master/CONTRIBUTING.md) as well.


## Will we merge your formula?

Probably. But we have rules to keep the quality and goals of Homebrew intact: Please read [Acceptable Formulae](Acceptable-Formulae.md).

## Some Quick Examples Before You Get Started

Formulae aren’t that complicated. [etl](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/etl.rb) is as simple as it gets.

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 [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.

## 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:

`$HOMEBREW_REPOSITORY/Library/Formula/foo.rb`

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

```ruby
class Foo < Formula
  url "http://example.com/foo-0.1.tar.gz"
  homepage ""
  sha1 "1234567890ABCDEF1234567890ABCDEF"

  # depends_on "cmake" => :build

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

**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`.


## Specifying other formulae as dependencies

```ruby
class Foo < Formula
  depends_on "jpeg"
  depends_on "gtk+" => :optional
  depends_on "readline" => :recommended
  depends_on "boost" => "with-icu"
  depends_on :x11 => :optional
end
```

A String specifies a formula dependency.

A Symbol specifies a special conditional dependency, such as X11.

A Hash specifies a formula dependency with some additional information. Given a single string key, the value can take several forms:
*   a Symbol (currently one of `:build`, `:optional`, `:recommended`).
    -   `:build` tags that dependency as a build-time only dependency, meaning it can be safely ignored
        when installing from a bottle and when listing missing dependencies using `brew missing`.
    -   `:optional` generates an implicit `with-foo` option for the formula. This means that, given
        `depends_on "foo" => :optional`, the user must pass `--with-foo` in order to enable the dependency.
    -   `:recommended` generates an implicit `without-foo` option, meaning that the dependency is enabled
        by default and the user must pass `--without-foo` to disable this dependency. The default
        description can be overridden using the normal option syntax (in this case, the option declaration must precede the dependency):

    ```ruby
    option "with-foo", "Compile with foo bindings" # This overrides the generated description if you want to
    depends_on "foo" => :optional # Generated description is "Build with foo support"
    ```

*   a String or an Array
    String values are interpreted as options to be passed to the dependency. You can also pass
    an array of strings, or an array of symbols and strings, in which case the symbols are
    interpreted as described above, and the strings are passed to the dependency as options.

    ```ruby
    depends_on "foo" => "with-bar"
    depends_on "foo" => %w{with-bar with-baz}
    depends_on "foo" => [:optional, "with-bar"]
    ```

## Formulae Revisions

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).

## Double-check for dependencies

When you already have a lot of brews installed, its easy to miss a common dependency like `glib` or `gettext`.

You can double-check which libraries a binary links to with the `otool` command (perhaps you need to use `xcrun otool`):

    $ otool -L /usr/local/bin/ldapvi
    /usr/local/bin/ldapvi:
	/usr/local/opt/openssl/lib/libssl.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
	/usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
	/usr/local/lib/libglib-2.0.0.dylib (compatibility version 4201.0.0, current version 4201.0.0)
	/usr/local/opt/gettext/lib/libintl.8.dylib (compatibility version 10.0.0, current version 10.2.0)
	/usr/local/opt/readline/lib/libreadline.6.dylib (compatibility version 6.0.0, current version 6.3.0)
	/usr/local/lib/libpopt.0.dylib (compatibility version 1.0.0, current version 1.0.0)
	/usr/lib/libncurses.5.4.dylib (compatibility version 5.4.0, current version 5.4.0)
	/System/Library/Frameworks/LDAP.framework/Versions/A/LDAP (compatibility version 1.0.0, current version 2.4.0)
	/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 1.0.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1213.0.0)

<commit_msg>formula-cookbook: document conflicts<commit_after># Formula Cookbook
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.

## Terminology - Homebrew speak

<table>
  <tbody>
    <tr>
      <th>Formula</th>
      <td>The package definition</td>
      <td><code>/usr/local/Library/Formula/foo.rb</code></td>
    </tr>
    <tr>
      <th>Keg</th>
      <td>The installation prefix of a Formula</td>
      <td><code>/usr/local/Cellar/foo/0.1</code></td>
    </tr>
    <tr>
      <th>opt prefix</th>
      <td>A symlink to the active version of a keg</td>
      <td><code>/usr/local/opt/foo</code></td>
    </tr>
    <tr>
      <th>Cellar</th>
      <td>All kegs are installed here</td>
      <td><code>/usr/local/Cellar</code></td>
    </tr>
    <tr>
      <th>Tap</th>
      <td>An optional repository (git) of Formulae</td>
      <td><code>/usr/local/Library/Taps</code></td>
    </tr>
    <tr>
      <th>Bottle</th>
      <td>Pre-built (binary) Keg that can be unpacked</td>
      <td><code>qt-4.8.4.mountain_lion.bottle.1.tar.gz</code></td>
    </tr>
  </tbody>
</table>

_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)
*   isn't already waiting to be merged (check the [issue tracker](https://github.com/Homebrew/homebrew/issues))
*   is still supported by upstream
*   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.

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

Be sure to look over the [contributing guidelines](https://github.com/Homebrew/homebrew/blob/master/CONTRIBUTING.md) as well.


## Will we merge your formula?

Probably. But we have rules to keep the quality and goals of Homebrew intact: Please read [Acceptable Formulae](Acceptable-Formulae.md).

## Some Quick Examples Before You Get Started

Formulae aren’t that complicated. [etl](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/etl.rb) is as simple as it gets.

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 [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.

## 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:

`$HOMEBREW_REPOSITORY/Library/Formula/foo.rb`

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

```ruby
class Foo < Formula
  url "http://example.com/foo-0.1.tar.gz"
  homepage ""
  sha1 "1234567890ABCDEF1234567890ABCDEF"

  # depends_on "cmake" => :build

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

**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`.


## Specifying other formulae as dependencies

```ruby
class Foo < Formula
  depends_on "jpeg"
  depends_on "gtk+" => :optional
  depends_on "readline" => :recommended
  depends_on "boost" => "with-icu"
  depends_on :x11 => :optional
end
```

A String specifies a formula dependency.

A Symbol specifies a special conditional dependency, such as X11.

A Hash specifies a formula dependency with some additional information. Given a single string key, the value can take several forms:
*   a Symbol (currently one of `:build`, `:optional`, `:recommended`).
    -   `:build` tags that dependency as a build-time only dependency, meaning it can be safely ignored
        when installing from a bottle and when listing missing dependencies using `brew missing`.
    -   `:optional` generates an implicit `with-foo` option for the formula. This means that, given
        `depends_on "foo" => :optional`, the user must pass `--with-foo` in order to enable the dependency.
    -   `:recommended` generates an implicit `without-foo` option, meaning that the dependency is enabled
        by default and the user must pass `--without-foo` to disable this dependency. The default
        description can be overridden using the normal option syntax (in this case, the option declaration must precede the dependency):

    ```ruby
    option "with-foo", "Compile with foo bindings" # This overrides the generated description if you want to
    depends_on "foo" => :optional # Generated description is "Build with foo support"
    ```

*   a String or an Array
    String values are interpreted as options to be passed to the dependency. You can also pass
    an array of strings, or an array of symbols and strings, in which case the symbols are
    interpreted as described above, and the strings are passed to the dependency as options.

    ```ruby
    depends_on "foo" => "with-bar"
    depends_on "foo" => %w{with-bar with-baz}
    depends_on "foo" => [:optional, "with-bar"]
    ```


## Specifying other formulae as conflicts

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"
```

## Formulae Revisions

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).

## Double-check for dependencies

When you already have a lot of brews installed, its easy to miss a common dependency like `glib` or `gettext`.

You can double-check which libraries a binary links to with the `otool` command (perhaps you need to use `xcrun otool`):

    $ otool -L /usr/local/bin/ldapvi
    /usr/local/bin/ldapvi:
	/usr/local/opt/openssl/lib/libssl.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
	/usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
	/usr/local/lib/libglib-2.0.0.dylib (compatibility version 4201.0.0, current version 4201.0.0)
	/usr/local/opt/gettext/lib/libintl.8.dylib (compatibility version 10.0.0, current version 10.2.0)
	/usr/local/opt/readline/lib/libreadline.6.dylib (compatibility version 6.0.0, current version 6.3.0)
	/usr/local/lib/libpopt.0.dylib (compatibility version 1.0.0, current version 1.0.0)
	/usr/lib/libncurses.5.4.dylib (compatibility version 5.4.0, current version 5.4.0)
	/System/Library/Frameworks/LDAP.framework/Versions/A/LDAP (compatibility version 1.0.0, current version 2.4.0)
	/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 1.0.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1213.0.0)


{'fraction_non_alphanumeric': 0.10084243890232714, 'fraction_numerical': 0.014096254900325298, 'mean_word_length': 3.936998147004324, 'pattern_counts': {'":': 0, '<': 135, '<?xml version=': 0, '>': 152, 'https://': 26, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4317699', 'n_tokens_mistral': 7376, 'n_tokens_neox': 7066, 'n_words': 2934}