diff --git a/.gitignore b/.gitignore index 4c3312af1ebea..ea107402c94c2 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ !/bin /bin/* !/bin/brew +!/share/doc/homebrew !/share/man/man1/brew.1 .DS_Store /Library/Homebrew/doc diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c16846ac8978d..eb0c59da598f5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,7 @@ Reporting Bugs -------------- First, please run `brew update` and `brew doctor`. -Second, read the [Troubleshooting Checklist](https://github.com/Homebrew/homebrew/wiki/troubleshooting). +Second, read the [Troubleshooting Checklist](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Troubleshooting.md). **If you don't read these it will take us far longer to help you with your problem.** @@ -18,9 +18,9 @@ Contributing Please read: * [Code of Conduct](https://github.com/Homebrew/homebrew/blob/master/CODEOFCONDUCT.md) -* [Formula Cookbook](https://github.com/Homebrew/homebrew/wiki/Formula-Cookbook) -* [Acceptable Formulae](https://github.com/Homebrew/homebrew/wiki/Acceptable-Formulae) +* [Formula Cookbook](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Formula-Cookbook.md) +* [Acceptable Formulae](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Acceptable-Formulae.md) * [Ruby Style Guide](https://github.com/styleguide/ruby) -* [How To Open a Homebrew Pull Request (and get it merged)](https://github.com/Homebrew/homebrew/wiki/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged)) +* [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) Thanks! diff --git a/Library/Contributions/example-formula.rb b/Library/Contributions/example-formula.rb index cb47261dc3470..b79f01777471e 100644 --- a/Library/Contributions/example-formula.rb +++ b/Library/Contributions/example-formula.rb @@ -3,7 +3,7 @@ # This is a non-functional example formula to showcase all features and # therefore, it's overly complex and dupes stuff just to comment on it. # You may want to use `brew create` to start your own new formula! -# Documentation: https://github.com/Homebrew/homebrew/wiki/Formula-Cookbook +# Documentation: https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Formula-Cookbook.md ## Naming -- Every Homebrew formula is a class of the type `Formula`. # Ruby classes have to start Upper case and dashes are not allowed. @@ -87,8 +87,7 @@ class ExampleFormula < Formula # Bottles are pre-built and added by the Homebrew maintainers for you. # If you maintain your own repository, you can add your own bottle links. - # Read in the wiki about how to provide bottles: - # + # https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Bottles.md bottle do root_url "http://mikemcquaid.com" # Optional root to calculate bottle URLs prefix "/opt/homebrew" # Optional HOMEBREW_PREFIX in which the bottles were built. @@ -413,8 +412,8 @@ def plist; nil; end __END__ # Room for a patch after the `__END__` -# Read in the wiki about how to get a patch in here: -# https://github.com/Homebrew/homebrew/wiki/Formula-Cookbook +# Read about how to get a patch in here: +# https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Formula-Cookbook.md # In short, `brew install --interactive --git ` and make your edits. # Then `git diff >> path/to/your/formula.rb` # Note, that HOMEBREW_PREFIX will be replaced in the path before it is diff --git a/Library/Homebrew/cmd/create.rb b/Library/Homebrew/cmd/create.rb index dcef372d872ea..9ba3e72040ebe 100644 --- a/Library/Homebrew/cmd/create.rb +++ b/Library/Homebrew/cmd/create.rb @@ -119,7 +119,7 @@ def generate! def template; <<-EOS.undent require "formula" - # Documentation: https://github.com/Homebrew/homebrew/wiki/Formula-Cookbook + # Documentation: https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Formula-Cookbook.md # #{HOMEBREW_CONTRIB}/example-formula.rb # PLEASE REMOVE ALL GENERATED COMMENTS BEFORE SUBMITTING YOUR PULL REQUEST! diff --git a/Library/Homebrew/cmd/help.rb b/Library/Homebrew/cmd/help.rb index cc1afd061f7f0..f4fedc52955e0 100644 --- a/Library/Homebrew/cmd/help.rb +++ b/Library/Homebrew/cmd/help.rb @@ -17,7 +17,7 @@ Brewing: brew create [URL [--no-fetch]] brew edit [FORMULA...] - open https://github.com/Homebrew/homebrew/wiki/Formula-Cookbook + open https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Formula-Cookbook.md Further help: man brew diff --git a/Library/Homebrew/cmd/tap-readme.rb b/Library/Homebrew/cmd/tap-readme.rb index 6356fe30810f1..a62ec3cc7ca3e 100644 --- a/Library/Homebrew/cmd/tap-readme.rb +++ b/Library/Homebrew/cmd/tap-readme.rb @@ -22,9 +22,9 @@ def tap_readme Docs ---- - `brew help`, `man brew`, or the Homebrew [wiki][]. + `brew help`, `man brew`, or the Homebrew [docs][]. - [wiki]:http://wiki.github.com/Homebrew/homebrew + [docs]:https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/README.md#readme EOS puts template if ARGV.verbose? diff --git a/Library/Homebrew/manpages/brew.1.md b/Library/Homebrew/manpages/brew.1.md index 0699a9f9a0801..e58fb469346e3 100644 --- a/Library/Homebrew/manpages/brew.1.md +++ b/Library/Homebrew/manpages/brew.1.md @@ -169,8 +169,8 @@ Note that these flags should only appear after a command. Pass `--all` to get information on all formulae, or `--installed` to get information on all installed formulae. - See the wiki for examples of using the JSON: - + See the docs for examples of using the JSON: + * `install [--debug] [--env=] [--ignore-dependencies] [--only-dependencies] [--cc=] [--build-from-source] [--devel|--HEAD]` : Install . @@ -441,8 +441,8 @@ by default: $ ls $(brew --repository)/Library/Contributions/cmd Documentation for the included external commands as well as instructions for -creating your own can be found on the wiki: - +creating your own can be found in the docs: + ## SPECIFYING FORMULAE @@ -598,7 +598,7 @@ If your proxy requires authentication: ## SEE ALSO -Homebrew Wiki: +Homebrew Documentation: `git`(1), `git-log`(1) diff --git a/Library/Homebrew/os.rb b/Library/Homebrew/os.rb index 9d98860501f4f..4c4f9ae057123 100644 --- a/Library/Homebrew/os.rb +++ b/Library/Homebrew/os.rb @@ -8,7 +8,7 @@ def self.linux? end if OS.mac? - ISSUES_URL = "https://github.com/Homebrew/homebrew/wiki/troubleshooting" + ISSUES_URL = "https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Troubleshooting.md#troubleshooting" PATH_OPEN = "/usr/bin/open" elsif OS.linux? ISSUES_URL = "https://github.com/Homebrew/linuxbrew/wiki/troubleshooting" diff --git a/Library/Homebrew/os/mac/xcode.rb b/Library/Homebrew/os/mac/xcode.rb index 30c141cd65bca..d5c636942a424 100644 --- a/Library/Homebrew/os/mac/xcode.rb +++ b/Library/Homebrew/os/mac/xcode.rb @@ -99,7 +99,7 @@ def uncached_version when 2327..2333 then "3.2.5" when 2335 # this build number applies to 3.2.6, 4.0 and 4.1 - # https://github.com/Homebrew/homebrew/wiki/Xcode + # https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Xcode.md "4.0" else case (MacOS.clang_version.to_f * 10).to_i diff --git a/README.md b/README.md index f2982ea8f7fcb..6e3dca3b7d8fd 100644 --- a/README.md +++ b/README.md @@ -11,13 +11,13 @@ What Packages Are Available? More Documentation ------------------ -`brew help` or `man brew` or check our [wiki][]. +`brew help` or `man brew` or check our [documentation][]. Troubleshooting --------------- First, please run `brew update` and `brew doctor`. -Second, read the [Troubleshooting Checklist](https://github.com/Homebrew/homebrew/wiki/troubleshooting). +Second, read the [Troubleshooting Checklist](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Troubleshooting.md). **If you don't read these it will take us far longer to help you with your problem.** @@ -42,7 +42,7 @@ We accept tips through [Gittip][tip]. [![Gittip](https://img.shields.io/gittip/Homebrew.svg?style=flat)](https://www.gittip.com/Homebrew/) [home]:http://brew.sh -[wiki]:https://github.com/Homebrew/homebrew/wiki +[documentation]:https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/ [mistydemeo]:https://github.com/mistydemeo [adamv]:https://github.com/adamv [jacknagel]:https://github.com/jacknagel diff --git a/share/doc/homebrew/Acceptable-Formulae.md b/share/doc/homebrew/Acceptable-Formulae.md new file mode 100644 index 0000000000000..922823413571d --- /dev/null +++ b/share/doc/homebrew/Acceptable-Formulae.md @@ -0,0 +1,114 @@ +# Acceptable Formulae +Some formulae should not go in +[Homebrew/homebrew](https://github.com/Homebrew/homebrew). But there are +additional [Interesting Taps & Branches](Interesting-Taps-&-Branches.md) and anyone can start his/her +own! + +### We try hard to avoid dupes in Homebrew/homebrew +Stuff that comes with OS X or is a library that is provided by +[RubyGems, CPAN or PyPi](http://github.com/Homebrew/homebrew/wiki/Gems,-Eggs-and-Perl-Modules) +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 +* We want our formulae to work with what comes with OS X + +There are exceptions: + +* Programs that a user will regularly interact with directly, like editors and + language runtimes +* Libraries that provide functionality or contain security updates not found in + the system version +* Things that are **designed to be installed in parallel to earlier versions of + themselves** + +#### Examples + + Formula | Reason + --- | --- + ruby, python | People want newer versions + bash | OS X's bash is stuck at 3.2 because newer versions are licensed under GPLv3 + zsh | This was a mistake, but it’s too late to remove it + emacs, vim | [Too popular to move to dupes](https://github.com/Homebrew/homebrew/pull/21594#issuecomment-21968819) + subversion | Originally added for 10.5, but people want the latest version + libcurl | Some formulae require a newer version than OS X provides + openssl | OS X's openssl is deprecated + libxml2 | Historically, OS X's libxml2 has been buggy + +We also maintain [a tap](https://github.com/Homebrew/homebrew-dueps) that +contains many duplicates not otherwise found in Homebrew. + +### We don’t like tools that upgrade themselves +Software that can upgrade itself does not integrate well with Homebrew's own +upgrade functionality. + +### We don’t like install-scripts that download things +Because that circumvents our hash-checks, makes finding/fixing bugs +harder, often breaks patches and disables the caching. Almost always you +can add a resource to the formula file to handle the +separate download and then the installer script will not attempt to load +that stuff on demand. Or there is a command line switch where you can +point it to the downloaded archive in order to avoid loading. + +### We don’t like binary formulae +Our policy is that formulae in the core repository +([Homebrew/homebrew](https://github.com/Homebrew/homebrew)) must be built +from source. Binary-only formulae should go to +[Homebrew/homebrew-binary](https://github.com/Homebrew/homebrew-binary). + +### Stable versions +Formulae in the core repository should have a stable version tagged by +the upstream project. Tarballs are preferred to git checkouts, and +tarballs should include the version in the filename whenever possible. + +Software that does not provide a stable, tagged version, or had guidance to +always install the most recent version, should be put in +[Homebrew/homebrew-headonly](https://github.com/Homebrew/homebrew-headonly). + +### Bindings +First check that there is not already a binding available via +[`gem`](http://rubygems.org/) or [`pip`](http://www.pip-installer.org/) +etc.. + +If not, then put bindings in the formula they bind to. This is more +useful to people. Just install the stuff! Having to faff around with +foo-ruby foo-perl etc. sucks. + +### Niche (or self-submitted) Stuff +The software in question must be +* maintained +* known +* stable +* used +* have a homepage + +We will reject formulae that seem too obscure, partly because they won’t +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! + +### Stuff that builds a .app +Don’t make your formula build an `.app` (native OS X Application), we +don’t want those things in Homebrew. Make it build a command line tool +or a library. However, we have a few exceptions to that, e.g. when the +App is just additional to CLI or if the GUI-application is non-native +for OS X and/or hard to get in binary elsewhere (example: font forge). +Check out the [homebrew-cask](https://github.com/phinze/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 +rejections may seem arbitrary or strange they are based from years of +experience making Homebrew work acceptably for our users. diff --git a/share/doc/homebrew/Bottles.md b/share/doc/homebrew/Bottles.md new file mode 100644 index 0000000000000..414d47e663330 --- /dev/null +++ b/share/doc/homebrew/Bottles.md @@ -0,0 +1,74 @@ +# Bottles +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 `. 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. + +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`. + +### Local Bottle Usage +Bottles can also be cached locally and installed by path e.g. `brew install /Library/Caches/Homebrew/qt-4.8.4.mountain_lion.bottle.1.tar.gz`. + +## Bottle Creation +Bottles are currently created using the [Brew Test Bot](Brew-Test-Bot.md). We will be slowly adding them to all formulae. + +By default, bottles will be built for the oldest CPU supported by the OS/architecture you're building for. (That's Core 2 for 64-bit OSs, Core for 32-bit.) This ensures that bottles are compatible with all computers you might distribute them to. If you *really* want your bottles to be optimized for something else, you can pass the `--bottle-arch=` option to build for another architecture - for example, `brew install foo --bottle-arch=penyrn`. Just remember that if you build for a newer architecture some of your users might get binaries they can't run and that would be sad! + +## Bottle Format +Bottles are simple gzipped tarballs of compiled binaries. Any metadata is stored in a formula's bottle DSL and in the bottle filename (i.e. MacOS version, revision). + +## Bottle DSL (Domain Specific Language) +Bottles have a DSL to be used in formulae which is contained in the `bottle do ... end` block. + +A simple (and typical) example: +```ruby +bottle do + sha1 'd3d13fe6f42416765207503a946db01378131d7b' => :mountain_lion + sha1 'cdc48e79de2dee796bb4ba1ad987f6b35ce1c1ee' => :lion + sha1 'a19b544c8c645d7daad1d39a070a0eb86dfe9b9c' => :snow_leopard +end +``` + +A full example: +```ruby +bottle do + root_url 'http://mikemcquaid.com' + prefix '/opt/homebrew' + cellar '/opt/homebrew/Cellar' + revision 4 + sha1 'd3d13fe6f42416765207503a946db01378131d7b' => :mountain_lion + sha1 'cdc48e79de2dee796bb4ba1ad987f6b35ce1c1ee' => :lion + sha1 'a19b544c8c645d7daad1d39a070a0eb86dfe9b9c' => :snow_leopard + sha1 '583dc9d98604c56983e17d66cfca2076fc56312b' => :snow_leopard_32 + sha1 '2ef5f57afae319a3e7618d5723059eae568276fa' => :leopard +end +``` + +### `root_url` +Optionally contains the URL root used to calculate bottle URLs. +By default this is omitted and the Homebrew default bottle URL root is used. This may be useful for taps which wish to provide bottles for their formulae or to cater for a non-default `HOMEBREW_CELLAR`. + +### `cellar` +Optionally contains the value of `HOMEBREW_CELLAR` in which the bottles were built. +Most compiled software contains references to its compiled location so cannot be simply relocated anywhere on disk. If this value is `:any` this means that the bottle can be safely installed in any Cellar as it did not contain any references to its installation Cellar. This can be omitted if a bottle is compiled (as all default Homebrew ones are) for the default `HOMEBREW_CELLAR` of `/usr/local/Cellar` + +### `prefix` +Optionally contains the value of `HOMEBREW_PREFIX` in which the bottles were built. +See description of `cellar`. When `cellar` is `:any` prefix should be omitted. + +### `revision` +Optionally contains the revision of the bottle. +Sometimes bottles may need be updated without bumping the version of the formula e.g. a new patch was applied. In that case the revision will have a value of 1 or more. + +### `sha1` +Contains the SHA-1 of bottle for a particular version of OS X. + +## Formula DSL +Additionally there is a method available in the formula DSL. + +### `pour_bottle?` +Optionally returns a boolean to decide whether a bottle should be used for this formula. +For example a bottle may break if another formula has been compiled with non-default options so this method could check for that case and return `false`. + +## Planned Improvements +Most bottle features have been (and planned improvements will be) implemented by @mikemcquaid. Contact him directly with questions. diff --git a/share/doc/homebrew/Brew-Test-Bot-For-Core-Contributors.md b/share/doc/homebrew/Brew-Test-Bot-For-Core-Contributors.md new file mode 100644 index 0000000000000..e8ff500819a3e --- /dev/null +++ b/share/doc/homebrew/Brew-Test-Bot-For-Core-Contributors.md @@ -0,0 +1,40 @@ +# 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 +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. + +## Homebrew Pull Requests + +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)). On a successful build it automatically uploads bottles. + +## Homebrew Testing + +This job is manually triggered to run +[`brew-test-bot.rb`](https://github.com/Homebrew/homebrew/blob/master/Library/Contributions/cmd/brew-test-bot.rb) +on with user-specified parameters. On a successful build it automatically uploads bottles. + +You can manually start this job with parameters to run [`brew-test-bot`](https://github.com/Homebrew/homebrew/blob/master/Library/Contributions/cmd/brew-test-bot.rb) with the same parameters. It's often useful to pass a pull request URL, a commit URL, a commit SHA-1 and/or formula names to have `brew-test-bot` test them, report the results and produce bottles. + +## Bottling +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-1 in the bottled formulae match the uploaded files. +4. Run `git push` to push the commits. + +To bottle a test build or pull request without `brew pull`: + +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-1 in the bottled formulae match the uploaded files. +7. Run `git push` to push the commits. diff --git a/share/doc/homebrew/Brew-Test-Bot.md b/share/doc/homebrew/Brew-Test-Bot.md new file mode 100644 index 0000000000000..dbb1bc46a6961 --- /dev/null +++ b/share/doc/homebrew/Brew-Test-Bot.md @@ -0,0 +1,67 @@ +# Brew Test Bot +`brew test-bot` is the name for the automated review and testing system funded +by [our Kickstarter in 2013](http://www.kickstarter.com/projects/homebrew/brew-test-bot). + +It comprises of four Mac Minis running in a data centre in England which host +[a Jenkins instance at http://bot.brew.sh](http://bot.brew.sh) and run the +[`brew-test-bot.rb`](https://github.com/Homebrew/homebrew/blob/master/Library/Homebrew/cmd/test-bot.rb) +Ruby script to perform automated testing of commits to the master branch, pull +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. + +For example, a job which has been queued but not yet started will have a +section in the pull-request that looks like this: + + +![Triggered Pull Request](brew-test-bot-triggered-pr.png) + +--- + +A failed build looks like this: + + +![Failed Pull Request](brew-test-bot-failed-pr.png) + +--- + +A passed build looks like this: + + +![Passed Pull Request](brew-test-bot-passed-pr.png) + +--- + +On failed or passed builds you can click the "Details" link to view the result +in Jenkins. + +When you click this you'll see the results. + +A passed build looks like this: + + +![Passed Jenkins Build](brew-test-bot-passed-jenkins.png) + +--- + +A failed build looks like this: + + +![Failed Jenkins Build](brew-test-bot-failed-jenkins.png) + +--- + +You can click the test results link +(e.g. `brew-test-bot.Homebrew/homebrew/pull/22183-3c17deb.install embree`) to +view the failed test output: + +![Failed Test](brew-test-bot-failed-test.png) + +--- diff --git a/share/doc/homebrew/C++-Standard-Libraries.md b/share/doc/homebrew/C++-Standard-Libraries.md new file mode 100644 index 0000000000000..f841044b99485 --- /dev/null +++ b/share/doc/homebrew/C++-Standard-Libraries.md @@ -0,0 +1,13 @@ +# C++ Standard Libraries +There are two C++ standard libraries supported by Apple compilers. + +The default for 10.8 and earlier is **libstdc++**, supported by Apple GCC compilers, GNU GCC compilers, and clang. + +The default for 10.9 is **libc++**, which is also the default for clang on older platforms when building C++11 code. + +There are subtle incompatibilities between several of the C++ standard libraries, so Homebrew will refuse to install software if a dependency was built with an incompatible C++ library. It's recommended that you install the dependency tree using a compatible compiler. + +**If you've upgraded to 10.9 from an earlier version** - because the default C++ standard library is now libc++, you may not be able to build software using dependencies that you built on 10.8 or lower. If you're reading this page because you were directed here by a build error, you can most likely fix the issue if you reinstall all the dependencies of the package you're trying to build. + +Example install using GCC 4.8: ```brew install DESIRED_FORMULA --cc=gcc-4.8```. +Get GCC 4.8 via: ```brew install gcc48``` diff --git a/share/doc/homebrew/Common-Issues-for-Core-Contributors.md b/share/doc/homebrew/Common-Issues-for-Core-Contributors.md new file mode 100644 index 0000000000000..3ec63a5136fd6 --- /dev/null +++ b/share/doc/homebrew/Common-Issues-for-Core-Contributors.md @@ -0,0 +1,16 @@ +# Common Issues for Core Contributors + +## Overview + +This is a page for maintainers to diagnose certain build errors. + +## Issues + +### `ld: internal error: atom not found in symbolIndex(__ZN10SQInstance3GetERK11SQObjectPtrRS0_) for architecture x86_64` + +The exact atom may be different. + +This can be caused by passing the obsolete `-s` flag to the linker. + +See: +https://github.com/Homebrew/homebrew/commit/7c9a9334631dc84d59131ca57419e8c828b1574b diff --git a/share/doc/homebrew/Common-Issues.md b/share/doc/homebrew/Common-Issues.md new file mode 100644 index 0000000000000..6deff92a09a75 --- /dev/null +++ b/share/doc/homebrew/Common-Issues.md @@ -0,0 +1,155 @@ +# Common Issues +This is a list of commonly encountered problems, known issues, and their solutions. + +### `brew` complains about absence of "Command Line Tools" +You need to have the Xcode Command Line Utilities installed (and updated): run `xcode-select --install` in the terminal. +(In OS X prior to 10.9, the "Command Line Tools" package can alternatively be installed from within Xcode. `⌘,` will get you to preferences. Visit the "Downloads" tab and hit the install button next to "Command Line Tools".) + +### Ruby `bad interpreter: /usr/bin/ruby^M: no such file or directory` +You cloned with git, and your git configuration is set to use Windows line endings. See this page: https://help.github.com/articles/dealing-with-line-endings + + +### Ruby `bad interpreter: /usr/bin/ruby` +You don't have a `/usr/bin/ruby` or it is not executable. It's not recommended to let this persist, you'd be surprised how many .apps, tools and scripts expect your OS X provided files and directories to be *unmodified* since OS X was installed. + +### `brew update` complains about untracked working tree files +After running `brew update`, you receive a git error warning about untracked files or local changes that would be overwritten by a checkout or merge, followed by a list of files inside your Homebrew installation. + +This is caused by an old bug in in the `update` code that has long since been fixed. However, the nature of the bug requires that you do the following: + +```bash +cd $(brew --repository) +git reset --hard FETCH_HEAD +``` +If `brew doctor` still complains about uncommitted modifications, also run this command: +```bash +cd $(brew --repository)/Library +git clean -fd +``` + +### invalid multibyte escape: /^\037\213/ + +You see an error similar to: + +``` +Error: /usr/local/Library/Homebrew/download_strategy.rb:84: invalid multibyte escape: /^\037\213/ +invalid multibyte escape: /^\037\235/ +``` + +In the past, Homebrew assumed that `/usr/bin/ruby` was Ruby 1.8. On OS X 10.9, it is now Ruby 2.0. There are various incompatibilities between the two versions, so if you upgrade to OS X 10.9 while using a sufficiently old version of Homebrew, you will encounter errors. + +The incompatibilities have been addressed in more recent versions of Homebrew, and it does not make assumptions about `/usr/bin/ruby`, instead it uses the executable inside OS X's Ruby 1.8 framework. + +To recover from this situation, do the following: + +``` +cd /usr/local # your Homebrew prefix +git fetch origin +git reset --hard FETCH_HEAD +brew update +``` + +### `launchctl` refuses to load launchd plist files +When trying to load a plist file into launchctl, you receive an error that resembles + +``` +Bug: launchctl.c:2325 (23930):13: (dbfd = open(g_job_overrides_db_path, [...] +launch_msg(): Socket is not connected +``` +or + +```bash +Could not open job overrides database at: /private/var/db/launchd.db/com.apple.launchd/overrides.plist: 13: Permission denied +launch_msg(): Socket is not connected +``` + +These are likely due to one of three issues: + +1. You are using iTerm. The solution is to use Terminal.app when interacting with `launchctl`. +2. You are using a terminal multiplexer such as `tmux` or `screen`. You should interact with `launchctl` from a separate Terminal.app shell. +3. You are attempting to run `launchctl` while logged in remotely. You should enable screen sharing on the remote machine and issue the command using Terminal.app running on that machine. +4. You are su'ed as a different user. + +### `brew upgrade` errors out +When running `brew upgrade`, you see something like this: +```text +$ brew upgrade +Error: undefined method `include?' for nil:NilClass +Please report this bug: + https://github.com/Homebrew/homebrew/wiki/checklist-before-filing-a-new-issue +/usr/local/Library/Homebrew/formula.rb:393:in `canonical_name' +/usr/local/Library/Homebrew/formula.rb:425:in `factory' +/usr/local/Library/Contributions/examples/brew-upgrade.rb:7 +/usr/local/Library/Contributions/examples/brew-upgrade.rb:7:in `map' +/usr/local/Library/Contributions/examples/brew-upgrade.rb:7 +/usr/local/bin/brew:46:in `require' +/usr/local/bin/brew:46:in `require?' +/usr/local/bin/brew:79 +``` + +This happens because an old version of the upgrade command is hanging around for some reason. The fix: + +``` +$ cd $(brew --repository)/Library/Contributions/examples +$ git clean -n # if this doesn't list anything that you want to keep, then +$ git clean -f # this will remove untracked files +``` + +### Python: `Segmentation fault: 11` on `import ` + +A `Segmentation fault: 11` is in 95% due to a different Python executable used for building the software vs. the python you use to import the module. Note that e.g. the `boost` bottle is built against system python and should be brewed from source to make it work with a brewed Python. +This can even happen when both python executables are the same version (e.g. 2.7.2). The explanation is that Python packages with C-extensions (those that have `.so` files) are compiled against a certain python binary/library that may have been built with a different arch (e.g. Apple's python is still not a pure 64bit). Other things can go wrong, too. Welcome to the dirty underworld of C. + +To solve this, you should remove the problematic formulae with those python bindings and all of it's dependencies. + + - `brew rm $(brew deps )` + - `brew rm ` + - Also check the `$(brew --prefix)/lib/python2.7/site-packages` directory and delete all remains of the corresponding python modules if they were not cleanly removed by the previous steps. + - Check that `which python` points to the python you want. Perhaps now is the time to `brew install python`. + - Then reinstall `brew install ` + - Now start `python` and try to `import` the module installed by the + +You can basically use any Python (2.x) for the bindings homebrew provides, but you can't mix. +Homebrew formulae use a brewed Python if available or, if not so, they use whatever `python` is in your `PATH`. + +### Python: `Fatal Python error: PyThreadState_Get: no current thread` + +``` +Fatal Python error: PyThreadState_Get: no current thread +Abort trap: 6 +``` + +This happens for `boost`, `pygtk` and/or `pygobject` and related modules, for the same reason as described above. +If the `boost` is your problem, please `brew rm boost`, `brew install boost --build-from-source`. This is needed because the boost bottle is built against system python. + +To solve this, follow the steps above. + +### Python: `Python.h not found` + +The formula needs a `depends_on :python`, probably. + +### Python: easy-install.pth cannot be linked +``` +Warning: Could not link . Unlinking... +Error: The `brew link` step did not complete successfully +The formula built, but is not symlinked into /usr/local +You can try again using `brew link ' + +Possible conflicting files are: +/usr/local/lib/python2.7/site-packages/site.py +/usr/local/lib/python2.7/site-packages/easy-install.pth +==> Could not symlink file: /homebrew/Cellar///lib/python2.7/site-packages/site.py +Target /usr/local/lib/python2.7/site-packages/site.py already exists. You may need to delete it. +To force the link and overwrite all other conflicting files, do: + brew link --overwrite formula_name + +To list all files that would be deleted: + brew link --overwrite --dry-run formula_name +``` + +Don't follow the advice of setuptools here but fix by adding +`--record=installed.txt` and `--single-version-externally-managed` flags to `setup.py`: + +### Python: `/usr/local/bin/virtualenv: ...: bad interpreter: No such file or directory` + +Did you try to pip install --upgrade virtualenv? Since the full path to Python is included, you will need to reinstall software like this after upgrading python itself. diff --git a/share/doc/homebrew/Custom-GCC-and-cross-compilers.md b/share/doc/homebrew/Custom-GCC-and-cross-compilers.md new file mode 100644 index 0000000000000..cd44ba556f1ba --- /dev/null +++ b/share/doc/homebrew/Custom-GCC-and-cross-compilers.md @@ -0,0 +1,14 @@ +# Custom GCC and cross compilers +Homebrew depends on having an up-to-date version of Xcode because it comes with specific versions of build tools e.g. `clang`. + +Installing a custom version of GCC or `autotools` into the `$PATH` has the potential to break lots of compiles so we prefer the Apple or Homebrew provided compilers. + +Cross-compilers based on GCC will typically be "keg-only" and therefore not linked into the path by default. + +Rather than merging in brews for either of these cases at this time, we're listing them on this page. If you come up with a formula for a new version of GCC or cross-compiler suite, please link it in here. + +* Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing C++11 support on earlier versions. +* [Homebrew-versions](https://github.com/homebrew/homebrew-versions) provides an up to date GCC duplicates e.g. `brew install homebrew/versions/gcc48` +* [MSP430 development](http://github.com/Homebrew/homebrew/issues/issue/2336) +* [OS161 development](https://github.com/maxpow4h/homebrew-os161) Your university probably uses a different version, replacing the URLs with your university's URLs will probably work. +* [ARM-EABI](https://github.com/paxswill/homebrew-paxswill) provides an arm-none-eabi toolchain formula. diff --git a/share/doc/homebrew/External-Commands.md b/share/doc/homebrew/External-Commands.md new file mode 100644 index 0000000000000..36a4fc8722c5b --- /dev/null +++ b/share/doc/homebrew/External-Commands.md @@ -0,0 +1,98 @@ +# External Commands +Homebrew, like Git, supports *external commands*. This lets you create new commands that can be run like: + +``` +$ brew mycommand --option1 --option3 formula +``` + +without modifying Homebrew's internals. + +## COMMAND TYPES +External commands come in two flavors: Ruby commands and shell scripts. + +In both cases, the command file should be `chmod +x` (executable) and live somewhere in `$PATH`. + +Internally, Homebrew finds commands with `which`(1). + +### RUBY COMMANDS +An external command `extcmd` implemented as a Ruby command should be named `brew-extcmd.rb`. The command is executed by doing a `require` on the full pathname. As the command is `require`d, it has full access to the Homebrew "environment", i.e. all global variables and modules that any internal command has access to. + +The command may `Kernel.exit` with a status code if it needs to; if it doesn't explicitly exit then Homebrew will return 0. + +### SHELL SCRIPTS +A shell script for an command named `extcmd` should be named `brew-extcmd`. This file will be run via `exec` with some Homebrew variables set as environmental variables, and passed any additional command-line arguments. + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableDescription
HOMEBREW_CACHEWhere Homebrew caches downloaded tarballs to, typically ~/Library/Caches/Homebrew.
HOMEBREW_CELLARThe location of the Homebrew Cellar, where software is staged, by default /usr/local/Cellar.
HOMEBREW_LIBRARY_PATHThe directory containing Homebrew’s own application code.
HOMEBREW_PREFIXWhere Homebrew installs software to, by default /usr/local.
HOMEBREW_REPOSITORYIf installed from a Git clone, the repo directory (i.e., where Homebrew’s .git directory lives).
+ +Note that the script itself can use any suitable shebang (`#!`) line, so an external “shell script” can be written for sh, bash, Ruby, or anything else. + +## USER-SUBMITTED COMMANDS +These commands have been contributed by Homebrew users but are not included in the main Homebrew repository, nor are they installed by the installer script. You can install them manually, as outlined above. + +>*NOTE:* They are largely untested, and as always, be careful about running untested code on your machine. + +### brew-cask + +>Install .app and other "Drag to install" packages from Homebrew. +> +> https://github.com/caskroom/homebrew-cask +> +> Install using: +> ``` + $ brew tap caskroom/cask + $ brew install brew-cask +> ``` + +### brew-desc +>Get short descriptions for Homebrew formulae or search formulae by description: [https://github.com/telemachus/brew-desc](https://github.com/telemachus/homebrew-desc) + +>You can install manually or using `brew tap`: +> ``` +> $ brew install telemachus/desc/brew-desc +> ``` + +### brew-gem and brew-pip +>Install any gem pip package into a self-contained Homebrew cellar location +> +>[https://github.com/josh/brew-gem](https://github.com/josh/brew-gem), [https://github.com/josh/brew-pip](https://github.com/josh/brew-pip) +> +>*Note:* These can also be installed with `brew install brew-gem` and `brew install brew-pip` + +### brew-growl +>Get Growl notifications for Homebrew https://github.com/secondplanet/brew-growl + +### brew-more +>Scrapes a formula's homepage to get more information: [https://gist.github.com/475200](https://gist.github.com/475200) + +### brew-services +>Simple support to start formulae using launchctl, has out of the box support for any formula which defines `startup_plist` (e.g. mysql, postgres, redis u.v.m.): [https://gist.github.com/766293](https://gist.github.com/766293) + +## SEE ALSO +Homebrew Wiki: + +`brew`(1), `which`(1), `grep`(1), [`ronn`(1)](http://rtomayko.github.com/ronn/) diff --git a/share/doc/homebrew/FAQ.md b/share/doc/homebrew/FAQ.md new file mode 100644 index 0000000000000..817fd2d7ab4ea --- /dev/null +++ b/share/doc/homebrew/FAQ.md @@ -0,0 +1,247 @@ +# FAQ +### How do I update my local packages? +First update the formulae and Homebrew itself: + + brew update + +You can now find out what is outdated with: + + brew outdated + +Upgrade everything with: + + brew upgrade + +Or upgrade a specific formula with: + + brew upgrade $FORMULA + + + +### How do I uninstall old versions of a formula? +By default, Homebrew does not uninstall old versions of a formula, so +over time you will accumulate old versions. To remove them, simply use: + + brew cleanup $FORMULA + +or clean up everything at once: + + brew cleanup + +to see what would be cleaned up: + + brew cleanup -n + + + +### How do I uninstall Homebrew? +If you installed to `/usr/local` then you can use the script in [this +gist](https://gist.github.com/1173223) to uninstall — it will only +remove Homebrew and the stuff Homebrew installed leaving anything else +in `/usr/local` alone. + +Provided you haven’t put anything else in Homebrew’s prefix +(`brew --prefix`), you can generally just `rm -rf` that directory. This +is because Homebrew won’t touch files outside its prefix. + + + +### How do I uninstall a formula? +If you do not uninstall all of the versions that Homebrew has installed, +Homebrew will continue to attempt to install the newest version it knows +about when you do (`brew upgrade`). This can be surprising. + +To remove a formula entirely, you may do +(`brew uninstall formula_name --force`). + +Be careful as this is a destructive operation and unfortunately, in +Homebrew 0.9.5 it seems that Homebrew does not support the `--dry-run` +option. + +### Where does stuff get downloaded? + + brew --cache + +Which is usually: `/Library/Caches/Homebrew` + +### My Mac `.app`s don’t find `/usr/local/bin` utilities! +GUI apps on OS X don’t have `/usr/local/bin` in their `PATH` by default. +If you’re on Mountain Lion, you can fix this by running +`launchctl setenv PATH "/usr/local/bin:$PATH"`. [More details +here](http://stackoverflow.com/questions/135688/setting-environment-variables-in-os-x/5444960#5444960), +including how to set this across reboots. If you’re pre-Mountain Lion, +[here’s an official +alternative](http://developer.apple.com/library/mac/#qa/qa1067/_index.html). + +### How do I contribute to Homebrew? +Read everything in https://github.com/Homebrew/homebrew/blob/master/CONTRIBUTING.md. + +### Why do you compile everything? +Projects distribute source tarballs, generally, but if they provide a +good binary, we’ll use it. Though we don’t always, because 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 +pre-compiled versions are referred to as **bottles** and are available +at: +[http://sf.net/projects/machomebrew/files](http://sf.net/projects/machomebrew/files). + +If available, bottled binaries will be used by default except under the +following conditions: + +* Options were passed to the install command i.e. `brew install $FORMULA` +will use a bottled version of $FORMULA, but +`brew install `$FORMULA —enable-bar` will trigger a source build. +* The `--build-from-source` option is invoked. +* The environment variable `HOMEBREW_BUILD_FROM_SOURCE` is set. +* The machine is not running OS X 10.7+ as all bottled builds are +generated on Lion or later. +* Homebrew is installed to a prefix other than the standard +`/usr/local` (although some bottles support this) + +In order to completely disable bottled builds, simply add a value for +the environment variable `HOMEBREW_BUILD_FROM_SOURCE` to +your profile. + +We aim to bottle everything. + +### How do I get a formula from someone else’s branch? + + brew install hub + brew update + cd $(brew --repository) + hub pull someone_else + +Or: + +`brew install http://raw.github.com/user/repo/branch/formula.rb` + +Or: + +`brew pull http://github.com/Homebrew/homebrew/pulls/1234` + +### Why does Homebrew insist I install to `/usr/local` with such vehemence? + + +1. **It’s easier**
`/usr/local/bin` is already in your + `PATH`. +2. **It’s easier**
Tons of build scripts break if their dependencies + aren’t in either `/usr` or `/usr/local`. We + fix this for Homebrew formulae (although we don’t always test for + it), but you’ll find that many RubyGems and Python setup scripts + break which is something outside our control. +3. **It’s safe**
Apple has left this directory for us. Which means + there is no `/usr/local` directory by default, so there + is no need to worry about messing up existing tools. + +**If you plan to install gems that depend on +brews then save yourself a bunch of hassle and install to +`/usr/local`!** + +It is not always straightforward to tell `gem` to look in non-standard directories for headers and libraries. If you choose `/usr/local`, many things will "just work". + +### Why does Homebrew say sudo is bad? +**tl;dr** Sudo is dangerous, and you installed TextMate.app without sudo +anyway. + +Homebrew is designed to work without using sudo. You can decide to use +it but we strongly recommend not to do so. If you have used sudo and run +into a bug then it is likely to be the cause. Please don’t file a bug +report unless you can reproduce it after reinstalling Homebrew from +scratch without using sudo. + +You should only ever sudo a tool you trust. Of course, you can trust +Homebrew ;) But do you trust the multi-megabyte Makefile that Homebrew +runs? Developers often understand C++ far better than they understand +make syntax. It’s too high a risk to sudo such stuff. It could break +your base system, or alter it subtly. + +And indeed, we’ve seen some build scripts try to modify +`/usr` even when the prefix was specified as something else +entirely. + +Did you `chown root /Applications/TextMate.app`? Probably +not. So is it that important to `chown root wget`? + +If you need to run Homebrew in a multi-user environment, consider +creating a separate user account especially for use of Homebrew. + +### Why isn’t a particular command documented? + +If it’s not in `man brew`, it’s probably an external command. These are documented [here](https://github.com/Homebrew/homebrew/wiki/External-Commands). + +### Why haven’t you pulled my pull request? +If it’s been a while, bump it with a “bump” comment. Sometimes we miss requests and there are plenty of them. Maybe we were thinking on something. It will encourage consideration. In the meantime if you could rebase the pull request so that it can be cherry-picked more easily we will love you for a long time. + +### Can I edit formulae myself? +Yes! It’s easy! Just `brew edit $FORMULA`. You don’t have to submit modifications back to*Homebrew/homebrew*, just edit the formula as you personally need it and `brew install`. As a bonus `brew update` will merge your changes with upstream so you can still keep the formula up-to-date **with** your personal modifications! + +### Can I make new formulae? +Yes! It’s easy! Just `brew create URL` Homebrew will then open the +formula in `$EDITOR` so you can edit it, but it probably already +installs, try it: `brew install $FORMULA`. If you come up any issues, +run the command with the `-d` switch like so: `brew install -d $FORMULA` +which drops you into a debugging shell. + +If you want your new formula to be part of *Homebrew/homebrew* or want +to learn more about writing formula then please read the [Formula Cookbook](Formula-Cookbook.md). + +### Can I install my own stuff to `/usr/local`? +Yes, brew is designed to not get in your way so you can use it how you +like. + +Install your own stuff, but be aware that if you install common +libraries, like libexpat yourself, it may cause trouble when trying to +build certain Homebrew formula. As a result `brew doctor` will warn you +about this. + +Thus it’s probably better to install your own stuff to the Cellar and +then `brew link` it. Like so: + +```bash +$ cd foo-0.1 +$ brew diy +./configure —prefix=/usr/local/Cellar/foo/0.1 +$ ./configure —prefix=/usr/local/Cellar/foo/0.1 +[snip] +$ make && make install +$ brew link foo +Linking /usr/local/Cellar/foo/0.1… 17 symlinks created +``` + +### Where was a formula deleted? +Use `brew log $FORMULA` to find out! + +Sometimes formula are moved to specialized repositories. These are the +likely candidates: + +* [https://github.com/Homebrew/homebrew-dupes](https://github.com/Homebrew/homebrew-dupes) +* [https://github.com/Homebrew/homebrew-versions](https://github.com/Homebrew/homebrew-versions) +* [https://github.com/Homebrew/homebrew-games](https://github.com/Homebrew/homebrew-games) + +You can use `brew tap` to access these formulae: + +```bash +brew tap homebrew/games +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 +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 ;-) + +### What does *keg-only* mean? +It means the formula is installed only into the Cellar, it is not linked +into `/usr/local`. This means most tools will not find it. We don’t do +this for stupid reasons. You can link the formula in still if you need +to with `brew link`. + +### How can I specify different configure arguments for a formula? +`brew edit $FORMULA` and edit the formula. Currently there is no +other way to do this, but we’ll design something like that into brew2. diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md new file mode 100644 index 0000000000000..98b0f7542af8e --- /dev/null +++ b/share/doc/homebrew/Formula-Cookbook.md @@ -0,0 +1,949 @@ +# Formula Cookbook +Making a formula is easy. Just `brew create URL` and then `brew install $FORMULA` (perhaps with `--debug --verbose`). Basically, a formula is a Ruby file. You can place it anywhere you want (local or remote) and install it by pointing to the file or URL. + +We want your formula to be awesome, and the cookbook will tell you how. + +## Terminology - Homebrew speak + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FormulaThe package definition/usr/local/Library/Formula/foo.rb
KegThe installation prefix of a Formula/usr/local/Cellar/foo/0.1
opt prefixA symlink to the active version of a keg/usr/local/opt/foo
CellarAll kegs are installed here/usr/local/Cellar
TapAn optional repository (git) of Formulae/usr/local/Library/Taps
BottlePre-built (binary) Keg that can be unpackedqt-4.8.4.mountain_lion.bottle.1.tar.gz
+ +_More general: `brew --prefix` and `brew --repository` instead of `/usr/local` but lets KISS._ + + +## An Introduction + +Did you see `/usr/local/.git`? Homebrew is built on Git. This means you can just do your work in `/usr/local` and merge in upstream changes as you go. + +Homebrew installs to the `Cellar`, it then symlinks some of the installation into `/usr/local` so that other programs can see what's going on. We suggest you `brew ls` a few of the kegs in your Cellar to see how it is all arranged. + +Packages are installed according to their formulae, which live in `$(brew --repository)/Library/Formula`. Check some out. You can view any formula at anytime; e.g. `brew edit wget`. + + + +# Basic Instructions + +Make sure you run `brew update` before you start. This turns your Homebrew installation into a Git repository. + +Before contributing, make sure your package: + +* meets all our [Acceptable Formulae](Acceptable-Formulae.md) requirements +* isn't already in Homebrew (check `brew search $FORMULA`) +* isn't in another [Homebrew tap](https://github.com/Homebrew) +* isn't already waiting to be merged (check the [issue tracker](http://github.com/Homebrew/homebrew/issues)) +* is still supported by upstream +* has a stable, tagged version (i.e. not just a GitHub repository with no versions) + +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](http://github.com/Homebrew/homebrew/tree/master/Library/Formula/git.rb) and [flac](http://github.com/Homebrew/homebrew/tree/master/Library/Formula/flac.rb) show more advanced functionality. + +A more complete [cheat-sheet](https://github.com/Homebrew/homebrew/blob/master/Library/Contributions/example-formula.rb) shows almost all the stuff you can use in a Formula. + +## Grab the URL + +All you need to make a formula is a URL to the tarball. + + brew create http://example.com/foo-0.1.tar.gz + +This creates: + +`/usr/local/Library/Formula/foo.rb` + +And opens it in your `$EDITOR`. It'll look like: + +```ruby +require "formula" + +class Foo < Formula + url "http://example.com/foo-0.1.tar.gz" + homepage "" + sha1 "1234567890ABCDEF1234567890ABCDEF" + + # depends_on "cmake" => :build + + def install + system "./configure", "--prefix=#{prefix}", "--disable-debug", "--disable-dependency-tracking" +# system "cmake", ".", *std_cmake_args + system "make install" + end +end +``` + +**Note:** If `brew` said `Warning: Version cannot be determined from URL` when doing the `create` step, you’ll need to explicitly add the correct version to the formula with `version "foo"` **and then save the formula**. `brew install` should then proceed without any trouble. + +**Note:** If `brew` said `No formula found for "php54-timezonedb". Searching open pull requests...` and you are writing a Tap, you should run `brew tap --repair`. + +## Fill in the Homepage + +**We don’t accept formulae without homepages!** + +Homebrew doesn’t have a description field because the homepage is always up to date, and Homebrew is not. That’s way less maintenance for us. Try `brew home qt`. + + +## Check the build system + + brew install -i foo + +You’re now at new prompt with the tarball extracted to a temporary sandbox. + +Check the package’s `README`. Does the package install with `autotools`, `cmake`, or something else? Delete the commented out cmake lines if the package uses autotools (i.e. if it has a `configure` script). + + +## Check for dependencies + +The `README` probably tells you about dependencies. Homebrew or OS X probably already has them. You can check for Homebrew deps with `brew search`. These are the common deps that OS X comes with: + +* `libexpat` +* `libGL` +* `libiconv` +* `libpcap` +* `libxml2` +* `Python` +* `Ruby` + +There are plenty of others. Check `/usr/lib` to see. + +We try to not duplicate libraries and complicated tools in core Homebrew. We dupe some common tools though. But generally, we avoid dupes because it’s one of Homebrew’s foundations. (And it causes build and usage problems!) + +However, we maintain a special [tap that provides dupes](https://github.com/Homebrew/homebrew-dupes). + +*Important:* Since the introduction of `superenv`, `brew --prefix`/bin is NOT on the `$PATH` during formula installation. If you have dependencies at build time, you must specify them and brew will add them to the `$PATH`. You can test around this with `--env=std`. + + +## Specifying other formulae as dependencies + +```ruby +class Foo < Formula + depends_on "jpeg" + depends_on "gtk+" => :optional + depends_on "readline" => :recommended + depends_on "boost" => "with-icu" + depends_on :x11 +end +``` + +A String specifies a formula dependency. + +A Symbol specifies a special conditional dependency, such as X11. + +A Hash specifies a formula dependency with some additional information. Given a single string key, the value can take several forms: +* a Symbol (currently one of `:build`, `:optional`, `:recommended`). + - `:build` tags that dependency as a build-time only dependency, meaning it can be safely ignored + when installing from a bottle and when listing missing dependencies using `brew missing`. + - `:optional` generates an implicit `with-foo` option for the formula. This means that, given + `depends_on "foo" => :optional`, the user must pass `--with-foo` in order to enable the dependency. + - `:recommended` generates an implicit `without-foo` option, meaning that the dependency is enabled + by default and the user must pass `--without-foo` to disable this dependency. The default + description can be overridden using the normal option syntax (in this case, the option declaration must precede the dependency): + + ```ruby + option "with-foo", "Compile with foo bindings" # This overrides the generated description if you want to + depends_on "foo" => :optional # Generated description is "Build with foo support" + ``` + +* a String or an Array + String values are interpreted as options to be passed to the dependency. You can also pass + an array of strings, or an array of symbols and strings, in which case the symbols are + interpreted as described above, and the strings are passed to the dependency as options. + + ```ruby + depends_on "foo" => "with-bar" + depends_on "foo" => %w{with-bar with-baz} + depends_on "foo" => [:optional, "with-bar"] + ``` + + +## Double-check for dependencies + +When you already have a lot of brews installed, its easy to miss a common dependency like `glib` or `gettext`. + +You can double-check which libraries a binary links to with the `otool` command (perhaps you need to use `xcrun otool`): + + $ otool -L /usr/local/bin/ldapvi + /usr/local/bin/ldapvi: + /usr/lib/libssl.0.9.8.dylib (compatibility version 0.9.8, current version 0.9.8) + /usr/lib/libcrypto.0.9.8.dylib (compatibility version 0.9.8, current version 0.9.8) + /usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.3) + /usr/local/Cellar/glib/2.22.4/lib/libglib-2.0.0.dylib (compatibility version 2201.0.0, current version 2201.4.0) + /usr/local/Cellar/gettext/0.17/lib/libintl.8.dylib (compatibility version 9.0.0, current version 9.2.0) + /usr/local/Cellar/readline/6.0/lib/libreadline.6.0.dylib (compatibility version 6.0.0, current version 6.0.0) + /usr/local/Cellar/popt/1.15/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.2.0) + /usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 38.0.0) + /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 125.0.0) + + +## Specifying gems, Python modules 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: + +```ruby +class Foo < Formula + resource "pycrypto" do + url "https://pypi.python.org/packages/source/p/pycrypto/pycrypto-2.6.tar.gz" + sha1 "c17e41a80b3fbf2ee4e8f2d8bb9e28c5d08bbb84" + end + + def install + resource("pycrypto").stage { system "python", "setup.py", "install", "--prefix=#{libexec}" } + end +end +``` + +See [ansible](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/ansible.rb) for an example of a formula that does this well. The end-result means the user doesn't have to faff with `pip` or Python and can just run `ansible`. + +[This script](https://raw.githubusercontent.com/tdsmith/labmisc/master/mkpydeps) can help you generate resource stanzas for the dependencies of your Python application. + +If your formula needs a gem or python module and it can't be made into a resource you’ll need to check for these external dependencies: + +```ruby +class Foo < Formula + depends_on "mg" => :ruby + depends_on "json" => :python + depends_on "Authen::NTLM" => :perl +end +``` + +Note that we probably won't accept the formulae in this case; it's a far worse user experience than vendoring libraries with resources. + +## Test the formula + +Exit out of the interactive shell. + + brew install --verbose --debug foo + +Debug will ask you to open an interactive shell when the build fails so you can try to figure out what went wrong. + +Check the top of the `./configure` output (if applicable)! Some configure scripts do not recognize `--disable-debug`. If you see a warning about it, remove the option from the formula. + +## Add a test to the formula + +Please add a `test do` block to the formula. This will be run by `brew test foo` and the [Brew Test Bot](Brew-Test-Bot.md). + +The `test do` block automatically creates and changes to a temporary directory which is deleted after run. You can access this Pathname with the `testpath` function. + +We want tests that don't require any user input and test the basic functionality of the application. For example `foo build-foo input.foo` is a good test and (despite their widespread use) `foo --version` and `foo --help` are bad tests. However, a bad test is better than no test at all. + +See [cmake](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/cmake.rb) for an example of a formula with a good test. A basic `CMakeLists.txt` file is written CMake uses it to generate Makefiles. This test checks that CMake doesn't e.g. segfault during basic operation. + +## Manuals + +Homebrew expects to find man pages in `[prefix]/share/man/...`, and not in `[prefix]/man/...`. + +Some software installs to man instead of `share/man`, so check the output and add a `"--mandir=#{man}"` to the `./configure` line if needed. + + +## A Quick Word on Naming + +**THE NAME IS VERY IMPORTANT!** + +Name the formula like the project markets the product. So it’s `pkg-config`, not `pkgconfig`; `sdl_mixer`, not `sdl-mixer` or `sdlmixer`. + +The only exception is stuff like “Apache Ant”. Apache sticks “Apache” in front of everything, but we use the formula name `ant`. We only include the prefix in cases like *GNUplot* (because it’s part of the name) and *GNU Go* (because everyone calls it “GNU go”—nobody just calls it “Go”). The word “Go” is too common and there are too many implementations of it. + +If you’re not sure about the name check the homepage, and check the Wikipedia page. + +[ALSO CHECK WHAT DEBIAN CALLS IT!](http://www.debian.org/distrib/packages) + +If you’re *still* not sure, just commit. I’ll apply some arbitrary rule and make a decision ;) + +When importing classes, Homebrew will require the formula and then create an instance of the class. It does this by assuming the formula name can be directly converted to the class name using a `regexp`. The rules are simple: + +* `foo-bar.rb` => `FooBar` +* `foobar.rb` => `Foobar` + +Thus, if you change the name of the class, you must also rename the file. Filenames should be all lowercase. + +Add aliases by creating symlinks in `Library/Aliases`. + + +## Audit the formula + +You can run `brew audit` to test formulae for adherence to Homebrew house style. This includes warnings for trailing whitespace, preferred URLs for certain source hosts, and a lot of other style issues. Fixing these warnings before committing will make the process a lot smoother for us. + + +## Commit + +Everything is built on Git, so contribution is easy: + + brew install git # if you already have git installed, skip this command + brew update # required in more ways than you think (initializes the brew git repository if you don't already have it) + cd `brew --repository` + # Create a new git branch for your formula so your pull request is easy to + # modify if any changes come up during review. + git checkout -b + git add Library/Formula/foo.rb + git commit + +The established standard for Git commit messages is: + +* the first line is a commit summary of *50 characters or less*, then +* two (2) newlines, then +* explain the commit throughly + +At Homebrew, we like to put the name of the formula upfront like so "foobar 7.3 (new formula)". +This may seem crazy short, but you’ll find that forcing yourself to summarise the commit encourages you to be atomic and concise. If you can’t summarise it in 50-80 characters, you’re probably trying to commit two commits as one. For a more thorough explanation, please read Tim Pope’s excellent blog post, [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). + +The preferred commit message format for simple version updates is "foobar 7.3". + +Ensure you reference any relevant GitHub issue `#12345` in the commit message. Homebrew’s history is the first thing future contributors will look to when trying to understand the current state of formulae they’re interested in. + + +## Push + +Now you just need to push back to GitHub. + +If you haven’t forked Homebrew yet, [go to the repo and hit the fork button](http://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 + +Now, please open a Pull Request (on your github repo page) for new and updated brews. + +* 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://www.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 + + +* 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/homebrew` +* `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 + + +# 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 + +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." +end +``` + + +## bin.install "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 +x foo`). + +## 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: + +```ruby +inreplace "path" do |s| + s.gsub! /foo/, "bar" +end +``` + +Make sure you modify `s`! This block ignores the returned value. + +`inreplace` should be used instead of patches when it is patching something that will never be accepted upstream e.g. make the software’s build system respect Homebrew’s installation hierarchy. If it's Homebrew and MacPorts or OS X specific it should be turned into a patch instead. + +If you need modify variables in a Makefile, rather than using `inreplace`, pass them as arguments to make: + +```rb +system "make", "target", "VAR2=value1", "VAR2=value2", "VAR3=values can have spaces" +``` + +```rb +args = %W[ + CC=#{ENV.cc} + PREFIX=#{prefix} +] + +system "make", *args +``` + +Note that values *can* contain unescaped spaces if you use the multiple-argument form of `system`. + +## Patches + +While patches should generally be avoided, sometimes they are necessary. + +When patching (i.e. fixing header file inclusion, fixing compiler warnings, etc.) the first thing to do is check whether or not the upstream project is aware of the issue. If not, file a bug report and/or submit your patch for inclusion. We may sometimes still accept your patch before it was submitted upstream but by getting the ball rolling on fixing the upstream issue you reduce the length of time we have to carry the patch around. + +*Always, always, always justify a patch with a code comment!* Otherwise, nobody will know when it is safe to remove the patch, or safe to leave it in when updating the formula. The comment should include a link to the relevant upstream issue(s). + +External patches can be declared using resource-style blocks: + +```rb +patch do + url "https://example.com/example_patch.diff" + sha1 "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef" +end +``` + +A strip level of -p1 is assumed. It can be overridden using a symbol argument: + +```rb +patch :p0 do + url "https://example.com/example_patch.diff" + sha1 "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef" +end +``` + +Patches can be declared in stable, devel, and head blocks. NOTE: always use a block instead of a conditional, i.e. `stable do ... end` instead of `if build.stable? then ... end`. + +```rb +stable do + # some other things... + + patch do + url "https://example.com/example_patch.diff" + sha1 "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef" + end +end +``` + +Embedded (__END__) patches can be declared like so: + +```rb +patch :DATA +patch :p0, :DATA +``` + +with the patch data included at the end of the file: + +``` +__END__ +diff --git a/foo/showfigfonts b/foo/showfigfonts +index 643c60b..543379c 100644 +--- a/foo/showfigfonts ++++ b/foo/showfigfonts +@@ -14,6 +14,7 @@ +… +``` + +Patches can also be embedded by passing a string. This makes it possible to provide multiple embedded patches while making only some of them conditional. +```rb +patch :p0, "..." +``` + +In embedded patches, the string `HOMEBREW_PREFIX` is replaced with the value of the constant `HOMEBREW_PREFIX` before the patch is applied. + + +## Creating the diff + + brew install --interactive --git foo + … + (make some edits) + … + git diff | pbcopy + brew edit foo + +Now just paste into the formula after `__END__`. +Instead of `git diff | pbcopy`, for some editors `git diff >> path/to/your/formula/foo.rb` might help you that the diff is not touched (e.g. white space removal, indentation, etc.) + + + +# Advanced Formula Tricks + +If anything isn’t clear, you can usually figure it out with some `grep` and the `Library/Formula` directory. Please amend this wiki page if you think it will help! + + +## Unstable versions (`HEAD`, `devel`) + +Formulae can specify alternate downloads for the upstream project’s `devel` release (unstable but not `trunk`) or `HEAD` (`master/trunk`). + +### HEAD + +HEAD URLs (activated by passing `--HEAD`) build the development cutting edge. Specifying it is easy: + +```ruby +class Foo < Formula + head "https://github.com/mxcl/lastfm-cocoa.git" +end +``` + +Homebrew understands `git`, `svn`, and `hg` URLs, and has a way to specify `cvs` repositories as a URL as well. You can test whether the `HEAD` is being built with `build.head?`. + +To use a specific commit, tag, or branch from a repository, specify head with the `:revision`, `:tag`, or `:branch` option, like so: + +```ruby +class Foo < Formula + head "https://github.com/some/package.git", :revision => "090930930295adslfknsdfsdaffnasd13" + # or :branch => "develop" + # or :tag => "1_0_release" +end +``` + +Formulae that only have `head` versions should be submitted to [homebrew/headonly](https://github.com/Homebrew/homebrew-headonly) instead of Homebrew/homebrew. + +### devel + +The "devel" spec (activated by passing `--devel`) is used for a project’s unstable releases. It is specified in a block: + +```ruby +devel do + url "https://foo.com/foo-0.1.tar.gz" + sha1 "deadbeefdeadbeefdeadbeafdeadbeefdeadbeef" +end +``` + +You can test if the "devel" spec is in use with `build.devel?`. + +## Compiler selection + +Sometimes a package fails to build when using a certain compiler. Since recent XCode no longer includes a GCC compiler, we cannot simply force the use of GCC. Instead, the correct way to declare this is the `fails_with` DSL method. A properly constructed `fails_with` block documents the latest compiler build version known to cause compilation to fail, and the cause of the failure. For example: + +```ruby +fails_with :llvm do + build 2335 + cause <<-EOS.undent + The "cause" field should include a short summary of the error. Include + the URLs of any relevant information, such as upstream bug reports. Wrap + the text at a sensible boundary (~72-80 characters), but do not break + URLs over multiple lines. + EOS +end +``` + +`build` takes a Fixnum (you can find this number in your `brew --config` output). `cause` takes a string, and the use of heredocs is encouraged to improve readability and allow for more comprehensive documentation. + +`fails_with` declarations can be used with any of `:gcc`, `:llvm`, and `:clang`. Homebrew will use this information to select a working compiler (if one is available). + + +## Specifying the Download Strategy explicitly + +To use one of Homebrew’s built-in download strategies, specify the `:using =>` flag on a `url` or `head`. For example: + +```ruby +class Sip < Formula + url "http://www.riverbankcomputing.co.uk/hg/sip/archive/4.11" + md5 "dbafd7101a4e7caee6f529912a1356e5" + head "http://www.riverbankcomputing.co.uk/hg/sip", :using => :hg + homepage "http://www.riverbankcomputing.co.uk/software/sip" +``` + +The downloaders offered by Homebrew are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Value of :usingCorresponds To
:bzrBazaarDownloadStrategy
:curlCurlDownloadStrategy
:cvsCVSDownloadStrategy
:gitGitDownloadStrategy
:hgMercurialDownloadStrategy
:nounzipNoUnzipCurlDownloadStrategy
:postCurlPostDownloadStrategy
:svnSubversionDownloadStrategy
+ + +If you need more control over the way files are downloaded and staged, you can create a custom download strategy and specify it using the `url` method's `:using` option: + + +```ruby +class MyDownloadStrategy < SomeHomebrewDownloadStrategy + # Does something cool +end + +class Foo < Formula + url "something", :using => MyDownloadStrategy +end +``` + +Specifying download strategies can be useful when used with a local repo, where a plain URL would not let you specify how to access it. For example: + +```ruby +class Bar < Formula + head "/users/abc/src/git.git", :using => :git +end +``` + + +## Just copying some files + +When your code in the install function is run, the current working directory is set to the extracted tarball. + +So it is easy to just copy some files: + +```ruby +prefix.install "file1", "file2" +``` + +Or everything: + +```ruby +prefix.install Dir["output/*"] +``` + +Generally we'd rather you were specific about what files or directories need to be installed rather than installing everything. + +### Variables for directory locations + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDefaultExample
HOMEBREW_PREFIX/usr/local
prefix#{HOMEBREW_PREFIX}/Cellar/#{name}/#{version}/usr/local/Cellar/foo/0.1
opt_prefix#{HOMEBREW_PREFIX}/opt/#{name}/usr/local/opt/foo
bin#{prefix}/bin/usr/local/Cellar/foo/0.1/bin
doc#{prefix}/share/doc/foo/usr/local/Cellar/foo/0.1/share/doc/foo
include#{prefix}/include/usr/local/Cellar/foo/0.1/include
info#{prefix}/share/info/usr/local/Cellar/foo/0.1/share/info
lib#{prefix}/lib/usr/local/Cellar/foo/0.1/lib
libexec#{prefix}/libexec/usr/local/Cellar/foo/0.1/libexec
man#{prefix}/share/man/usr/local/Cellar/foo/0.1/share/man
man[1-8]#{prefix}/share/man/man[1-8]/usr/local/Cellar/foo/0.1/share/man/man[1-8]
sbin#{prefix}/sbin/usr/local/Cellar/foo/0.1/sbin
share#{prefix}/share/usr/local/Cellar/foo/0.1/share
etc#{HOMEBREW_PREFIX}/etc/usr/local/etc
var#{HOMEBREW_PREFIX}/var/usr/local/var
buildpathA temporary dir somewhere on your system/private/tmp/[formula-name]-0q2b/[formula-name]
+ +These can be used, for instance, in code such as + +```ruby +bin.install Dir["output/*"] +``` + +to install binaries into their correct location into the cellar, and + +```ruby +man.mkpath +``` + +to create the directory structure to the man 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. + + +## Adding optional steps + +If you want to add an option: + +```ruby +class Yourformula < Formula + ... + option "with-ham", "Description of the option" + option "without-spam", "Another description" + depends_on "foo" => :optional # will automatically add a with-foo option + ... +``` + +And then to define the effects the options have: + +```ruby +if build.with? "ham" + # note, no "with" in the option name (it is added by the build.with? method) +end + +if build.without? "ham" + # works as you'd expect. True if `--without-ham` was given. +end + +if build.include? "enable-ham" + # the old style, only useful for options other than `with`/`without` style +end +``` + +Option names should be prefixed with one of the words `with`, `without`, `no`, or a verb in the imperative tense describing the action to be taken. For example, an option to run a test suite should be named `--with-test` or `--with-check` rather than `--test`, and an option to enable a shared library should be named `--enable-shared` rather than `--shared`. + +See the [graphviz](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/graphviz.rb) formula for an example. + + +## File level operations + +You can use the file utilities provided by Ruby (`FileUtils`). These are included in the `Formula` class, so you do not need the `FileUtils.` prefix to use them. They are documented [here](http://www.ruby-doc.org/stdlib/libdoc/fileutils/rdoc/index.html). + +When creating symlinks, take special care to ensure they are *relative* symlinks. This makes it easier to create a relocatable bottle. For example, to create a symlink in `bin` to an executable in `libexec`, use + +```rb +bin.install_symlink libexec/"name" +``` + +*not* + +```rb +ln_s libexec/"name", bin +``` + +The symlinks created by `install_symlink` are guaranteed to be relative. `ln_s` will only produce a relative symlink when given a relative path. + +## Handling files that should persist over formula upgrades + +For example, Ruby 1.9’s gems should be installed to `var/lib/ruby/` so that gems don’t need to be reinstalled when upgrading Ruby. You can usually do this with symlink trickery, or *better* a configure option. + +### launchd plist files + +Homebrew provides two Formula methods for launchd plist files. `plist_name` will return `homebrew.mxcl.`, and `plist_path` will return, for example, `/usr/local/Cellar/foo/0.1/homebrew.mxcl.foo.plist`. + +## Updating formulae + +Eventually a new version of the software will be released. In this case you should update the `url` and `sha1`/`sha256`. Even although it will warn on your local machine please leave the `bottle do ... end` block as-is; our CI system will update it when we pull your change. + +Check if the formula you are updating is a dependency for any other formulae by running `brew uses UPDATED_FORMULA`. If it is a dependency please `brew reinstall` all the dependencies after it is installed and verify they work correctly. + +# Style guide + +Homebrew wants to maintain a consistent Ruby style across all formulae based on [Ruby Style Guide](https://github.com/styleguide/ruby). Other formulae may not have been updated to match this guide yet but all new ones should. Also: + +* The order of methods in a formula should be consistent with other formulae (e.g.: `def patches` goes before `def install`) +* An empty line is required before the `__END__` line + + + +# Troubleshooting for people writing new formulae + +### Version detection fails + +Homebrew tries to automatically determine the version from the URL in order to save on duplication. If the tarball has a funny name though, you may have to assign the version number: + +```ruby +class Foobar + version "0.7" +end +``` + +## Bad Makefiles + +Not all projects have makefiles that will run in parallel so try to deparallelize: + + brew edit foo + +Add all this to the formula (so there will already be a class line, don’t add another or change that, and there’s already an install function, don't add another one, add the lines in the install function below to the top of the problem formula’s install function). + +```ruby +class Foo < Formula + skip_clean :all + def install + ENV.deparallelize + ENV.no_optimization + system "make" # separate make and make install steps + system "make install" + end +end +``` + +If that fixes it, please open an [issue](http://github.com/Homebrew/homebrew/issues) so that we can fix it for everyone. + +## Still won’t work? + +Check out what MacPorts and Fink do: + +`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. + +# Fortran + +Some software requires a Fortran compiler. This can be declared by adding `depends_on :fortran` to a formula. `:fortran` is a special dependency that does several things. + +First, it looks to see if you have set the `FC` environment variable. If it is set, Homebrew will use this value during compilation. If it is not set, it will check to see if `gfortran` is found in `PATH`. If it is, Homebrew will use its location as the value of `FC`. Otherwise, the `gcc` formula will be treated as a dependency and installed prior to compilation. + +If you have set `FC` to a custom Fortran compiler, you may additionally set `FCFLAGS` and `FFLAGS`. Alternatively, you can pass `--default-fortran-flags` to `brew install` to use Homebrew's standard `CFLAGS`. + +When using Homebrew's own gfortran compiler, the standard `CFLAGS` are used and user-supplied values of `FCFLAGS` and `FFLAGS` are ignored for consistency and reproducibility reasons. + + +# How to start over (reset to `master`)? + +Have you created a real mess in git which paralyzes you to create the commit you just want to push? +Then you might consider start from scratch. +Your changes will be discarded in favour of the `master` branch: + +`git checkout master` + +`git reset --hard FETCH_HEAD` diff --git a/share/doc/homebrew/Gems,-Eggs-and-Perl-Modules.md b/share/doc/homebrew/Gems,-Eggs-and-Perl-Modules.md new file mode 100644 index 0000000000000..d0111964c9282 --- /dev/null +++ b/share/doc/homebrew/Gems,-Eggs-and-Perl-Modules.md @@ -0,0 +1,136 @@ +# Gems, Eggs and Perl Modules +On a fresh OS X installation there are three empty directories for +add-ons available to all users: + + /Library/Ruby + /Library/Python + /Library/Perl + +Starting with OS X Lion (10.7), you need `sudo` to install to these like +so: `sudo gem install`, `sudo easy_install` or `sudo cpan -i`. + +An option to avoid `sudo` is to use an access control list: +`chmod +a 'user:YOUR_NAME_HERE allow add_subdirectory,add_file,delete_child,directory_inherit' /Library/Python/2.7/site-packages`, +for example, will let you add packages to Python 2.7 as yourself. That +is probably safer than changing the group ownership of the directory. + +### So why was I using sudo? +Habit maybe? + +One reason is executables go in `/usr/local/bin`. Usually this isn’t a +writable location. But if you installed Homebrew as we recommend, +`/usr/local` will be writable without sudo. So now you are good to +install the development tools you need without risking a sudo. + +### Python packages (eggs) without sudo +Rather than changing the rights on /Library/Python, we recommend the +following options: + +### With a brewed Python - you don’t need sudo +Note, `easy_install` is deprecated. We install `pip` (or `pip3` for +python3) along with python/python3. + +We set up distutils such that `pip install` will always put modules in +`$(brew --prefix)/lib/pythonX.Y/site-packages` and scripts in +`$(brew --prefix)/share/python`. Therefore, you won’t need `sudo`! + +Do `brew info python` or `brew info python3` for precise information +about the paths. Note, a brewed Python still searches for modules in +`/Library/Python/X.Y/site-packages` and also in +`~/Library/Python/X.Y/lib/python/site-packages`. + +### With system’s Python +_This is only recommended if you **don't** use a brewed Python._ + +On OS X, any [Python version X.Y also searches in +`~/Library/Python/X.Y/lib/python/site-packages` for +modules](http://docs.python.org/2/install/index.html#inst-alt-install-user). +That dir might not yet exist, but you can create it: +`mkdir -p ~/Library/Python/2.7/lib/python/site-packages` + +To teach `easy_install` and `pip` to install there, either use the +`—user` switch or create a `~/.pydistutils.cfg` file with the +following content: + + [install] + install_lib = ~/Library/Python/$py_version_short/lib/python/site-packages + +### Using virtualenv - works with brewed and system’s Python + +[Virtualenv](http://www.virtualenv.org/en/latest/) ships `pip` and +creates isolated Python environments with separate site-packages, +therefore you won’t need `sudo`. + +Rubygems without sudo +--------------------- + +**If you use rbenv or RVM then you should ignore this stuff** + +Brewed Ruby installs executables to `$(brew --prefix)/opt/ruby/bin` +without sudo. You should add this to your path. See the caveats in the +`ruby` formula for up-to-date information. + +### With system’s Ruby + +To make Ruby install install to `/usr/local`, we need to add +`gem: -n/usr/local/bin` to your `~/.gemrc`. It’s YAML…so do it manually +or use this: + + echo "gem: -n/usr/local/bin" >> ~/.gemrc + +**However all versions of RubyGems before 1.3.6 are buggy** and ignore +the above setting. Sadly a fresh install of Snow Leopard comes with +1.3.5. Currently the only known way to get round this is to upgrade +rubygems as root: + +`sudo gem update --system` + +### An Alternative + +Just install everything into the Homebrew prefix like this: + +`echo "export GEM_HOME=\"$(brew --prefix)\"" >> ~/.bashrc` + +### It doesn’t work! I get some “permissions” error when I try to install stuff! + +*Note, maybe you shouldn’t do this on Lion, since Apple have decided it +is not a good default.* + +If you ever did a `sudo gem`, etc. before then a lot of files will have +been created chown root. Fix with: + +`sudo chown -R $USER /Library/Ruby /Library/Perl /Library/Python` + +Perl CPAN Modules without sudo +------------------------------ + +The Perl module local::lib works similarly to rbenv/RVM (although for +modules only, not perl installations). A simple solution that only +pollutes your /Library/Perl a little is to install +[local::lib](http://search.cpan.org/search?query=local::lib) with sudo: + +`sudo cpan local::lib` + +Note that will install some other dependencies like `Module::Install`. +Then put the appropriate incantation in your shell’s startup, e.g. for +`.bash_profile` you insert the below, for others see the +[local::lib](http://search.cpan.org/search?query=local::lib) docs. + +`eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)` + +Now (after you restart your shell) `cpan` or `perl -MCPAN -eshell` etc. +will install modules and binaries in `~/perl5` and the relevant +subdirectories will be in your `PATH` and `PERL5LIB` etc. + +### Avoiding sudo altogether for Perl + +If you don’t even want (or can’t) use sudo for bootstrapping +`local::lib` just manually install `local::lib` in +~/perl5 and add the relevant path to `PERL5LIB` before the .bashrc eval incantation. + +Another alternative is to use `perlbrew` to install a separate copy of Perl in your home directory, or wherever you like : +```bash +curl -kL http://install.perlbrew.pl | bash +perlbrew install perl-5.16.2 +echo ".~/perl5/perlbrew/etc/bashrc" >> ~/.bashrc +``` diff --git a/share/doc/homebrew/Homebrew-0.8.md b/share/doc/homebrew/Homebrew-0.8.md new file mode 100644 index 0000000000000..f673511071e0e --- /dev/null +++ b/share/doc/homebrew/Homebrew-0.8.md @@ -0,0 +1,38 @@ +# 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 diff --git a/share/doc/homebrew/Homebrew-0.9.3.md b/share/doc/homebrew/Homebrew-0.9.3.md new file mode 100644 index 0000000000000..a6d32d2b027d4 --- /dev/null +++ b/share/doc/homebrew/Homebrew-0.9.3.md @@ -0,0 +1,34 @@ +# 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[1](#_1). +* `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`[2](#_2)) 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[†](#_†) +* We no longer worry about system duplicates[†](#_†) +* 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 +
+
    +
  • †: Nearly as much, anyway.
    • +
  • 1: Formula can opt-into re-adding the user’s PATH again. Some formulae need this.
    • +
  • 2: Indeed; this is selected based on Xcode version.
    • +
+
diff --git a/share/doc/homebrew/Homebrew-0.9.md b/share/doc/homebrew/Homebrew-0.9.md new file mode 100644 index 0000000000000..83919de8f2542 --- /dev/null +++ b/share/doc/homebrew/Homebrew-0.9.md @@ -0,0 +1,28 @@ +# 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. diff --git a/share/doc/homebrew/Homebrew-2.md b/share/doc/homebrew/Homebrew-2.md new file mode 100644 index 0000000000000..80b9e3f6a79b0 --- /dev/null +++ b/share/doc/homebrew/Homebrew-2.md @@ -0,0 +1,3 @@ +# Homebrew 2 +Idea for Homebrew 2: +* https://github.com/Homebrew/homebrew/issues/11041 diff --git a/share/doc/homebrew/Homebrew-and-Python.md b/share/doc/homebrew/Homebrew-and-Python.md new file mode 100644 index 0000000000000..28fbbe7ef18b4 --- /dev/null +++ b/share/doc/homebrew/Homebrew-and-Python.md @@ -0,0 +1,159 @@ +# Homebrew and Python +## Overview + +This page describes how Python is handled in Homebrew. + +Homebrew should work with any [CPython](http://stackoverflow.com/questions/2324208/is-there-any-difference-between-cpython-and-python) and defaults to the OS X system Python. + +Homebrew provides formulae to brew a more up-to-date Python 2.7.x (and 3.x). + +**Important:** If you choose to install a Python which isn't either of these two (system Python or brewed Python), the Homebrew team can only provide limited support. + + +## Python 2.x or Python 3.x + +Homebrew provides a formula for Python 2.7.x and one for Python 3.x. They don't conflict, so they can both be installed. The executable `python` will always point to the 2.x and `python3` to the 3.x version. + +([Wondering which one to choose?](http://wiki.python.org/moin/Python2orPython3)) + + +## Setuptools, Pip, etc. + +The Python formulae install [`pip`](http://www.pip-installer.org) and [Setuptools](https://pypi.python.org/pypi/setuptools). + +Setuptools can be updated via Pip, without having to re-brew Python: + + pip install --upgrade setuptools + +Similarly, Pip can be used to upgrade itself via: + + pip install --upgrade pip + +### Note on `pip install --user` + +The normal `pip install --user` is disabled for brewed Python. This is because of a bug in distutils, because Homebrew writes a `distutils.cfg` which sets the package `prefix`. + +A possible workaround (which puts executable scripts in `~/Library/Python/./bin`) is: + + pip install --user --install-option="--prefix=" + +You can make this "empty prefix" the default by adding a `~/.pydistutils.cfg` file with the following contents: + + [install] + prefix= + +## `site-packages` and the `PYTHONPATH` + +The `site-packages` is a directory that contains Python modules (especially bindings installed by other formulae). Homebrew creates it here: + + $(brew --prefix)/lib/pythonX.Y/site-packages + +So, for Python 2.7.x, you'll find it at `/usr/local/lib/python2.7/site-packages`. + +Python 2.7 also searches for modules in: + + - `/Library/Python/2.7/site-packages` + - `~/Library/Python/2.7/lib/python/site-packages` + +Homebrew's `site-packages` directory is first created if (1) any Homebrew formula with Python bindings are installed, or (2) upon `brew install python`. + +### Why here? + +The reasoning for this location is to preserve your modules between (minor) upgrades or re-installations of Python. Additionally, Homebrew has a strict policy never to write stuff outside of the `brew --prefix`, so we don't spam your system. + +## Homebrew-provided Python bindings + +Some formulae provide python bindings. Sometimes a `--with-python` or `--with-python3` option has to be passed to `brew install` in order to build the python bindings. (Check with `brew options `.) + +Homebrew builds bindings against the first `python` (and `python-config`) in your `PATH`. (Check with `which python`). + +**Warning!** Python may crash (see [Common Issues](Common-Issues.md)) if you `import ` from a brewed Python if you ran `brew install ` against the system Python. If you decide to switch to the brewed Python, then reinstall all formulae with python bindings (e.g. `pyside`, `wxwidgets`, `pygtk`, `pygobject`, `opencv`, `vtk` and `boost`). + +## Policy for non-brewed Python bindings + +These should be installed via `pip install `. To discover, you can use `pip search` or . (**Note:** System Python does not provide `pip`. Simply `easy_install pip` to fix that.) + + +## Brewed Python modules + +For brewed Python, modules installed with `pip` or `python setup.py install` will be installed to `$(brew --prefix)/lib/pythonX.Y/site-packages` directory (explained above). Executable python scripts will be in `$(brew --prefix)/bin`. (To better conform to standard behavior, `brew` no longer puts Python scripts into `share/python/$(brew --prefix)`.) + +The system Python may not know which compiler flags to set in order to build bindings for software installed in Homebrew so you may need to: + +`CFLAGS=-I$(brew --prefix)/include LDFLAGS=-L$(brew --prefix)/lib pip install `. + + +## Virtualenv + +**WARNING:** When you `brew install` formulae that provide Python bindings, you should **not be in an active virtual environment**. + +Activate the virtualenv *after* you've brewed, or brew in a fresh Terminal window. +Homebrew will still install Python modules into Homebrew's `site-packages` and *not* into the virtual environment's site-package. + +Virtualenv has a switch to allow "global" (i.e. Homebrew's) `site-packages` to be accessible from within the virtualenv. + +## Creating a formulae with nice Python bindings + +You can add the following :special dependency to the formula: + + depends_on :python + +This assures that Homebrew looks for a suitable Python 2.7 and sets up `PATH` accordingly (as well as a few other things; see below). Omitting this line may lead to error messages like `Python.h not found`. + +To allow the user to opt-out (via `--without-python`): + + depends_on :python => :recommended + +To allow the user to opt-in (via `--with-python3` for Python3): + + depends_on :python3 => :optional + +These options are automatically generated. In the formula you can check via `build.with? 'python'` what the user has decided. + +If you need to specify that specific Python modules (rather than just Python itself) are needed: + + depends_on 'numpy' => :python + +Or if the import name is different to the module name: + + depends_on "MacFSEvents" => [:python, "fsevents"] + + +### If the software provides a `setup.py` + +Usually this line will do the trick: + + system "python", "setup.py", "--prefix=#{prefix}" + +The `--prefix=#{prefix}` part is to ensure that Python bindings are installed into the Cellar for that specific formula in: + + $(brew --prefix)/Cellar///lib/python2.7/site-packages + +When `brew link` is run (automatically at the end of `brew install`), the Python modules should be linked into `$(brew --prefix)/lib/pythonX.Y/site-packages`, and the scripts should go into `$(brew --prefix)/bin`. This enables brew to `unlink`/`link`/`uninstall` cleanly. + +If the `setup.py` is older, it may need two additional arguments to avoid writing an `easy-install.pth` file (which will conflict with the `easy-install.pth` already installed by `pip`/`setuptools`). So, if you get a `brew link` problem mentioning this file, add this to the `setup.py` args: + + "--single-version-externally-managed", "--record=installed.txt" + +### If the formula uses `configure`/`make` + +Generally, the `./configure` files provided by software Homebrew installs can find `python` or `python-config` (and/or look at the `PYTHON` var). Both are set up by Homebrew during brewing. + +Often, a `--with-python` or similar flag can be given to `configure`. Check with `./configure --help`. + +If the `configure` and `make` scripts do not want to install into the Cellar, one option is to: + +1. Call `./configure --without-python` (or a similar named option) +1. `cd` into the directory containing the Python bindings +1. Call `setup.py` explicitly (as described above) + +Sometimes we have to `inreplace` a `Makefile` to use our prefix for the python bindings. (`inreplace` is one of Homebrew's helper methods, which greps and edits text files on-the-fly.) + +## Technical details + +Formula authors necessarily don't need to read this. + +Adding `depends_on :python` triggers the following actions: + +- The user `PATH` (the original `PATH`, not the superenv `PATH`) is searched for a suitable `python` executable (`python3` for 3.x). +- The `PYTHONPATH` is set (internally only), so the system Python can find brewed python modules. diff --git a/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md b/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md new file mode 100644 index 0000000000000..eaf16914284f4 --- /dev/null +++ b/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md @@ -0,0 +1,35 @@ +# How To Open a Homebrew Pull Request (and get it merged) +The following commands are used by Homebrew's contributors to setup a fork of Homebrew's Git repository on GitHub, create a new branch and create a GitHub pull request of the changes in that branch. + +To setup a your own fork of the Homebrew repository: + +1. Change to the directory containing your Homebrew installation with `cd $(brew --repository)` +2. Fork the Homebrew repository on GitHub. This creates a pushable, personal remote repository. This is needed as only Homebrew maintainers have push access to the main repository. +3. Add the pushable forked repository with `git remote add YOUR_USERNAME https://github.com/YOUR_USERNAME/homebrew.git` + +To make a new branch and submit it for review: + +1. Checkout the `master` branch with `git checkout master` +2. Retrieve new changes to the `master` branch with `brew update` (which calls `git pull`) +3. Create a new branch from the latest `master` branch with `git checkout -b YOUR_BRANCH_NAME origin/master` +4. Make your changes to any Homebrew formula with `brew edit` (following all the requirements in the [Formula Cookbook](Formula-Cookbook.md)). Run `brew audit ANY_CHANGED_FORMULA`, `brew tests` and `brew install ANY_CHANGED_FORMULA && brew test ANY_CHANGED_FORMULA` and ensure all of these pass without issue. +5. Make a separate commit for each changed formula with `git add` and `git commit`. +6. Upload your new commits to the branch to your fork with `git push --set-upstream YOUR_USERNAME YOUR_BRANCH_NAME` +7. Go to https://github.com/Homebrew/homebrew and create a pull request to request review and merge of commits in your pushed branch. Make sure you explain why the change is needed and, if fixing a bug, how to reproduce the bug. Await feedback or a merge from Homebrew's maintainers. + +To respond well to feedback: + +1. Ask for clarification of anything you don't understand and help with anything you don't know how to do. +2. Post a comment on your pull request if you've provided all the requested changes/information and it hasn't been merged after a week. Post a comment on your pull request if you're stuck and need help. +3. Keep discussion in the pull request unless requested otherwise (i.e. do not email maintainers privately). +4. Do not continue discussion in closed pull requests. +5. Do not argue with Homebrew maintainers. You may disagree but unless they change their mind please implement what they request. Ultimately they control what is included in Homebrew as they have to support any changes that are made. + +To make changes based on feedback: + +1. Checkout your branch again with `git checkout YOUR_BRANCH_NAME` +2. Make any requested changes and commit them with `git add` and `git commit` +3. Squash new commits into one change per formula with `git rebase --interactive origin/master` +4. Push to the fork's remote branch and the pull request with `git push --force` + +Once all feedback has been addressed and if it's a change we want to include (we include most changes) then we'll add your commit to Homebrew. Well done, you are now a Homebrew contributor! diff --git a/share/doc/homebrew/Installation.md b/share/doc/homebrew/Installation.md new file mode 100644 index 0000000000000..b00ef059387ba --- /dev/null +++ b/share/doc/homebrew/Installation.md @@ -0,0 +1,91 @@ +# Installation +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#wiki-sudo) 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. + +## Requirements +* An Intel CPU [1](#1) +* OS X 10.6 or higher [2](#2) +* Command Line Tools for Xcode: `xcode-select --install`, + https://developer.apple.com/downloads or + [Xcode](http://itunes.apple.com/us/app/xcode/id497799835) [3](#3) +* A Bourne-compatible shell for installation (e.g. bash or zsh) [4](#4) + +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. + +However do yourself a favor and install to `/usr/local`. Some things may +not build when installed elsewhere. One of the reasons Homebrew just +works relative to the competition is **because** we recommend installing +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 not recommended. +You may consider updating your CA certificates instead. + +## Uninstallation +Uninstallation is documented in the [FAQ](FAQ.md). + +1 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). + +2 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). + +3 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). + +4 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. diff --git a/share/doc/homebrew/Interesting-Taps-&-Branches.md b/share/doc/homebrew/Interesting-Taps-&-Branches.md new file mode 100644 index 0000000000000..8e137cb1ca3ba --- /dev/null +++ b/share/doc/homebrew/Interesting-Taps-&-Branches.md @@ -0,0 +1,104 @@ +# Interesting Taps & Branches +A Tap is homebrew-speak for a git repository containing extra formulae. +Homebrew has the capability to add (and remove) multiple taps to your local installation with the `brew tap` and `brew untap` command. Type `man brew` in your Terminal. The main repository https://github.com/Homebrew/homebrew often called "Homebrew/homebrew" is always built-in. + +## Main Taps + +* [homebrew/science](https://github.com/Homebrew/homebrew-science) + - A collection of scientific libraries and tools. + +* [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes) + - Need GDB or a newer Tk? System duplicates go here. + +* [homebrew/versions](https://github.com/Homebrew/homebrew-versions) + - Need e.g. older or newer versions of Python? Newer versions of GCC? + +* [homebrew/games](https://github.com/Homebrew/homebrew-games) + - Game formulae. + +* [homebrew/apache](https://github.com/Homebrew/homebrew-apache) + - A tap for Apache modules, extending OS X's built-in Apache. These brews may require unconventional additional setup, as explained in the caveats. + +* [homebrew/headonly](https://github.com/Homebrew/homebrew-headonly) + - A tap for brews that don't have stable versions. + +* [homebrew/php](https://github.com/Homebrew/homebrew-php) + - Repository for php-related formulae. + +* [homebrew/python](https://github.com/Homebrew/homebrew-python) + - A few Python formulae that do not build well with `pip` alone. + +* [homebrew/completions](https://github.com/Homebrew/homebrew-completions) + - Shell completion formulae. + +* [homebrew/x11](https://github.com/Homebrew/homebrew-x11) + - Formulae with hard X11 dependencies. + +* [homebrew/boneyard](https://github.com/Homebrew/homebrew-boneyard) + - Formula are not deleted, they are moved here. + +* [homebrew/nginx](https://github.com/Homebrew/homebrew-nginx) + - Feature rich Nginx tap for modules + +* [homebrew/binary](https://github.com/Homebrew/homebrew-binary) + - Precompiled binary formulae. + + +`brew search` looks in these main taps and as well in [Homebrew/homebrew](https://github.com/Homebrew/homebrew). So don't worry about missing stuff. We will add other taps to the search as they become well maintained and popular. + +You can be added as a maintainer for one of the Homebrew organization taps and aid the project! If you are interested write to our list: homebrew@librelist.com. We want your help! + + +## Other Interesting Taps + +* [larsimmisch/avr](https://github.com/larsimmisch/homebrew-avr) + - GNU AVR toolchain (avr-gcc etc. for Arduino hackers). + +* [titanous/gnuradio](https://github.com/titanous/homebrew-gnuradio) + - GNU Radio and friends running on OS X. + +* [besport/ocaml](https://github.com/besport/homebrew-ocaml) + - A tap for Ocaml libraries, though with caveats, it requires you install its customized ocaml formula. Perhaps a template for more work. + +* [nolith/embedded](https://github.com/nolith/homebrew-embedded) + - Flashing tools for embedded devices and olsrd for mesh network routing. + +* [anarchivist/forensics](https://github.com/anarchivist/homebrew-forensics) + - Digital forensics-related formulae; mostly head-only, binary-only, or unstable. + +* [petere/postgresql](https://github.com/petere/homebrew-postgresql) + - Allows installing multiple PostgreSQL versions in parallel. + +* [iMichka/MacVTKITKPythonBottles](https://github.com/iMichka/homebrew-MacVTKITKPythonBottles) + - VTK and ITK binaries with Python wrapping. + +* [edavis/emacs](https://github.com/edavis/homebrew-emacs) + - A tap for Emacs packages. + +## Interesting Branches (aka forks) + +* [mistydemeo/tigerbrew](https://github.com/mistydemeo/tigerbrew) + - Experimental Tiger PowerPC version + +* [codebutler](https://github.com/codebutler/homebrew/commits/master) + - Preliminary support for GTK+ using the Quartz (native OS X) back-end + +* [paxan/linux](https://github.com/paxan/homebrew/commits/linux) + - Experimental Linux version + +* [homebrew/linuxbrew](https://github.com/Homebrew/linuxbrew) + - Experimental Linux version + +* [rmyers/homebrew](https://github.com/rmyers/homebrew) + - Experimental Solaris version + +* [nddrylliog/winbrew](https://github.com/nddrylliog/winbrew) + - Experimental Windows version + +* [wilmoore/homebrew-home](https://github.com/wilmoore/homebrew-home) + - Homebrew install for those that like to Homebrew @ $HOME (i.e. ~/.homebrew). + + +## Technical Details + +Your taps are git repositories located at `$(brew --prefix)/Library/Taps`. diff --git a/share/doc/homebrew/Maintainer-Guidelines.md b/share/doc/homebrew/Maintainer-Guidelines.md new file mode 100644 index 0000000000000..c7fa58c7492a9 --- /dev/null +++ b/share/doc/homebrew/Maintainer-Guidelines.md @@ -0,0 +1,148 @@ +# Maintainer Guidelines +**This guide is for maintainers.** These special people have **write +access** to Homebrew’s repository and help merge the contributions of +others. You may find what is written here interesting, but it’s +definitely not a beginner’s guide. + +Maybe you were looking for the [Formula Cookbook](Formula-Cookbook.md)? + +## Quick Checklist + +This is all that really matters: +- Ensure the name is correct. This cannot be changed later, so it must + be right the first time! +- Add aliases +- Ensure it is not a dupe of anything that comes with OS X +- Ensure it is not a library that can be installed with + [gem](http://en.wikipedia.org/wiki/RubyGems), + [cpan](http://en.wikipedia.org/wiki/Cpan) or + [pip](https://crate.io). +- Ensure the name is not in Ruby’s stdlib (Try + `Formula.factory('readline')` in the `brew irb` shell) +- Ensure that any dependencies are accurate + +You should test the build process. But you’re really pressed for time, +just get it in there and let someone else test the build. + +Checking deps is important, because they will probably stick around +forever. Nobody really checks if they are necessary or not. Use the +`:optional` and `:recommended` modifiers as appropriate. + +Depend on as little stuff as possible. Avoid X11 functionality unless it +is required. 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. + +### 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. +For example, we chose `objective-caml`, but we should have chosen `ocaml`. +Choose what people say to each other when talking about the project. + +Add other names as aliases with the `aka` class function. Ensure the +name referenced on the homepage is one of these, as it may be different +and have underscores and hyphens and so on. + +We don’t allow versions in formula names (e.g. `bash4.rb`). This is +sometimes frustrating, but we’re trying to solve this properly. +(`python3.rb` is a rare exception, because it’s basically a “new” +language and installs no conflicting executables.) + +For now, if someone submits a formula like this, we’ll leave them in +their own tree. + +### Merging, rebasing, cherry-picking +Merging is mainly useful when new work is being done. Please `rebase` or +cherry-pick contributions rather than fill our tree up with noisy merge +commits. + +Don’t `rebase` until you finally `push`. Once pushed, you can’t `rebase` +: **you’re a maintainer now!** + +Cherry-picking changes the date of the commit, which kind of sucks. + +Don’t `merge` unclean branches. So if someone is still learning `git` +their branch is filled with nonsensical merges, then `rebase` and squash +the commits. Our main branch history should be useful to other people, +not confusing. + +### Testing +We need to at least check it builds. Use [Brew Test Bot](Brew-Test-Bot.md) for this. + +Verify the formula works if possible. If you can’t tell—for example, if +it’s a library—trust the original contributor, it worked for them, so +chances are it is fine. If you aren’t an expert in the tool in question, +you can’t really gauge if the formula installed the program correctly. +At some point an expert will come along, cry blue murder that it doesn’t +work, and fix it. This is how open source works. + +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](http://help.github.com/git-email-settings/) +2. Sign off cherry-picks if you amended them (GitX can do this, + otherwise there is a command line flag for it) +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. + +### Dupes +The main branch avoids dupes as much as possible. The exception is +libraries that OS X provides but have bugs, and the bugs are fixed in a +newer version. Or libraries that OS X provides, but they are too old for +some other formula. + +Still determine if it possible to avoid the dupe. Be thorough. Duped +libs and tools cause bugs that are tricky to solve. Once the formula is +pulled, we can’t go back on that willy-nilly. + +If it dupes anything ask another comtributor first. Some dupes are okay, +some can cause subtle issues we don’t want to have to deal with in the +future. + +Dupes we have allowed: +- `libxml` \<— OS X version is old and buggy +- `libpng` \<— Ditto + +#### 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 +new guy didn’t know why it was there. Regressions suck. + +### Don’t allow bloated diffs +Amend a cherry-pick to remove commits that are only changes in +whitespace. They are not acceptable because our history is important and +`git blame` should be useful. + +Whitespace corrections (to ruby standard etc.) are allowed (in fact this +is a good opportunity to do it) provided the line itself has some kind +of modification that is not whitespace in it. But be careful about +making changes to inline patches—make sure they still apply. + +This rule is why the `case` statement in the `brew` tool is a mess. +We’ll fix such things up for v2. + +### Moving formulae from one tap to another +And preserving the history. I made a +[gist](https://gist.github.com/samueljohn/5280700) about this, based on +Jack’s initial version. diff --git a/share/doc/homebrew/Press.md b/share/doc/homebrew/Press.md new file mode 100644 index 0000000000000..8a733783641c3 --- /dev/null +++ b/share/doc/homebrew/Press.md @@ -0,0 +1,17 @@ +# Press +### Featured +* [Homebrew: OS X’s Missing Package Manager](http://www.engineyard.com/blog/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](http://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](http://activemq.apache.org/getting-started.html#GettingStarted-UsingHomebrewinstalleronOSX) diff --git a/share/doc/homebrew/Querying-Brew.md b/share/doc/homebrew/Querying-Brew.md new file mode 100644 index 0000000000000..f0933a56d4eaa --- /dev/null +++ b/share/doc/homebrew/Querying-Brew.md @@ -0,0 +1,67 @@ +# Querying Brew +_In this document we will be using [jq](http://stedolan.github.io/jq/) to parse JSON, available from Homebrew using `brew install jq`._ + +## Overview + +`brew` provides commands for getting common types of information out of the system. `brew list` showed installed formulae. `brew deps foo` shows the dependencies that `foo` needs. + +Additional commands, including external commands, can of course be written to provide more detailed information. There are a couple of disadvantages here. First, it means writing Ruby against a possibly changing Homebrew codebase. There will be more code to touch during refactors, and Homebrew can't guarantee that external commands will continue to work. Second, it means designing the commands themselves, specifying input parameters and output formats. + +To enable users to do rich queries without the problems above, Homebrew provides the `brew info` command. + +## `brew info --json` + +`brew info` outputs JSON-formatted information about formulae. This JSON can then be parsed using your tools of choice. + +From the manpage: + + * `info --json=` (--all|--installed|): + Print a JSON representation of . Currently the only accepted value + for is `v1`. + + Pass `--all` to get information on all formulae, or `--installed` to get + information on all installed formulae. + +The current schema version is `v1`. Note that fields may be added to the schema as needed without incrementing the schema. Any significant breaking changes will cause a change to the schema version. + +The schema itself is not currently documented outside of the code that generates it: [Formula#to_hash](https://github.com/Homebrew/homebrew/blob/master/Library/Homebrew/formula.rb#L443) + +(**TODO**: add a manpage for the schema) + +## Examples + +_The top-level element of the JSON is always an array, so the `map` operator is used to act on the data._ + +### Prety-print a single formula's info + +`brew info --json=v1 tig | jq .` + +### Installed formulae + +To show full JSON information about all installed formulae: + +`brew info --json=v1 --all | jq "map(select(.installed != []))"` + +You'll note that processing all formulae can be slow; it's quicker to let `brew` do this: + +`brew info --json=v1 --installed` + +### Linked keg-only formulae + +Some formulae are marked as "keg-only", meaning that installed files are not linked to the shared `bin`, `lib`, etc. directors, as doing so can cause conflicts. Such formulae can be forced to link to the shared directories, but doing so is not recommended (and will cause `brew doctor` to complain.) + +To find the names of linked keg-only formulae: + +`brew info --json=v1 --installed | jq "map(select(.keg_only == true and .linked_keg != null) | .name)"` + +### Unlinked normal formulae + +To find the names of normal (not keg-only) formulae that are installed, but not linked to the shared directories: + +`brew info --json=v1 --installed | jq "map(select(.keg_only == false and .linked_keg == null) | .name)"` + +## Concluding remarks + +Using the JSON output, queries can be made against Homebrew with less risk of being broken due to Homebrew code changes, and without needing to understand Homebrew's ruby internals. + +If the JSON does not provide some information that it ought to, please submit request, preferably with a patch to add the desired information. diff --git a/share/doc/homebrew/README.md b/share/doc/homebrew/README.md new file mode 100644 index 0000000000000..8a6a01a2f359a --- /dev/null +++ b/share/doc/homebrew/README.md @@ -0,0 +1,53 @@ +# 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) + +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. + +## Troubleshooting +First, please run `brew update` 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 +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 http://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) + +### 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. + +## Supporters +[A list of the awesome people who gave £5 or more to our +Kickstarter](https://github.com/Homebrew/homebrew/blob/master/SUPPORTERS.md). diff --git a/share/doc/homebrew/The-brew-command.md b/share/doc/homebrew/The-brew-command.md new file mode 100644 index 0000000000000..a8c3011ffafd4 --- /dev/null +++ b/share/doc/homebrew/The-brew-command.md @@ -0,0 +1,3 @@ +# The brew command +This page has been deprecated in favor of the Homebrew manual (type +`man brew` in Terminal). diff --git a/share/doc/homebrew/Tips-N'-Tricks.md b/share/doc/homebrew/Tips-N'-Tricks.md new file mode 100644 index 0000000000000..91f15a9f6c7c9 --- /dev/null +++ b/share/doc/homebrew/Tips-N'-Tricks.md @@ -0,0 +1,125 @@ +# Tips N' Tricks +## Package versions + +The preferred and supported method of installing specific versions of formulae is to use the [Homebrew-versions](https://github.com/Homebrew/homebrew-versions) tap. + +### Installing directly from pull-requests + +You can browse pull requests https://github.com/Homebrew/homebrew/pulls +and install through the direct link. For example Python 3.3.0 pull request https://github.com/Homebrew/homebrew/pull/15199 + +```zsh +brew install https://raw.github.com/dsr/homebrew/9b22d42f50fcbc5e52c764448b3ac002bc153bd7/Library/Formula/python3.rb +``` + +## Quickly remove something from /usr/local + +```bash +brew unlink $FORMULA +``` + +This can be useful if a package can't build against the version of something you have linked into `/usr/local`. + +And of course, you can simply `brew link $FORMULA` again afterwards! + + + +## Install into Homebrew without formulas + +```bash +./configure --prefix=/usr/local/Cellar/foo/1.2 && make && make install && brew link foo +``` + + + +## Command tab-completion + + +### Bash +Add to your `~/.bashrc` or `~/.bash_profile` (whichever you have configured to run on shell startup): + +```bash +source `brew --repository`/Library/Contributions/brew_bash_completion.sh +``` + + +### ZSH +Run in terminal (may require `sudo`): + +```zsh +ln -s "$(brew --prefix)/Library/Contributions/brew_zsh_completion.zsh" /usr/local/share/zsh/site-functions +``` + +## Pre-downloading a file for a formula + +Sometimes it's faster to download a file via means other than those strategies that are available as part of Homebrew. For example, Erlang provides a Torrent that'll let you download at 4–5× the normal HTTP method. Download the file and drop it in `~/Library/Caches/Homebrew`, but watch the file name. Homebrew downloads files as {{ formula name }}-{{ version }}. In the case of Erlang, this requires renaming the file from otp_src_R13B03 to erlang-R13B03. + +**New:** +```bash +mv the_tarball `brew --cache formula-name` +``` + +You can also pre-cache the download by using the command `brew fetch formula` which also displays the SHA1 and SHA256 values. This can be useful for updating formulae to new versions. + + + +## Using Homebrew behind a proxy + +Behind the scenes, Homebrew uses several commands for downloading files (e.g. curl, git, svn). Many of these tools can download via a proxy. It's a common (though not universal) convention for these command-line tools to observe getting the proxy parameters from environment variables (e.g. `http_proxy`). Unfortunately, most tools are inconsistent in their use of these environment parameters (e.g. curl supports `http_proxy`, `HTTPS_PROXY`, `FTP_PROXY`, `GOPHER_PROXY`, `ALL_PROXY`, `NO_PROXY`). + +Luckily, for the majority of cases setting `http_proxy` is enough. You can set this environment variable in several ways (search on the internet for details), but the way I prefer is: + +```bash +$ http_proxy=http://: brew install $FORMULA +``` + + +### Proxy Authentication + +```bash +$ http_proxy=http://:@: brew install $FORMULA +``` + +**NB:** this technique will also work if you prefer to use `sudo` with Homebrew. But as `sudo` clears the environment before executing Homebrew, your proxy settings may get lost. + +**Workaround:** + +```bash +$ http_proxy=http://: sudo -E brew install $FORMULA +``` + +## Installing stuff without the Xcode-CLT + +```bash +$ brew sh # or: eval $(brew --env) +$ gem install ronn # or c-programs +``` + +This imports the brew environment into your existing shell, gem will pick up the environment variables and be able to build. As a bonus brew's automatically determined optimization flags are set. + +## Install only a formula's dependencies (not the formula) + +``` +brew install --only-dependencies $FORMULA +``` + +## brew irb + +```bash +$ brew irb +1.8.7 :001 > Formula.factory("ace").methods - Object.methods + => [:install, :path, :homepage, :downloader, :stable, :bottle, :devel, :head, :active_spec, :buildpath, :ensure_specs_set, :url, :version, :specs, :mirrors, :installed?, :explicitly_requested?, :linked_keg, :installed_prefix, :prefix, :rack, :bin, :doc, :include, :info, :lib, :libexec, :man, :man1, :man2, :man3, :man4, :man5, :man6, :man7, :man8, :sbin, :share, :etc, :var, :plist_name, :plist_path, :download_strategy, :cached_download, :caveats, :options, :patches, :keg_only?, :fails_with?, :skip_clean?, :brew, :std_cmake_args, :deps, :external_deps, :recursive_deps, :system, :fetch, :verify_download_integrity, :fails_with_llvm, :fails_with_llvm?, :std_cmake_parameters, :mkdir, :mktemp] +1.8.7 :002 > +``` + +## Hiding the beer mug emoji when finishing a build + +```bash +export HOMEBREW_NO_EMOJI=1 +``` + +This sets the HOMEBREW_NO_EMOJI environment variable, causing homebrew to hide all emoji. + +## Sublime text: Syntax for formulae including the diff + +In Sublime Text 2/3, you can use Package Control to install [Homebrew-formula-syntax](https://github.com/samueljohn/Homebrew-formula-syntax). diff --git a/share/doc/homebrew/Troubleshooting.md b/share/doc/homebrew/Troubleshooting.md new file mode 100644 index 0000000000000..d6b2f229826f4 --- /dev/null +++ b/share/doc/homebrew/Troubleshooting.md @@ -0,0 +1,56 @@ +# Troubleshooting +## Read this first! + +Please run `brew update` and `brew doctor` *before* creating an issue! + +If you create an issue, please also create a [Gist][] by running + +``` +brew gist-logs +``` + +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][]? +* 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`. + +#### 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. + +## 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 "\ failed to build on 10.x", where \ 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 ` + * You can also create a [Gist][] manually. Include the following: + 1. The output from `HOMEBREW_MAKE_JOBS=1 brew install -v 2>&1` + 2. The contents of the largest numbered log in `~/Library/Logs/Homebrew/`, 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]:http://support.apple.com/kb/DL1572 +[JDK 7]:http://docs.oracle.com/javase/7/docs/webnotes/install/mac/mac-install-faq.html diff --git a/share/doc/homebrew/Winbrew.md b/share/doc/homebrew/Winbrew.md new file mode 100644 index 0000000000000..f175d39364304 --- /dev/null +++ b/share/doc/homebrew/Winbrew.md @@ -0,0 +1,4 @@ +# Winbrew +Winbrew is an experimental port of Homebrew for Windows (with an MSYS/MinGW environment): + + * https://github.com/nddrylliog/winbrew diff --git a/share/doc/homebrew/Xcode.md b/share/doc/homebrew/Xcode.md new file mode 100644 index 0000000000000..7fb71f624ba06 --- /dev/null +++ b/share/doc/homebrew/Xcode.md @@ -0,0 +1,62 @@ +# Xcode +## Supported Xcode Versions +Homebrew supports and recommends the latest Xcode and/or Command Line +Tools available for your platform: + + OS X | Xcode | Command Line Tools + ----- | ----- | ---------------------------- + 10.6 | 3.2.6 | N/A + 10.7 | 4.6.3 | April 2013 + 10.8 | 5.1.1 | April 2014 + 10.9 | 6.0.1 | September 2014 (for Xcode 6) + 10.10 | 6.1 | 6.1 + + +## Compiler Version Database + + Xcode | GCC 4.0 | GCC 4.2 | LLVM-GCC 4.2 | LLVM | Clang | LLVM (SVN) + --------- | ----------- | ----------- | ---------------- | ----------- | --------------- | ---------- + 2.5.0 | 5370 | — | — | — | — | — + 3.1.4 | 5493 | 5577 | 5555 | 2064.3 | — | — + 3.2.0 | 5493 | 5646 | 5646 | 2118 | — | — + 3.2.1 | 5493 | 5646 | 5646 | 2206 | — | — + 3.2.2 | 5493 | 5659 | 5646 | 2207.5 | 1.0.2 | — + 3.2.3 | 5494 | 5664 | 5658 | 2326.10 | 1.5 (60) | — + 3.2.4 | 5494 | 5664 | 5658 | 2326.10 | 1.5 (60) | — + 3.2.5 | 5494 | 5664 | 5658 | 2333.4 | 1.6 (70) | — + 3.2.6 | 5494 | 5666 | 5658 | 2335.6 | 1.7 (77) | 2.9 + 4.0.0 | 5494 | 5666 | 5658 | 2335.9 | 2.0 (137) | 2.9 + 4.0.2 | 5494 | 5666 | 5658 | 2335.9 | 2.0 (137) | 2.9 + 4.1.0 | — | 5666 | 5658 | 2335.15.00 | 2.1 (163.7.1) | 3.0 + 4.2.0 | — | — | 5658 | 2336.1.00 | 3.0 (211.10.1) | 3.0 + 4.3.0 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.45) | 3.1 + 4.3.1 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.54) | 3.1 + 4.3.2 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.58) | 3.1 + 4.3.3 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.61) | 3.1 + 4.4.0 | — | — | 5658 | 2336.11.00 | 4.0 (421.0.57) | 3.1 + 4.4.1 | — | — | 5658 | 2336.11.00 | 4.0 (421.0.60) | 3.1 + 4.5.0 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.65) | 3.1 + 4.5.1 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.66) | 3.1 + 4.5.2 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.66) | 3.1 + 4.6.0 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.24) | 3.2 + 4.6.1 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.27) | 3.2 + 4.6.2 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.28) | 3.2 + 4.6.3 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.28) | 3.2 + 5.0.0 | — | — | — | — | 5.0 (500.2.76) | 3.3 + 5.0.1 | — | — | — | — | 5.0 (500.2.78) | 3.3 + 5.0.1 | — | — | — | — | 5.0 (500.2.79) | 3.3 + 5.1 | — | — | — | — | 5.1 (503.0.38) | 3.4 + 5.1.1 | — | — | — | — | 5.1 (503.0.40) | 3.4 + 6.0 | — | — | — | — | 6.0 (600.0.51) | 3.5 + 6.0.1 | — | — | — | — | 6.0 (600.0.51) | 3.5 + 6.1 | — | — | — | — | 6.0 (600.0.54) | 3.5 + +## References to Xcode and compiler versions in code +When a new Xcode release is made, the following things need to be +updated: + +* `MacOS::Xcode.latest_version` +* `MacOS::CLT.latest_version` +* `MacOS::STANDARD_COMPILERS` +* `MacOS::Xcode.version fallback logic` +* ensure compiler version Regexps continue to work (`MacOS` module) diff --git a/share/doc/homebrew/brew-tap.md b/share/doc/homebrew/brew-tap.md new file mode 100644 index 0000000000000..001f3a8e1665a --- /dev/null +++ b/share/doc/homebrew/brew-tap.md @@ -0,0 +1,46 @@ +# brew tap +The `brew tap` command is powerful, but has a few subtleties worth describing. + +**tl;dr** `brew tap` allows you to add more Github repos to the list of formulae that `brew` tracks, updates and installs from. When naming tap repos and formulas, however, there are a few gotchas to beware of. + +## The command + +* If you run `brew tap` with no arguments, it will list the currently + tapped repositories. Example: + +```bash +$ brew tap +homebrew/dupes +telemachus/desc +telemachus/vim +``` + +* If you run `brew tap` with a single argument, `brew` will attempt to + parse the argument into a valid 'username/repo' combination. If the argument is a valid name, then `brew tap` will attempt to clone the repository and symlink all its formulae. (See below for what it means to be a 'valid name'.) After that, `brew` will be able to work on those formulae as if there were in Homebrew's canonical repository. You can install and uninstall them with `brew [un]install`, and the formulae are automatically updated when you run `brew update`. (See below for a few exceptions on names and installation.) + +* In you run `brew tap --repair`, then `brew` will check for dead symlinks + and relink all valid formulae across all your taps. + +* You can remove a tapped repository using the `brew untap` command. + +## Naming conventions and limitations + +`brew tap username/repo` employs some shortcuts and has some limitations. + +* On Github, your repository must be named `homebrew-something`. + The prefix 'homebrew-' is not optional. + +* When you use `brew tap` on the command line, you can leave out the + 'homebrew-' prefix in commands. + + That is, `brew tap username/foobar` can be used as a shortcut for the long version: `brew tap username/homebrew-foobar`. The command will automatically add back the 'homebrew-' prefix. + +## Formula duplicate names +If your tap contains a formula that is also present in master, that's fine, but it means that you must install it explicitly. + +For example, you can create a tap for an alternative `vim` formula, but in that case when you install from there you must run the command with a more explicit installation target: + +```bash +brew install vim # installs from Homebrew/homebrew +brew install username/repo/vim # installs from your custom repo +``` diff --git a/share/doc/homebrew/brew-test-bot-failed-jenkins.png b/share/doc/homebrew/brew-test-bot-failed-jenkins.png new file mode 100644 index 0000000000000..bdfa8205f53a1 Binary files /dev/null and b/share/doc/homebrew/brew-test-bot-failed-jenkins.png differ diff --git a/share/doc/homebrew/brew-test-bot-failed-pr.png b/share/doc/homebrew/brew-test-bot-failed-pr.png new file mode 100644 index 0000000000000..2487ac446c3c5 Binary files /dev/null and b/share/doc/homebrew/brew-test-bot-failed-pr.png differ diff --git a/share/doc/homebrew/brew-test-bot-failed-test.png b/share/doc/homebrew/brew-test-bot-failed-test.png new file mode 100644 index 0000000000000..0820910e79eb1 Binary files /dev/null and b/share/doc/homebrew/brew-test-bot-failed-test.png differ diff --git a/share/doc/homebrew/brew-test-bot-for-core-contributors-block.png b/share/doc/homebrew/brew-test-bot-for-core-contributors-block.png new file mode 100644 index 0000000000000..3406990e48fc1 Binary files /dev/null and b/share/doc/homebrew/brew-test-bot-for-core-contributors-block.png differ diff --git a/share/doc/homebrew/brew-test-bot-for-core-contributors-console.png b/share/doc/homebrew/brew-test-bot-for-core-contributors-console.png new file mode 100644 index 0000000000000..64d77b5d7374a Binary files /dev/null and b/share/doc/homebrew/brew-test-bot-for-core-contributors-console.png differ diff --git a/share/doc/homebrew/brew-test-bot-for-core-contributors-tabs.png b/share/doc/homebrew/brew-test-bot-for-core-contributors-tabs.png new file mode 100644 index 0000000000000..97e3cbeab45e4 Binary files /dev/null and b/share/doc/homebrew/brew-test-bot-for-core-contributors-tabs.png differ diff --git a/share/doc/homebrew/brew-test-bot-for-core-contributors-trigger.png b/share/doc/homebrew/brew-test-bot-for-core-contributors-trigger.png new file mode 100644 index 0000000000000..235644b9dc972 Binary files /dev/null and b/share/doc/homebrew/brew-test-bot-for-core-contributors-trigger.png differ diff --git a/share/doc/homebrew/brew-test-bot-passed-jenkins.png b/share/doc/homebrew/brew-test-bot-passed-jenkins.png new file mode 100644 index 0000000000000..be0467581cd27 Binary files /dev/null and b/share/doc/homebrew/brew-test-bot-passed-jenkins.png differ diff --git a/share/doc/homebrew/brew-test-bot-passed-pr.png b/share/doc/homebrew/brew-test-bot-passed-pr.png new file mode 100644 index 0000000000000..06acd588076bd Binary files /dev/null and b/share/doc/homebrew/brew-test-bot-passed-pr.png differ diff --git a/share/doc/homebrew/brew-test-bot-triggered-pr.png b/share/doc/homebrew/brew-test-bot-triggered-pr.png new file mode 100644 index 0000000000000..3643dcdbb27d1 Binary files /dev/null and b/share/doc/homebrew/brew-test-bot-triggered-pr.png differ diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1 index d432311f7e4ae..ea3a43e67ac72 100644 --- a/share/man/man1/brew.1 +++ b/share/man/man1/brew.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BREW" "1" "September 2014" "Homebrew" "brew" +.TH "BREW" "1" "October 2014" "Homebrew" "brew" . .SH "NAME" \fBbrew\fR \- The missing package manager for OS X @@ -187,7 +187,7 @@ Print a JSON representation of \fIformulae\fR\. Currently the only accepted valu Pass \fB\-\-all\fR to get information on all formulae, or \fB\-\-installed\fR to get information on all installed formulae\. . .IP -See the wiki for examples of using the JSON: \fIhttps://github\.com/Homebrew/homebrew/wiki/Querying\-Brew\fR +See the docs for examples of using the JSON: \fIhttps://github\.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Querying\-Brew\.md\fR . .TP \fBinstall [\-\-debug] [\-\-env=] [\-\-ignore\-dependencies] [\-\-only\-dependencies] [\-\-cc=] [\-\-build\-from\-source] [\-\-devel|\-\-HEAD]\fR \fIformula\fR @@ -476,7 +476,7 @@ $ ls $(brew \-\-repository)/Library/Contributions/cmd .IP "" 0 . .P -Documentation for the included external commands as well as instructions for creating your own can be found on the wiki: \fIhttp://wiki\.github\.com/Homebrew/homebrew/External\-Commands\fR +Documentation for the included external commands as well as instructions for creating your own can be found in the docs: \fIhttps://github\.com/Homebrew/homebrew/blob/master/share/doc/homebrew/External\-Commands\.md\fR . .SH "SPECIFYING FORMULAE" Many Homebrew commands accept one or more \fIformula\fR arguments\. These arguments can take several different forms: @@ -641,7 +641,7 @@ http_proxy=http://:@: brew install foo .IP "" 0 . .SH "SEE ALSO" -Homebrew Wiki: \fIhttp://wiki\.github\.com/Homebrew/homebrew/\fR +Homebrew Documentation: \fIhttps://github\.com/Homebrew/homebrew/blob/master/share/doc/homebrew/\fR . .P \fBgit\fR(1), \fBgit\-log\fR(1)