mirrors/brew
1
0
Fork 0
mirror of https://github.com/Homebrew/brew.git synced 2025-07-14 16:09:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

Overhaul, simplify and cleanup documentation.

Browse Source 
Remove duplication, link to the API documentation more often,
tweak wording, add `@UniqMartin` as a maintainer, note `@jacknagel`'s
and `@adamv`'s significant past contributions to Homebrew, delete some
outdated or unneeded documentation, add some missing `Formula` API.
entries and simplify/improve `CONTRIBUTING.md`.

Closes Homebrew/homebrew#46179.

Closes Homebrew/homebrew#46618.

Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
This commit is contained in:
Mike McQuaid 2015-12-06 22:18:16 +00:00
parent fe8a0569ca
commit b745546943
31 changed files with 362 additions and 753 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@ -11,6 +11,10 @@
!/bin
/bin/*
!/bin/brew
!/share
/share/*
!/share/doc
/share/doc/*
!/share/doc/homebrew
!/share/man/man1/brew.1
.DS_Store

29
CONTRIBUTING.md
View File

@ -1,25 +1,24 @@
# Contributing to Homebrew
## Reporting Bugs
First, please run `brew update` and `brew doctor`.
First time contributing to Homebrew? Read our [Code of Conduct](https://github.com/Homebrew/homebrew/blob/master/CODEOFCONDUCT.md#code-of-conduct).
Second, read the [Troubleshooting Checklist](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Troubleshooting.md#troubleshooting).
To report a bug:
**If you don't read these it will take us far longer to help you with your problem.**
- run `brew update` (twice), run and read `brew doctor`, read [the Troubleshooting Checklist](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Troubleshooting.md#troubleshooting), open an issue on the formula's repository.
## Security
Please report security issues to security@brew.sh.
Submit a `1.2.3` version upgrade for the `foo` formula:
## Contributing
Please read:
- `brew edit foo`, edit [`url`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#url-class_method) and [`sha256`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#sha256%3D-class_method)/[`tag`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#url-class_method), leave the [`bottle`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#bottle-class_method) as-is, `brew install foo`, `git commit` with commit subject `foo 1.2.3`, [open a pull request](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md#how-to-open-a-homebrew-pull-request-and-get-it-merged) and fix any failing tests.
* [Code of Conduct](https://github.com/Homebrew/homebrew/blob/master/CODEOFCONDUCT.md#code-of-conduct)
To add a new formula for `foo` version `2.3.4` from `$URL`:
To contribute code please read:
- Read [the Formula Cookbook](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Formula-Cookbook.md#formula-cookbook) or: `brew create $URL` and make edits, `brew install foo`, `brew audit --online --strict foo`, `git commit` with message formatted `foo 2.3.4 (new formula)`, [open a pull request](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md#how-to-open-a-homebrew-pull-request-and-get-it-merged) and fix any failing tests.
* [Formula API](http://www.rubydoc.info/github/Homebrew/homebrew/master/frames)
* [Formula Cookbook](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Formula-Cookbook.md#formula-cookbook)
* [Acceptable Formulae](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Acceptable-Formulae.md#acceptable-formulae)
* [Ruby Style Guide](https://github.com/styleguide/ruby)
* [How To Open a Homebrew Pull Request (and get it merged)](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md#how-to-open-a-homebrew-pull-request-and-get-it-merged)
To contribute a fix to the `foo` formula:
- `brew edit foo` and make edits, leave the [`bottle`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#bottle-class_method) as-is, `brew install foo`, `git commit` with message formatted `foo: fix <insert details>.`, [open a pull request](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md#how-to-open-a-homebrew-pull-request-and-get-it-merged) and fix any failing tests.
To report a security vulnerability:
- [Email security@brew.sh](mailto:security@brew.sh) (a private mailing list) with detailed reproduction instructions using [our PGP key](https://keybase.io/homebrew/key.asc).
Thanks!

10
Library/Homebrew/formula.rb
View File

@ -723,11 +723,12 @@ class Formula
end
alias_method :startup_plist, :plist
# The {.plist} name (the name of the launchd service).
# The generated launchd {.plist} service name.
def plist_name
"homebrew.mxcl."+name
end
# The generated launchd {.plist} file path.
def plist_path
prefix+(plist_name+".plist")
end
@ -1627,7 +1628,7 @@ class Formula
# `S3DownloadStrategy` (download from S3 using signed request)
#
# <pre>url "https://packed.sources.and.we.prefer.https.example.com/archive-1.2.3.tar.bz2"</pre>
# <pre>url "https://some.dont.provide.archives.example.com", :using => :git, :tag => "1.2.3"</pre>
# <pre>url "https://some.dont.provide.archives.example.com", :using => :git, :tag => "1.2.3", :revision => "db8e4de5b2d6653f66aea53094624468caad15d2"</pre>
def url(val, specs = {})
stable.url(val, specs)
end
@ -1853,6 +1854,11 @@ class Formula
specs.each { |spec| spec.option(name, description) }
end
# @!attribute [w] deprecated_option
# Deprecated options are used to rename options and migrate users who used
# them to newer ones. They are mostly used for migrating non-`with` options
# (e.g. `enable-debug`) to `with` options (e.g. `with-debug`).
# <pre>deprecated_option "enable-debug" => "with-debug"</pre>
def deprecated_option(hash)
specs.each { |spec| spec.deprecated_option(hash) }
end

2
Library/Homebrew/language/haskell.rb
View File

@ -1,6 +1,6 @@
module Language
module Haskell
# module for formulas using cabal-install as build tool
# module for formulae using cabal-install as build tool
module Cabal
module ClassMethods
def setup_ghc_compilers

10
Library/Homebrew/manpages/brew.1.md
View File

@ -592,7 +592,9 @@ can take several different forms:
* `HOMEBREW_BUILD_FROM_SOURCE`:
If set, instructs Homebrew to compile from source even when a formula
provides a bottle.
provides a bottle. This environment variable is intended for use by
Homebrew developers. Please do not file issues if you encounter errors when
using this environment variable.
* `HOMEBREW_CACHE`:
If set, instructs Homebrew to use the given directory as the download cache.
@ -715,10 +717,10 @@ Homebrew Documentation: <https://github.com/Homebrew/homebrew/blob/master/share/
## AUTHORS
Homebrew's current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Mike McQuaid, Baptiste Fontaine, Brett Koonce, Dominyk Tiller, Tim Smith and Alex Dunn.
Homebrew's current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Mike McQuaid, Baptiste Fontaine, Brett Koonce, Martin Afanasjew, Dominyk Tiller, Tim Smith and Alex Dunn.
Homebrew was originally created by Max Howell.
Former maintainers with significant contributions include Jack Nagel, Adam Vandenberg and Homebrew's creator: Max Howell.
## BUGS
See Issues on GitHub: <https://github.com/Homebrew/homebrew/issues>
See our issues on GitHub: <https://github.com/Homebrew/homebrew/issues>

4
README.md
View File

@ -25,9 +25,9 @@ This is our PGP key which is valid until June 17, 2016.
* Full key: https://keybase.io/homebrew/key.asc
## Who Are You?
Homebrew's current maintainers are [Misty De Meo](https://github.com/mistydemeo), [Andrew Janke](https://github.com/apjanke), [Xu Cheng](https://github.com/xu-cheng), [Mike McQuaid](https://github.com/mikemcquaid), [Baptiste Fontaine](https://github.com/bfontaine), [Brett Koonce](https://github.com/asparagui), [Dominyk Tiller](https://github.com/DomT4), [Tim Smith](https://github.com/tdsmith) and [Alex Dunn](https://github.com/dunn).
Homebrew's current maintainers are [Misty De Meo](https://github.com/mistydemeo), [Andrew Janke](https://github.com/apjanke), [Xu Cheng](https://github.com/xu-cheng), [Mike McQuaid](https://github.com/mikemcquaid), [Baptiste Fontaine](https://github.com/bfontaine), [Brett Koonce](https://github.com/asparagui), [Martin Afanasjew](https://github.com/UniqMartin), [Dominyk Tiller](https://github.com/DomT4), [Tim Smith](https://github.com/tdsmith) and [Alex Dunn](https://github.com/dunn).
Homebrew was originally created by [Max Howell](https://github.com/mxcl).
Former maintainers with significant contributions include [Jack Nagel](https://github.com/jacknagel), [Adam Vandenberg](https://github.com/adamv) and Homebrew's creator: [Max Howell](https://github.com/mxcl).
## License
Code is under the [BSD 2 Clause (NetBSD) license](https://github.com/Homebrew/homebrew/tree/master/LICENSE.txt).

14
share/doc/homebrew/Acceptable-Formulae.md
View File

@ -11,7 +11,7 @@ should not be duplicated. There are good reasons for this:
* Duplicate libraries regularly break builds
* Subtle bugs emerge with duplicate libraries, and to a lesser extent,
duplicate tools
duplicate tools
* We want our formulae to work with what comes with OS X
There are exceptions:
@ -59,7 +59,7 @@ point it to the downloaded archive in order to avoid loading.
Our policy is that formulae in the core repository
([Homebrew/homebrew](https://github.com/Homebrew/homebrew)) must be built
from source (or produce cross-platform binaries like e.g. Java). Binary-only
formulae should go to [homebrew/binary](https://github.com/Homebrew/homebrew-binary).
formulae should go to [homebrew/binary](https://github.com/Homebrew/homebrew-binary) or [homebrew-cask](https://github.com/caskroom/homebrew-cask).
### Stable versions
Formulae in the core repository must have a stable version tagged by
@ -95,8 +95,7 @@ get maintained and partly because we have to draw the line somewhere.
We frown on authors submitting their own work unless it is very popular.
Don’t forget Homebrew is all git underneath! Maintain your own fork or
tap if you have to!
Don’t forget Homebrew is all `git` underneath! Maintain your tap if you have to!
There may be exceptions to these rules in the main repository, we may
include things that don't meet these criteria or reject things that do.
@ -112,13 +111,6 @@ for OS X and/or hard to get in binary elsewhere (example: fontforge).
Check out the [homebrew-cask](https://github.com/caskroom/homebrew-cask)
project if you’d like to brew native OS X Applications.
### Building under “superenv” is best
The “superenv” is code Homebrew uses to try to minimize finding
undeclared dependencies accidentally. Some formulae will only work under
the original “standard env” which is selected in a formula by adding
`env :std`. The preference for new formulae is that they be made to
work under superenv (which is the default) whenever possible.
### Sometimes there are exceptions
Even if all criteria are met we may not accept the formula.
Documentation tends to lag behind current decision-making. Although some

2
share/doc/homebrew/Bottles.md
View File

@ -2,7 +2,7 @@
Bottles are Homebrew's binary packages. They are produced by installing a formula with `brew install --build-bottle $FORMULA` and then bottling it with `brew bottle $FORMULA`. This outputs the bottle DSL which should be inserted into the formula file.
## Bottle Usage
If a bottle is available and usable it will be downloaded and poured automatically when you `brew install <formula>`. If you wish to disable this you can do it by specifying `--build-from-source` or set `export HOMEBREW_BUILD_FROM_SOURCE=1` environment variable.
If a bottle is available and usable it will be downloaded and poured automatically when you `brew install <formula>`. If you wish to disable this you can do it by specifying `--build-from-source`.
Bottles will not be used if the user requests it (see above), if the formula requests it (with `pour_bottle?`), if any options are specified on installation (bottles are all compiled with default options), if the bottle is not up to date (e.g. lacking a checksum) or the bottle's `cellar` is not `:any` or equal to the current `HOMEBREW_CELLAR`.

18
share/doc/homebrew/Brew-Test-Bot-For-Core-Contributors.md
View File

@ -1,10 +1,7 @@
# Brew Test Bot For Core Contributors
If a build has run and passed on `brew test-bot` then it can be used to quickly bottle formulae.
There are three types of Jenkins jobs:
## [Homebrew](http://bot.brew.sh/job/Homebrew/)
This job automatically builds anything committed to the master branch. On failure it sends an email to `brew-test-bot@googlegroups.com`. It tests rather than builds bottles.
There are two types of Jenkins jobs you will interact with:
## [Homebrew Pull Requests](http://bot.brew.sh/job/Homebrew%20Pull%20Requests/)
This job automatically builds any pull requests submitted to Homebrew/homebrew. On success or failure it updates the pull request status (see more details on the [main Brew Test Bot wiki page](Brew-Test-Bot.md)). On a successful build it automatically uploads bottles.
@ -19,15 +16,10 @@ To pull and bottle a pull request with `brew pull`:
1. Ensure the job has already completed successfully.
2. Run `brew pull --bottle 12345` where `12345` is the pull request number (or URL). If it complains about a missing URL with `BrewTestBot` in it then the bottles have not finished uploading yet; wait and try again later.
3. Run `brew fetch --force-bottle $FORMULAE` to check the SHA-256 in the bottled formulae match the uploaded files.
4. Run `git push` to push the commits.
3. Run `git push` to push the commits.
To bottle a test build or pull request without `brew pull`:
To bottle a test build :
1. Ensure the job has already completed successfully.
2. For testing builds note the job number (e.g. `123`). For pull request builds note the pull request number (e.g. `45678`).
3. Run `git fetch --tags https://github.com/BrewTestBot/homebrew.git`
4. For testing builds run `git merge testing-123` (where `123` is the testing job number). For pull requests builds run `git merge pr-45678` (where `45678` is the pull request number).
5. Run `git rebase origin/master` to get rid of any nasty merge commits.
6. Run `brew fetch --force-bottle $FORMULAE` to check the SHA-256 in the bottled formulae match the uploaded files.
7. Run `git push` to push the commits.
2. Run `brew pull --bottle http://bot.brew.sh/job/Homebrew%20Testing/1234/` where `http://bot.brew.sh/job/Homebrew%20Testing/1234/` is the testing build URL in Jenkins.
3. Run `git push` to push the commits.

4
share/doc/homebrew/Brew-Test-Bot.md
View File

@ -10,10 +10,6 @@ requests and custom builds requested by maintainers.
## Pull Requests
There is [a brew test-bot mailing list on Google Groups](https://groups.google.com/forum/#!forum/brew-test-bot)
which emails its members any failed builds that failed on the Homebrew master
branch.
The bot automatically builds pull requests and updates their status depending
on the result of the job.

2
share/doc/homebrew/External-Commands.md
View File

@ -1,7 +1,7 @@
# External Commands
Homebrew, like Git, supports *external commands*. This lets you create new commands that can be run like:
```
```shell
$ brew mycommand --option1 --option3 formula
```

12
share/doc/homebrew/FAQ.md
View File

@ -80,14 +80,10 @@ including how to set this across reboots. If you’re pre-Mountain Lion,
alternative](https://developer.apple.com/legacy/library/qa/qa1067/_index.html).
### How do I contribute to Homebrew?
Read everything in https://github.com/Homebrew/homebrew/blob/master/CONTRIBUTING.md.
Read [CONTRIBUTING.md](/CONTRIBUTING.md).
### Why do you compile everything?
Homebrew is about **homebrewing**, it’s half the point that you can just
`brew edit $FORMULA` and change how the formula is compiled to your own
specification.
Homebrew does provide pre-compiled versions for some formulae. These
Homebrew provides pre-compiled versions for some formulae. These
pre-compiled versions are referred to as **bottles** and are available
at:
[https://bintray.com/homebrew/bottles](https://bintray.com/homebrew/bottles).
@ -126,7 +122,7 @@ Or:
`brew pull https://github.com/Homebrew/homebrew/pulls/1234`
### Why does Homebrew insist I install to `/usr/local` with such vehemence?
### Why does Homebrew insist I install to `/usr/local`?
<a name="usrlocal"></a>
1. **It’s easier**<br>`/usr/local/bin` is already in your
@ -235,7 +231,7 @@ brew install …
Note that brew search still finds formula in taps.
### Homebrew is a poor name, it is generic, why was it chosen?
mxcl was too concerned with the beer theme and didn’t consider that the
@mxcl was too concerned with the beer theme and didn’t consider that the
project may actually prove popular. By the time he realized it was too
late. However, today, the first google hit for “homebrew” is not beer
related ;-)

607
share/doc/homebrew/Formula-Cookbook.md
View File

@ -1,145 +1,94 @@
# 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.
A formula is a package definition written in Ruby. It can be created with `brew create $URL` and installed with `brew install $FORMULA` and debugged with `brew install --debug --verbose $FORMULA`. Formulae use the [Formula API](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula) which provides various Homebrew-specific helpers.
We want your formula to be awesome, and the cookbook will tell you how.
## API documentation
Some people find it easier to jump straight into API documentation rather than a walkthrough. If you're one of these check out the [Formula API](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula) which shows all the stuff you can use in a Homebrew Formula.
## 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._
## Homebrew Terminology
| Term | Description | Example |
|----------------|------------------------------------------------------------|------------------------------------------------------|
| **Formula** | The package definition | `/usr/local/Library/Formula/foo.rb` |
| **Keg** | The installation prefix of a **Formula** | `/usr/local/Cellar/foo/0.1` |
| **opt prefix** | A symlink to the active version of a **Keg** | `/usr/local/opt/foo ` |
| **Cellar** | All **Kegs** are installed here | `/usr/local/Cellar` |
| **Tap** | An optional Git repository of **Formulae** and/or commands | `/usr/local/Library/Taps/homebrew/homebrew-versions` |
| **Bottle** | Pre-built **Keg** used instead of building from source | `qt-4.8.4.mavericks.bottle.tar.gz` |
## 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`.
Homebrew uses Git for downloading updates and contributing to the project.
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 `/usr/local/Library/Formula`. Check one out a simple one e.g. `brew edit etl` (or [etl](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/etl.rb)) or a more advanced one e.g. `brew edit git` or [Git](https://github.com/Homebrew/homebrew/tree/master/Library/Formula/git.rb).
# 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:
Before submitting a new formula 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 in another official [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
* is still supported by upstream (i.e. doesn't require extensive patching)
* 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 versions belong.
* passes all `brew audit --strict --online $FORMULA` tests.
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.
Before submitting a new formula make sure you read over our [contribution guidelines](https://github.com/Homebrew/homebrew/blob/master/CONTRIBUTING.md).
## Grab the URL
All you need to make a formula is a URL to the tarball.
Run `brew create` with a URL to the source tarball:
brew create https://example.com/foo-0.1.tar.gz
```shell
brew create https://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:
This creates `/usr/local/Library/Formula/foo.rb` and opens it in your `$EDITOR`. It'll look something like:
```ruby
class Foo < Formula
url "https://example.com/foo-0.1.tar.gz"
desc ""
homepage ""
url "https://example.com/foo-0.1.tar.gz"
sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7"
# depends_on "cmake" => :build
def install
system "./configure", "--prefix=#{prefix}", "--disable-debug", "--disable-dependency-tracking"
# system "cmake", ".", *std_cmake_args
# 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.
If `brew` said `Warning: Version cannot be determined from URL` when doing the `create` step, you’ll need to explicitly add the correct [`version`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#version-class_method) to the formula and then save the formula.
**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`.
Homebrew will try to guess the formula’s name from its URL. If it fails to do
so you can override this with `brew create <url> --set-name <name>`.
**Note:** Homebrew will try to guess the formula’s name from its URL. If it
fails to do so you can use `brew create <url> --set-name <name>`.
## Fill in the [`homepage`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#homepage%3D-class_method)
## Fill in the Homepage
**We don’t accept formulae without [`homepage`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#homepage%3D-class_method)s!**
**We don’t accept formulae without homepages!**
A SSL/TLS (https) [`homepage`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#homepage%3D-class_method) is preferred, if one is available.
SSL/TLS (https) homepage is preferred, if one is available.
Homebrew now has a description field (`desc`). Try and summarize this from the homepage.
Try to summarize from the [`homepage`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#homepage%3D-class_method) what the formula does in the [`desc`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#desc%3D-class_method)ription. Note that the [`desc`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#desc%3D-class_method)ription is automatically preprended with the formula name.
## Check the build system
brew install -i foo
```shell
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 the package’s `README`. Does the package install with `./configure`, `cmake`, or something else? Delete the commented out `cmake` lines if the package uses `./configure`.
## 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:
The `README` probably tells you about dependencies and Homebrew or OS X probably already has them. You can check for Homebrew dependencies with `brew search`. Some common dependencies that OS X comes with:
* `libexpat`
* `libGL`
@ -149,18 +98,17 @@ The `README` probably tells you about dependencies. Homebrew or OS X probably al
* `Python`
* `Ruby`
There are plenty of others. Check `/usr/lib` to see.
There are plenty of others; check `/usr/lib` for them.
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!)
We generally try to not duplicate system libraries and complicated tools in core Homebrew but we do duplicate some commonly used tools.
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)*.
One very 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 if it detects you haven't done this.
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’s OpenSSL is [`keg_only`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#keg_only-class_method) to avoid conflicting with the system so sometimes formulae need to have environmental variables set or special configuration flags passed to locate our 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`.
Homebrew maintains a special [tap that provides other useful system duplicates](https://github.com/Homebrew/homebrew-dupes).
*Important:* `$(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` or create a [`Requirement`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Requirement).
## Specifying other formulae as dependencies
@ -174,29 +122,33 @@ class Foo < Formula
end
```
A String specifies a formula dependency.
A String (e.g. `"jpeg"`) specifies a formula dependency.
A Symbol specifies a special conditional dependency, such as X11.
A Symbol (e.g. `:x11`) specifies a [`Requirement`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Requirement) which can be fulfilled by one or more formulae, casks or other system-wide installed software (e.g. X11).
A Hash (e.g. `=>`) specifies a formula dependency with some additional information. Given a single string key, the value can take several forms:
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):
- `:build` means that dependency is a build-time only dependency so it can
be skipped when installing from a bottle or 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 use 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"
```
```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.
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"
@ -204,21 +156,20 @@ A Hash specifies a formula dependency with some additional information. Given a
depends_on "foo" => [:optional, "with-bar"]
```
## Specifying conflicts with other formulae
## Specifying other formulae as conflicts
Sometimes there’s hard conflict between formulae, and it can’t be avoided or circumvented with `keg_only`.
Sometimes there’s hard conflict between formulae, and it can’t be avoided or circumvented with [`keg_only`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#keg_only-class_method).
`mbedtls` is a good [example](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/mbedtls.rb) formula for minor conflict.
`mbedtls` ships and compiles a "Hello World" executable. This is obviously non-essential to `mbedtls`’s functionality, and conflict with the popular GNU `hello` formula would be overkill, so we just remove it.
[pdftohtml](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/pdftohtml.rb) provides an example of a serious
conflict, where both formula ship a identically-named binary that is essential to functionality, so a `conflicts_with` is preferable.
conflict, where both formula ship a identically-named binary that is essential to functionality, so a [`conflicts_with`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#conflicts_with-class_method) is preferable.
As a general rule, `conflicts_with` should be a last-resort option. It’s a fairly blunt instrument.
As a general rule, [`conflicts_with`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#conflicts_with-class_method) should be a last-resort option. It’s a fairly blunt instrument.
The syntax for conflict that can’t be worked around is
The syntax for conflict that can’t be worked around is:
```ruby
conflicts_with "blueduck", :because => "yellowduck also ships a duck binary"
@ -226,39 +177,38 @@ 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.
In Homebrew we sometimes accept formulae updates that don’t include a version bump. These include 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.
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`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#revision%3D-class_method) 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).
Where a dependent of a formula fails against a new version of that dependency it must receive a [`revision`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#revision%3D-class_method). 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).
[`revision`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#revision%3D-class_method)s 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, it's 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)
When you already have a lot of formulae installed, it's easy to miss a common dependency. You can double-check which libraries a binary links to with the `otool` command (perhaps you need to use `xcrun otool`):
```shell
$ 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)
```
## Specifying gems, Python modules, Go projects, etc. as dependencies
Homebrew doesn’t package already packaged language-specific libraries. These should be installed directly from `gem`/`cpan`/`pip` etc.
If you're installing an application then please locally vendor all the language-specific dependencies:
If you're installing an application then please use [`resource`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#resource-class_method)s for all the language-specific dependencies:
```ruby
class Foo < Formula
@ -273,39 +223,25 @@ class Foo < Formula
end
```
[jrnl](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/jrnl.rb) is 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`.
[jrnl](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/jrnl.rb) is an example of a formula that does this well. The end result means the user doesn't have use `pip` or Python and can just run `jrnl`.
[homebrew-pypi-poet](https://github.com/tdsmith/homebrew-pypi-poet) can help you generate resource stanzas for the dependencies of your Python application.
[homebrew-pypi-poet](https://github.com/tdsmith/homebrew-pypi-poet) can help you generate resource stanzas for the dependencies of your Python application and [homebrew-go-resources](https://github.com/samertm/homebrew-go-resources) can help you generate go\_resource stanzas for the dependencies of your go application.
Similarly, [homebrew-go-resources](https://github.com/samertm/homebrew-go-resources) can help you generate go\_resource stanzas for the dependencies of your go application.
## Install the formula
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
```shell
brew install --verbose --debug foo
```
Note that we probably won't accept the formulae in this case; it's a far worse user experience than vendoring libraries with resources.
`--debug` will ask you to open an interactive shell if the build fails so you can try to figure out what went wrong.
## 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.
Check the top of the e.g. `./configure` output. Some configure scripts do not recognize e.g. `--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).
Please add a [`test do`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#test-class_method) 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.
The [`test do`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#test-class_method) block automatically creates and changes to a temporary directory which is deleted after run. You can access this [`Pathname`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Pathname) with the [`testpath`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#testpath-instance_method) 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.
@ -313,28 +249,23 @@ See [cmake](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/cma
## 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.
Homebrew expects to find manual 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.
[ALSO CHECK WHAT DEBIAN CALLS IT!](https://www.debian.org/distrib/packages)
If you’re not sure about the name check the homepage, and check the Wikipedia page and [what Debian call it](https://www.debian.org/distrib/packages).
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 ;)
If you’re *still* not sure, just commit. We’ll apply some arbitrary rule and make a decision :wink:.
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:
@ -345,109 +276,88 @@ Thus, if you change the name of the class, you must also rename the file. Filena
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. The audit command 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.
You can run `brew audit --strict --online` to test formulae for adherence to Homebrew house style. The `audit` command 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 quicker for everyone.
New formulae being submitted to Homebrew should run `brew audit <formula name> --strict --online`. This command is performed by the Brew Test Bot on new submissions as part of the automated build and test process, and highlights more potential issues than the standard audit.
New formulae being submitted to Homebrew should run `brew audit --strict --online foo`. This command is performed by the Brew Test Bot on new submissions as part of the automated build and test process, and highlights more potential issues than the standard audit.
Use `brew info` and check if the version guessed by Homebrew from the URL is
correct. Add an explicit `version` if not.
correct. Add an explicit [`version`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#version-class_method) if not.
## 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
```shell
brew update # required in more ways than you think (initializes the brew git repository if you don't already have it)
cd /usr/local
# 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
* the first line is a commit summary of *50 characters or less*
* two (2) newlines, then
* explain the commit throughly
At Homebrew, we like to put the name of the formula up front like so: "foobar 7.3 (new formula)".
At Homebrew, we like to put the name of the formula up front 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.
The preferred commit message format for simple version updates is `foobar 7.3` and for fixes is `foobar: fix flibble matrix.`.
Ensure you reference any relevant GitHub issue e.g. `Closes #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.
## Push
Now you just need to push back to GitHub.
Now you just need to push your commit to GitHub.
If you haven’t forked Homebrew yet, [go to the repo and hit the fork button](https://github.com/Homebrew/homebrew).
If you have already forked Homebrew on GitHub, then you can manually push (just make sure you have been pulling from the Homebrew/homebrew master):
git push git@github.com:myname/homebrew.git <what-you-called-your-branch>
```shell
git push https://github.com/myname/homebrew/ <what-you-called-your-branch>
```
Now, please open a Pull Request (on your GitHub repo page) for new and updated brews.
Now, please [open a pull request](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md#how-to-open-a-homebrew-pull-request-and-get-it-merged) for your changes.
* One formula per commit; one commit per formula
* Keep merge commits out of the request
* If you have any merge or mixup commits, please [squash](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) them.
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.)
* A temporary sandbox is created in `/tmp/$formulaname`
* `DownloadStrategy.stage` is called (extracts tarball to above sandbox, exports git repository to sandbox, etc.)
* Patches are applied
* Current directory is changed to the stage root (so when you `system make`, it works)
* `Formula.install` is called
* Anything installed to the keg is cleaned (see later)
* The keg is symlinked into Homebrew’s prefix
* Caveats are displayed
* Keep merge commits out of the pull request
# Convenience Tools
## Messaging
Three commands are provided for displaying informational messages to the user:
* `ohai` for general info
* `opoo` for warning messages
* `onoe` for error messages
* `odie` for error messages and immediately exiting
In particular, when a test needs to be performed before installation use `onoe` to bail out gracefully. For example:
```ruby
if some_test?
system "make", "install"
else
onoe "Error! Something is wrong."
if build.with?("qt") && build.with("qt5")
odie "Options --with-qt and --with-qt5 are mutually exclusive."
end
system "make", "install"
```
## `bin.install "foo"`
## bin.install "foo"
You’ll see stuff like that in other formulae. This moves the file `foo` into the Formula’s `bin` directory (`/usr/local/Cellar/pkg/0.1/bin`) and makes it executable (`chmod 0555 foo`).
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`).
## inreplace
## [`inreplace`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Utils/Inreplace)
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:
`before` and `after` can be strings or regular expressions. You can also use the block form:
```ruby
inreplace "path" do |s|
@ -457,9 +367,9 @@ 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.
`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 something that affects both Homebrew and MacPorts (i.e. OS X specific) it should be turned into an upstream submitted patch instead.
If you need modify variables in a Makefile, rather than using `inreplace`, pass them as arguments to make:
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"
@ -478,31 +388,31 @@ Note that values *can* contain unescaped spaces if you use the multiple-argument
## Patches
While patches should generally be avoided, sometimes they are necessary.
While [`patch`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#patch-class_method)es 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.
When [`patch`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#patch-class_method)ing (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).
*Always justify a [`patch`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#patch-class_method) 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:
External [`patch`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#patch-class_method)es can be declared using resource-style blocks:
```rb
```ruby
patch do
url "https://example.com/example_patch.diff"
sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7"
end
```
A strip level of -p1 is assumed. It can be overridden using a symbol argument:
A strip level of `-p1` is assumed. It can be overridden using a symbol argument:
```rb
```ruby
patch :p0 do
url "https://example.com/example_patch.diff"
sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7"
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`.
[`patch`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#patch-class_method)es can be declared in [`stable`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#stable-class_method), [`devel`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#devel-class_method), and [`head`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#head-class_method) 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
@ -541,33 +451,42 @@ 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
```shell
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.)
Instead of `git diff | pbcopy`, for some editors `git diff >> path/to/your/formula/foo.rb` might help you ensure that the patch is not touched (e.g. white space removal, indentation, etc.)
# 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 document if you think it will help!
If anything isn’t clear, you can usually figure it out by `grep`ping the `Library/Formula` directory. Please submit a pull request to amend this document if you think it will help!
## Unstable versions (`devel`, `head`)
## Unstable versions (`HEAD`, `devel`)
Formulae can specify alternate downloads for the upstream project’s [`devel`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#devel-class_method) release (unstable but not `master`/`trunk`) or [`head`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#head-class_method) (`master`/`trunk`).
Formulae can specify alternate downloads for the upstream project’s `devel` release (unstable but not `trunk`) or `HEAD` (`master/trunk`).
### `devel`
### HEAD
The [`devel`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#devel-class_method) spec (activated by passing `--devel`) is used for a project’s unstable releases. It is specified in a block:
HEAD URLs (activated by passing `--HEAD`) build the development cutting edge. Specifying it is easy:
```ruby
devel do
url "https://foo.com/foo-0.1.tar.gz"
sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7"
end
```
You can test if the `devel` spec is in use with `build.devel?`.
### `head`
[`head`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#head-class_method) URLs (activated by passing `--HEAD`) build the development cutting edge. Specifying it is easy:
```ruby
class Foo < Formula
@ -575,9 +494,9 @@ class Foo < Formula
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?`.
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`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#head-class_method) is being built with `build.head?`.
To use a specific commit, tag, or branch from a repository, specify head with the `:tag` and `:revision`, `:revision`, or `:branch` option, like so:
To use a specific commit, tag, or branch from a repository, specify [`head`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#head-class_method) with the `:tag` and `:revision`, `:revision`, or `:branch` option, like so:
```ruby
class Foo < Formula
@ -588,24 +507,9 @@ class Foo < Formula
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"
sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7"
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:
Sometimes a package fails to build when using a certain compiler. Since recent Xcodes no longer include a GCC compiler we cannot simply force the use of GCC. Instead, the correct way to declare this is the [`fails_with` DSL method](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#fails_with-class_method). A properly constructed [`fails_with`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#fails_with-class_method) 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
@ -619,10 +523,9 @@ fails_with :llvm do
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).
`build` takes a Fixnum (an integer; 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`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#fails_with-class_method) 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
@ -636,53 +539,20 @@ class Python3 < Formula
head "https://hg.python.org/cpython", :using => :hg
```
The downloaders offered by Homebrew are:
Download strategies offered by Homebrew are:
<table>
<thead>
<tr>
<th>Value of <code>:using</code></th>
<th>Corresponds To</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>:bzr</code></td>
<td><code>BazaarDownloadStrategy</code></td>
</tr>
<tr>
<td><code>:curl</code></td>
<td><code>CurlDownloadStrategy</code></td>
</tr>
<tr>
<td><code>:cvs</code></td>
<td><code>CVSDownloadStrategy</code></td>
</tr>
<tr>
<td><code>:git</code></td>
<td><code>GitDownloadStrategy</code></td>
</tr>
<tr>
<td><code>:hg</code></td>
<td><code>MercurialDownloadStrategy</code></td>
</tr>
<tr>
<td><code>:nounzip</code></td>
<td><code>NoUnzipCurlDownloadStrategy</code></td>
</tr>
<tr>
<td><code>:post</code></td>
<td><code>CurlPostDownloadStrategy</code></td>
</tr>
<tr>
<td><code>:svn</code></td>
<td><code>SubversionDownloadStrategy</code></td>
</tr>
</tbody>
</table>
| `:using` value | download strategy |
|----------------|-------------------------------|
| `:bzr` | `BazaarDownloadStrategy` |
| `:curl` | `CurlDownloadStrategy` |
| `:cvs` | `CVSDownloadStrategy` |
| `:git` | `GitDownloadStrategy` |
| `:hg` | `MercurialDownloadStrategy` |
| `:nounzip` | `NoUnzipCurlDownloadStrategy` |
| `:post` | `CurlPostDownloadStrategy` |
| `:svn` | `SubversionDownloadStrategy` |
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:
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`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#url-class_method) method's `:using` option:
```ruby
@ -695,20 +565,11 @@ class Foo < Formula
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
## Just moving 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:
So it is easy to just move some files:
```ruby
prefix.install "file1", "file2"
@ -827,32 +688,21 @@ These can be used, for instance, in code such as
bin.install Dir["output/*"]
```
to install binaries into their correct location into the cellar, and
to move binaries into their correct location into the cellar, and
```ruby
man.mkpath
```
to create the directory structure to the man location.
to create the directory structure to the manual page location.
To install man pages into specific locations, use `man1.install "foo.1", "bar.1"`, `man2.install "foo.2"`, etc.
Note that in the context of Homebrew, `libexec` is reserved for private use by the formula and therefore is not symlinked into `HOMEBREW_PREFIX`.
### Installation without linking into `/usr/local` (keg-only)
If you only need a program for a dependency and it does not need to be linked for public use in `/usr/local`, specify
```ruby
keg_only "This is my rationale."
```
in the Formula class.
Note that in the context of Homebrew, [`libexec`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#libexec-instance_method) is reserved for private use by the formula and therefore is not symlinked into `HOMEBREW_PREFIX`.
## Adding optional steps
If you want to add an option:
If you want to add an [`option`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#option-class_method):
```ruby
class Yourformula < Formula
@ -864,7 +714,7 @@ class Yourformula < Formula
...
```
And then to define the effects the options have:
And then to define the effects the [`option`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#option-class_method)s have:
```ruby
if build.with? "ham"
@ -876,24 +726,24 @@ if build.without? "ham"
end
```
Option names should be prefixed with the words `with` or `without`. 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 `--with-shared` rather than `--shared` or `--enable-shared`.
[`option`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#option-class_method) names should be prefixed with the words `with` or `without`. 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 `--with-shared` rather than `--shared` or `--enable-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.
Note that [`option`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#option-class_method)s that aren’t `build.with? ` or `build.without?` should be deprecated with [`deprecated_option`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#deprecated_option-class_method). See [wget](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/wget.rb#L27-L31) 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).
You can use the file utilities provided by Ruby's [`FileUtils`](http://www.ruby-doc.org/stdlib/libdoc/fileutils/rdoc/index.html). These are included in the `Formula` class, so you do not need the `FileUtils.` prefix to use them.
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
```ruby
bin.install_symlink libexec/"name"
```
*not*
instead of:
```rb
```ruby
ln_s libexec/"name", bin
```
@ -905,6 +755,7 @@ For example, Ruby 1.9’s gems should be installed to `var/lib/ruby/` so that ge
### launchd plist files
<<<<<<< 12f42a6761cb29ed3c9715fe2cbccff02bdc448f
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`.
## Updating formulae
@ -923,37 +774,24 @@ Homebrew wants to maintain a consistent Ruby style across all formulae based on
* An empty line is required before the `__END__` line
=======
Homebrew provides two Formula methods for launchd plist files. [`plist_name`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#plist_name-instance_method) will return e.g. `homebrew.mxcl.<formula>` and [`plist_path`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#plist_path-instance_method) will return e.g. `/usr/local/Cellar/foo/0.1/homebrew.mxcl.foo.plist`.
>>>>>>> Overhaul, simplify and cleanup documentation.
# 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
```
Homebrew tries to automatically determine the [`version`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#version-class_method) from the [`url`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#url-class_method) in avoid duplication. If the tarball has an unusual name you may need to manually assign the [`version`](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula#version-class_method).
## 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).
Not all projects have makefiles that will run in parallel so try to deparallelize by adding these lines to the `install` method:
```ruby
class Foo < Formula
skip_clean :all
def install
ENV.deparallelize
ENV.no_optimization
system "make" # separate make and make install steps
system "make", "install"
end
end
ENV.deparallelize
system "make" # separate make and make install steps
system "make", "install"
```
If that fixes it, please open an [issue](https://github.com/Homebrew/homebrew/issues) so that we can fix it for everyone.
@ -962,39 +800,30 @@ If that fixes it, please open an [issue](https://github.com/Homebrew/homebrew/is
Check out what MacPorts and Fink do:
`brew -S --macports foo`
`brew -S --fink foo`
```shell
brew -S --macports foo
brew -S --fink foo
```
# Superenv Notes
`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.
`superenv` is our "super environment" that isolates builds by removing `/usr/local/bin` and all user `PATH`s that are not essential for the build. It does this because user `PATH`s are often full of stuff that breaks builds. `superenv` also removes 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.
# 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.
Some software requires a Fortran compiler. This can be declared by adding `depends_on :fortran` to a formula. `:fortran` is a `Requirement` 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.
When using Homebrew's `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 upstream `master`)
# How to start over (reset to `master`)?
Have you created a real mess in git which stops you from creating a commit you want to submit to us? You might want to consider consider starting again from scratch. Your changes can be reset to the Homebrew's `master` branch by running:
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:
`git checkout master`
`git reset --hard FETCH_HEAD`
```shell
git checkout -f master
git reset --hard origin/master
```

38
share/doc/homebrew/Homebrew-0.8.md
View File

@ -1,38 +0,0 @@
# Homebrew 0.8
On March 12, 2011, the "refactor" branch was merged into trunk, and Homebrew bumped to version 0.8.
The major user-visible change in this version is that all Homebrew commands have been split out into separate ruby files, in the "Library/Homebrew/cmd" folder. Adding a new core command now means adding a new file to the "cmd" folder, following the same pattern as in other files.
In addition, external commands can now override core commands, so if you have an executable "brew-remove.rb" in your path ahead of "brew", that version of "remove" will be used instead of the core command. **Please use caution when using this feature** as we can't help you diagnose other build problems if you override built-in commands. This feature is meant for deep tinkering, and trying out new features without modifying core directly.
The guts of Homebrew, utility modules and whatnot, have also been reorganized and cleaned up, for the better we think. Xcode detection in particular has been redone, which should make it easier to support Xcode 4 / Lion, which is a very high priority for the project.
Also pushed with this release is some improvements in support for Fortran-based projects, including "R".
### Formula acceptance policy
Homebrew still tries not to duplicate system-provided functionality. There are cases, especially in order to support Leopard, where newer versions of system-provided software is duplicated in Homebrew, but we are trying to be tougher on accepting duplicates.
Software that requires patching to build on OS X is OK, but patches should (A) be properly sourced and documented and (B) every attempt should be made to get the upstream project to take the OS X patch upstream. MacPorts is a useful starting point for patches, but remember that they often patch more heavily than Homebrew-based formulae need to (often not submitting patches upstream), so do try to create a minimal version of any patch sourced from MacPorts.
### External Repos
Note that Homebrew (prior to 0.8) can install brews from URLs and absolute path names, so it is no longer necessary for all brews to live in the core Library. The previous "duplicates" branch maintained by adamv has been deprecated and replaced with the [Homebrew-Alt](https://github.com/adamv/homebrew-alt) repository.
Homebrew-Alt has a more liberal formula acceptance policy, and we may direct pull requests to this repository instead in some cases.
### Issues
If you do have Xcode 4 installed, and brews are failing due to llvm-gcc, there are new "--use-gcc" and "HOMEBREW_USE_GCC" flags to force use of GCC 4.2 while we work on an integrated solution.
If you have modified core Homebrew files, chances are this change won't merge or rebase cleanly for you. We apologize for this, but feel that it was important to do a "big bang cleanup" prior to any "1.0" release.
### The Future
The future is unwritten.
But current priorities include:
* Proper Xcode 4 support, along with maintaining Xcode 3.2.x support for the time being
* Proper Lion support, when it releases, including handling its new and updated system-provided libraries
* Multi-repo support, to allow file-only repos including dependency resolution
Other avenues of exploration include:
* Providing (mostly) stable textual outputs on some commands, like git does, so external tools can have stable outputs to parse

34
share/doc/homebrew/Homebrew-0.9.3.md
View File

@ -1,34 +0,0 @@
# Homebrew 0.9.3
## What is Superenv?
**Superenv** is an attempt to improve build-reliability and end-build-quality. It is:
* The user’s `PATH` is ignored. Thus, only tools we authorize can be used during builds<sup>[1](#_1)</sup>.
* `PATH` is reconstructed. For example: `/usr/local/Library/$ENV/4.3:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`.
* `/usr/local/Library/$ENV/4.3` (`superbin`<sup>[2](#_2)</sup>) contains wrapper-scripts for `cc`, etc.)
* We unset all build-related `ENV` variables.
* Build systems now pick their preferred compilers from `superbin`.
* `superbin` scripts are smart. They forcibly insert all include-paths and library-paths that Homebrew formulae need to compile, as well as remove flags that break builds.
## Rationale & Benefits
Because we are working with a practically virgin environment, we are essentially giving build-systems the kind of environments that the developers are using to build with. This makes them more reliable. By stepping into the toolchain between the build-system and the compiler, we have complete control over the toolchain. We can prevent a good deal of breakage, and it ensures that Homebrew uses the same executables that the compiler sees (and not those bundled with the system).
So:
* We no longer worry about MacPorts/Fink being installed<sup>[0](#_0)</sup>
* We no longer worry about system duplicates<sup>[0](#_0)</sup>
* We override common tools and fix them—we no longer have to do so with workarounds in affected formula, waiting for a fix from Apple.
* Builds are forcibly optimized how we want, and debug info forcibly removed.
----
## Footnotes
<div style="color: #555; font-size: 85%">
<ul>
<li><a id="_0"><sup>0</sup></a>: Nearly as much, anyway.</li>
<li><a id="_1"><sup>1</sup></a>: Formula can opt-into re-adding the user’s <code>PATH</code> again. Some formulae need this.</li>
<li><a id="_2"><sup>2</sup></a>: Indeed; this is selected based on Xcode version.</li>
</ul>
</div>

28
share/doc/homebrew/Homebrew-0.9.md
View File

@ -1,28 +0,0 @@
# Homebrew 0.9
The main new feature in Homebrew-0.9 is `brew tap`.
brew-tap allows you to import formula from other repositories into your Homebrew instance. For example:
brew tap josegonzalez/php
Will install the recently deleted PHP formula that @josegonzalez maintains because he's the expert and we're not.
We are planning to remove some of the longtail and move it into the new Homebrew organization so that we can keep the formula in mxcl/master in better shape.
`brew search` has been adapted to search over the common taps. So movement of formula will not cause you to not find the formula you are looking for.
Tap has many possibilities; for example, does your organization have its own Homebrew fork with its own custom formula? Well now you can just have a tap and stop having to merge mxcl/master with your own fork all the time.
This also means we will have a dedicated dupes tap so that people can stop asking us to put dupes in mxcl/master. Perhaps you want a formula for every ruby gem? Now you can make a tap!
Formula in mxcl/master cannot be overwritten, so to install a "conflict" you can use an extended syntax, eg:
brew install homebrew/dupes/gcc42
To untap, use `brew untap`.
Formula can depend on formula from other taps:
depends_on "homebrew/dupes/tcl-tk"
Though this will not install the tap, it will prompt the user to do that first.

3
share/doc/homebrew/Homebrew-2.md
View File

@ -1,3 +0,0 @@
# Homebrew 2
Idea for Homebrew 2:
* https://github.com/Homebrew/homebrew/issues/11041

29
share/doc/homebrew/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md
View File

@ -10,7 +10,7 @@ As an example:
That’s because Homebrew keeps it locked away in its prefix, accessible only via its opt directory. `keg_only` = Not symlinked into the `$PATH` by default.
### But how do I get non-Homebrew builds to find those tools?
### How do I get non-Homebrew builds to find those tools?
A number of people in this situation are either forcefully linking `keg_only` tools with `brew link --force` or moving default system utilities out of the `$PATH` and replacing them with manually-created symlinks to the Homebrew-provided tool.
@ -20,22 +20,31 @@ It is also incredibly difficult to debug a build failure if you make changes to
If you’ve linked something and there’s no problems at all? Awesome, feel free to ignore the `brew doctor` error. But *please* don’t try to go around it. It’s really hard to help you out if we don’t know the full picture, and we *want* to be able to help you if you get stuck.
### Alright. Stop complaining at me, I get it - but how do I use those tools outside of Homebrew?
### How do I use those tools outside of Homebrew?
Useful, reliable alternatives exist should you desire to use `keg_only` tools outside of Homebrew’s build processes:
----
You can set flags to give configure scripts or Makefiles a nudge in the right direction. An example of flag setting:
`./configure --prefix=/Users/Dave/Downloads CFLAGS=-I$(brew --prefix)/opt/openssl/include LDFLAGS=-L$(brew --prefix)/opt/openssl/lib`
```shell
./configure --prefix=/Users/Dave/Downloads CFLAGS=-I$(brew --prefix)/opt/openssl/include LDFLAGS=-L$(brew --prefix)/opt/openssl/lib
```
An example using `pip`:
`CFLAGS=-I$(brew --prefix)/opt/icu4c/include LDFLAGS=-L$(brew --prefix)/opt/icu4c/lib pip install pyicu`
```shell
CFLAGS=-I$(brew --prefix)/opt/icu4c/include LDFLAGS=-L$(brew --prefix)/opt/icu4c/lib pip install pyicu
```
----
You can temporarily prepend your `$PATH` with the tool’s bin directory, such as:
`export PATH=$(brew --prefix)/opt/openssl/bin:$PATH`
```shell
export PATH=$(brew --prefix)/opt/openssl/bin:$PATH
```
This will immediately move that folder to the front of your `$PATH`, ensuring any build script that searches the `$PATH` will find it.
Changing your `$PATH` using that command ensures the change only exists for the duration of that shell session. Once you are no longer in that terminal tab/window, the `$PATH` ceases to be prepended.
@ -45,9 +54,15 @@ Changing your `$PATH` using that command ensures the change only exists for the
If the tool you are attempting to build is [pkg-config](https://en.wikipedia.org/wiki/Pkg-config) aware, you can amend your `PKG_CONFIG_PATH` to find that `keg_only` utility’s `.pc` file, if it has one. Not all formulae ship with those files.
An example of that is:
`export PKG_CONFIG_PATH=$(brew --prefix)/opt/openssl/lib/pkgconfig `
```shell
export PKG_CONFIG_PATH=$(brew --prefix)/opt/openssl/lib/pkgconfig
```
If you’re curious about `PKG_CONFIG_PATH` and which paths it searches by default, `man pkg-config` goes into detail on that.
You can also get `pkg-config` to detail its currently searched paths with:
`pkg-config --variable pc_path pkg-config`
```shell
pkg-config --variable pc_path pkg-config`
```

74
share/doc/homebrew/Installation.md
View File

@ -3,45 +3,26 @@ The suggested and easiest way to install Homebrew is on the
[homepage](http://brew.sh).
The standard script installs Homebrew to `/usr/local` so that
[you don’t need sudo](FAQ.md#why-does-homebrew-say-sudo-is-bad-) when you `brew install`. It is a
careful script, it can be run even if you have stuff installed to
`/usr/local` already. It tells you exactly what it will do before it
does it too. And you have to confirm everything it will do before it
starts.
There are other ways to install Homebrew which provide you with more
flexibility. They are listed below the requirements.
[you don’t need sudo](FAQ.md#why-does-homebrew-say-sudo-is-bad-) when you
`brew install`. It is a careful script, it can be run even if you have stuff
installed to `/usr/local` already. It tells you exactly what it will do before
it does it too. And you have to confirm everything it will do before it starts.
## Requirements
* An Intel CPU <sup>[1](#1)</sup>
* OS X 10.6 or higher <sup>[2](#2)</sup>
* OS X 10.9 or higher <sup>[2](#2)</sup>
* Command Line Tools for Xcode: `xcode-select --install`,
https://developer.apple.com/downloads or
[Xcode](https://itunes.apple.com/us/app/xcode/id497799835) <sup>[3](#3)</sup>
* A Bourne-compatible shell for installation (e.g. bash or zsh) <sup>[4](#4)</sup>
If you want to build software that utilizes X11 components, you’ll need
to install [XQuartz](https://xquartz.macosforge.org). Apple provided a
distribution of XQuartz (“X11.app”) prior to OS X 10.8. This is
supported where possible, but many projects now require more up-to-date
libraries than those in the Apple distribution, so installing the
[latest version available for your
OS](https://xquartz.macosforge.org/trac/wiki/Releases) is recommended.
On 10.8 and newer, you should install the [most recent
version](https://xquartz.macosforge.org).
If you want to build Java bindings (in software such as Subversion,
Berkeley-DB, CMake, etc.) Apple’s “Java Developer Update” is required.
The latest versions are “Update 10” for 10.5 and “Update 9” for 10.6.
## Alternative Installs
### Untar anywhere
Just extract (or `git clone`) Homebrew wherever you want. Just
avoid:
* Directories with names that contain spaces. Homebrew itself can handle spaces, but many build scripts cannot.
* `/sw` and `/opt/local` because build scripts get confused when
Homebrew is there instead of Fink or MacPorts, respectively.
* `/sw` and `/opt/local` because build scripts get confused when Homebrew is there instead of Fink or MacPorts, respectively.
However do yourself a favor and install to `/usr/local`. Some things may
not build when installed elsewhere. One of the reasons Homebrew just
@ -50,42 +31,27 @@ to `/usr/local`. *Pick another prefix at your peril!*
`mkdir homebrew && curl -L https://github.com/Homebrew/homebrew/tarball/master | tar xz --strip 1 -C homebrew`
### Untar anywhere and then symlink the `brew` command elsewhere
You can also install Homebrew into e.g.
`~/Developer` and then symlink the brew command into `/usr/local/bin`.
Everything will install into `~/Developer`, but your
brew command is still in the path. **NOTE** that Homebrew will still
need to create symlinks into `/usr/local` or nothing will
work! But the actual files are installed to
`~/Developer/Cellar`.
### Multiple installations
Create a Homebrew installation wherever you extract the tarball. Whichever brew command is called is where the packages will be installed. You can use this as you see fit, e.g. a system set of libs in `/usr/local` and tweaked formulae for development in `~/homebrew`.
### Ignoring SSL certificate errors (not recommended)
The instructions on the homepage use `curl` to download a Ruby script
from GitHub over HTTPS. Older versions of OS X may not have the necessary CA
certificates to verify GitHub's SSL certificate. In that case, you can
add `--insecure` to the `curl` command, forcing `curl` to ignore SSL certificate errors.
This will leave your connection to GitHub vulnerable to MITM, and is <strong>not recommended</strong>.
You may consider updating your CA certificates instead.
## Uninstallation
Uninstallation is documented in the [FAQ](FAQ.md).
<a name="1"><sup>1</sup></a> Not all formulae have CPU or OS requirements, but you can assume
you will have trouble if you don’t conform. Also, you can find
PowerPC and Tiger branches from other users in the fork network. See
[Interesting Taps & Branches](Interesting-Taps-&-Branches.md).
<a name="1"><sup>1</sup></a> Not all formulae have CPU or OS requirements, but
you can assume you will have trouble if you don’t conform. Also, you can find
PowerPC and Tiger branches from other users in the fork network. See
[Interesting Taps & Branches](Interesting-Taps-&-Branches.md).
<a name="2"><sup>2</sup></a> 10.7 or higher is recommended. 10.6 is supported on a
best-effort basis. For 10.4 and 10.5, see [Tigerbrew](https://github.com/mistydemeo/tigerbrew).
<a name="2"><sup>2</sup></a> 10.9 or higher is recommended. 10.5 - 10.8 are
supported on a best-effort basis. For 10.4 and 10.5, see
[Tigerbrew](https://github.com/mistydemeo/tigerbrew).
<a name="3"><sup>3</sup></a> Most formulae require a compiler. A handful require a full Xcode
installation. You can install Xcode, the CLT, or both; Homebrew
supports all three configurations. Downloading Xcode may require an Apple Developer account on older versions of OS X. Sign up for free [here](https://developer.apple.com/register/index.action).
<a name="3"><sup>3</sup></a> Most formulae require a compiler. A handful
require a full Xcode installation. You can install Xcode, the CLT, or both;
Homebrew supports all three configurations. Downloading Xcode may require an
Apple Developer account on older versions of OS X. Sign up for free
[here](https://developer.apple.com/register/index.action).
<a name="4"><sup>4</sup></a> The one-liner installation method found on
[brew.sh](http://brew.sh) requires a Bourne-compatible shell (e.g.
bash or zsh). Notably, fish, tcsh and csh will not work.
[brew.sh](http://brew.sh) requires a Bourne-compatible shell (e.g. bash or
zsh). Notably, fish, tcsh and csh will not work.

4
share/doc/homebrew/Interesting-Taps-&-Branches.md
View File

@ -52,14 +52,12 @@ You can be added as a maintainer for one of the Homebrew organization taps and a
* [titanous/gnuradio](https://github.com/titanous/homebrew-gnuradio): GNU Radio and friends running on OS X.
## Interesting Branches (aka forks)
## Interesting Forks
* [mistydemeo/tigerbrew](https://github.com/mistydemeo/tigerbrew): Experimental Tiger PowerPC version
* [homebrew/linuxbrew](https://github.com/Homebrew/linuxbrew): Experimental Linux version
* [wilmoore/homebrew-home](https://github.com/wilmoore/homebrew-home): Homebrew install for those that like to Homebrew @ $HOME (i.e. ~/.homebrew).
* [nddrylliog/homebrew-mingw](https://github.com/nddrylliog/homebrew-mingw): An experimental port of Homebrew for Windows (with an MSYS/MinGW environment).
## Technical Details

19
share/doc/homebrew/Maintainer-Guidelines.md
View File

@ -31,12 +31,12 @@ For example, we build Wireshark, but not the monolithic GUI. If users want
that, they should just grab the DMG that Wireshark themselves provide.
Homebrew is about Unix software. Stuff that builds to an `.app` should
be accepted frugally. That is, rarely.
probably be in Homebrew Cask instead.
### Naming
The name is the strictest item, because we can’t change it afterwards.
Choose a name that’s the colloquial (most common) name for the project.
Choose a name that’s the most common name for the project.
For example, we chose `objective-caml`, but we should have chosen `ocaml`.
Choose what people say to each other when talking about the project.
@ -82,15 +82,6 @@ If the formula uses a repository, then the `url` parameter should have a
tag or revision. `url` s have versions and are stable (not yet
implemented!).
### Testing in `/usr/local` and somewhere else
If not completely annoying, test in both `/usr/local` and somewhere
else. Preferably on different machines to ensure the `/usr/local`
install doesn’t effect the other one.
The reason for this is some build systems suck, and fail if deps aren’t
installed in `/usr/local`, even though Homebrew goes to some lengths to
try to make this work.
## Common “Gotchas”
1. [Ensure you have set your username and email address
properly](https://help.github.com/articles/setting-your-email-in-git/)
@ -99,10 +90,6 @@ try to make this work.
3. If the commit fixes a bug, use “Fixes \#104” syntax to close the bug
report and link to the commit
### Build “Gotchas”
Often parallel builds work with 2-core systems, but fail on 4-core
systems.
### Duplicates
The main repository avoids duplicates as much as possible. The exception is
libraries that OS X provides but have bugs, and the bugs are fixed in a
@ -120,7 +107,7 @@ Dupes we have allowed:
- `libxml` \<— OS X version is old and buggy
- `libpng` \<— Ditto
#### Add comments!
#### Add comments
It may be enough to refer to an issue ticket, but make sure changes that
if you came to them unaware of the surrounding issues would make sense
to you. Many times on other projects I’ve seen code removed because the

17
share/doc/homebrew/Press.md
View File

@ -1,17 +0,0 @@
# Press
### Featured
* [Homebrew: OS X’s Missing Package Manager](https://blog.engineyard.com/2010/homebrew-os-xs-missing-package-manager/)
* [MacPorts to Homebrew : New Packaging system for Mac OS X](http://blog.abhiomkar.in/2010/01/02/macports-to-homebrew-new-packaging-system-for-mac-os-x/)
* [Installing the homebrew package manager for OS X](http://userprimary.net/posts/2010/08/19/installing-homebrew-for-OSX/)
* [Conheça o Homebrew, o Melhor Gerenciador de Pacotes para Mac OS](http://pedromenezes.com/conheca-o-homebrew-o-melhor-gerenciador-de-pacotes-para-mac-os) (pt-BR)
* [Homebrew on The Unofficial Apple Weblog (Homebrew, the perfect gift for command line lovers)](http://www.tuaw.com/2009/12/25/homebrew-the-perfect-gift-for-command-line-lovers/) (Dec, 2009)
* [Homebrew](http://blog.secondplanetanimation.com/2011/04/16/homebrew/)
* [Gource visualization](https://www.youtube.com/watch?v=ZX0xCWANfW4)
### Mentioned
- [Celery Quick
Start](http://mathematism.com/2010/02/16/message-queues-django-and-celery-quick-start/)
- [CouchDB: The Definitive Guide (Installing on OS X, Appendix
B)](http://oreilly.com/catalog/9780596155902)
- [Installing ActiveMQ on OS
X](https://activemq.apache.org/getting-started.html#GettingStarted-UsingHomebrewinstalleronOSX)

2
share/doc/homebrew/Python-for-Formula-Authors.md
View File

@ -166,7 +166,7 @@ Formulæ that declare a dependency on `:python` will always be bottled against H
Libraries may be installed to `libexec` and added to `sys.path` by writing a .pth file (named like "homebrew-foo.pth") to the `prefix` site-packages. This simplifies the ensuing drama if pip is accidentally used to upgrade a Homebrew-installed package and prevents the accumulation of stale .pyc files in Homebrew's site-packages.
Most formulas presently just install to `prefix`.
Most formulae presently just install to `prefix`.
## Dependencies

44
share/doc/homebrew/README.md
View File

@ -1,52 +1,32 @@
# README
Homebrew installs the stuff you need that Apple didn’t.
- [Install Homebrew](Installation.md)
- [FAQ](FAQ.md)
- [Tips n' Tricks](Tips-N'-Tricks.md)
- [Gems, Eggs and Perl Modules](Gems,-Eggs-and-Perl-Modules.md) and [Homebrew and Python](Homebrew-and-Python.md)
- [Install Homebrew](Installation.md)
- [Frequently Asked Questions](FAQ.md)
- [Tips and Tricks](Tips-N'-Tricks.md)
- [Gems, Eggs and Perl Modules](Gems,-Eggs-and-Perl-Modules.md)
- [Homebrew and Python](Homebrew-and-Python.md)
Please note: Homebrew is not 1.0 yet. Generally it works well, but when
it doesn’t we’d hope you report the bug. If it’s still broken at 1.0 you
have our permission to throw a strop and make a big fuss.
it doesn’t we’d hope you report the bug.
## Troubleshooting
First, please run `brew update` and `brew doctor`.
First, please run `brew update` (twice) and `brew doctor`.
Second, please read the [Troubleshooting Checklist](Troubleshooting.md).
**If you don’t read these it will take us far longer to help you with
**If you don’t follow these steps it will take us far longer to help you with
your problem.**
However! Fixing build issues is easier than you think: try
`brew edit $FORMULA` and see how you fare.
## Contributing
In short:
1. [Fork Homebrew](https://github.com/Homebrew/homebrew/fork).
2. `brew create https://example.com/foo-0.1.tar.gz`
3. `git checkout -b foo`
4. `git commit Library/Formula/foo.rb && git push`
5. [Pull Request](https://github.com/Homebrew/homebrew/pulls).
In long:
- [Formula Cookbook](Formula-Cookbook.md)
- [Acceptable Formulae](Acceptable-Formulae.md)
- [Ruby Style Guide](https://github.com/styleguide/ruby)
Read [CONTRIBUTING.md](/CONTRIBUTING.md).
### Community Forums
- [@MacHomebrew](https://twitter.com/MacHomebrew)
- [homebrew@librelist.com](mailto:homebrew@librelist.com)
([archive](http://librelist.com/browser/homebrew))
- [freenode.net\#machomebrew](irc://irc.freenode.net/#machomebrew)
## News
- [Homebrew 0.9.3](Homebrew-0.9.3.md) Superenv is here to save the day.
- [Homebrew 0.9](Homebrew-0.9.md) `brew-tap` lands.
- [Homebrew 0.8](Homebrew-0.8.md) has been released, including the “refactor” branch
and some improved support for Fortran-based software.
- [@MacHomebrew](https://twitter.com/MacHomebrew)
- [homebrew@librelist.com](mailto:homebrew@librelist.com) ([archive](http://librelist.com/browser/homebrew))
- [freenode.net\#machomebrew](irc://irc.freenode.net/#machomebrew)
## Supporters
[A list of the awesome people who gave £5 or more to our

12
share/doc/homebrew/Rename-A-Formula.md
View File

@ -1,15 +1,15 @@
# Renaming a Formula
Sometimes software and formulae need to be renamed. To rename core formula
you need:
you need to:
1. Rename formula file and its class to new formula. New name must meet all the rules of naming. Fix any test failures that may occur due to the stricter requirements for new formula than existing formula (e.g. brew audit --strict must pass for that formula).
1. Rename the formula file and its class to a new formula. The new name must meet all the usual rules of formula naming. Fix any test failures that may occur due to the stricter requirements for new formulae than existing formulae (i.e. `brew audit --strict` must pass for that formula).
2. Create a pull request to the main repository deleting the formula file, adding new formula file and also add it to `Library/Homebrew/formula_renames.rb` with a commit message like `newack: renamed from ack`
2. Create a pull request to the main Homebrew repository deleting the old formula file, adding the new formula file and add it to `Library/Homebrew/formula_renames.rb` with a commit message like `newack: renamed from ack`
To rename tap formula you need to follow the same steps, but add formula to `formula_renames.json` in the root of your tap. You don't need to change `Library/Homebrew/formula_renames.rb`, because that file is for core formulae only. Use canonical name (e.g. `ack` instead of `user/repo/ack`).
To rename tap formulae you need to follow the same steps but add formulae to `formula_renames.json` in the root of your tap. You don't need to change `Library/Homebrew/formula_renames.rb`, because that file is for Homebrew core formulae only. Use canonical name (e.g. `ack` instead of `user/repo/ack`).
`Library/Homebrew/formula_renames.rb` example for core formula renames:
A `Library/Homebrew/formula_renames.rb` example for a core formula rename:
```ruby
FORMULA_RENAMES = {
@ -17,7 +17,7 @@ FORMULA_RENAMES = {
}
```
`formula_renames.json` example for tap:
A `formula_renames.json` example for a tap formula rename:
```json
{

3
share/doc/homebrew/The-brew-command.md
View File

@ -1,3 +0,0 @@
# The brew command
This page has been deprecated in favor of the [Homebrew manual](https://github.com/Homebrew/homebrew/blob/master/Library/Homebrew/manpages/brew.1.md) (type
`man brew` in Terminal).

2
share/doc/homebrew/Tips-N'-Tricks.md
View File

@ -36,7 +36,7 @@ brew switch $FORMULA $VERSION
Use `brew info $FORMULA` to check what versions are installed but not currently activated, then `brew switch $FORMULA $VERSION` to activate the desired version. This can be useful if you would like to switch between versions of a formula.
## Install into Homebrew without formulas
## Install into Homebrew without formulae
```sh
./configure --prefix=/usr/local/Cellar/foo/1.2 && make && make install && brew link foo

60
share/doc/homebrew/Troubleshooting.md
View File

@ -1,59 +1,27 @@
# Troubleshooting
**If you saw `Error: uninitialized constant Formulary::HOMEBREW_CORE_FORMULA_REGEX. Please report this bug: ...` don't worry: it's [already been fixed](https://github.com/Homebrew/homebrew/commit/ac5707c37470c25583d8fb712bf5dc04ab91db4b). Please only create an issue (or comment on [the existing one](https://github.com/Homebrew/homebrew/issues/42553)) if running `brew update` again doesn't fix it. Thanks!**
**Run `brew update` (twice) and `brew doctor` *before* creating an issue!**
## Read this first!
Please run `brew update` and `brew doctor` *before* creating an issue!
If you create an issue related to a formula, please also create a [Gist][] by running
When creating a formula-related issue please include the link output by running:
```shell
brew gist-logs <formula>
```
brew gist-logs <formula name>
```
and include a link to the gist in the issue.
Read on for more detailed instructions.
Thank you!
## Check for common issues
* Run `brew update` — then try again.
* Run `brew doctor` — the doctor diagnoses common issues.
* Read through the [Common Issues](Common-Issues.md) page.
* If you’re installing something Java-related, maybe you need the [Java Developer Update][] or [JDK 7][]?
* Run `brew update` (twice).
* Run `brew doctor` and fix all the warnings (**outdated Xcode/CLT and unbrewed dylibs are very likely to cause problems**).
* Read through the [Common Issues](Common-Issues.md).
* If you’re installing something Java-related, maybe you need to install Java (`brew cask install java`)?
* Check that **Command Line Tools for Xcode (CLT)** and/or **Xcode** are up to date.
* If things fail with permissions errors, check the permissions in `/usr/local`. If you’re unsure what to do, you can `sudo chown -R $(whoami) /usr/local`.
* If you see permission errors after upgrading to El Capitan please see the [El Capitan and Homebrew](El_Capitan_and_Homebrew.md) document.
#### Listen to Dr. Brew
* **Update Xcode and/or Command Line Tools for Xcode!** Make sure that Xcode is up-to-date in the App Store. Check that the CLT package is up-to-date (either via Xcode, Preferences or at [Apple Developer][]).
* If `brew doctor` warns about unbrewed dylibs, be advised that they are **very likely to cause build problems**.
## Check to see if the issue has been reported
* Browse open issues on the [issue tracker](https://github.com/Homebrew/homebrew/issues) to see if someone else has already reported the same problem.
* Make sure you check issues on the correct repository. If the formula that failed to build is part of a tap, like [homebrew/science](https://github.com/Homebrew/homebrew-science) or [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes), check there instead.
* Check the [issue tracker](https://github.com/Homebrew/homebrew/issues) to see if someone else has already reported the same issue.
* Make sure you check issues on the correct repository. If the formula that failed to build is part of a tap like [homebrew/science](https://github.com/Homebrew/homebrew-science) or [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes) check there instead.
## Create an issue
1. [Create a new issue](https://github.com/Homebrew/homebrew/issues/new)
* Again, make sure you file the issue against the correct repository.
* If you are reporting a build failure, title it "\<formula name> failed to build on 10.x", where \<formula name> is the name of the formula that failed to build, and 10.x is the version of OS X you are using.
* Otherwise, choose a title that best describes the problem you are experiencing.
2. Upload a [Gist][] with relevant debugging information
* The simplest method is to run `brew gist-logs <formula name>`
* You can also create a [Gist][] manually. Include the following:
1. The output from `HOMEBREW_MAKE_JOBS=1 brew install -v <formula name> 2>&1`
2. The contents of the largest numbered log in `~/Library/Logs/Homebrew/<formula name>`, e.g. `03.make`
3. The output from `brew config` and `brew doctor`
* If you are reporting a bug rather than a build failure, please include `brew config`, `brew doctor`, and enough information to reliably reproduce the bug.
3. Include a link to the gist in your new issue
* Be sure to use the `https:` URL (i.e. the URL in your browser's address bar), not the `git:` URL.
[Gist]:https://gist.github.com
[Apple Developer]:https://developer.apple.com/downloads
[Java Developer Update]:https://support.apple.com/kb/DL1572
[JDK 7]:https://docs.oracle.com/javase/7/docs/webnotes/install/mac/mac-install-faq.html
0. Upload debugging information to a [Gist](https://gist.github.com):
- If you had a formula error: run `brew gist-logs <formula>` (where `<formula>` is the name of the formula that failed to build).
- If you encountered a non-formula bug: upload the output of `brew config` and `brew doctor` to a new [Gist](https://gist.github.com).
1. [Create a new issue](https://github.com/Homebrew/homebrew/issues/new) titled "\<formula name> failed to build on 10.x", where `<formula name>` is the name of the formula that failed to build, and `10.x` is the version of OS X you are using and including the link output by `brew gist-logs

8
share/doc/homebrew/brew-tap.md
View File

@ -1,8 +1,8 @@
# brew tap
**tl;dr** `brew tap` adds more repos to the list of formulae that `brew`
tracks, updates, and installs from. By default, `tap` assumes that the repos
come from GitHub, but the command isn't limited to any one location.
`brew tap` adds more repos to the list of formulae that `brew` tracks, updates,
and installs from. By default, `tap` assumes that the repos come from GitHub,
but the command isn't limited to any one location.
## The command
@ -65,7 +65,7 @@ Whenever a `brew install foo` command is issued, brew will find which formula
to use by searching in the following order:
* Pinned taps
* Core formulas
* Core formulae
* Other taps
If you need a formula to be installed from a particular tap, you can use fully

10
share/doc/homebrew/brew.1.html
View File

@ -511,7 +511,9 @@ a Homebrew-built Git if installed, or the system-provided binary.</p>
<dt><code>HOMEBREW_BROWSER</code></dt><dd><p>If set, uses this setting as the browser when opening project homepages,
instead of the OS default browser.</p></dd>
<dt><code>HOMEBREW_BUILD_FROM_SOURCE</code></dt><dd><p>If set, instructs Homebrew to compile from source even when a formula
provides a bottle.</p></dd>
provides a bottle. This environment variable is intended for use by
Homebrew developers. Please do not file issues if you encounter errors when
using this environment variable.</p></dd>
<dt><code>HOMEBREW_CACHE</code></dt><dd><p>If set, instructs Homebrew to use the given directory as the download cache.</p>
<p><em>Default:</em> <code>~/Library/Caches/Homebrew</code> if it exists; otherwise,
@ -602,12 +604,12 @@ your shell profile, or you can use it before a brew command:</p>
<h2 id="AUTHORS">AUTHORS</h2>
<p>Homebrew's current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Mike McQuaid, Baptiste Fontaine, Brett Koonce, Dominyk Tiller, Tim Smith and Alex Dunn.</p>
<p>Homebrew's current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Mike McQuaid, Baptiste Fontaine, Brett Koonce, Martin Afanasjew, Dominyk Tiller, Tim Smith and Alex Dunn.</p>
<p>Homebrew was originally created by Max Howell.</p>
<p>Former maintainers with significant contributions include Jack Nagel, Adam Vandenberg and Homebrew's creator: Max Howell.</p>
<h2 id="BUGS">BUGS</h2>
<p>See Issues on GitHub: <a href="https://github.com/Homebrew/homebrew/issues" data-bare-link="true">https://github.com/Homebrew/homebrew/issues</a></p>
<p>See our issues on GitHub: <a href="https://github.com/Homebrew/homebrew/issues" data-bare-link="true">https://github.com/Homebrew/homebrew/issues</a></p>
</div>

8
share/man/man1/brew.1
View File

@ -555,7 +555,7 @@ If set, uses this setting as the browser when opening project homepages, instead
.
.TP
\fBHOMEBREW_BUILD_FROM_SOURCE\fR
If set, instructs Homebrew to compile from source even when a formula provides a bottle\.
If set, instructs Homebrew to compile from source even when a formula provides a bottle\. This environment variable is intended for use by Homebrew developers\. Please do not file issues if you encounter errors when using this environment variable\.
.
.TP
\fBHOMEBREW_CACHE\fR
@ -692,10 +692,10 @@ Homebrew Documentation: \fIhttps://github\.com/Homebrew/homebrew/blob/master/sha
\fBgit\fR(1), \fBgit\-log\fR(1)
.
.SH "AUTHORS"
Homebrew\'s current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Mike McQuaid, Baptiste Fontaine, Brett Koonce, Dominyk Tiller, Tim Smith and Alex Dunn\.
Homebrew\'s current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Mike McQuaid, Baptiste Fontaine, Brett Koonce, Martin Afanasjew, Dominyk Tiller, Tim Smith and Alex Dunn\.
.
.P
Homebrew was originally created by Max Howell\.
Former maintainers with significant contributions include Jack Nagel, Adam Vandenberg and Homebrew\'s creator: Max Howell\.
.
.SH "BUGS"
See Issues on GitHub: \fIhttps://github\.com/Homebrew/homebrew/issues\fR
See our issues on GitHub: \fIhttps://github\.com/Homebrew/homebrew/issues\fR