diff options
| author | Mike McQuaid | 2016-09-19 19:58:21 +0100 |
|---|---|---|
| committer | Mike McQuaid | 2016-09-20 10:41:42 +0100 |
| commit | bd6fb88ddc72a0de4c27f65e60a82790a5d87f3f (patch) | |
| tree | 4a40854293dc41c0184f5532583a864712aa5b8c /docs | |
| parent | f87e3626bb241bc88bead4ed6448a76c1bf49f56 (diff) | |
| download | brew-bd6fb88ddc72a0de4c27f65e60a82790a5d87f3f.tar.bz2 | |
Rearrange repository files.
Diffstat (limited to 'docs')
43 files changed, 4884 insertions, 0 deletions
diff --git a/docs/Acceptable-Formulae.md b/docs/Acceptable-Formulae.md new file mode 100644 index 000000000..15e800336 --- /dev/null +++ b/docs/Acceptable-Formulae.md @@ -0,0 +1,116 @@ +# Acceptable Formulae +Some formulae should not go in +[homebrew/core](https://github.com/Homebrew/homebrew-core). But there are +additional [Interesting Taps & Forks](Interesting-Taps-&-Forks.md) and anyone can start their +own! + +### We try hard to avoid dupes in Homebrew/homebrew +Stuff that comes with macOS or libraries that are provided by +[RubyGems, CPAN or PyPi](Gems,-Eggs-and-Perl-Modules.md) +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 macOS + +There are exceptions: + +* OpenSSL - Apple has formally deprecated OpenSSL on macOS in favour of their own Security Framework + & consequently the macOS OpenSSL is rarely updated and frequently falls behind important security updates. + Homebrew endeavours to use our shipped OpenSSL as much + as possible. +* 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, perl | People want newer versions + bash | macOS'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 macOS provides + openssl | macOS's openssl is deprecated & outdated. + libxml2 | Historically, macOS's libxml2 has been buggy + +We also maintain [a tap](https://github.com/Homebrew/homebrew-dupes) 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/core](https://github.com/Homebrew/homebrew-core)) must be open-source +and either built from source or produce cross-platform binaries like e.g. Java). +Binary-only formulae should go to +[Homebrew Cask](https://github.com/caskroom/homebrew-cask). + +### Stable versions +Formulae in the core repository must 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 only provides a development/beta, tagged version should be put in +[homebrew/devel-only](https://github.com/Homebrew/homebrew-devel-only). +We donât accept software without a tagged version because they regularly break +due to upstream changes; we canât provide [bottles](Bottles.md) for them; and +we donât have an automatic update mechanism for `head-only` formulae which +makes them very quickly outdated. + +### Bindings +First check that there is not already a binding available via +[`gem`](https://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<a name="Niche_Stuff"></a> +The software in question must be +* maintained (e.g. upstream is still making new releases) +* known +* stable (e.g. not declared "unstable" or "beta" by upstream) +* 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 tap if you have to! + +There may be exceptions to these rules in the main repository, we may +include things that don't meet these criteria or reject things that do. +Please trust that we need to use our discretion based on our experience +running a package manager. + +### Stuff that builds an .app +Donât make your formula build an `.app` (native macOS Application); we +donât want those things in Homebrew (but +[Homebrew Cask](https://github.com/caskroom/homebrew-cask) does). +Make it build a command-line tool or a library. + +### 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/docs/Analytics.md b/docs/Analytics.md new file mode 100644 index 000000000..83386b3ee --- /dev/null +++ b/docs/Analytics.md @@ -0,0 +1,57 @@ +# Homebrew's Anonymous Aggregate User Behaviour Analytics +Homebrew has begun gathering anonymous aggregate user behaviour analytics and reporting these to Google Analytics. You will be notified the first time you run `brew update` or install Homebrew. + +## Why? +Homebrew is provided free of charge and run entirely by volunteers in their spare time. As a result, we do not have the resources to do detailed user studies of Homebrew users to decide on how best to design future features and prioritise current work. Anonymous aggregate user analytics allow us to prioritise fixes and features based on how, where and when people use Homebrew. For example: + +- if a formula is widely used and is failing often it will enable us to prioritise fixing that formula over others. +- collecting the OS version allows us to decide what versions of macOS to prioritise and support and identify build failures that occur only on single versions. + +## What? +Homebrew's analytics record some shared information for every event: + +- The Homebrew user agent e.g. `Homebrew/0.9.9 (Macintosh; Intel macOS 10.12.0) curl/7.43.0` +- The Google Analytics version i.e. `1` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#v) +- The Homebrew analytics tracking ID e.g. `UA-75654628-1` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#tid) +- A Homebrew analytics user ID e.g. `1BAB65CC-FE7F-4D8C-AB45-B7DB5A6BA9CB`. This is generated by `uuidgen` and stored in the repository-specific Git configuration variable `homebrew.analyticsuuid` within `$(brew --repository)/.git/config`. This does not allow us to track individual users but does enable us to accurately measure user counts vs. event counts (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#cid) +- The Google Analytics anonymous IP setting is enabled i.e. `1` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#aip) +- The Homebrew application name e.g. `Homebrew` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#an) +- The Homebrew application version e.g. `0.9.9` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#av) +- The Homebrew analytics hit type e.g. `screenview` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#t) + +Homebrew's analytics records the following different events: + +- a `screenview` hit type with the official Homebrew command you have run (with arguments stripped) e.g. `brew list` (not `brew list foo` or any external commands except `bundle` and `services`) +- an `event` hit type with the `install` event category, the Homebrew formula from a non-private GitHub tap you have requested to install and any used options e.g. `wget --with-pcre` as the action and an event label e.g. `macOS 10.12, non-/usr/local, CI` to indicate the OS version, non-standard installation location and invocation as part of CI. This allows us to identify formulae that need fixed and where more easily. +- an `event` hit type with the `BuildError` event category, the Homebrew formula that failed to install e.g. `wget` as the action and an event label e.g. `macOS 10.12` +- an `exception` hit type with the `exception` event category, exception description of the exception name e.g. `FormulaUnavailableError` and whether the exception was fatal e.g. `1` + +You can also view all the information that is sent by Homebrew's analytics by setting `HOMEBREW_ANALYTICS_DEBUG=1` in your environment. Please note this will also stop any analytics being sent. + +It is impossible for the Homebrew developers to match any particular event to any particular user, even if we had access to the Homebrew analytics user ID (which we do not). An example of the most user-specific information we can see from Google Analytics: + + + +As far as we can tell it would be impossible for Google to match the randomly generated Homebrew-only analytics user ID to any other Google Analytics user ID. If Google turned evil the only thing they could do would be to lie about anonymising IP addresses and attempt to match users based on IP addresses. + +## When/Where? +Homebrew's analytics are sent throughout Homebrew's execution to Google Analytics over HTTPS. + +## Who? +Homebrew's analytics are accessible to Homebrew's current maintainers. Contact @mikemcquaid if you are a maintainer and need access. + +## How? +The code is viewable in https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb and https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.sh. They are done in a separate background process and fail fast to avoid delaying any execution. They will fail immediately and silently if you have no network connection. + +## Opting out +Homebrew analytics helps us maintainers and leaving it on is appreciated. However, if you want to opt out of Homebrew's analytics, you can set this variable in your environment: + +```sh +export HOMEBREW_NO_ANALYTICS=1 +``` + +Alternatively, this will prevent analytics from ever being sent: + +```sh +brew analytics off +``` diff --git a/docs/Bottles.md b/docs/Bottles.md new file mode 100644 index 000000000..196b36e1f --- /dev/null +++ b/docs/Bottles.md @@ -0,0 +1,77 @@ +# 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 <formula>`. If you wish to disable this you can do it by specifying `--build-from-source`. + +Bottles will not be used if the user requests it (see above), if the formula requests it (with `pour_bottle?`), if any options are specified on installation (bottles are all compiled with default options), if the bottle is not up to date (e.g. lacking a checksum) or the bottle's `cellar` is not `:any` or equal to the current `HOMEBREW_CELLAR`. + +## Bottle Creation +Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md). This happens mostly when people submit pull requests to Homebrew and the `bottle do` block is updated by maintainers when they `brew pull --bottle` the contents of a pull request. For the Homebrew organisations' taps they are uploaded to and downloaded from [Bintray](https://bintray.com/homebrew). + +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=penryn`. 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 + sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :sierra + sha256 "c71db15326ee9196cd98602e38d0b7fb2b818cdd48eede4ee8eb827d809e09ba" => :el_capitan + sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" => :yosemite +end +``` + +A full example: +```ruby +bottle do + root_url "https://example.com" + prefix "/opt/homebrew" + cellar "/opt/homebrew/Cellar" + rebuild 4 + sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :sierra + sha256 "c71db15326ee9196cd98602e38d0b7fb2b818cdd48eede4ee8eb827d809e09ba" => :el_capitan + sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" => :yosemite +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` or `:any_skip_relocation` 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` or `:any_skip_relocation` prefix should be omitted. + +### `rebuild` +Optionally contains the rebuild version 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 rebuild will have a value of 1 or more. + +### `sha256` +Contains the SHA-256 of bottle for a particular version of macOS. + +## 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`. + +A full example: +```ruby +pour_bottle? do + reason "The bottle needs the Xcode CLT to be installed." + satisfy { MacOS::CLT.installed? } +end +``` + +## Planned Improvements +Most bottle features have been (and planned improvements will be) implemented by @MikeMcQuaid. Contact him directly with questions. diff --git a/docs/Brew-Test-Bot-For-Core-Contributors.md b/docs/Brew-Test-Bot-For-Core-Contributors.md new file mode 100644 index 000000000..8e264ea7e --- /dev/null +++ b/docs/Brew-Test-Bot-For-Core-Contributors.md @@ -0,0 +1,25 @@ +# 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 two types of Jenkins jobs you will interact with: + +## [Homebrew Pull Requests](https://bot.brew.sh/job/Homebrew%20Core%20Pull%20Requests/) +This job automatically builds any pull requests submitted to Homebrew/homebrew-core. On success or failure it updates the pull request status (see more details on the [main Brew Test Bot wiki page](Brew-Test-Bot.md)). On a successful build it automatically uploads bottles. + +## [Homebrew Testing](https://bot.brew.sh/job/Homebrew%20Testing/) +This job is manually triggered to run [`brew test-bot`](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/dev-cmd/test-bot.rb) 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/brew/blob/master/Library/Homebrew/dev-cmd/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 `git push` to push the commits. + +To bottle a test build : + +1. Ensure the job has already completed successfully. +2. Run `brew pull --bottle https://bot.brew.sh/job/Homebrew%20Testing/1234/` where `https://bot.brew.sh/job/Homebrew%20Testing/1234/` is the testing build URL in Jenkins. +3. Run `git push` to push the commits. diff --git a/docs/Brew-Test-Bot.md b/docs/Brew-Test-Bot.md new file mode 100644 index 000000000..0a5f76bda --- /dev/null +++ b/docs/Brew-Test-Bot.md @@ -0,0 +1,63 @@ +# Brew Test Bot +`brew test-bot` is the name for the automated review and testing system funded +by [our Kickstarter in 2013](https://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 https://bot.brew.sh](https://bot.brew.sh) and run the +[`brew test-bot.rb`](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/dev-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 + +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: + + + + +--- + +A failed build looks like this: + + + + +--- + +A passed build looks like this: + + + + +--- + +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: + + + + +--- + +A failed build looks like this: + + + + +--- + +You can click the test results link +(e.g. `brew-test-bot.el_capitan.install openssl`) to +view the failed test output: + + + +--- diff --git a/docs/C++-Standard-Libraries.md b/docs/C++-Standard-Libraries.md new file mode 100644 index 000000000..0bb987def --- /dev/null +++ b/docs/C++-Standard-Libraries.md @@ -0,0 +1,23 @@ +# 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. This was marked deprecated with a +warning during compile as of Xcode 8. + +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/docs/Checksum_Deprecation.md b/docs/Checksum_Deprecation.md new file mode 100644 index 000000000..d8ad81b85 --- /dev/null +++ b/docs/Checksum_Deprecation.md @@ -0,0 +1,27 @@ +# Checksum Deprecation + +During early 2015 Homebrew started the process of deprecating _SHA1_ for package +integrity verification. Since then every formulae under the Homebrew organisation +has been moved onto _SHA256_ verification; this includes both source packages +and our precompiled packages (bottles). + +We also stopped supporting _MD5_ entirely. It was removed from core formulae in 2012 but until April 2015 if you tried to install a formula still using an +_MD5_ checksum Homebrew wouldn't actively stop you. + +On _SHA1_ we added a `brew audit` check that flags _SHA1_ checksums as deprecated +and requests that you use _SHA256_. + +We saw positive ecosystem engagement on moving from _MD5_ & _SHA1_ to the recommended _SHA256_ and thanks to that we're in a strong position to move forwards. + +## Moving forwards on SHA1. + +From March 20th 2016 we've stepped up the visibility of that notification & you'll start +seeing deprecation warnings when installing _SHA1_-validated formula. +If you see these please consider reporting it to where the formula originated. + +We're targeting **the end of September 2016** for _SHA1_ support removal, +19 months after we started warning people to move away from it for verification. +This will be enforced in the same way _MD5_ is today, by blocking the installation of that individual formula until the checksum is migrated. + +This means prior to that date custom taps, local custom formulae, etc +need to be migrated to use _SHA256_. diff --git a/docs/Common-Issues-for-Core-Contributors.md b/docs/Common-Issues-for-Core-Contributors.md new file mode 100644 index 000000000..b0bea8c39 --- /dev/null +++ b/docs/Common-Issues-for-Core-Contributors.md @@ -0,0 +1,14 @@ +# 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 and can be +fixed like [this](https://github.com/Homebrew/legacy-homebrew/commit/7c9a9334631dc84d59131ca57419e8c828b1574b). diff --git a/docs/Common-Issues.md b/docs/Common-Issues.md new file mode 100644 index 000000000..320ad6d89 --- /dev/null +++ b/docs/Common-Issues.md @@ -0,0 +1,133 @@ +# 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 macOS provided files and directories to be *unmodified* since macOS 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 MacOS's Ruby framework or a vendored Ruby. + +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 four 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/brew/blob/master/share/doc/homebrew/Troubleshooting.md +/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: easy-install.pth cannot be linked +``` +Warning: Could not link <formulaname>. 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 <formulaname>' + +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/<formulaname>/<version>/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 here but fix by using +`Language::Python.setup_install_args` in the formula as described in +[Python for Formula Authors](Python-for-Formula-Authors.md). + +### Upgrading macOS + +Upgrading macOS can cause errors like the following: + +- `dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.54.dylib` +- `configure: error: Cannot find libz` + +Following an macOS upgrade it may be necessary to reinstall the Xcode Command Line Tools and `brew upgrade` all installed formula: + +```bash +xcode-select --install +brew upgrade +``` diff --git a/docs/Custom-GCC-and-cross-compilers.md b/docs/Custom-GCC-and-cross-compilers.md new file mode 100644 index 000000000..1d662c158 --- /dev/null +++ b/docs/Custom-GCC-and-cross-compilers.md @@ -0,0 +1,21 @@ +# 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` +* [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V +toolchain including binutils and gcc. diff --git a/docs/External-Commands.md b/docs/External-Commands.md new file mode 100644 index 000000000..090b664cb --- /dev/null +++ b/docs/External-Commands.md @@ -0,0 +1,84 @@ +# External Commands +Homebrew, like Git, supports *external commands*. This lets you create new commands that can be run like: + +```shell +$ brew mycommand --option1 --option3 formula +``` + +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 executable (`chmod +x`) and live somewhere in `$PATH`. + +### 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. + +<table> + <tr> + <td><strong>Variable</strong></td> + <td><strong>Description</strong></td> + </tr> + <tr> + <td>HOMEBREW_CACHE</td> + <td>Where Homebrew caches downloaded tarballs to, by default <code>~/Library/Caches/Homebrew</code>. </td> + </tr> + <tr> + <td>HOMEBREW_CELLAR</td> + <td>The location of the Homebrew Cellar, where software is staged. This will be <code>$HOMEBREW_PREFIX/Cellar</code> if that directory exists, or <code>$HOMEBREW_REPOSITORY/Cellar</code> otherwise.</td> + </tr> + <tr> + <td>HOMEBREW_LIBRARY_PATH</td> + <td>The directory containing Homebrewâs own application code.</td> + </tr> + <tr> + <td>HOMEBREW_PREFIX</td> + <td>Where Homebrew installs software. This is always the grandparent directory of the `brew` executable, <code>/usr/local</code> by default.</td> + </tr> + <tr> + <td>HOMEBREW_REPOSITORY</td> + <td>If installed from a Git clone, the repo directory (i.e., where Homebrewâs <code>.git</code> directory lives).</td> + </tr> +</table> + +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-livecheck +> Check if there is a new upstream version of a formula. +> +> See the [`README`](https://github.com/youtux/homebrew-livecheck/blob/master/README.md) for more info and usage. +> +> Install using: +> ``` +> $ brew tap youtux/livecheck +> ``` + +### brew-gem +>Install any gem package into a self-contained Homebrew cellar location: <https://github.com/sportngin/brew-gem> +> +>*Note:* This can also be installed with `brew install brew-gem`. + +### brew-growl +>Get Growl notifications for Homebrew https://github.com/secondplanet/brew-growl + +### 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://github.com/Homebrew/homebrew-services](https://github.com/Homebrew/homebrew-services) + +> Install using: +> ``` + $ brew tap homebrew/services +> ``` + +## SEE ALSO +Homebrew Docs: <https://github.com/Homebrew/brew/tree/master/share/doc/homebrew> diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 000000000..2f6d4f9ea --- /dev/null +++ b/docs/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 + +<a name="cleanup"></a> + +### How do I stop certain formulae from being updated? +To stop something from being updated/upgraded: + + brew pin $FORMULA + +To allow that formulae to update again: + + brew unpin $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 + +<a name="uninstall"></a> + +### How do I uninstall Homebrew? +To uninstall Homebrew, paste the command below in a terminal prompt. + +```bash +ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/uninstall)" +``` +Download the [uninstall script](https://raw.githubusercontent.com/Homebrew/install/master/uninstall) +and run `./uninstall --help` to view more uninstall options. + +<a name="uninstall-package"></a> + +### 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 --all`). 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. + +### 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 macOS 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](https://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](https://developer.apple.com/legacy/library/qa/qa1067/_index.html). + +### How do I contribute to Homebrew? +Read [CONTRIBUTING.md](/.github/CONTRIBUTING.md). + +### Why do you compile everything? +Homebrew provides pre-compiled versions for many formulae. These +pre-compiled versions are referred to as **bottles** and are available +at: +[https://bintray.com/homebrew/bottles](https://bintray.com/homebrew/bottles). + +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.9+ as all bottled builds are +generated on Mavericks 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 https://raw.github.com/user/repo/branch/formula.rb` + +Or: + +`brew pull https://github.com/Homebrew/homebrew-core/pull/1234` + +### Why does Homebrew prefer I install to `/usr/local`? +<a name="usrlocal"></a> + +1. **Itâs easier**<br>`/usr/local/bin` is already in your + `PATH`. +2. **Itâs easier**<br>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**<br>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? <a name="sudo"></a> +**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](External-Commands.md). + +### 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-core*, 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 with 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/core* or want +to learn more about writing formulae, 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 formulae are moved to specialized repositories. These are the +likely candidates: + +* [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes) +* [homebrew/games](https://github.com/Homebrew/homebrew-games) +* [homebrew/versions](https://github.com/Homebrew/homebrew-versions) + +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 still link in the formula 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. diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md new file mode 100644 index 000000000..876a6645f --- /dev/null +++ b/docs/Formula-Cookbook.md @@ -0,0 +1,850 @@ +# Formula Cookbook +A formula is a package definition written in Ruby. It can be created with `brew create $URL`, installed with `brew install $FORMULA`, and debugged with `brew install --debug --verbose $FORMULA`. Formulae use the [Formula API](http://www.rubydoc.info/github/Homebrew/brew/master/Formula) which provides various Homebrew-specific helpers. + +## Homebrew Terminology + +| Term | Description | Example | +|----------------|------------------------------------------------------------|-----------------------------------------------------------------| +| **Formula** | The package definition | `/usr/local/Library/Taps/homebrew/homebrew-core/Formula/foo.rb` | +| **Keg** | The installation prefix of a **Formula** | `/usr/local/Cellar/foo/0.1` | +| **opt prefix** | A symlink to the active version of a **Keg** | `/usr/local/opt/foo ` | +| **Cellar** | All **Kegs** are installed here | `/usr/local/Cellar` | +| **Tap** | An optional Git repository of **Formulae** and/or commands | `/usr/local/Library/Taps/homebrew/homebrew-versions` | +| **Bottle** | Pre-built **Keg** used instead of building from source | `qt-4.8.4.mavericks.bottle.tar.gz` | + +## An Introduction + +Homebrew uses Git for downloading updates and contributing to the project. + +Homebrew installs to the `Cellar` it then symlinks some of the installation into `/usr/local` so that other programs can see what's going on. We suggest you `brew ls` a few of the kegs in your Cellar to see how it is all arranged. + +Packages are installed according to their formulae, which live in `/usr/local/Library/Taps/homebrew/homebrew-core/Formula`. Check one out a simple one e.g. `brew edit etl` (or [etl](https://github.com/Homebrew/homebrew-core/blob/master/Formula/etl.rb)) or a more advanced one e.g. `brew edit git` or [Git](https://github.com/Homebrew/homebrew-core/blob/master/Formula/git.rb). + +# Basic Instructions + +Make sure you run `brew update` before you start. This turns your Homebrew installation into a Git repository. + +Before submitting a new formula make sure your package: + +* meets all our [Acceptable Formulae](Acceptable-Formulae.md) requirements +* isn't already in Homebrew (check `brew search $FORMULA`) +* isn't in another official [Homebrew tap](https://github.com/Homebrew) +* isn't already waiting to be merged (check the [issue tracker](https://github.com/Homebrew/homebrew-core/pulls)) +* is still supported by upstream (i.e. doesn't require extensive patching) +* has a stable, tagged version (i.e. not just a GitHub repository with no versions). See [Interesting-Taps-&-Forks](Interesting-Taps-&-Forks.md) for where pre-release versions belong. +* passes all `brew audit --new-formula $FORMULA` tests. + +Before submitting a new formula make sure you read over our [contribution guidelines](https://github.com/Homebrew/brew/blob/master/.github/CONTRIBUTING.md). + +## Grab the URL + +Run `brew create` with a URL to the source tarball: + +```shell +brew create https://example.com/foo-0.1.tar.gz +``` + +This creates `/usr/local/Library/Taps/homebrew/homebrew-core/Formula/foo.rb` and opens it in your `$EDITOR`. It'll look something like: + +```ruby +class Foo < Formula + desc "" + homepage "" + url "https://example.com/foo-0.1.tar.gz" + sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" + + # depends_on "cmake" => :build + + def install + system "./configure", "--prefix=#{prefix}", "--disable-debug", "--disable-dependency-tracking" + # system "cmake", ".", *std_cmake_args + system "make", "install" + end +end +``` + +If `brew` said `Warning: Version cannot be determined from URL` when doing the `create` step, youâll need to explicitly add the correct [`version`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version-class_method) to the formula and then save the formula. + +Homebrew will try to guess the formulaâs name from its URL. If it fails to do +so you can override this with `brew create <url> --set-name <name>`. + +## Fill in the [`homepage`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#homepage%3D-class_method) + +**We donât accept formulae without a [`homepage`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#homepage%3D-class_method)!** + +A SSL/TLS (https) [`homepage`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#homepage%3D-class_method) is preferred, if one is available. + +Try to summarize from the [`homepage`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#homepage%3D-class_method) what the formula does in the [`desc`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#desc%3D-class_method)ription. Note that the [`desc`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#desc%3D-class_method)ription is automatically prepended with the formula name. + +## Check the build system + +```shell +brew install -i foo +``` + +Youâre now at new prompt with the tarball extracted to a temporary sandbox. + +Check the packageâs `README`. Does the package install with `./configure`, `cmake`, or something else? Delete the commented out `cmake` lines if the package uses `./configure`. + +## Check for dependencies + +The `README` probably tells you about dependencies and Homebrew or macOS probably already has them. You can check for Homebrew dependencies with `brew search`. Some common dependencies that macOS comes with: + +* `libexpat` +* `libGL` +* `libiconv` +* `libpcap` +* `libxml2` +* `Python` +* `Ruby` + +There are plenty of others; check `/usr/lib` for them. + +We generally try to not duplicate system libraries and complicated tools in core Homebrew but we do duplicate some commonly used tools. + +Special exceptions are OpenSSL and LibreSSL. Things that use either *should* be built using Homebrewâs shipped equivalent and our test bot's post-install `audit` will warn if it detects you haven't done this. + +Homebrewâs OpenSSL is +[`keg_only`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#keg_only-class_method) +to avoid conflicting with the system so sometimes formulae need to +have environment variables set or special configuration flags passed +to locate our OpenSSL. You can see this mechanism in the +[clamav](https://github.com/Homebrew/homebrew-core/blob/ae2206f3e5bb2a7c0065ae1b164d2d011b85858b/Formula/clamav.rb#L38) +formula. Usually this is unnecessary because Homebrew sets up our [build environment](https://github.com/Homebrew/brew/blob/fb3bec8d70d375a97554d4c3fed82ad2332b2191/Library/Homebrew/extend/ENV/super.rb) +to favour finding `keg_only` formulae first. + +Homebrew maintains a special [tap that provides other useful system duplicates](https://github.com/Homebrew/homebrew-dupes). + +*Important:* `$(brew --prefix)/bin` is NOT on the `$PATH` during formula installation. If you have dependencies at build time, you must specify them and brew will add them to the `$PATH` or create a [`Requirement`](http://www.rubydoc.info/github/Homebrew/brew/master/Requirement). + +## Specifying other formulae as dependencies + +```ruby +class Foo < Formula + depends_on "pkg-config" => :run + depends_on "jpeg" + depends_on "boost" => "with-icu" + depends_on "readline" => :recommended + depends_on "gtk+" => :optional + depends_on :x11 => :optional +end +``` + +A String (e.g. `"jpeg"`) specifies a formula dependency. + +A Symbol (e.g. `:x11`) specifies a [`Requirement`](http://www.rubydoc.info/github/Homebrew/brew/master/Requirement) which can be fulfilled by one or more formulae, casks or other system-wide installed software (e.g. X11). + +A Hash (e.g. `=>`) specifies a formula dependency with some additional information. Given a single string key, the value can take several forms: + +* a Symbol (currently one of `:build`, `:optional`, `:run` or `:recommended`). + - `:build` means that dependency is a build-time only dependency so it can + be skipped when installing from a bottle or when listing missing + dependencies using `brew missing`. + - `:optional` generates an implicit `with-foo` option for the formula. + This means that, given `depends_on "foo" => :optional`, the user must pass `--with-foo` in order to use the dependency. + - `:run` can mean the dependency is only required at run, or it can be used + to declare build dependencies such as `pkg-config` are needed at + runtime as well, which will silence the audit warning. `:run` dependencies + are currently available at build-time. + - `:recommended` generates an implicit `without-foo` option, meaning that + the dependency is enabled by default and the user must pass + `--without-foo` to disable this dependency. The default + description can be overridden using the normal option syntax (in this case, the option declaration must precede the dependency): + + ```ruby + option "with-foo", "Compile with foo bindings" # This overrides the generated description if you want to + depends_on "foo" => :optional # Generated description is "Build with foo support" + ``` + +* a String or an Array + String values are interpreted as options to be passed to the dependency. + You can also pass an array of strings, or an array of symbols and strings, + in which case the symbols are interpreted as described above, and the + strings are passed to the dependency as options. + + ```ruby + depends_on "foo" => "with-bar" + depends_on "foo" => %w{with-bar with-baz} + depends_on "foo" => [:optional, "with-bar"] + ``` + +## Specifying conflicts with other formulae + +Sometimes thereâs hard conflict between formulae, and it canât be avoided or circumvented with [`keg_only`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#keg_only-class_method). + +`mbedtls` is a good [example](https://github.com/Homebrew/homebrew-core/blob/master/Formula/mbedtls.rb) formula for minor conflict. + +`mbedtls` ships and compiles a "Hello World" executable. This is obviously non-essential to `mbedtls`âs functionality, and conflict with the popular GNU `hello` formula would be overkill, so we just [remove it](https://github.com/Homebrew/homebrew-core/blob/ae2206f3e5bb2a7c0065ae1b164d2d011b85858b/Formula/mbedtls.rb#L27-L28) during the installation process. + +[pdftohtml](https://github.com/Homebrew/homebrew-core/blob/master/Formula/pdftohtml.rb) provides an example of a serious +conflict, where both formula ship an identically-named binary that is essential to functionality, so a [`conflicts_with`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#conflicts_with-class_method) is preferable. + +As a general rule, [`conflicts_with`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#conflicts_with-class_method) should be a last-resort option. Itâs a fairly blunt instrument. + +The syntax for conflict that canât be worked around is: + +```ruby +conflicts_with "blueduck", :because => "yellowduck also ships a duck binary" +``` + +## Formulae Revisions + +In Homebrew we sometimes accept formulae updates that donât include a version bump. These include resource updates, new patches or fixing a security issue with a formula. + +Occasionally, these updates require a forced-recompile of the formula itself or its dependents to either ensure formulae continue to function as expected or to close a security issue. This forced-recompile is known as a [`revision`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method) and inserted underneath the `homepage`/`url`/`sha` block. + +Where a dependent of a formula fails against a new version of that dependency it must receive a [`revision`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method). An example of such failure can be seen [here](https://github.com/Homebrew/legacy-homebrew/issues/31195) and the fix [here](https://github.com/Homebrew/legacy-homebrew/pull/31207). + +[`revision`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method)s are also used for formulae that move from the system OpenSSL to the Homebrew-shipped OpenSSL without any other changes to that formula. This ensures users arenât left exposed to the potential security issues of the outdated OpenSSL. An example of this can be seen in [this commit](https://github.com/Homebrew/legacy-homebrew/commit/6b9d60d474d72b1848304297d91adc6120ea6f96). + +## Version Scheme Changes + +Sometimes formulae have version schemes that change such that a direct comparison between two versions no longer produces the correct result. For example, a project might be version `13` and then decide to become `1.0.0`. As `13` is translated to `13.0.0` by our versioning system by default this requires intervention. + +Where a version scheme of a formula fails to recognise a new version as newer it must receive a [`version_scheme`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version_scheme%3D-class_method). An example of this can be seen [here](https://github.com/Homebrew/homebrew-core/pull/4006). + +## Double-check for dependencies + +When you already have a lot of formulae installed, it's easy to miss a common dependency. You can double-check which libraries a binary links to with the `otool` command (perhaps you need to use `xcrun otool`): + +```shell +$ otool -L /usr/local/bin/ldapvi +/usr/local/bin/ldapvi: +/usr/local/opt/openssl/lib/libssl.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0) +/usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0) +/usr/local/lib/libglib-2.0.0.dylib (compatibility version 4201.0.0, current version 4201.0.0) +/usr/local/opt/gettext/lib/libintl.8.dylib (compatibility version 10.0.0, current version 10.2.0) +/usr/local/opt/readline/lib/libreadline.6.dylib (compatibility version 6.0.0, current version 6.3.0) +/usr/local/lib/libpopt.0.dylib (compatibility version 1.0.0, current version 1.0.0) +/usr/lib/libncurses.5.4.dylib (compatibility version 5.4.0, current version 5.4.0) +/System/Library/Frameworks/LDAP.framework/Versions/A/LDAP (compatibility version 1.0.0, current version 2.4.0) +/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 1.0.0) +/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1213.0.0) +``` + +## Specifying gems, Python modules, Go projects, etc. as dependencies + +Homebrew doesnât package already packaged language-specific libraries. These should be installed directly from `gem`/`cpan`/`pip` etc. + +If you're installing an application then please use [`resource`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#resource-class_method)s for all the language-specific dependencies: + +```ruby +class Foo < Formula + resource "pycrypto" do + url "https://files.pythonhosted.org/packages/60/db/645aa9af249f059cc3a368b118de33889219e0362141e75d4eaf6f80f163/pycrypto-2.6.1.tar.gz" + sha256 "f2ce1e989b272cfcb677616763e0a2e7ec659effa67a88aa92b3a65528f60a3c" + end + + def install + resource("pycrypto").stage { system "python", *Language::Python.setup_install_args(libexec/"vendor") } + end +end +``` + +[jrnl](https://github.com/Homebrew/homebrew-core/blob/master/Formula/jrnl.rb) is an example of a formula that does this well. The end result means the user doesn't have use `pip` or Python and can just run `jrnl`. + +[homebrew-pypi-poet](https://github.com/tdsmith/homebrew-pypi-poet) can help you generate resource stanzas for the dependencies of your Python application and [gdm](https://github.com/sparrc/gdm#homebrew) can help you generate go\_resource stanzas for the dependencies of your go application. + +## Install the formula + +```shell +brew install --verbose --debug foo +``` + +`--debug` will ask you to open an interactive shell if the build fails so you can try to figure out what went wrong. + +Check the top of the e.g. `./configure` output. Some configure scripts do not recognize e.g. `--disable-debug`. If you see a warning about it, remove the option from the formula. + +## Add a test to the formula + +Please add a [`test do`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#test-class_method) block to the formula. This will be run by `brew test foo` and the [Brew Test Bot](Brew-Test-Bot.md). + +The +[`test do`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#test-class_method) +block automatically creates and changes to a temporary directory which +is deleted after run. You can access this +[`Pathname`](http://www.rubydoc.info/github/Homebrew/brew/master/Pathname) +with the +[`testpath`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#testpath-instance_method) +function. The environment variable `HOME` is set to `testpath` within +the `test do` block. + +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-core/blob/master/Formula/cmake.rb) for an example of a formula with a good test. The formula writes a basic `CMakeLists.txt` file into the test directory then calls CMake to generate Makefiles. This test checks that CMake doesn't e.g. segfault during basic operation. Another good example is [tinyxml2](https://github.com/Homebrew/homebrew-core/blob/master/Formula/tinyxml2.rb), which writes a small C++ source file into the test directory, compiles and links it against the tinyxml2 library and finally checks that the resulting program runs successfully. + +## Manuals + +Homebrew expects to find manual pages in `#{prefix}/share/man/...`, and not in `#{prefix}/man/...`. + +Some software installs to `man` instead of `share/man`, so check the output and add a `"--mandir=#{man}"` to the `./configure` line if needed. + +## A Quick Word on Naming + +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 and [what Debian call it](https://www.debian.org/distrib/packages). + +Where Homebrew already has a formula called `foo` we typically do not accept requests to replace that formula with something else also named `foo`. This is to avoid both confusing and surprising usersâ expectation. + +When two formulae share an upstream name, e.g. [`AESCrypt`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/aescrypt.rb) and [`AESCrypt`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/aescrypt-packetizer.rb) the newer formula must typically adapt the name to avoid conflict with the current formula. + +If youâre *still* not sure, just commit. Weâll apply some arbitrary rule and make a decision :wink:. + +When importing classes, Homebrew will require the formula and then create an instance of the class. It does this by assuming the formula name can be directly converted to the class name using a `regexp`. The rules are simple: + +* `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, and class names should be the strict CamelCase equivalent, e.g. formulae `gnu-go` and `sdl_mixer` become classes `GnuGo` and `SdlMixer`, even if part of their name is an acronym. + +Add aliases by creating symlinks in an `Aliases` directory in the tap root. + +## Audit the formula + +You can run `brew audit --strict --online` to test formulae for adherence to Homebrew house style. The `audit` command includes warnings for trailing whitespace, preferred URLs for certain source hosts, and a lot of other style issues. Fixing these warnings before committing will make the process a lot quicker for everyone. + +New formulae being submitted to Homebrew should run `brew audit --new-formula foo`. This command is performed by the Brew Test Bot on new submissions as part of the automated build and test process, and highlights more potential issues than the standard audit. + +Use `brew info` and check if the version guessed by Homebrew from the URL is +correct. Add an explicit [`version`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version-class_method) if not. + +## Commit + +Everything is built on Git, so contribution is easy: + +```shell +brew update # required in more ways than you think (initializes the brew git repository if you don't already have it) +cd $(brew --repo homebrew/core) +# Create a new git branch for your formula so your pull request is easy to +# modify if any changes come up during review. +git checkout -b <some-descriptive-name> +git add 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* +* two (2) newlines, then +* explain the commit thoroughly + +At Homebrew, we like to put the name of the formula up front like so: `foobar 7.3 (new formula)`. +This may seem crazy short, but youâll find that forcing yourself to summarise the commit encourages you to be atomic and concise. If you canât summarise it in 50-80 characters, youâre probably trying to commit two commits as one. For a more thorough explanation, please read Tim Popeâs excellent blog post, [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). + +The preferred commit message format for simple version updates is `foobar 7.3` and for fixes is `foobar: fix flibble matrix.`. + +Ensure you reference any relevant GitHub issue e.g. `Closes #12345` in the commit message. Homebrewâs history is the first thing future contributors will look to when trying to understand the current state of formulae theyâre interested in. + +## Push + +Now you just need to push your commit to GitHub. + +If you havenât forked Homebrew yet, [go to the `homebrew-core` repository and hit the fork button](https://github.com/Homebrew/homebrew-core). + +If you have already forked Homebrew on GitHub, then you can manually push (just make sure you have been pulling from the `Homebrew/homebrew-core` master): + +```shell +git push https://github.com/myname/homebrew-core/ <what-you-called-your-branch> +``` + +Now, please [open a pull request](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md#how-to-open-a-homebrew-pull-request-and-get-it-merged) for your changes. + +* One formula per commit; one commit per formula +* Keep merge commits out of the pull request + +# Convenience Tools +## Messaging + +Three commands are provided for displaying informational messages to the user: + +* `ohai` for general info +* `opoo` for warning messages +* `odie` for error messages and immediately exiting + +In particular, when a test needs to be performed before installation use `odie` to bail out gracefully. For example: + +```ruby +if build.with?("qt") && build.with("qt5") + odie "Options --with-qt and --with-qt5 are mutually exclusive." +end +system "make", "install" +``` + +## `bin.install "foo"` + +Youâll see stuff like that in other formulae. This moves the file `foo` into the Formulaâs `bin` directory (`/usr/local/Cellar/pkg/0.1/bin`) and makes it executable (`chmod 0555 foo`). + +## [`inreplace`](http://www.rubydoc.info/github/Homebrew/brew/master/Utils/Inreplace) + +A convenience function that can edit files in-place. For example: + +`inreplace "path", before, after` + +`before` and `after` can be strings or regular expressions. You should use the block form if you need to make multiple replacements in a file: + +```ruby +inreplace "path" do |s| + s.gsub! /foo/, "bar" + s.gsub! "123", "456" +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 something that affects both Homebrew and MacPorts (i.e. macOS specific) it should be turned into an upstream submitted patch instead. + +If you need modify variables in a `Makefile`, rather than using `inreplace`, pass them as arguments to `make`: + +```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 [`patch`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#patch-class_method)es should generally be avoided, sometimes they are necessary. + +When [`patch`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#patch-class_method)ing (i.e. fixing header file inclusion, fixing compiler warnings, etc.) the first thing to do is check whether or not the upstream project is aware of the issue. If not, file a bug report and/or submit your patch for inclusion. We may sometimes still accept your patch before it was submitted upstream but by getting the ball rolling on fixing the upstream issue you reduce the length of time we have to carry the patch around. + +*Always justify a [`patch`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#patch-class_method) with a code comment!* Otherwise, nobody will know when it is safe to remove the patch, or safe to leave it in when updating the formula. The comment should include a link to the relevant upstream issue(s). + +External [`patch`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#patch-class_method)es can be declared using resource-style blocks: + +```ruby +patch do + url "https://example.com/example_patch.diff" + sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" +end +``` + +A strip level of `-p1` is assumed. It can be overridden using a symbol argument: + +```ruby +patch :p0 do + url "https://example.com/example_patch.diff" + sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" +end +``` + +[`patch`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#patch-class_method)es can be declared in [`stable`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#stable-class_method), [`devel`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#devel-class_method), and [`head`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#head-class_method) blocks. NOTE: always use a block instead of a conditional, i.e. `stable do ... end` instead of `if build.stable? then ... end`. + +```rb +stable do + # some other things... + + patch do + url "https://example.com/example_patch.diff" + sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" + 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 + +```shell +brew install --interactive --git foo +# (make some edits) +git diff | pbcopy +brew edit foo +``` + +Now just paste into the formula after `__END__`. +Instead of `git diff | pbcopy`, for some editors `git diff >> path/to/your/formula/foo.rb` might help you ensure that the patch is not touched (e.g. white space removal, indentation, etc.) + +# Advanced Formula Tricks + +If anything isnât clear, you can usually figure it out by `grep`ping the `$(brew --repo homebrew/core)` directory. Please submit a pull request to amend this document if you think it will help! + +## Unstable versions (`devel`, `head`) + +Formulae can specify alternate downloads for the upstream projectâs [`devel`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#devel-class_method) release (unstable but not `master`/`trunk`) or [`head`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#head-class_method) (`master`/`trunk`). + +### `devel` + +The [`devel`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#devel-class_method) spec (activated by passing `--devel`) is used for a projectâs unstable releases. It is specified in a block: + +```ruby +devel do + url "https://foo.com/foo-0.1.tar.gz" + sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7" +end +``` + +You can test if the `devel` spec is in use with `build.devel?`. + +### `head` + +[`head`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#head-class_method) 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`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#head-class_method) is being built with `build.head?`. + +To use a specific commit, tag, or branch from a repository, specify [`head`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#head-class_method) with the `:tag` and `:revision`, `:revision`, or `:branch` option, like so: + +```ruby +class Foo < Formula + head "https://github.com/some/package.git", :revision => "090930930295adslfknsdfsdaffnasd13" + # or :branch => "develop" (the default is "master") + # or :tag => "1_0_release", + # :revision => "090930930295adslfknsdfsdaffnasd13" +end +``` + +## Compiler selection + +Sometimes a package fails to build when using a certain compiler. Since recent Xcodes no longer include a GCC compiler we cannot simply force the use of GCC. Instead, the correct way to declare this is the [`fails_with` DSL method](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#fails_with-class_method). A properly constructed [`fails_with`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#fails_with-class_method) block documents the latest compiler build version known to cause compilation to fail, and the cause of the failure. For example: + +```ruby +fails_with :llvm do + 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 (an integer; you can find this number in your `brew --config` output). `cause` takes a String, and the use of heredocs is encouraged to improve readability and allow for more comprehensive documentation. + +[`fails_with`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#fails_with-class_method) declarations can be used with any of `:gcc`, `:llvm`, and `:clang`. Homebrew will use this information to select a working compiler (if one is available). + +## Specifying the Download Strategy explicitly + +To use one of Homebrewâs built-in download strategies, specify the `:using =>` flag on a `url` or `head`. For example: + +```ruby +class Python3 < Formula + homepage "https://www.python.org/" + url "https://www.python.org/ftp/python/3.4.3/Python-3.4.3.tar.xz" + sha256 "b5b3963533768d5fc325a4d7a6bd6f666726002d696f1d399ec06b043ea996b8" + head "https://hg.python.org/cpython", :using => :hg +``` + +Download strategies offered by Homebrew are: + +| `:using` value | download strategy | +|----------------|-------------------------------| +| `:bzr` | `BazaarDownloadStrategy` | +| `:curl` | `CurlDownloadStrategy` | +| `:cvs` | `CVSDownloadStrategy` | +| `:git` | `GitDownloadStrategy` | +| `:hg` | `MercurialDownloadStrategy` | +| `:nounzip` | `NoUnzipCurlDownloadStrategy` | +| `:post` | `CurlPostDownloadStrategy` | +| `:svn` | `SubversionDownloadStrategy` | + +If you need more control over the way files are downloaded and staged, you can create a custom download strategy and specify it using the [`url`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#url-class_method) method's `:using` option: + + +```ruby +class MyDownloadStrategy < SomeHomebrewDownloadStrategy + # Does something cool +end + +class Foo < Formula + url "something", :using => MyDownloadStrategy +end +``` + +## Just moving some files + +When your code in the install function is run, the current working directory is set to the extracted tarball. + +So it is easy to just move 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 + +<table> + <thead> + <tr> + <th>Name</th> + <th>Default</th> + <th>Example</th> + </tr> + </thead> + <tbody> + <tr> + <th><code>HOMEBREW_PREFIX</code></th> + <td><code>/usr/local</code></td> + <td></td> + </tr> + <tr> + <th><code>prefix</code></th> + <td><code>#{HOMEBREW_PREFIX}/Cellar/#{name}/#{version}</code></td> + <td><code>/usr/local/Cellar/foo/0.1</code></td> + </tr> + <tr> + <th><code>opt_prefix</code></th> + <td><code>#{HOMEBREW_PREFIX}/opt/#{name}</code></td> + <td><code>/usr/local/opt/foo</code></td> + </tr> + <tr> + <th><code>bin</code></th> + <td><code>#{prefix}/bin</code></td> + <td><code>/usr/local/Cellar/foo/0.1/bin</code></td> + </tr> + <tr> + <th><code>doc</code></th> + <td><code>#{prefix}/share/doc/foo</code></td> + <td><code>/usr/local/Cellar/foo/0.1/share/doc/foo</code></td> + </tr> + <tr> + <th><code>include</code></th> + <td><code>#{prefix}/include</code></td> + <td><code>/usr/local/Cellar/foo/0.1/include</code></td> + </tr> + <tr> + <th><code>info</code></th> + <td><code>#{prefix}/share/info</code></td> + <td><code>/usr/local/Cellar/foo/0.1/share/info</code></td> + </tr> + <tr> + <th><code>lib</code></th> + <td><code>#{prefix}/lib</code></td> + <td><code>/usr/local/Cellar/foo/0.1/lib</code></td> + </tr> + <tr> + <th><code>libexec</code></th> + <td><code>#{prefix}/libexec</code></td> + <td><code>/usr/local/Cellar/foo/0.1/libexec</code></td> + </tr> + <tr> + <th><code>man</code></th> + <td><code>#{prefix}/share/man</code></td> + <td><code>/usr/local/Cellar/foo/0.1/share/man</code></td> + </tr> + <tr> + <th><code>man[1-8]</code></th> + <td><code>#{prefix}/share/man/man[1-8]</code></td> + <td><code>/usr/local/Cellar/foo/0.1/share/man/man[1-8]</code></td> + </tr> + <tr> + <th><code>sbin</code></th> + <td><code>#{prefix}/sbin</code></td> + <td><code>/usr/local/Cellar/foo/0.1/sbin</code></td> + </tr> + <tr> + <th><code>share</code></th> + <td><code>#{prefix}/share</code></td> + <td><code>/usr/local/Cellar/foo/0.1/share</code></td> + </tr> + <tr> + <th><code>pkgshare</code></th> + <td><code>#{prefix}/share/foo</code></td> + <td><code>/usr/local/Cellar/foo/0.1/share/foo</code></td> + </tr> + <tr> + <th><code>etc</code></th> + <td><code>#{HOMEBREW_PREFIX}/etc</code></td> + <td><code>/usr/local/etc</code></td> + </tr> + <tr> + <th><code>var</code></th> + <td><code>#{HOMEBREW_PREFIX}/var</code></td> + <td><code>/usr/local/var</code></td> + </tr> + <tr> + <th><code>buildpath</code></th> + <td>A temporary directory somewhere on your system</td> + <td><code>/private/tmp/[formula-name]-0q2b/[formula-name]</code></td> + </tr> + </tbody> +</table> + +These can be used, for instance, in code such as + +```ruby +bin.install Dir["output/*"] +``` + +to move binaries into their correct location into the cellar, and + +```ruby +man.mkpath +``` + +to create the directory structure to the manual page location. + +To install man pages into specific locations, use `man1.install "foo.1", "bar.1"`, `man2.install "foo.2"`, etc. + +Note that in the context of Homebrew, [`libexec`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#libexec-instance_method) is reserved for private use by the formula and therefore is not symlinked into `HOMEBREW_PREFIX`. + +## Adding optional steps + +If you want to add an [`option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#option-class_method): + +```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 [`option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#option-class_method)s 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 +``` + +[`option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#option-class_method) names should be prefixed with the words `with` or `without`. For example, an option to run a test suite should be named `--with-test` or `--with-check` rather than `--test`, and an option to enable a shared library `--with-shared` rather than `--shared` or `--enable-shared`. + +Note that [`option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#option-class_method)s that arenât `build.with? ` or `build.without?` should be deprecated with [`deprecated_option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#deprecated_option-class_method). See [wget](https://github.com/Homebrew/homebrew-core/blob/master/Formula/wget.rb#L27-L31) for an example. + + +## File level operations + +You can use the file utilities provided by Ruby's [`FileUtils`](http://www.ruby-doc.org/stdlib/libdoc/fileutils/rdoc/index.html). These are included in the `Formula` class, so you do not need the `FileUtils.` prefix to use them. + +When creating symlinks, take special care to ensure they are *relative* symlinks. This makes it easier to create a relocatable bottle. For example, to create a symlink in `bin` to an executable in `libexec`, use + +```ruby +bin.install_symlink libexec/"name" +``` + +instead of: + +```ruby +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`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#plist_name-instance_method) will return e.g. `homebrew.mxcl.<formula>` and [`plist_path`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#plist_path-instance_method) will return e.g. `/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 `sha256`. If a `revision` line exists outside any `bottle do` block *and* the new release is stable rather than devel, it should be removed. + +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 install` goes before `def post_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`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version-class_method) from the [`url`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#url-class_method) in avoid duplication. If the tarball has an unusual name you may need to manually assign the [`version`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version-class_method). + +## Bad Makefiles + +Not all projects have makefiles that will run in parallel so try to deparallelize by adding these lines to the `install` method: + +```ruby +ENV.deparallelize +system "make" # separate make and make install steps +system "make", "install" +``` + +If that fixes it, please open an [issue](https://github.com/Homebrew/homebrew-core/issues) so that we can fix it for everyone. + +## Still wonât work? + +Check out what MacPorts and Fink do: + +```shell +brew -S --macports foo +brew -S --fink foo +``` + +# Superenv Notes + +`superenv` is our "super environment" that isolates builds by removing `/usr/local/bin` and all user `PATH`s that are not essential for the build. It does this because user `PATH`s are often full of stuff that breaks builds. `superenv` also removes bad flags from the commands passed to `clang`/`gcc` and injects others (for example all `keg_only` dependencies are added to the `-I` and `-L` flags. + +# Fortran + +Some software requires a Fortran compiler. This can be declared by adding `depends_on :fortran` to a formula. `:fortran` is a `Requirement` that does several things. + +First, it looks to see if you have set the `FC` environment variable. If it is set, Homebrew will use this value during compilation. If it is not set, it will check to see if `gfortran` is found in `PATH`. If it is, Homebrew will use its location as the value of `FC`. Otherwise, the `gcc` formula will be treated as a dependency and installed prior to compilation. + +If you have set `FC` to a custom Fortran compiler, you may additionally set `FCFLAGS` and `FFLAGS`. Alternatively, you can pass `--default-fortran-flags` to `brew install` to use Homebrew's standard `CFLAGS`. + +When using Homebrew's `gfortran` compiler, the standard `CFLAGS` are used and user-supplied values of `FCFLAGS` and `FFLAGS` are ignored for consistency and reproducibility reasons. + +# How to start over (reset to upstream `master`) + +Have you created a real mess in git which stops you from creating a commit you want to submit to us? You might want to consider starting again from scratch. Your changes can be reset to the Homebrew's `master` branch by running: + +```shell +git checkout -f master +git reset --hard origin/master +``` diff --git a/docs/Gems,-Eggs-and-Perl-Modules.md b/docs/Gems,-Eggs-and-Perl-Modules.md new file mode 100644 index 000000000..dfbdc224f --- /dev/null +++ b/docs/Gems,-Eggs-and-Perl-Modules.md @@ -0,0 +1,136 @@ +# Gems, Eggs and Perl Modules +On a fresh macOS 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 macOS, any [Python version X.Y also searches in +`~/Library/Python/X.Y/lib/python/site-packages` for +modules](https://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 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](https://metacpan.org/pod/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](https://metacpan.org/pod/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/docs/Homebrew-and-Python.md b/docs/Homebrew-and-Python.md new file mode 100644 index 000000000..5b8676dbc --- /dev/null +++ b/docs/Homebrew-and-Python.md @@ -0,0 +1,97 @@ +# Homebrew and Python +## Overview + +This page describes how Python is handled in Homebrew for users. See [Python for Formula Authors](Python-for-Formula-Authors.md) for advice on writing formulae to install packages written in Python. + +Homebrew should work with any [CPython](https://stackoverflow.com/questions/2324208/is-there-any-difference-between-cpython-and-python) and defaults to the macOS 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?](https://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/<X>.<Y>/bin`) is: + + pip install --user --install-option="--prefix=" <package-name> + +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 <formula>`.) + +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 <module>` from a brewed Python if you ran `brew install <formula_with_python_bindings>` 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-python`). + +## Policy for non-brewed Python bindings + +These should be installed via `pip install <x>`. To discover, you can use `pip search` or <https://pypi.python.org/pypi>. (**Note:** System Python does not provide `pip`. Follow the instructions at https://pip.readthedocs.org/en/stable/installing/#install-pip to install it for your system Python if you would like it.) + + +## 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`. + +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 <package>`. + + +## 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. + +## Why is Homebrew's Python being installed as a dependency? + +Formulae that depend on the special :python target are bottled against the Homebrew Python and require it to be installed. You can avoid installing Homebrew's Python by building these formulae with `--build-from-source`. diff --git a/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md b/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md new file mode 100644 index 000000000..03d3a00fa --- /dev/null +++ b/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md @@ -0,0 +1,70 @@ +# How To Open a Homebrew Pull Request (and get it merged) + +The following commands are used by Homebrew contributors to set up a fork of Homebrew's Git repository on GitHub, create a new branch and create a GitHub pull request ("PR") of the changes in that branch. + +Depending on the change you want to make, you need to send the pull request to the appropriate one of Homebrew's main repositories. If you want to submit a change to Homebrew core code (the `brew` implementation), you should open the pull request on [Homebrew/brew](https://github.com/Homebrew/brew). If you want to submit a change for a formula, you should open the pull request on [the `homebrew/core` tap](https://github.com/Homebrew/homebrew-core) or another [official tap](https://github.com/Homebrew), based on the formula type. + +## Set up your own fork of the Homebrew repository + +### Core `brew` code related pull request + +1. [Fork the Homebrew/brew repository on GitHub](https://github.com/Homebrew/brew/fork). + * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories. +2. Change to the directory containing your Homebrew installation with `cd $(brew --repository)`. +3. Add your pushable forked repository with `git remote add <YOUR_USERNAME> https://github.com/<YOUR_USERNAME>/brew.git`. + * `<YOUR_USERNAME>` is your GitHub username, not your local machine username. + +### Formulae related pull request + +1. [Fork the Homebrew/homebrew-core repository on GitHub](https://github.com/Homebrew/homebrew-core/fork). + * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories. +2. Change to the directory containing Homebrew formulae with `cd $(brew --repository homebrew/core)`. +3. Add your pushable forked repository with `git remote add <YOUR_USERNAME> https://github.com/<YOUR_USERNAME>/homebrew-core.git` + * `<YOUR_USERNAME>` is your GitHub username, not your local machine username. + +For formulae in central taps other than `homebrew/core`, such as `homebrew/science` or `homebrew/games`, substitute that tap's name for `homebrew/core` in each step, and alter the GitHub repository URLs as necessary. + +## Create your pull request from a new branch + +To make a new branch and submit it for review, create a GitHub pull request with the following steps: + +1. Check out the `master` branch with `git checkout master`. +2. Retrieve new changes to the `master` branch with `brew update`. +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` or your favorite text editor, following all the guidelines in the [Formula Cookbook](Formula-Cookbook.md). + * If there's a `bottle do` block in the formula: don't remove or change it; we'll update it when we pull your PR. +5. Test your changes on each changed formula by doing the following, and ensure they all pass without issue. (Make sure you do the `brew audit` step while your changed formula is installed.) + 1. `brew tests` + 2. `brew install --build-from-source <CHANGED_FORMULA>` + 3. `brew test <CHANGED_FORMULA>` + 4. `brew audit --strict <CHANGED_FORMULA>` +6. Make a separate commit for each changed formula with `git add` and `git commit`. +7. Upload your new commits to the branch on your fork with `git push --set-upstream <YOUR_USERNAME> <YOUR_BRANCH_NAME>`. +8. Go to https://github.com/Homebrew/homebrew-core and create a pull request to request review and merging of the commits in your pushed branch. Explain why the change is needed and, if fixing a bug, how to reproduce the bug. Make sure you have done each step in the checklist that appears in your new PR. + * Please note that our preferred commit message format for simple version updates is "`<FORMULA_NAME> <NEW_VERSION>`", e.g. "`source-highlight 3.1.8`". `devel` version updates should have the commit message suffixed with `(devel)`, e.g. "`nginx 1.9.1 (devel)`". If updating both stable and `devel`, the format should be a concatenation of these two forms, e.g. "`x264 r2699, r2705 (devel)`". +9. Await feedback or a merge from Homebrew's maintainers. We typically respond to all PRs within a couple days, but it may take up to a week, depending on the maintainers' workload. +10. Thank you! + +## Following up + +To respond well to feedback: + +1. Ask for clarification of anything you don't understand and for 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. + * A `needs response` label on a PR means that the Homebrew maintainers need you to respond to previous comments. +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. Check out 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 commit per formula with `git rebase --interactive origin/master`. +4. Push to your remote fork's branch and the pull request with `git push --force`. + +If you are working on a PR for a single formula, `git commit --amend` is a convenient way of keeping your commits squashed as you go. + +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. Note that the PR status may show up as "Closed" instead of "Merged" because of the way we merge contributions. Don't worry: you will still get author credit in the actual merged commit. + +Well done, you are now a Homebrew contributor! diff --git a/docs/How-to-Create-and-Maintain-a-Tap.md b/docs/How-to-Create-and-Maintain-a-Tap.md new file mode 100644 index 000000000..ff7de8029 --- /dev/null +++ b/docs/How-to-Create-and-Maintain-a-Tap.md @@ -0,0 +1,56 @@ +# How to Create and Maintain a Tap +Taps are external sources of Homebrew formulae and/or external commands. They +can be created by anyone to provide their own formulae and/or external commands +to any Homebrew user. + +## Creating a tap +A tap is usually a git repository available online, but you can use anything as +long as itâs a protocol that git understands, or even just a directory with +files in it. +If hosted on GitHub, we recommend that the repositoryâs name start with +`homebrew-`. + +Tap formulae follow the same format as the coreâs ones, and can be added at the +repositoryâs root, or under `Formula` or `HomebrewFormula` subdirectories. We +recommend the latter options because it makes the repository organisation +easier to grasp, and top-level files are not mixed with formulae. + +See [homebrew/tex](https://github.com/Homebrew/homebrew-tex) for an example of +a tap with a `Formula` subdirectory. + +### Installing +If itâs on GitHub, users can install any of your formulae with +`brew install user/repo/formula`. Homebrew will automatically add your +`github.com/user/homebrew-repo` tap before installing the formula. +`user/repo/formula` points to the `github.com/user/homebrew-repo/**/formula.rb` +file here. + +If they want to get your tap without installing any formula at the same time, +users can add it with the [`brew tap` command](brew-tap.md). + +If itâs on GitHub, they can use `brew tap user/repo`, where `user` is your +GitHub username and `homebrew-repo` your repository. + +If itâs hosted outside of GitHub, they have to use `brew tap user/repo <url>`, +where `user` and `repo` will be used to refer to your tap and `<url>` is your +Git clone URL. + +Users can then install your formulae either with `brew install foo` if thereâs +no core formula with the same name, or with `brew install user/repo/foo` to +avoid conflicts. + +## Maintaining a tap +A tap is just a git repository so you donât have to do anything specific when +making modifications apart from committing and pushing your changes. + +### Updating +Once your tap installed, Homebrew will update it each time an user runs +`brew update`. Outdated formulae will be upgraded when an user runs +`brew upgrade`, like core formulae. + +## External commands +You can provide your tap users with custom `brew` commands by adding them in a +`cmd` subdirectory. [Read more on external commands](External-Commands.md). + +See [homebrew/aliases](https://github.com/Homebrew/homebrew-aliases) for an +example of a tap with external commands. diff --git a/docs/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md b/docs/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md new file mode 100644 index 000000000..f71c75164 --- /dev/null +++ b/docs/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md @@ -0,0 +1,68 @@ +# How to build software outside Homebrew with Homebrew `keg-only` dependencies + +## What does `keg-only` mean? + +The [FAQ](FAQ.md) briefly explains this. + +As an example: + +*OpenSSL isnât symlinked into my `$PATH` and non-Homebrew builds canât find it!* + +This is because Homebrew keeps it locked inside its individual prefix, rather than symlinking to the publicly-available location, usually `/usr/local`. + +## Advice on potential workarounds. + +A number of people in this situation are either forcefully linking `keg_only` tools with `brew link --force` or moving default system utilities out of the `$PATH` and replacing them with manually-created symlinks to the Homebrew-provided tool. + +*Please* do not remove macOS native tools and forcefully replace them with symlinks back to the Homebrew-provided tool. Doing so can and likely will cause significant breakage when attempting to build software. + +`brew link --force` creates a warning in `brew doctor` to let both you and maintainers know that link exists and could be causing issues. If youâve linked something and thereâs no problems at all? Feel free to ignore the `brew doctor` error. + +## How do I use those tools outside of Homebrew? + +Useful, reliable alternatives exist should you wish to use `keg_only` tools outside of Homebrew. + +### Build flags: + + +You can set flags to give configure scripts or Makefiles a nudge in the right direction. An example of flag setting: + +```shell +./configure --prefix=/Users/Dave/Downloads CFLAGS=-I$(brew --prefix)/opt/openssl/include LDFLAGS=-L$(brew --prefix)/opt/openssl/lib +``` + +An example using `pip`: + +```shell +CFLAGS=-I$(brew --prefix)/opt/icu4c/include LDFLAGS=-L$(brew --prefix)/opt/icu4c/lib pip install pyicu +``` + +### `$PATH` modification: + +You can temporarily prepend your `$PATH` with the toolâs bin directory, such as: + +```shell +export PATH=$(brew --prefix)/opt/openssl/bin:$PATH +``` + +This will prepend that folder to your `$PATH`, ensuring any build script that searches the `$PATH` will find it first. + +Changing your `$PATH` using that command ensures the change only exists for the duration of that shell session. Once you are no longer in that session, the `$PATH` reverts to the prior state. + +### `pkg-config` detection: + +If the tool you are attempting to build is [pkg-config](https://en.wikipedia.org/wiki/Pkg-config) aware, you can amend your `PKG_CONFIG_PATH` to find that `keg_only` utilityâs `.pc` file, if it has them. Not all formulae ship with those files. + +An example of that is: + +```shell +export PKG_CONFIG_PATH=$(brew --prefix)/opt/openssl/lib/pkgconfig +``` + +If youâre curious about the `PKG_CONFIG_PATH` variable `man pkg-config` goes into more detail. + +You can get `pkg-config` to detail the default search path with: + +```shell +pkg-config --variable pc_path pkg-config +``` diff --git a/docs/Installation.md b/docs/Installation.md new file mode 100644 index 000000000..8ee1891cf --- /dev/null +++ b/docs/Installation.md @@ -0,0 +1,57 @@ +# 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#why-does-homebrew-say-sudo-is-bad-) when you +`brew install`. It is a careful script, it can be run even if you have stuff +installed to `/usr/local` already. It tells you exactly what it will do before +it does it too. And you have to confirm everything it will do before it starts. + +## Requirements +* An Intel CPU <sup>[1](#1)</sup> +* OS X 10.10 or higher <sup>[2](#2)</sup> +* Command Line Tools for Xcode: `xcode-select --install`, + https://developer.apple.com/downloads or + [Xcode](https://itunes.apple.com/us/app/xcode/id497799835) <sup>[3](#3)</sup> +* A Bourne-compatible shell for installation (e.g. bash or zsh) <sup>[4](#4)</sup> + +## 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/brew/tarball/master | tar xz --strip 1 -C homebrew` + +### 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`. + +## Uninstallation +Uninstallation is documented in the [FAQ](FAQ.md). + +<a name="1"><sup>1</sup></a> Not all formulae have CPU or OS requirements, but +you can assume you will have trouble if you donât conform. Also, you can find +PowerPC and Tiger branches from other users in the fork network. See +[Interesting Taps & Forks](Interesting-Taps-&-Forks.md). + +<a name="2"><sup>2</sup></a> 10.10 or higher is recommended. 10.5 - 10.8 are +supported on a best-effort basis. For 10.4 and 10.5, see +[Tigerbrew](https://github.com/mistydemeo/tigerbrew). + +<a name="3"><sup>3</sup></a> Most formulae require a compiler. A handful +require a full Xcode installation. You can install Xcode, the CLT, or both; +Homebrew supports all three configurations. Downloading Xcode may require an +Apple Developer account on older versions of Mac OS X. Sign up for free +[here](https://developer.apple.com/register/index.action). + +<a name="4"><sup>4</sup></a> The one-liner installation method found on +[brew.sh](http://brew.sh) requires a Bourne-compatible shell (e.g. bash or +zsh). Notably, fish, tcsh and csh will not work. diff --git a/docs/Interesting-Taps-&-Forks.md b/docs/Interesting-Taps-&-Forks.md new file mode 100644 index 000000000..d23277b15 --- /dev/null +++ b/docs/Interesting-Taps-&-Forks.md @@ -0,0 +1,63 @@ +# Interesting Taps & Forks +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-core, often called `homebrew/core`, is always built-in. + +## Main Taps + +* [homebrew/apache](https://github.com/Homebrew/homebrew-apache): A tap for Apache modules, extending macOS's built-in Apache. These brews may require unconventional additional setup, as explained in the caveats. + +* [homebrew/boneyard](https://github.com/Homebrew/homebrew-boneyard): Formulae from other official taps, primarily (homebrew/core) are not deleted, they are moved here. + +* [homebrew/bundle](https://github.com/Homebrew/homebrew-bundle): Bundler for non-Ruby dependencies from Homebrew. + +* [homebrew/completions](https://github.com/Homebrew/homebrew-completions): Shell completion formulae. + +* [homebrew/devel-only](https://github.com/Homebrew/homebrew-devel-only): A tap for brews that only have pre-release/development versions. + +* [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes): Need GDB or a newer Tk? System duplicates go here. + +* [homebrew/emacs](https://github.com/Homebrew/homebrew-emacs): A tap for Emacs packages. + +* [homebrew/games](https://github.com/Homebrew/homebrew-games): Game or gaming-emulation related formulae. + +* [homebrew/head-only](https://github.com/Homebrew/homebrew-head-only): A tap for brews that only have unstable, unreleased versions. This tap is **deprecated** and doesnât accept new formulae. + +* [homebrew/nginx](https://github.com/Homebrew/homebrew-nginx): Feature rich Nginx tap for modules. + +* [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/science](https://github.com/Homebrew/homebrew-science): A collection of scientific libraries and tools. + +* [homebrew/services](https://github.com/Homebrew/homebrew-services): A tool to start Homebrew formulae's plists with `launchctl`. + +* [homebrew/versions](https://github.com/Homebrew/homebrew-versions): Need e.g. older or newer versions of Postgresql? Older versions of GCC? + +* [homebrew/x11](https://github.com/Homebrew/homebrew-x11): Formulae with hard X11 dependencies. + +`brew search` looks in these main taps as well as in [homebrew/core](https://github.com/Homebrew/homebrew-core). 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-discuss@googlegroups.com. We want your help! + +## Other Interesting Taps + +* [InstantClientTap/instantclient](https://github.com/InstantClientTap/homebrew-instantclient): A tap for Oracle Instant Client. The packages need to be downloaded manually. + +* [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. + +* [osx-cross/avr](https://github.com/osx-cross/homebrew-avr): GNU AVR toolchain (Libc, compilers and other tools for Atmel MCUs, useful for Arduino hackers and AVR programmers). + +* [petere/postgresql](https://github.com/petere/homebrew-postgresql): Allows installing multiple PostgreSQL versions in parallel. + +* [titanous/gnuradio](https://github.com/titanous/homebrew-gnuradio): GNU Radio and friends running on macOS. + +## Interesting Forks + +* [mistydemeo/tigerbrew](https://github.com/mistydemeo/tigerbrew): Experimental Tiger PowerPC version + +* [Linuxbrew/brew](https://github.com/Linuxbrew/brew): Experimental Linux version + +## Technical Details + +Your taps are git repositories located at `$(brew --prefix)/Library/Taps`. diff --git a/docs/Kickstarter-Supporters.md b/docs/Kickstarter-Supporters.md new file mode 100644 index 000000000..01f0fcc16 --- /dev/null +++ b/docs/Kickstarter-Supporters.md @@ -0,0 +1,726 @@ +# Kickstarter Supporters +This file contains a list of the awesome people who gave ÂŁ5 or more to +[our Kickstarter](https://www.kickstarter.com/projects/homebrew/brew-test-bot). + +This list is still incomplete as we need addresses for everyone who receives +a physical reward. Kickstarter recommends asking only when we are ready to +ship (to avoid changes of address) so we can't ask for more names/URLs +until then. + +These mind-blowing people supported our Kickstarter by giving us ÂŁ450 or more: + +[](http://hashrocket.com/) + +These spectacular people supported our Kickstarter by giving us ÂŁ400 or more: + +* [Cargo Media](http://www.cargomedia.ch/) + +These incredible people supported our Kickstarter by giving us ÂŁ200 or more: + +* Stephan Toggweiler +* [The Tor Project](https://www.torproject.org) + +These amazing people supported our Kickstarter by giving us ÂŁ100 or more: + +* [Mac Mini Vault](http://www.macminivault.com) +* jpr +* [Greg Sieranski](http://wonbyte.com) +* [Stanley Stuart](http://fivetanley.com) +* [Conor McDermottroe](http://www.mcdermottroe.com) +* [Spike Grobstein](http://spike.grobste.in) +* [nonfiction studios inc.](http://nonfiction.ca/) +* [Dev Fu! LLC](http://devfu.com) +* [Human Made Limited](https://hmn.md/) +* [Roland Moriz](https://roland.io/) +* [Rob Freiburger](http://robfreiburger.com/) +* [Carter Schonwald](http://www.wellposed.com) +* [Andy Piper](http://andypiper.co.uk) +* [Moriah Trostler](http://www.televolve.com) +* [Zach Kelling](http://whatit.is) +* [Scott Densmore](http://scottdensmore.com) +* [Adam Walz](http://www.adamwalz.net) +* [Timo Tijhof](https://github.com/Krinkle) +* [Joshua Hull](https://github.com/joshbuddy) +* [Chad Catlett](http://www.chadcatlett.com/) + +These awesome people supported our Kickstarter by giving us ÂŁ50 or more: + +* [Oliver Sigge](http://oliver-sigge.de) +* [grahams](http://sean-graham.com/) +* [Brian Ford](http://briantford.com) +* Will Froning +* [Florian Eckerstorfer](http://florianeckerstorfer.com) +* [Leonhard Melzer](http://foomoo.de/) +* [Klaus GroĂmann](https://github.com/iKlaus) +* [monmon](https://github.com/monmon) +* [nimbly](http://nimbly.be) +* [cimnine](https://cimnine.ch) +* [Greg DeAngelis](http://greg.deangel.is) +* [Johan Carlquist](https://www.rymdvarel.se) +* [Simon Lundström](http://soy.se) +* [Samir Talwar](http://samirtalwar.com/) +* [John Wu](http://www.johnwu.com) +* [Jan Lehnardt](https://couchdb.apache.org) +* [Adam Auden](http://bimble.net/) +* [closure.jp](http://closure.jp/) +* Scott S. +* [Rachel Baker](http://rachelbaker.me) +* Dominique Poulain +* [Talks](http://tlks.me) +* [Philipp Bosch](http://pb.io) +* [Alexandru Badiu](http://ctrlz.ro) +* [Misha Manulis](http://brewbit.com) +* [MrBri](http://mrbri.com) +* [Marc Van Olmen](http://www.marcvanolmen.com) +* [Scott Gardner](http://scotteg.com) +* [Peter JC](http://peterjc.dk) +* [Nathan Toups](http://rojoroboto.com) +* [Fluent Globe](http://fluentglobe.com) +* [Dmitri Akatov](http://akatov.com) +* [Joey Mink](http://joeymink.com) +* [MentalPower](https://mentalpower.us) +* [worldofchris](http://www.worldofchris.com) +* [JoĂ«l Kuijten](http://pm5544.eu) +* [William Griffiths](http://Cwmni.com) +* [Paul Howard](https://github.com/pauldhoward) +* [MĂ„rten Gustafson](http://marten.gustafson.pp.se) +* [Markus Heurung](http://markusheurung.de) +* [Rajiv Aaron Manglani](https://www.rajivmanglani.com/) +* Zachary Elliott +* [Justin Weiss](https://www.justinweiss.com) +* Matt Dickoff +* [Pivotal Ops](http://pivotallabs.com) +* [William Woodall](http://williamjwoodall.com) +* [Jiayong Ou](http://orly.ch) +* [Joshua Peek](https://github.com/josh) +* [Sifter](https://sifterapp.com) +* [Morten Bight](http://justabeech.com) +* Markus Heurung +* David Hardiman +* [Olly Legg](http://51degrees.net) +* [Ben Darlow](http://www.darlow.eu/) +* [Alexey Zakhlestin](https://github.com/indeyets) +* Fernando Blat +* [Adam Holt](http://adamholt.co.uk) +* Trevor Turk +* [Jochen Weiland](https://jweiland.net) +* Paul Mietz Egli +* Petr Olah +* Ken Mayer +* [Jeremy D. Frens](http://www.norecess.org/) +* Peter Quade +* C J Silverio +* [Roddi](http://www.winkenschuerfel.de) +* Jeffrey Sullivan Jr +* Jonathan Borzilleri +* Ethan Bruning +* Nick Mixdorf +* Alex Duryee +* Zac Ragan +* [Lane Lillquist](http://www.lillq.com) +* [Robert Schmidl](https://github.com/RobRoy) +* [Collective Idea](http://collectiveidea.com) +* [Freckle Time Tracking](https://letsfreckle.com/) +* [Hans-Christian Otto](http://hans-christian-otto.de/) +* Dan Lane +* Seth Szymanski +* [osh Runge](http://joshrunge.com) +* Glen Hunt +* [Venantius](http://www.venanti.us) +* Matt Jones +* [Jen Savage](https://savagejen.github.io/) +* [Trenton Schulz](http://www.norwegianrockcat.com) +* Jake Kaufman +* [Hiro](http://blog.qli.jp/) +* Debreczeni BarnabĂĄs +* [Scott Handley](http://evomics.org) +* [Scott Lipsig](https://github.com/scottscott) +* Nick Zadrozny +* Mikael Roos +* Stephen Eckenrode +* [Kevin Sumner](http://kevinsumner.com) +* Rahul +* [Nothing Interactive](https://www.nothing.ch) +* [Nick Sivo](http://nicksivo.com) +* [Claus Pfisterer](http://www.apochroma.ch) +* Bob Doyle +* Gabriel Boyer +* Tom +* Yann Lawrence +* Frederick Ostrander +* [David Wagner](https://noiseandheat.com) +* [Craig Labenz and Matt Kahl](http://www.Stik.com) +* Alan Grosskurth + +These brilliant people supported our Kickstarter by giving us ÂŁ15 or more: + +* [Brian Lalor](https://github.com/blalor) +* [Aaron Ackerman](https://twitter.com/_aaronackerman_) +* [Rodreegez](http://rodreegez.com) +* [Stephan Diederich](https://github.com/diederich) +* [Andrew Nesbitt](http://nesbitt.io) +* [Blaine Cook](http://romeda.org/) +* [Raquel Hernandez](http://raquelhernandez.net) +* [JD Harrington](https://twitter.com/psi) +* [P.J. Onori](http://www.somerandomdude.com) +* [Egbert Veenstra](http://egbert.co) +* [Bramus Van Damme](https://www.bram.us/) +* [Matt Vagni](https://www.twitter.com/mattvagni) +* [Matt Cannon](http://www.mattcannon.co.uk) +* [Dannel Jurado](http://demarko.org) +* [Benjamin Esham](http://www.bdesham.info) +* [Nick Rogers](https://twitter.com/zikolas) +* [Abe Estrada](https://abeestrada.com) +* [Mattias Larsson](https://www.yahoo.com/) +* [Dave Ross](http://davidmichaelross.com) +* [Andrian Budantsov](http://andrian.io/) +* [Jason Smith](https://twitter.com/waitingallday) +* [Martin Coxall](https://twitter.com/grabcocque) +* [Nick Jones](mailto:nick@dischord.org) +* [EsmĂ© Cowles](https://github.com/escowles) +* [Garrett L. Ward](http://glward.net) +* [Carl Laird](http://allthingsoptimal.com) +* [Mx A. Matienzo](http://matienzo.org/) +* [Sean Dunn](http://www.dunns.me) +* [Kara Van Malssen](https://avpreserve.com) +* [phette23](http://phette.net) +* [Jemal Cole](http://jemal.co/) +* [Branden Wiegand](http://brandenwiegand.com) +* [Adam Spooner](http://adamjspooner.com) +* [Evan McNulty](http://www.evanm.net/) +* [Abdullah AlDwyish](https://twitter.com/adwayish) +* [Simon Jodet](https://jodet.com) +* [Christian Maier](http://sieben.me) +* [Justin Pecott](http://justin.pecott.net) +* [Yuya Saito](https://github.com/studiomohawk) +* [jan](https://alpha.app.net/derjan) +* [beanieboi](https://abwesend.com) +* [dirkr](https://niebegeg.net) +* [ouvanous](http://ouvanous.com) +* [dlinsin](https://dlinsin.github.io) +* [Alex Morega](https://grep.ro/) +* [Chris McGrath](https://twitter.com/chrismcg) +* [Ben](http://blog.bueti-online.ch) +* [Ishaan Gulrajani](https://ishaan.io) +* [Horst Gutmann](https://zerokspot.com/) +* [freecastle](http://freiburg79.de/) +* [Hynek Schlawack](https://hynek.me) +* [aiusepsi](http://aiusepsi.co.uk) +* [Stefan Borsje](https://yourkarma.com) +* [Mark Goody](http://markgoody.ie/) +* [Terje Sten Bjerkseth](https://github.com/terjesb) +* [Wade Winningham](http://www.updrift.com) +* [Opendream](http://www.opendream.co.th) +* [Todd Grooms](http://toddgrooms.com) +* Christian Savard +* [Michael Novak](http://michaelnovakjr.com) +* [Jon Prettyman](https://www.sprighealth.com/) +* [Ruby Daily](http://rubydaily.org) +* derBernd +* [toolbear](http://tool-man.org/) +* [S Schreiber](http://www.stevenfschreiber.com) +* [Paul Bowsher](https://github.com/boffbowsh/) +* [Daniel Lindsley](http://toastdriven.com/) +* [Felipe Coury](http://gistia.com) +* [noahhendrix](https://twitter.com/noahhendrix) +* [Kevin Davies](http://theausguild.org) +* [Geknowm](http://geknowm.com) +* [Tod Olson](https://www.lib.uchicago.edu/~tod/) +* [Christian Busch](https://debilux.org) +* [Victor Asteinza](http://victorasteinza.com) +* [Hans N. Hjort](http://www.hansnilsson.net) +* [Rachel Heaton](http://www.rmheaton.com) +* [CodeCatalyst](http://codecatalyst.com/) +* [Luke Karrys](http://lukekarrys.com) +* [Brandon Weiss](http://brandonweiss.me) +* [Gareth](http://gareth.com.au) +* [Nate Robins](https://xmission.com/~nate) +* [Jay Graves](http://doubleencore.com) +* [John Wittkoski](https://github.com/jwittkoski) +* [Micah Woods](http://www.hashrocket.com) +* [Raphael Stolt](https://raphaelstolt.blogspot.de) +* [Hatimeria](http://hatimeria.com) +* [Barron Bichon](http://blueplaid.net/) +* [Torvos](https://www.torvos.ca) +* [Alexander Zautke](http://alexander-zautke.com) +* [Sam Kelly](http://skel.ly) +* [Tobias Ottenweller](https://github.com/tomco) +* [Ragan Webber](Http://raganwebber.com) +* [Wesley Moore](http://wezm.net/) +* [pangratz](http://code418.com) +* [jus](http://jus.li) +* [Teng Siong Ong](http://siong1987.com) +* [Bryan Liles](http://thunderboltlabs.com) +* [Tony Pitale](http://tpitale.com) +* [Ryan Ahearn](http://rcahearn.net) +* [ITerativ GmbH](http://www.iterativ.ch/) +* [Brian Nelson](http://www.clientresourcesinc.com) +* [Jeff Beemn](https://jeffbeeman.com) +* [loranger](https://github.com/loranger/) +* TorbjĂžrn Vatn +* [Justin Hileman](http://justinhileman.info) +* [Martin Tithonium](http://martian.at/) +* [Ivan De Marino](http://ivandemarino.me) +* [JĂžrgen TjernĂž](http://jorgenpt.tumblr.com) +* [Peter Souter](https://github.com/petems) +* Marco +* [Steve McKinney](http://stephenmckinney.me) +* Felix Adusei +* [Richard Lee](http://dlackty.org/) +* [Shane O'Grady](http://ogrady.ie) +* [Sebastian Staudt](http://koraktor.de) +* [Eric Blair](http://room45.co/) +* [Andreas Behr](http://www.codedreality.com) +* [Terry Churchill](http://www.doc-linux.co.uk) +* [Maximilian Haack](http://3141.eu) +* [Pascal Jungblut](https://pascalj.de) +* [Absolight](https://www.absolight.fr/) +* [Ben Hagen](https://plus.google.com/102873090274552422645/) +* [Wilbur Smith](https://twitter.com/thewilbur) +* bup +* [epiGenesys](https://www.epigenesys.co.uk/) +* Greg Clarke +* [CoEPP](http://www.coepp.org.au) +* [JĂ©rĂŽme Foray](https://foray-jero.me/) +* [bobuk](https://twitter.com/bobuk) +* [Christoph Hochstrasser](https://christophh.net) +* [JoĂŁo Bolila](http://Bolila.com) +* [Yaroslav Markin](https://github.com/yaroslav) +* [David White](https://wizardfrag.co.uk) +* Jonatan Lindström +* [AYSTech Consulting](http://aystech.net) +* [Josh Dick](http://joshdick.net) +* [Alexey Mirniy](https://www.linkedin.com/in/pharmazone) +* [Simon Gate](Http://smgt.me) +* [Josh Yaganeh](https://github.com/jyaganeh) +* Dirk Kraft +* [stefan crain](https://github.com/stefancrain) +* [xorbyte](https://hackd.net) +* Dom +* [kmcphillips](http://kevinmcphillips.ca) +* [Justin Kolberg](http://www.aelatis.com) +* [Benjamin Medicke](http://benmedicke.com/) +* [Hibri Marzook](http://www.hibri.net) +* [Jeremy Pinnix](http://pixelgrazer.com) +* [Arne de Bree](http://www.arnedebree.nl) +* [Oleksandr Skrypnyk](https://sxua.github.io) +* [Ilya Otyutskiy](https://twitter.com/thesharp) +* Chris Hellmuth +* Unknown Comic +* Brian Miller +* [Zhang Yi](http://tomodachi.name) +* [Romain Lespinasse](https://dandelion.github.io) +* [achiiive.com](http://achiiive.com) +* [Michael Hawkins](http://hawkinsunlimited.com) +* [Tim Sutton](https://github.com/timsutton) +* [Arne Eilermann](https://kleinerdrei.net/) +* [Jeroen Seegers](http://www.jeroenseegers.com) +* [Dan Karney](https://twitter.com/KarneAsada) +* [James Curbo](http://www.curbo.org) +* [Mark Norman Francis](https://github.com/norm/) +* [Lee Brandt](http://leebrandt.me) +* [Dan Ivovich](http://danivovich.com/) +* [Eli Juicy Jones](http://elijones.us/) +* [Daniel Hertz](http://www.dhertz.com) +* [Chuck Fouts](https://github.com/gnarl) +* [Chip Warden](https://twitter.com/lgw4) +* [Ethan Schoonover](http://ethanschoonover.com) +* [Chi Trung Nguyen](http://ctnguyen.net) +* [Danny Amey](http://www.dannyamey.com/) +* Oscar +* [Brian Pollack](http://www.protovate.com) +* [Andrew Broman](http://cccultura.com) +* [Chris Metcalf](http://chrismetcalf.net) +* [smartwatermelon](http://projectinsomnia.com) +* [Ursul_polar](https://twitter.com/ursul_polar) +* David Hodo +* [Jeff Field](https://twitter.com/jfield) +* [dholm](https://github.com/dholm/) +* [Chase Southard](http://southard.co) +* Paul Jenkins +* [Johnneylee Jack Rollins](https://spaceghost.github.io) +* [Jose Marcelino](http://metavurt.net) +* [Adam](https://example.com) +* [François Lamboley](http://www.frostland.fr/) +* [Mike Anderson](http://mrmikea.com) +* [Ian Johnson](https://ialsotakephotos.com/) +* Dave Coyle +* Brian Fuchs +* Fernando +* [Denny Lee](http://dennyglee.com) +* [Ernie Hershey](http://www.ernie.org) +* [Hao Gao](http://www.haogao.me) +* [Tim Gilbert](https://timgilbert.wordpress.com/) +* [Keith Thompson](http://keiththomps.com) + +These wonderful people supported our Kickstarter by giving us ÂŁ10 or more: + +* [Simon Rascovsky](http://teleradiologia.com) +* [silsha](http://felixarndt.de) +* [Martin Kopischke](http://martin.kopischke.net) +* [John Kary](http://johnkary.net) +* [David M. Carr](http://david.carrclan.us) +* [Dale Tournemille](http://www.tournemille.com) +* [VirtualWolf](http://virtualwolf.org) +* [Lovingly Handmade Pornography](http://lovinglyhandmadepornography.com/) +* [Ben Handzo](http://handzo.com) +* [Jean-Philippe Sirois](http://jpsirois.com) +* [Sindre Sorhus](https://sindresorhus.com) +* [Nick Ruest](http://ruebot.net) +* [Steven Huey](https://twitter.com/stevehuey) +* [Craig Bernstein](http://cwb.us/) +* [Peter Murray](https://dltj.org/) +* [Andrew Madsen](http://www.openreelsoftware.com) +* [pb30](http://pb30.com) +* [squaredesign](https://squaredesign.com) +* [Alex Burka](http://www.alexburka.com) +* CiarĂĄn Walsh +* [Andrew Brown](http://pvalu.es) +* [Bethany Sumner](http://www.bethanysumner.com/) +* [Orta](http://orta.io) +* [MichaĆ GoĆÄbiowski](https://mgol.eu) +* [Adam C. Foltzer](http://www.acfoltzer.net/) +* [Steve Hiemstra](https://www.speg.com) +* [Anton Sipos](http://www.softwarefuturism.com) +* [Sergey Nebolsin](http://fedot.com) +* [Dan Poltawski](http://blog.danpoltawski.co.uk) +* [Dieter Komendera](http://www.komendera.com/) +* [Lukas Westermann, at-point ag](http://at-point.ch/) +* [Milan Cermak](http://milancermak.com) +* [Sebastian Krysmanski](http://manski.net) +* [Mike Stenhouse](http://mikesten.com) +* [Alastair Stuart](https://eurotalk.com) +* [David Rekowski](http://rekowski.info) +* [Roland Leth](http://rolandleth.com) +* [Maurice Kelly](http://blog.chatswood.org.uk/) +* [Daryl Spitzer](https://twitter.com/yacitus) +* [Jose Peleteiro](https://peleteiro.net) +* [Mikael Hultgren](http://www.artsoftheinsane.com) +* [Richard Japenga](http://japenga.eu) +* [Pierre Riteau](https://github.com/priteau) +* [Nathan Vander Wilt](http://exts.ch) +* [Jean-Baptiste Escoyez](http://www.inspirationfactory.be) +* [Tobias MĂŒller](http://www.twam.info) +* [Boris Mann](http://www.bmannconsulting.com) +* [Zach A. Thomas](https://github.com/zathomas) +* [Andrey Yunoshev](http://yunoshev.ru) +* [David McFarland](http://www.dcmcfarland.com) +* [Roland Tanglao](http://rolandtanglao.com) +* [Jacob Elder](http://jacobelder.com) +* [ToWatchList](https://towatchlist.com/) +* [Joshua Jabbour](https://about.me/joshuajabbour) +* [Daniel Giribet](http://dani.calidos.com) +* [Eric Wallmander](http://wallmander.net/) +* [Teakhouten meubelen](http://teakmeubelen.nl/) +* [Gerard "smeevil" de Brieder](http://www.govannon.nl) +* [Marius Ciocanel](http://mariusciocanel.com) +* [David Sommers](http://davidsommers.com/) +* [Ray Grasso](http://raygrasso.com) +* [Tim Uruski](http://tim.uruski.name) +* [Robert Clark](http://www.touchtech.co.nz) +* [Wes Oldenbeuving](http://narnach.com/) +* [Jon Fuller](http://erg7.com) +* [PredictionIO (Open-source machine learning server)](https://prediction.io) +* Nikolaus Wittenstein +* [StormMQ](http://stormmq.com/) +* [Barry Hoggard](http://www.tristanmedia.com/) +* [Purplish Tree](http://PurplishTree.com) +* [Stefan Huber](http://signalwerk.ch/) +* Julien Palmas +* [Cameron Spencer](http://eusonic.com) +* [alesdotio](https://github.com/alesdotio) +* [version2.io](http://version2.io) +* [Jeremy Clarke](http://jeremyclarke.org) +* [Dimitar Dimitrov](http://ddimitrov.name/) +* [Hacker School](https://www.hackerschool.com/) +* [Franklin](https://frankl.in) +* [Wes Garrison](http://databasically.com) +* [Braulio Carreno](http://carreno.me) +* [Derek Croft](http://www.kiindly.com) +* [Doc Ritezel](http://ritezel.com) +* [Christoph Heer](http://christophheer.me) +* [Kuba Suder](https://mackuba.eu) +* [Jason Garber](http://sixtwothree.org) +* [Alejandro Caceres](http://punkspider.hyperiongray.com) +* [Slobodan Miskovic](https://miskovic.ca) +* [Kurt Ostergaard](http://KurtOstergaard.com) +* [Simply Business](https://www.simplybusiness.co.uk/) +* [Tate Johnson](http://tatey.com) +* [Gerry Cardinal III](http://gerrycardinal.com/) +* [Andrew Kalek](http://anlek.com) +* [Bryan Coe](http://www.BryanACoe.com) +* 360 Virtual Tours +* [James Turnbull](http://www.kartar.net) +* [Dominic Morgan](https://d3r.com) +* [Mario Witte](http://www.mariowitte.com) +* [Studio NAND](http://www.nand.io) +* [Per Sandström](https://www.helloper.com) +* [Jochen SchĂ€fer](http://www.joschs-robotics.de) +* [Jökull SĂłlberg AuĂ°unsson](http://www.solberg.is) +* [kolpax](http://kolpax.io) +* [Matt Davis](http://penandpants.com) +* [Scott Chamberlain](https://ropensci.org/) +* [Jaehoon You](https://github.com/teslamint) +* [Wayne Robinson](http://www.wayne-robinson.com) +* [Kitt Hodsden](https://kitt.hodsden.org/) +* [Justin Johnson](https://justinjohnson.org/) +* [David Cristofaro](http://davidcristofaro.com/) +* Steve Salkin +* [Kristopher Johnson](http://undefinedvalue.com/) +* [Kumar McMillan](https://twitter.com/kumar303) +* [Brannon Sherry](http://code-junkie.com) +* [Neo Innovation - Lean Consultancy](http://neo.com/) +* [Jeff Warner](http://www.stormysoftware.com) +* [Jeremy Walker](http://www.ihid.co.uk) +* [Michael Sanders](http://msanders.com) +* [Zulfiqar Ali](https://www.simplerses.com) +* [Josh Hepworth](http://friendsoftheweb.com) +* [Michael Dippery](http://monkey-robot.com/) +* [Jonathan Beavers](https://jon4than.com) +* [Jason Nourse](http://jasonnourse.com) +* [cj little](http://cjlittle.com) +* [Nicholas Mott](http://www.discovilante.com) +* [Jean-Luc Geering](http://www.ufirstgroup.com/) +* [Ingo Kampe](https://kreuzwerker.de/) +* [Jason Rasmussen](http://www.sourcefire.com) +* [Reni Margold](http://renimargold.com) +* [Jacopo](https://github.com/dedalusj) +* [Incremental Productions Ltd](https://www.incremental.co.uk/) +* [condero Aktiengesellschaft](http://www.condero.com) +* [Mintrus](http://mintrus.com) +* [Ezekiel Templin](http://zeke.templ.in/) +* [Matt Robinson](https://www.lazycat.org/) +* [Greg Kaufman](http://gregkaufman.com) +* [Chris Wilkes](https://github.com/cwilkes) +* [Maven Security Consulting](https://www.mavensecurity.com) +* [Christopher Vander Poel](http://www.wlvrn.com) +* [Weiyin LIANG](http://pyology.com) +* [Epic Awesome](https://epicawesome.co/) +* [Evan Oxfeld](https://twitter.com/evanoxfeld) +* [Alexander Lash](http://alexla.sh) +* [Ferran Selles](http://www.nulltrace.com) +* [Rick Companje](http://www.companje.nl) +* [Alexander Zubko](https://www.youtube.com/watch?v=jqxENMKaeCU) +* [Iain Beeston](https://iainbeeston.com/) +* [Geoff Bowers](https://www.daemon.com.au) +* [Logan Cox](http://lo5an.com) +* [Helmwind](http://helmwind.com) +* [JosĂ© Tiburcio Ribeiro Netto](http://mineiro.org) +* [Cloudier](http://www.cloudier.com) +* [Adam Merrifield](http://seydesign.com) +* [Alan Chiang](http://itsnotvalid.com) +* Ralf Norbert Sooth +* [Cameron Tod](https://camerontod.com) +* [Paul McLanahan](http://pmac.io) +* [Lance Ulmer](http://lanceulmer.com) +* [Thomas Jachmann](http://thomasjachmann.com) +* [Jonathan Foster](http://fostertheweb.com) +* [Diogo Neves](http://diogoneves.com) +* [Arvy](http://www.codingepiphany.com) +* [James Pellerano](http://jamespellerano.com) +* [Birger J. NordĂžlum](http://mindtooth.me) +* [Bob Saska](https://r35.net) +* [Michael McCarthy](https://github.com/mikeycmccarthy) +* [Scott Courtney](https://www.sinenomine.net/) +* [Courtney Wilburn](http://blog.cjwilburn.com) +* [Gregory Man](https://github.com/gregory-m) +* [Sean Porter](http://seanporter.com) +* [Jerome Glacken](http://www.jeromeglacken.com) +* Chris Severs +* [Joacim Löwgren](http://www.jorum.se) +* [Shawn Price](http://shawnprice.com/) +* [Dominick LoBraico](http://dominick.me) +* [Denis Wolf](https://deniswolf.net) + +These lovely people supported our Kickstarter by giving us ÂŁ5 or more: + +* Lasse Bang Mikkelsen +* Greg Leppert +* Peter Manser +* Edd Hannay +* Jonathan Halcrow +* Aaron Malone +* Jonic Linley +* richardjburton.com +* Lukas SpieĂ +* Alicia Cozine +* Tieg Zaharia +* Nicholas Friederich +* Jeremy Weathers +* Jed Meade +* Wayne Pan +* Christopher Wright +* Patrick Armstrong +* Lance Ivy +* Vaughan Thomas +* Paul Hoffman +* Chris Black +* Kevin Cupp +* Andrew Cornett +* Jörn Huxhorn +* Janosch Hildebrand +* Andrew Janke +* D. Kevin Stilwell Jr. +* Kent Holloway +* MichaĆ PluciĆski +* Martial Michel +* Jay McGavren +* Michael Salmon +* Olivier Saut +* Max Seelemann +* Frans van Camp +* Leif Bladt +* David Reynolds +* Ulrich Petri +* Justin Falcone +* Damien Klinnert +* Rob Stinogle +* Luke Campbell +* Stan Mazurek +* Chris van Es +* Kai Wells +* Kevin Clark +* Sven Aas +* David Kapp +* Sean Knox +* Peter Jaros +* Shaun Jackman +* Alex Koloskov +* Richard Eriksson +* Eric Wolter +* Stefan Daschek +* Joel Gerhold +* Rubens Altimari +* Adrian Sampson +* Mark Schabacker +* Alexey Popov +* Joan Wolkerstorfer +* Robbie Tingey +* Sittipon Simasanti +* Lucian Cesca +* Alpha Chen +* Adam Duracz +* Christoph Pojer +* Jason Wells +* Manuel Binna +* Tomek Paczkowski +* Jamie Oliver +* Hirotsugu Asari +* anasazy +* Mike Boers +* Brad Wright +* Max Shishkin +* Keaton Mowery +* Wes Hargrove +* Jon Austin +* Joey Stanford +* Giovanni Angoli +* Fukuball Lin +* orip +* Christian Maughan TegnĂ©r +* ChristianGeek +* Kevin Toppel +* Mark Rogerson +* Anna Gerber +* Matthew Billings +* Kevin Dew +* Pelle Wessman +* TimothĂ©e Peignier +* Andrea Lattuada +* Mirko Caserta +* Dan Drabik +* Ferdinand Salis-Samaden +* Rob Staenke +* Marko Soikkeli +* Alexander Tarmolov +* Adam Neuwirth +* Phillip Lawler +* Superbil +* Aaron Suggs +* Nikolaj Brandt Jensen +* Sven Lito +* Seth Fitzsimmons +* Jeroen Houtzager +* Daniel Kempkens +* kilsey +* Ioann Maria +* Alex Nelson +* Fergal Hainey +* KJA +* Tsz Ming WONG +* BalĂĄzs Pete +* RaĂșl Marcos Lorenzo +* Federico "sQuEE" Sun +* Christopher Gateley +* Mark S. C. Smith +* Tim O'Brien +* Joshua Conner +* Lucas Dohmen +* Joe VanAndel +* Gabriel Harrison +* Nicolas Crowell +* joch_n +* Ralph Reijs Nachum +* Kyle Miller +* Anonymous +* Sam Sellars +* Phil B. +* John Duprey +* mike smith +* carla capps +* Sergey Timoshin +* con-f-use +* Urban Blom +* Calle Englund +* Stephen Childs +* Ben Plantinga +* Dorian Kernytsky +* Michael Henretty +* Bill Rafferty +* Princess Lilian in Memoriam +* Shlok Datye +* Thierry Hayoz +* Mark Paschal +* Matt Vanderpol +* W. Evan Sheehan +* Kristian Söderholm +* Hunter Shedlock +* Iraquitan Cordeiro Filho +* Charlie Fulton +* Andrew Kent +* Andreas M. Nilsson +* Remon Georgy +* Rob Newman +* Gossie +* Ivy Tsai +* cmchap +* GaĂ«tan Gueraud +* Thomas Coudray +* Karl Thiebolt +* Suti +* shazow +* Keenan Brock +* Kyle T. Mandli +* Robert Anderson +* T.J. Simmons +* M Stallman +* @staticnull +* AsbjĂžrn Ulsberg +* Tobias Stehle +* Glenn Ian Baker +* Quintin Pan +* Matt White +* Hugo Vincent +* @lmjabreu +* Joe Sheehan +* Park Jaeku +* Matthew Mirande +* Arnaud +* Cyriel van 't End +* Robert Parini +* Fiann O'Hagan +* Dan Morrow +* Liam Jones +* Tony Fernandez +* Arizona Edwards +* Asaf Ary diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md new file mode 100644 index 000000000..d83118642 --- /dev/null +++ b/docs/Maintainer-Guidelines.md @@ -0,0 +1,124 @@ +# 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 seems reasonable. +- Add aliases. +- Ensure it is not an unreasonable dupe of anything that comes with macOS. +- Ensure it is not a library that can be installed with + [gem](https://en.wikipedia.org/wiki/RubyGems), + [cpan](https://en.wikipedia.org/wiki/Cpan) or + [pip](https://pip.pypa.io/en/stable/). +- Ensure that any dependencies are accurate and minimal. We don't need to + support every possible optional feature for the software. +- Use the GitHub squash & merge workflow where bottles aren't required. +- Use `brew pull` otherwise, which adds messages to auto-close pull requests and pull bottles built by BrewTestBot. +- Thank people for contributing. + +Checking dependencies 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. Disable X11 functionality by default. +For example, we build Wireshark, but not the heavy GTK/Qt GUI by default. + +Homebrew is about Unix software. Stuff that builds to an `.app` should +probably be in Homebrew Cask instead. + +### Naming +The name is the strictest item, because avoiding a later name change is +desirable. + +Choose a name thatâs the most common name for the project. +For example, we initially 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 as symlinks in `Aliases` in the tap root. 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 mostly donât allow versions in formula names (e.g. `bash4.rb`); these should +be in the `homebrew/versions` tap. (`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 should be done in the brew repo to preserve history & GPG commit signing, +and squash/merge via GitHub should be used for formulae where those formulae +don't need bottles or the change does not require new bottles to be pulled. +Otherwise, you should use `brew pull` (or `rebase`/`cherry-pick` contributions). + +Donât `rebase` until you finally `push`. Once `master` is 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 (e.g. 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. Ideally, request a `test do` block to test that +functionality is consistently available. + +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!). + +## Common âGotchasâ +1. [Ensure you have set your username and email address + properly](https://help.github.com/articles/setting-your-email-in-git/) +2. Sign off cherry-picks if you amended them, [GitX-dev](https://github.com/rowanj/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 + +### Duplicates +The main repository avoids duplicates as much as possible. The exception is +libraries that macOS provides but have bugs, and the bugs are fixed in a +newer version. Or libraries that macOS provides, but they are too old for +some other formula. The rest should be in the `homebrew/dupes` tap. + +Still determine if it possible to avoid the duplicate. Be thorough. Duped +libraries 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 duplicates anything ask another maintainer 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` \<â macOS 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. diff --git a/docs/Maintainers-Avoiding-Burnout.md b/docs/Maintainers-Avoiding-Burnout.md new file mode 100644 index 000000000..f3ba3e346 --- /dev/null +++ b/docs/Maintainers-Avoiding-Burnout.md @@ -0,0 +1,48 @@ +# Maintainers: Avoiding Burnout +**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 for everyone. + +# 1. Use Homebrew + +Maintainers of Homebrew should be using it regularly. This is partly because +you won't be a good maintainer unless you can put yourself in the shoes of our +users but also because you may decide to stop using Homebrew and at that point +you should also decide not to be a maintainer and find other things to work on. + +# 2. No Guilt About Leaving + +All maintainers can stop working on Homebrew at any time without any guilt or +explanation (like a job). We may still ask for your help with questions after +you leave but you are under no obligation to answer them. Like a job, if you +create a big mess and then leave you still have no obligations but we may think +less of you (or, realistically, probably just revert the problematic work). +Like a job, you should probably take a break from Homebrew at least a few times +a year. + +This also means contributors should be consumers. If an owner finds they are +not using a project in the real-world, they should reconsider their involvement +with the project. + +# 3. Prioritise Maintainers Over Users + +It's important to be user-focused but ultimately, as long as you follow #1 +above, Homebrew's minimum number of users will be the number of maintainers. +However, if Homebrew has no maintainers it will quickly become useless to all +users and the project will die. As a result, no user complaint, behaviour or +need takes priority over the burnout of maintainers. If users do not like the +direction of the project, the easiest way to influence it is to make +significant, high-quality code contributions and become a maintainer. + +# 4. Learn To Say No + +Homebrew gets a lot of feature requests, non-reproducible bug reports, usage +questions and PRs we won't accept. These should be closed out as soon as we +realise that they aren't going to be resolved or merged. This is kinder than +deciding this after a long period of review. Our issue tracker should reflect +work to be done. + +--- + +Thanks to https://gist.github.com/ryanflorence/124070e7c4b3839d4573 which influenced this document diff --git a/docs/Migrating-A-Formula-To-A-Tap.md b/docs/Migrating-A-Formula-To-A-Tap.md new file mode 100644 index 000000000..7bc984f84 --- /dev/null +++ b/docs/Migrating-A-Formula-To-A-Tap.md @@ -0,0 +1,8 @@ +# Migrating A Formula To A Tap +There are times when we may wish to migrate a formula from one tap into another tap. To do this: + +1. Create a pull request to the new tap adding the formula file as-is from the original tap. Fix any test failures that may occur due to the stricter requirements for new formulae than existing formula (e.g. `brew audit --strict` must pass for that formula). +2. Create a pull request to the original tap deleting the formula file and add it to `tap_migrations.json` with a commit message like `gv: migrating to homebrew/x11`. +3. Put a link for each pull request in the other pull request so the maintainers can merge them both at once. + +Congratulations, you've moved a formula to a tap! diff --git a/docs/New-Maintainer-Checklist.md b/docs/New-Maintainer-Checklist.md new file mode 100644 index 000000000..c59e1c341 --- /dev/null +++ b/docs/New-Maintainer-Checklist.md @@ -0,0 +1,50 @@ +# New Maintainer Checklist +**This is a guide used by existing maintainers to invite new maintainers. You might find it interesting but there's nothing here users should have to know.** + +So, there's someone who has been making consistently high-quality contributions to Homebrew for a long time and shown themselves able to make slightly more advanced contributions than just e.g. formula updates? Let's invite them to be a maintainer! + +First, send them the invitation email: + +``` +The Homebrew team and I really appreciate your help on issues, pull requests and +your contributions around $THEIR_CONTRIBUTIONS. + +We would like to invite you to have commit access. There are no obligations, +but we'd appreciate your continuing help in keeping on top of contributions. + +A few requests: + +- please make pull requests on any changes to core (i.e. non-formula) code or + any non-trivial (e.g. not a test or audit improvement or version bump) + changes to formulae code and don't merge them unless you get at least one +1 +- use `brew pull` and let it auto-close issues wherever possible (it may take + ~5m). When this isn't possible always use `git pull --rebase`, `git rebase` + and `git cherry-pick` rather than `git merge` and never use GitHub's "Merge + pull request" button. If in doubt, check with GitX that you've not + accidentally added merge commits +- still create your branches on your fork rather than in the main repository +- if still in doubt please ask for help and we'll help you out - these are + probably worth a read: + - https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Brew-Test-Bot-For-Core-Contributors.md + - https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Maintainer-Guidelines.md + - possibly everything else in the documentation + +How does that sound? + +Thanks for all your work so far! +``` + +If they accept, follow a few steps to get them set up: + +- [x] Invite them to the [**@Homebrew/maintainers** team](https://github.com/orgs/Homebrew/teams/maintainers) to give them write access to all repositories (but don't make them owners yet) +- [x] Ask them to sign up for a [Bintray](https://bintray.com) account and invite them to [Bintray's Homebrew organisation](https://bintray.com/homebrew/organization/edit/members) as a member (but not administrator access yet) so they can publish new bottles +- [x] Add them to the [Jenkins' GitHub Authorization Settings admin user names](https://bot.brew.sh/configureSecurity/) so they can adjust settings and restart jobs +- [x] Add them to the [Jenkins' GitHub Pull Request Builder admin list](https://bot.brew.sh/configure) to enable `@BrewTestBot test this please` for them +- [x] Invite them to the [`homebrew-dev` private maintainers mailing list](https://groups.google.com/forum/#!managemembers/homebrew-dev/invite) +- [x] Invite them to the [`machomebrew` private maintainers Slack](https://machomebrew.slack.com/admin/invites) +- [x] Add them to [Homebrew's README](https://github.com/Homebrew/brew/edit/master/README.md) +- [x] Encourage them to enable [GitHub's Two Factor Authentication](https://help.github.com/articles/about-two-factor-authentication/) + +After a few weeks/months with no problems consider making them [owners on the Homebrew GitHub organisation](https://github.com/orgs/Homebrew/people) and [administrators on Bintray](https://bintray.com/homebrew/organization/edit/members). + +Now sit back, relax and let the new maintainers handle more of our contributions. diff --git a/docs/Node-for-Formula-Authors.md b/docs/Node-for-Formula-Authors.md new file mode 100644 index 000000000..642a0f067 --- /dev/null +++ b/docs/Node-for-Formula-Authors.md @@ -0,0 +1,115 @@ +# Node for formula authors + +This document explains how to successfully use Node and npm in a Node module based Homebrew formula. + +# Running `npm install` + +Homebrew provides two helper methods in a `Language::Node` module, `std_npm_install_args` and `local_npm_install_args`. They both set up the correct environment for npm and return arguments for `npm install` for their specific use cases. Please use them instead of invoking `npm install` explicitly. The syntax for a standard Node module installation is: + +```ruby +system "npm", "install", *Language::Node.std_npm_install_args(libexec) +``` + +where `libexec` is the destination prefix (usually the `libexec` variable). + +# Download URL + +If the Node module is also available on the npm registry, we prefer npm hosted release tarballs over GitHub (or elsewhere) hosted source tarballs. The advantages of these tarballs are that they doesn't include the files from the `.npmignore` (such as tests) resulting in a smaller download size and that a possibly transpilation step is already done (e.g. no need to compile CoffeeScript files as a build step). + +The npm registry URLs have usually the format of: + +``` +https://registry.npmjs.org/<name>/-/<name>-<version>.tgz +``` + +Alternatively you could curl the JSON at `https://registry.npmjs.org/<name>` and look for the value of `versions[<version>].dist.tarball` for the correct tarball URL. + +# Dependencies + +Node modules, which are compatible with the latest Node version should declare a dependencies on the `node` formula. + +```ruby +depends_on "node" +``` + +If your formula requires to be executed with an older Node version you must vendor this older Node version as done in the [`kibana` formula](https://github.com/Homebrew/homebrew-core/blob/c6202f91a129e2f994d904f299a308cc6fbd58e5/Formula/kibana.rb). + +### Special requirements for native addons + +If your node module is a native addon or has a native addon somewhere in it's dependency tree you have to declare an additional dependency. Since the compilation of the native addon results in a invocation of `node-gyp` we need an additional build time dependency on `:python` (because gyp depends on Python 2.7). + +```ruby +depends_on :python => :build +``` + +Please also note, that such a formula would only be compatible with the same Node major version it originally was compiled with. This means that we need to revision every formula with a Node native addon with every major version bump of the `node` formula. To make sure we don't overlook your formula on a Node major version bump, write a meaningful test which would fail in such a case (invoked with an ABI incompatible Node version). + +# Installation + +Node modules should be installed to `libexec`. This prevents the Node modules from contaminating the global `node_modules`, which is important so that npm doesn't try to manage Homebrew-installed Node modules. + +In the following we distinguish between 2 type of Node module using formulae: +* formulae for standard Node modules compatible with npm's global module format which should use [`std_npm_install_args`](#installing-global-style-modules-with-std_npm_install_args-to-libexec) (like [`azure-cli`](https://github.com/Homebrew/homebrew-core/blob/d93fe9ba3bcc9071b699c8da4e7d733518d3337e/Formula/azure-cli.rb) or [`autocode`](https://github.com/Homebrew/homebrew-core/blob/1a670a6269e1e07f86683c2d164977c9bd8a3fb6/Formula/autocode.rb)) and +* formulae were the `npm install` step is only one of multiple not exclusively Node related install steps (not compatible with npm's global module format) which have to use [`local_npm_install_args`](#installing-module-dependencies-locally-with-local_npm_install_args) (like [`elixirscript`](https://github.com/Homebrew/homebrew-core/blob/ec1e40d37e81af63122a354f0101c377f6a4e66d/Formula/elixirscript.rb) or [`kibana`](https://github.com/Homebrew/homebrew-core/blob/c6202f91a129e2f994d904f299a308cc6fbd58e5/Formula/kibana.rb)) + +Both methods have in common, that they are setting the correct environment for using npm inside Homebrew up and returning the arguments for invoking `npm install` for their specific use cases. This includes fixing an important edge case with the npm cache (Caused by Homebrew's redirection of `$HOME` during the build and test process) by using our own custom `npm_cache` inside `HOMEBREW_CACHE`, which would otherwise result in very long build times and high disk space usage. + +To use them you have to require the Node language module at the beginning of your formula file with: + +```ruby +require "language/node" +``` + +### Installing global style modules with `std_npm_install_args` to libexec + +In your formula's `install` method, simply cd to the top level of your Node module if necessary and than use `system` to invoke `npm install` with `Language::Node.std_npm_install_args` like: + +```ruby +system "npm", "install", *Language::Node.std_npm_install_args(libexec) +``` + +This will install your Node module in npm's global module style with a custom prefix to `libexec`. All your modules executable will be automatically resolved by npm into `libexec/"bin"` for you, which is not symlinked into Homebrew's prefix. We need to make sure these are installed. Do this with we need to symlink all executables to `bin` with: + +```ruby +bin.install_symlink Dir["#{libexec}/bin/*"] +``` + +### Installing module dependencies locally with `local_npm_install_args` + +In your formula's `install` method, do any installation steps which need to be done before the `npm install` step and than cd to the top level of the included Node module. Then, use `system` with `Language::Node.local_npm_install_args` to invoke `npm install` like: + +```ruby +system "npm", "install", *Language::Node.local_npm_install_args +``` + +This will install all of your Node modules dependencies to your local build path. You can now continue with your build steps and take care of the installation into the Homebrew `prefix` by your own, following the [general Homebrew formula instructions](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Formula-Cookbook.md). + +# Example + +Installing a standard Node module based formula would look like this: + +```ruby +require "language/node" + +class Foo < Formula + desc "..." + homepage "..." + url "https://registry.npmjs.org/foo/-/foo-1.4.2.tgz" + sha256 "..." + + depends_on "node" + # uncomment if there is a native addon inside the dependency tree + # depends_on :python => :build + + def install + system "npm", "install", *Language::Node.std_npm_install_args(libexec) + bin.install_symlink Dir["#{libexec}/bin/*"] + end + + test do + # add a meaningful test here + end +end +``` + +For examples using the `local_npm_install_args` method look at the [`elixirscript`](https://github.com/Homebrew/homebrew-core/blob/ec1e40d37e81af63122a354f0101c377f6a4e66d/Formula/elixirscript.rb) or [`kibana`](https://github.com/Homebrew/homebrew-core/blob/c6202f91a129e2f994d904f299a308cc6fbd58e5/Formula/kibana.rb) formula. diff --git a/docs/Prose-Style-Guidelines.md b/docs/Prose-Style-Guidelines.md new file mode 100644 index 000000000..8c4f1d1f0 --- /dev/null +++ b/docs/Prose-Style-Guidelines.md @@ -0,0 +1,88 @@ +# Prose Style Guidelines + +This is a set of style and usage guidelines for Homebrew's prose documentation aimed at users, contributors, and maintainers (as opposed to executable computer code). It applies to documents like those in `share/doc/homebrew` in the `Homebrew/brew` repo, announcement emails, and other communications with the Homebrew community. + +This does not apply to any Ruby or other computer code. You can use it to inform technical documentation extracted from computer code, like embedded man pages, but it's just a suggestion there. + +## Goals and audience + +The primary goal of Homebrew's prose documents is communicating with its community of users and contributors. "Users" includes "contributors" here; wherever you see "users" you can substitute "users and contributors". + +Understandability trumps any particular style guideline. + +Users trump maintainers, except in specifically maintainer-focused documents. + +Homebrew's audience includes users with a wide range of education and experience, and users for whom English is not a native language. We aim to support as many of those users as feasible. + +We strive for "correct" but not "fancy" usage. Think newspaper article, not academic paper. + +This is a set of guidelines to be applied using human judgment, not a set of hard and fast rules. It is like [The Economist's Style Guide](http://www.economist.com/styleguide/introduction) or [Garner's Modern American Usage](https://en.wikipedia.org/wiki/Garner's_Modern_American_Usage). It is less like the [Ruby Style Guide](https://github.com/bbatsov/ruby-style-guide). All guidelines here are open to interpretation and discussion. 100% conformance to these guidelines is *not* a goal. + +The intent of this document is to help authors make decisions about clarity, style, and consistency. It is not to help settle arguments about who knows English better. Don't use this document to be a jerk. + +## Guidelines + +We prefer: + +### Style and usage + +* British/Commonwealth English over American English, in general +* "e.g." and "i.e.": Go ahead and use "e.g." or "i.e." instead of spelling them out. Don't worry about putting a comma after them. + * "e.g." means "for example"; "i.e." means "that is" +* Offset nontrivial subordinate clauses with commas + +### Personal pronouns + +* We respect all people's choice of personal pronouns +* Singular "they" when someone's gender is unknown +* Avoid gender-specific language when not necessary + +### Structure and markup + +* Sentence case in section headings, not Title Case +* Periods at the ends of list items where most items in that list are complete sentences +* More generally, parallel list item structure +* Capitalize all list items if you want, even if they're not complete sentences; just be consistent within each list, and preferably, throughout the whole page +* Use a subordinate list item instead of dropping a multi-sentence paragraph-long item into a list of sentence fragments +* Prefer Markdown over other markup formats unless their specific features are needed. +* GitHub flavored Markdown. GitHub's implementation is the standard, period. + +### Typographical conventions + +* Literal text in commands and code is styled in `fixed width font` +* Placeholders inside code snippets are marked up with `<...>` brackets + * e.g. `git remote add <my-user-name> https://github.com/<my-user-name>/homebrew-core.git` +* Names of commands like `git` and `brew` are styled in `fixed width font` +* No "$" with environment variables mentioned outside code snippets + * e.g. "Set `BLAH` to 5", not "Set `$BLAH` to 5" +* One space after periods, not two +* Capitalized proper nouns +* We do not defer to extensive nonstandard capitalization, typesetting, or other styling of brand names, aside from the normal capitalization of proper nouns and simple internal capitalization +* No "TM", ™, <sup>SM</sup>, ©, ®, or other explicit indicators of rights ownership or trademarks; we take these as understood when the brand name is mentioned +* Tap names like `homebrew/core` are styled in `fixed width font`. Repository names may be styled in either fixed width font like "`Homebrew/homebrew-core`", as links like "[Homebrew/homebrew-core](https://github.com/homebrew/homebrew-core)", or regular text like "Homebrew/homebrew-core", based on which looks best for a given use. + * But be consistent within a single document + * Capitalize repository names to match the user and repository names on GitHub. Keep tap names in lower case. +* Commas + * No Oxford commas + * Prefer a "loose" comma style: "when in doubt, leave it out" unless needed for clarity + +### Terminology, words, and word styling + +* "pull request", not "Pull Request" +* "check out" is the verb; "checkout" is the noun +* Spell out certain technical words + * "repository", not "repo" + * When abbreviating, introduce the abbreviation with the first usage in any document +* Some abbreviations (near-universally understood among our user base) are fine, though. + * "Mac" is fine; "Macintosh" isn't necessary +* "macOS" for all versions, "OS X" or "Mac OS X" when describing specific older versions +* "RuboCop", not "Rubocop" +* A pull request is made "on" a repository; that repository is "at" a URL + +## How to use these guidelines + +Refer to these guidelines to make decisions about style and usage in your own writing for Homebrew documents and communication. + +PRs that fix style and usage throughout a document or multiple documents are okay and encouraged. PRs for just one or two style changes are a bit much. + +Giving style and usage feedback on a PR or commit that involves documents is okay and encouraged. But keep in mind that these are just guidelines, and for any change, the author may have made a deliberate choice to break these rules in the interest of understandability or aesthetics. diff --git a/docs/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md new file mode 100644 index 000000000..716a3b359 --- /dev/null +++ b/docs/Python-for-Formula-Authors.md @@ -0,0 +1,237 @@ +# Introduction + +This document explains how to successfully use Python in a Homebrew formula. + +Homebrew draws a distinction between Python **applications** and Python **libraries**. The difference is that users generally do not care that applications are written in Python; it is unusual that a user would expect to be able to `import foo` after installing an application. Examples of applications are `ansible` and `jrnl`. + +Python libraries exist to be imported from other Python modules; they are often dependencies of Python applications. They are usually no more than incidentally useful from a Terminal.app command line. Examples of libraries are `py2cairo` and the bindings that are installed by `protobuf --with-python`. + +Bindings are a special case of libraries that allow Python code to interact with a library or application implemented in another language. + +Homebrew is happy to accept applications that are built in Python, whether the apps are available from PyPI or not. Homebrew generally won't accept libraries that can be installed correctly with `pip install foo`. Libraries that can be pip-installed but have several Homebrew dependencies may be appropriate for the [homebrew/python](https://github.com/Homebrew/homebrew-python) tap. Bindings may be installed for packages that provide them, especially if equivalent functionality isn't available through pip. + +# Running setup.py + +Homebrew provides a helper method, `Language::Python.setup_install_args`, which returns arguments for invoking setup.py. Please use it instead of invoking `setup.py` explicitly. The syntax is: + +```ruby +system "python", *Language::Python.setup_install_args(prefix) +``` + +where `prefix` is the destination prefix (usually `libexec` or `prefix`). + +# Python module dependencies + +In general, applications should unconditionally bundle all of their dependencies and libraries should install any unsatisfied dependencies; these strategies are discussed in depth in the following sections. + +In the rare instance that this proves impractical, you can specify a Python module as an external dependency using the syntax: + +```ruby +depends_on "numpy" => :python +``` + +Or if the import name is different from the module name: + +```ruby +depends_on "MacFSEvents" => [:python, "fsevents"] +``` + +If you submit a formula with this syntax to core, you may be asked to rewrite it as a `Requirement`. + +# Applications + +`ansible.rb` and `jrnl.rb` are good examples of applications that follow this advice. + +## Python declarations + +Applications that are compatible with Python 2 **should** use the Apple-provided system Python in /usr/bin on systems that provide Python 2.7. To do this, declare: +```ruby +depends_on :python if MacOS.version <= :snow_leopard +``` +No explicit Python dependency is needed on recent OS versions since /usr/bin is always in `PATH` for Homebrew formulĂŠ; on Leopard and older, the python in `PATH` is used if it's at least version 2.7, or else Homebrew's python is installed. + +FormulĂŠ for apps that require Python 3 **should** declare an unconditional dependency on `:python3`, which will cause the formula to use the first python3 discovered in `PATH` at install time (or install Homebrew's if there isn't one). These apps **must** work with the current Homebrew python3 formula. + +## Installing + +Applications should be installed into a Python [virtualenv](https://virtualenv.pypa.io/en/stable/) environment rooted in `libexec`. This prevents the app's Python modules from contaminating the system site-packages and vice versa. + +All of the Python module dependencies of the application (and their dependencies, recursively) should be declared as `resource`s in the formula and installed into the virtualenv, as well. Each dependency should be explicitly specified; please do not rely on `setup.py` or `pip` to perform automatic dependency resolution, for the [reasons described here](Acceptable-Formulae.md#we-dont-like-install-scripts-that-download-things). + +You can use [homebrew-pypi-poet](https://pypi.python.org/pypi/homebrew-pypi-poet) to help you write resource stanzas. To use it, set up a virtualenv and install your package and all its dependencies. Then, `pip install homebrew-pypi-poet` into the same virtualenv. Running `poet some_package` will generate the necessary resource stanzas. You can do this like: + +```bash +# Install virtualenvwrapper +$ brew install python +$ python -m pip install virtualenvwrapper +$ source $(brew --prefix)/bin/virtualenvwrapper.sh + +# Set up a temporary virtual environment +$ mktmpenv + +# Install the package of interest as well as homebrew-pypi-poet +$ pip install some_package homebrew-pypi-poet +$ poet some_package + +# Destroy the temporary virtualenv you just created +$ deactivate +``` + +Homebrew provides helper methods for instantiating and populating virtualenvs. You can use them by putting `include Language::Python::Virtualenv` on the `Formula` class definition, above `def install`. + +For most applications, all you will need to write is: + +```ruby +def install + virtualenv_install_with_resources +end +``` + +This is exactly the same as writing: + +```ruby +def install + # Create a virtualenv in `libexec`. If your app needs Python 3, make sure that + # `depends_on :python3` is declared, and use `virtualenv_create(libexec, "python3")`. + venv = virtualenv_create(libexec) + # Install all of the resources declared on the formula into the virtualenv. + venv.pip_install resources + # `link_scripts` takes a look at the virtualenv's bin directory before and + # after executing the block which is passed into it. If the block caused any + # new scripts to be written to the virtualenv's bin directory, link_scripts + # will symlink those scripts into the path given as its argument (here, the + # formula's `bin` directory in the Cellar.) + # `pip_install buildpath` will install the package that the formula points to, + # because buildpath is the location where the formula's tarball was unpacked. + venv.link_scripts(bin) { venv.pip_install buildpath } +end +``` + +## Example + +Installing a formula with dependencies will look like this: + +```ruby +class Foo < Formula + url ... + + resource "six" do + url "https://pypi.python.org/packages/source/s/six/six-1.9.0.tar.gz" + sha256 "e24052411fc4fbd1f672635537c3fc2330d9481b18c0317695b46259512c91d5" + end + + resource "parsedatetime" do + url "https://pypi.python.org/packages/source/p/parsedatetime/parsedatetime-1.4.tar.gz" + sha256 "09bfcd8f3c239c75e77b3ff05d782ab2c1aed0892f250ce2adf948d4308fe9dc" + end + + include Language::Python::Virtualenv + + def install + virtualenv_install_with_resources + end +end +``` + +You can also use the more verbose form and request that specific resources are installed: + +```ruby +def install + venv = virtualenv_create(libexec) + %w[six parsedatetime].each do |r| + venv.pip_install resource(r) + end + venv.link_scripts(bin) { venv.pip_install buildpath } +end +``` +in case you need to do different things for different resources. + +# Bindings + +To add an option to a formula to build Python bindings, use `depends_on :python => :recommended` and install the bindings conditionally on `build.with? "python"` in your `install` method. + +Python bindings should be optional because if the formula is bottled, any `:recommended` or mandatory dependencies on `:python` are always resolved by installing the Homebrew `python` formula, which will upset users that prefer to use the system Python. This is because we cannot generally create a binary package that works against both versions of Python. + +## Dependencies + +Bindings should follow the same advice for Python module dependencies as libraries; see below for more. + +## Installing bindings + +If the bindings are installed by invoking a `setup.py`, do something like: +```ruby +cd "source/python" do + system "python", *Language::Python.setup_install_args(prefix) +end +``` + +If the configure script takes a `--with-python` flag, it usually will not need extra help finding Python. + +If the `configure` and `make` scripts do not want to install into the Cellar, sometimes you can: + +1. Call `./configure --without-python` (or a similar named option) +1. `cd` into the directory containing the Python bindings +1. Call `setup.py` with `system` and `Language::Python.setup_install_args` (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.) + +# Libraries + +## Python declarations + +Libraries **should** declare a dependency on `:python` or `:python3` as appropriate, which will respectively cause the formula to use the first python or python3 discovered in `PATH` at install time. If a library supports both Python 2.x and Python 3.x, the `:python` dependency **should** be `:recommended` (i.e. built by default) and the :python3 dependency should be `:optional`. Python 2.x libraries **must** function when they are installed against either the system Python or Homebrew Python. + +FormulĂŠ that declare a dependency on `:python` will always be bottled against Homebrew's python, since we cannot in general build binary packages that can be imported from both Pythons. Users can add `--build-from-source` after `brew install` to compile against whichever python is in `PATH`. + +## Installing + +Libraries may be installed to `libexec` and added to `sys.path` by writing a .pth file (named like "homebrew-foo.pth") to the `prefix` site-packages. This simplifies the ensuing drama if pip is accidentally used to upgrade a Homebrew-installed package and prevents the accumulation of stale .pyc files in Homebrew's site-packages. + +Most formulae presently just install to `prefix`. + +## Dependencies + +The dependencies of libraries must be installed so that they are importable. The principle of minimum surprise suggests that installing a Homebrew library should not alter the other libraries in a user's sys.path. The best way to achieve this is to only install dependencies if they are not already installed. To minimize the potential for linking conflicts, dependencies should be installed to `libexec/"vendor"` and added to `sys.path` by writing a second .pth file (named like "homebrew-foo-dependencies.pth") to the `prefix` site-packages. + +The `matplotlib.rb` formula in homebrew-python deploys this strategy. + +# Further down the rabbit hole + +Additional commentary that explains why Homebrew does some of the things it does. + +## setuptools vs. distutils vs. pip + +Distutils is a module in the Python standard library that provides developers a basic package management API. Setuptools is a module distributed outside the standard library that extends distutils. It is a convention that Python packages provide a setup.py that calls the `setup()` function from either distutils or setuptools. + +Setuptools provides the `easy_install` command, which is an end-user package management tool that fetches and installs packages from PyPI, the Python Package Index. Pip is another, newer end-user package management tool, which is also provided outside the standard library. While pip supplants `easy_install`, pip does not replace the other functionality of the setuptools module. + +Distutils and pip use a "flat" installation hierarchy that installs modules as individual files under site-packages while `easy_install` installs zipped eggs to site-packages instead. + +Distribute (not to be confused with distutils) is an obsolete fork of setuptools. Distlib is a package maintained outside the standard library which is used by pip for some low-level packaging operations and is not relevant to most setup.py users. + +## What is `--single-version-externally-managed`? + +`--single-version-externally-managed` ("SVEM") is a setuptools-only [argument to setup.py install](https://pythonhosted.org/setuptools/setuptools.html#install-run-easy-install-or-old-style-installation). The primary effect of SVEM is to use distutils to perform the install instead of using setuptools' `easy_install`. + +`easy_install` does a few things that we need to avoid: + +* fetches and installs dependencies +* upgrades dependencies in sys.path in place +* writes .pth and site.py files which aren't useful for us and cause link conflicts + +setuptools requires that SVEM is used in conjunction with `--record`, which provides a list of files that can later be used to uninstall the package. We don't need or want this because Homebrew can manage uninstallation but since setuptools demands it we comply. The Homebrew convention is to call the record file "installed.txt". + +Detecting whether a `setup.py` uses `setup()` from setuptools or distutils is difficult, but we always need to pass this flag to setuptools-based scripts. `pip` faces the same problem that we do and forces `setup()` to use the setuptools version by loading a shim around `setup.py` that imports setuptools before doing anything else. Since setuptools monkey-patches distutils and replaces its `setup` function, this provides a single, consistent interface. We have borrowed this code and use it in `Language::Python.setup_install_args`. + + +## `--prefix` vs `--root` + +setup.py accepts a slightly bewildering array of installation options. The correct switch for Homebrew is `--prefix`, which automatically sets the `--install-foo` family of options using sane POSIX-y values. + +`--root` [is used](https://mail.python.org/pipermail/distutils-sig/2010-November/017099.html) when installing into a prefix that will not become part of the final installation location of the files, like when building a .rpm or binary distribution. When using a setup.py-based setuptools, `--root` has the side effect of activating `--single-version-externally-managed`. It is not safe to use `--root` with an empty `--prefix` because the `root` is removed from paths when byte-compiling modules. + +It is probably safe to use `--prefix` with `--root=/`, which should work with either setuptools or distutils-based setup.py's but is kinda ugly. + +## pip vs. setup.py + +[PEP 453](http://legacy.python.org/dev/peps/pep-0453/#recommendations-for-downstream-distributors) makes a recommendation to downstream distributors (us) that sdist tarballs should be installed with pip instead of by invoking setup.py directly. We do not do this because Apple's Python distribution does not include pip, so we can't assume that pip is available. We could do something clever to work around Apple's piplessness but the value proposition is not yet clear. diff --git a/docs/Querying-Brew.md b/docs/Querying-Brew.md new file mode 100644 index 000000000..84a2ba4eb --- /dev/null +++ b/docs/Querying-Brew.md @@ -0,0 +1,67 @@ +# Querying Brew +_In this document we will be using [jq](https://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=<version> (--all|--installed|<formula>)`: + Print a JSON representation of `<formula>`. Currently the only accepted value + for <version> 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/brew/blob/master/Library/Homebrew/formula.rb) + +(**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/docs/README.md b/docs/README.md new file mode 100644 index 000000000..4e95db81b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,33 @@ +# README +Homebrew installs the stuff you need that Apple didnât. + +- [Install Homebrew](Installation.md) +- [Frequently Asked Questions](FAQ.md) +- [Tips and Tricks](Tips-N'-Tricks.md) +- [Gems, Eggs and Perl Modules](Gems,-Eggs-and-Perl-Modules.md) +- [Homebrew and Python](Homebrew-and-Python.md) + +Please note: Homebrew is not 1.0 yet. Generally it works well, but when +it doesnât weâd hope you report the bug. +## Troubleshooting +First, please run `brew update` (twice) and `brew doctor`. + +Second, please read the [Troubleshooting Checklist](Troubleshooting.md). + +**If you donât follow these steps it will take us far longer to help you with +your problem.** + +However! Fixing build issues is easier than you think: try +`brew edit $FORMULA` and see how you fare. + +## Contributing +Read [CONTRIBUTING.md](/.github/CONTRIBUTING.md). + +### Community Forums +- [@MacHomebrew](https://twitter.com/MacHomebrew) +- [homebrew-discuss@googlegroups.com](mailto:homebrew-discuss@googlegroups.com) ([archive](https://groups.google.com/forum/#!forum/homebrew-discuss)) - subscribe by sending a mail to [homebrew-discuss+subscribe@googlegroups.com](mailto:homebrew-discuss+subscribe@googlegroups.com) +- [freenode.net\#machomebrew](irc://irc.freenode.net/#machomebrew) + +## Supporters +[A list of the awesome people who gave ÂŁ5 or more to our +Kickstarter](./Kickstarter-Supporters.md). diff --git a/docs/Rename-A-Formula.md b/docs/Rename-A-Formula.md new file mode 100644 index 000000000..efc7b8b11 --- /dev/null +++ b/docs/Rename-A-Formula.md @@ -0,0 +1,17 @@ +# Renaming a Formula + +Sometimes software and formulae need to be renamed. To rename a formula +you need to: + +1. Rename the formula file and its class to a new formula. The new name must meet all the usual rules of formula naming. Fix any test failures that may occur due to the stricter requirements for new formulae than existing formulae (i.e. `brew audit --strict` must pass for that formula). + +2. Create a pull request to the corresponding tap deleting the old formula file, adding the new formula file, and adding it to `formula_renames.json` with a commit message like `newack: renamed from ack`. Use the canonical name (e.g. `ack` instead of `user/repo/ack`). + + +A `formula_renames.json` example for a formula rename: + +```json +{ + "ack": "newack" +} +``` diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md new file mode 100644 index 000000000..e97f740ed --- /dev/null +++ b/docs/Tips-N'-Tricks.md @@ -0,0 +1,144 @@ +# Tips N' Tricks + +## Installing previous versions of formulae + +The preferred and supported method of installing specific versions of +formulae is to use the +[homebrew/versions](https://github.com/Homebrew/homebrew-versions) +tap. If the version youâre looking for isnât available, consider [opening a +pull request](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md)! + +### Installing directly from pull-requests + +You can browse pull requests https://github.com/Homebrew/homebrew-core/pulls +and install through the direct link. For example Python 3.3.0 pull request https://github.com/Homebrew/homebrew/pull/15199 + +```sh +brew install https://raw.github.com/dsr/homebrew/9b22d42f50fcbc5e52c764448b3ac002bc153bd7/Library/Formula/python3.rb +``` + +## Quickly remove something from /usr/local + +```sh +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! + +## Activate a previously installed version of a formula + +```sh +brew info $FORMULA +brew switch $FORMULA $VERSION +``` + +Use `brew info $FORMULA` to check what versions are installed but not currently activated, then `brew switch $FORMULA $VERSION` to activate the desired version. This can be useful if you would like to switch between versions of a formula. + +## Install into Homebrew without formulae + +```sh +./configure --prefix=/usr/local/Cellar/foo/1.2 && make && make install && brew link foo +``` + +## 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 <code>{{ formula +name }}-{{ version }}</code>. In the case of Erlang, this requires +renaming the file from <code>otp_src_R13B03</code> to +<code>erlang-R13B03</code>. + +`brew --cache -s erlang` will print the correct name of the cached +download. This means instead of manually renaming a formula, you can +run `mv the_tarball $(brew --cache -s $FORMULA)`. + +You can also pre-cache the download by using the command `brew fetch formula` which also displays the SHA256 value. 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), including at runtime: + +``` +http_proxy=http://<proxyhost>:<proxyport> brew install $FORMULA +``` + +### Proxy Authentication + +```sh +http_proxy=http://<user>:<password>@<proxyhost>:<proxyport> brew install $FORMULA +``` + +## Installing stuff without the Xcode-CLT + +```sh +$ 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) + +```sh +brew install --only-dependencies $FORMULA +``` + +## Interactive Homebrew Shell + +```sh +$ 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 + +```sh +export HOMEBREW_NO_EMOJI=1 +``` + +This sets the HOMEBREW_NO_EMOJI environment variable, causing Homebrew +to hide all emoji. + +The beer emoji can also be replaced with other character(s): + +```sh +export HOMEBREW_INSTALL_BADGE="âïž đž" +``` + +## Editor plugins + +### Sublime Text + +In Sublime Text 2/3, you can use Package Control to install +[Homebrew-formula-syntax](https://github.com/samueljohn/Homebrew-formula-syntax), +which adds highlighting for inline patches. + +### Vim + +[brew.vim](https://github.com/xu-cheng/brew.vim) adds highlighting to +inline patches in Vim. + +### Emacs + +[homebrew-mode](https://github.com/dunn/homebrew-mode) provides syntax +highlighting for inline patches as well as a number of helper functions +for editing formula files. + +### Atom + +[language-homebrew-formula](https://atom.io/packages/language-homebrew-formula) +adds highlighting and diff support (with the +[language-diff](https://atom.io/packages/language-diff) plugin). diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md new file mode 100644 index 000000000..4fc77d6cd --- /dev/null +++ b/docs/Troubleshooting.md @@ -0,0 +1,26 @@ +# Troubleshooting +**Run `brew update` (twice) and `brew doctor` *before* creating an issue!** + +When creating a formula-related issue please include the link output by running: + +```shell +brew gist-logs <formula> +``` + +## Check for common issues +* Run `brew update` (twice). +* Run `brew doctor` and fix all the warnings (**outdated Xcode/CLT and unbrewed dylibs are very likely to cause problems**). +* Read through the [Common Issues](Common-Issues.md). +* If youâre installing something Java-related, maybe you need to install Java (`brew cask install java`)? +* Check that **Command Line Tools for Xcode (CLT)** and/or **Xcode** are up to date. +* If things fail with permissions errors, check the permissions of `/usr/local`'s subdirectories. If youâre unsure what to do, you can `cd /usr/local && sudo chown -R $(whoami) bin etc include lib sbin share var Frameworks`. + +## Check to see if the issue has been reported +* Check the [issue tracker](https://github.com/Homebrew/homebrew-core/issues) to see if someone else has already reported the same issue. +* Make sure you check issues on the correct repository. If the formula that failed to build is part of a tap like [homebrew/science](https://github.com/Homebrew/homebrew-science) or [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes) check there instead. + +## Create an issue +0. Upload debugging information to a [Gist](https://gist.github.com): + - If you had a formula error: run `brew gist-logs <formula>` (where `<formula>` is the name of the formula that failed to build). + - If you encountered a non-formula bug: upload the output of `brew config` and `brew doctor` to a new [Gist](https://gist.github.com). +1. [Create a new issue](https://github.com/Homebrew/homebrew-core/issues/new) titled "\<formula name> failed to build on 10.x", where `<formula name>` is the name of the formula that failed to build, and `10.x` is the version of macOS you are using and including the link output by `brew gist-logs` diff --git a/docs/Xcode.md b/docs/Xcode.md new file mode 100644 index 000000000..98c5c6347 --- /dev/null +++ b/docs/Xcode.md @@ -0,0 +1,78 @@ +# Xcode +## Supported Xcode Versions +Homebrew supports and recommends the latest Xcode and/or Command Line +Tools available for your platform: + + macOS | 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.2 | 6.2 + 10.10 | 7.2.1 | 7.2 + 10.11 | 7.3.1 | 7.3 + 10.12 | 8.0 | 8.0 + + +## 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 + 6.2 | â | â | â | â | 6.0 (600.0.57) | 3.5 + 6.3 | â | â | â | â | 6.1 (602.0.49) | 3.6 + 6.3.1 | â | â | â | â | 6.1 (602.0.49) | 3.6 + 6.3.2 | â | â | â | â | 6.1 (602.0.53) | 3.6 + 6.4 | â | â | â | â | 6.1 (602.0.53) | 3.6 + 7.0 | â | â | â | â | 7.0 (700.0.72) | - + 7.0.1 | â | â | â | â | 7.0 (700.0.72) | - + 7.1 | â | â | â | â | 7.0 (700.1.76) | - + 7.1.1 | â | â | â | â | 7.0 (700.1.76) | - + 7.2 | â | â | â | â | 7.0 (700.1.81) | - + 7.2.1 | â | â | â | â | 7.0 (700.1.81) | - + 7.3 | â | â | â | â | 7.3 (703.0.29) | - + 7.3.1 | â | â | â | â | 7.3 (703.0.31) | - + 8.0 | â | â | â | â | 8.0 (800.0.38) | - + +## 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/docs/brew-tap.md b/docs/brew-tap.md new file mode 100644 index 000000000..624a83f33 --- /dev/null +++ b/docs/brew-tap.md @@ -0,0 +1,93 @@ +# brew tap + +`brew tap` adds more repos to the list of formulae that `brew` tracks, updates, +and installs from. By default, `tap` assumes that the repos come from GitHub, +but the command isn't limited to any one location. + +## The command + +* `brew tap` without arguments lists the currently tapped repositories. For + example: + +```bash +$ brew tap +homebrew/dupes +mistydemeo/tigerbrew +edavis/emacs +``` + +* `brew tap <user/repo>` makes a shallow clone of the repository at + https://github.com/user/repo. 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 details + about how `brew tap` handles the names of repositories.) + +* `brew tap <user/repo> <URL>` makes a shallow clone of the repository at URL. + Unlike the one-argument version, URL is not assumed to be GitHub, and it + doesn't have to be HTTP. Any location and any protocol that git can handle is + fine. + +* Add `--full` to either the one- or two-argument invocations above, and git + will make a complete clone rather than a shallow one. Full is the default for + Homebrew developers. + +* `brew tap --repair` migrates tapped formulae from symlink-based to + directory-based structure. (This should only need to be run once.) + +* `brew untap user/repo [user/repo user/repo ...]` removes the given taps. The + repos are deleted and `brew` will no longer be aware of its formulae. `brew + untap` can handle multiple removals at once. + +## Repository naming conventions and assumptions + +* On GitHub, your repository must be named `homebrew-something` in order to use + the one-argument form of `brew tap`. The prefix 'homebrew-' is not optional. + (The two-argument form doesn't have this limitation, but it forces you to + give the full URL explicitly.) + +* When you use `brew tap` on the command line, however, 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`. `brew` will automatically add + back the 'homebrew-' prefix whenever it's necessary. + +## Formula duplicate names + +If your tap contains a formula that is also present in [`homebrew/core`](https://github.com/Homebrew/homebrew-core), that's fine, +but it means that you must install it explicitly by default. + +If you would like to prioritize a tap over `homebrew/core`, you can use +`brew tap-pin username/repo` to pin the tap, +and use `brew tap-unpin username/repo` to revert the pin. + +Whenever a `brew install foo` command is issued, brew will find which formula +to use by searching in the following order: + +* Pinned taps +* Core formulae +* Other taps + +If you need a formula to be installed from a particular tap, you can use fully +qualified names to refer to them. + +For example, you can create a tap for an alternative `vim` formula. Without +pinning it, the behavior will be + +```bash +brew install vim # installs from homebrew/core +brew install username/repo/vim # installs from your custom repo +``` + +However if you pin the tap with `brew tap-pin username/repo`, you will need to +use `homebrew/core` to refer to the core formula. + +```bash +brew install vim # installs from your custom repo +brew install homebrew/core/vim # installs from homebrew/core +``` + +Do note that pinned taps are prioritized only when the formula name is directly +given by you. i.e., it will not influence formulae automatically installed as +dependencies. diff --git a/docs/brew.1.html b/docs/brew.1.html new file mode 100644 index 000000000..7e1e04e94 --- /dev/null +++ b/docs/brew.1.html @@ -0,0 +1,746 @@ +<div class='mp'> +<h2 id="NAME">NAME</h2> +<p class="man-name"> + <code>brew</code> - <span class="man-whatis">The missing package manager for macOS</span> +</p> + +<h2 id="SYNOPSIS">SYNOPSIS</h2> + +<p><code>brew</code> <code>--version</code><br /> +<code>brew</code> <var>command</var> [<code>--verbose</code>|<code>-v</code>] [<var>options</var>] [<var>formula</var>] ...</p> + +<h2 id="DESCRIPTION">DESCRIPTION</h2> + +<p>Homebrew is the easiest and most flexible way to install the UNIX tools Apple +didn't include with macOS.</p> + +<h2 id="ESSENTIAL-COMMANDS">ESSENTIAL COMMANDS</h2> + +<p>For the full command list, see the <a href="#COMMANDS" title="COMMANDS" data-bare-link="true">COMMANDS</a> section.</p> + +<p>With <code>--verbose</code> or <code>-v</code>, many commands print extra debugging information. Note that these flags should only appear after a command.</p> + +<dl> +<dt><code>install</code> <var>formula</var></dt><dd><p>Install <var>formula</var>.</p></dd> +<dt><code>remove</code> <var>formula</var></dt><dd><p>Uninstall <var>formula</var>.</p></dd> +<dt class="flush"><code>update</code></dt><dd><p>Fetch the newest version of Homebrew from GitHub using <code>git</code>(1).</p></dd> +<dt class="flush"><code>list</code></dt><dd><p>List all installed formulae.</p></dd> +<dt><code>search</code> <var>text</var>|<code>/</code><var>text</var><code>/</code></dt><dd><p>Perform a substring search of formula names for <var>text</var>. If <var>text</var> is +surrounded with slashes, then it is interpreted as a regular expression. +The search for <var>text</var> is extended online to some popular taps. +If no search term is given, all locally available formulae are listed.</p></dd> +</dl> + + +<h2 id="COMMANDS">COMMANDS</h2> + +<dl> +<dt><code>analytics</code> [<code>state</code>]</dt><dd><p>Display anonymous user behaviour analytics state. +Read more at <a href="https://git.io/brew-analytics" data-bare-link="true">https://git.io/brew-analytics</a>.</p></dd> +<dt><code>analytics</code> (<code>on</code>|<code>off</code>)</dt><dd><p>Turn on/off Homebrew's analytics.</p></dd> +<dt><code>analytics</code> <code>regenerate-uuid</code></dt><dd><p>Regenerate UUID used in Homebrew's analytics.</p></dd> +<dt><code>cat</code> <var>formula</var></dt><dd><p>Display the source to <var>formula</var>.</p></dd> +<dt><code>cleanup</code> [<code>--prune=</code><var>days</var>] [<code>--dry-run</code>] [<code>-s</code>] [<var>formulae</var>]</dt><dd><p>For all installed or specific formulae, remove any older versions from the +cellar. In addition, old downloads from the Homebrew download-cache are deleted.</p> + +<p>If <code>--prune=</code><var>days</var> is specified, remove all cache files older than <var>days</var>.</p> + +<p>If <code>--dry-run</code> or <code>-n</code> is passed, show what would be removed, but do not +actually remove anything.</p> + +<p>If <code>-s</code> is passed, scrubs the cache, removing downloads for even the latest +versions of formulae. Note downloads for any installed formulae will still not be +deleted. If you want to delete those too: <code>rm -rf $(brew --cache)</code></p></dd> +<dt><code>command</code> <var>cmd</var></dt><dd><p>Display the path to the file which is used when invoking <code>brew</code> <var>cmd</var>.</p></dd> +<dt><code>commands</code> [<code>--quiet</code> [<code>--include-aliases</code>]]</dt><dd><p>Show a list of built-in and external commands.</p> + +<p>If <code>--quiet</code> is passed, list only the names of commands without the header. +With <code>--include-aliases</code>, the aliases of internal commands will be included.</p></dd> +<dt class="flush"><code>config</code></dt><dd><p>Show Homebrew and system configuration useful for debugging. If you file +a bug report, you will likely be asked for this information if you do not +provide it.</p></dd> +<dt><code>deps</code> [<code>--1</code>] [<code>-n</code>] [<code>--union</code>] [<code>--full-name</code>] [<code>--installed</code>] [<code>--include-build</code>] [<code>--include-optional</code>] [<code>--skip-recommended</code>] <var>formulae</var></dt><dd><p>Show dependencies for <var>formulae</var>. When given multiple formula arguments, +show the intersection of dependencies for <var>formulae</var>.</p> + +<p>If <code>--1</code> is passed, only show dependencies one level down, instead of +recursing.</p> + +<p>If <code>-n</code> is passed, show dependencies in topological order.</p> + +<p>If <code>--union</code> is passed, show the union of dependencies for <var>formulae</var>, +instead of the intersection.</p> + +<p>If <code>--full-name</code> is passed, list dependencies by their full name.</p> + +<p>If <code>--installed</code> is passed, only list those dependencies that are +currently installed.</p> + +<p>By default, <code>deps</code> shows required and recommended dependencies for +<var>formulae</var>. To include the <code>:build</code> type dependencies, pass <code>--include-build</code>. +Similarly, pass <code>--include-optional</code> to include <code>:optional</code> dependencies. +To skip <code>:recommended</code> type dependencies, pass <code>--skip-recommended</code>.</p></dd> +<dt><code>deps</code> <code>--tree</code> [<var>filters</var>] (<var>formulae</var>|<code>--installed</code>)</dt><dd><p>Show dependencies as a tree. When given multiple formula arguments, output +individual trees for every formula.</p> + +<p>If <code>--installed</code> is passed, output a tree for every installed formula.</p> + +<p>The <var>filters</var> placeholder is any combination of options <code>--include-build</code>, +<code>--include-optional</code>, and <code>--skip-recommended</code> as documented above.</p></dd> +<dt><code>deps</code> [<var>filters</var>] (<code>--installed</code>|<code>--all</code>)</dt><dd><p>Show dependencies for installed or all available formulae. Every line of +output starts with the formula name, followed by a colon and all direct +dependencies of that formula.</p> + +<p>The <var>filters</var> placeholder is any combination of options <code>--include-build</code>, +<code>--include-optional</code>, and <code>--skip-recommended</code> as documented above.</p></dd> +<dt><code>desc</code> <var>formula</var></dt><dd><p>Display <var>formula</var>'s name and one-line description.</p></dd> +<dt><code>desc</code> [<code>-s</code>|<code>-n</code>|<code>-d</code>] <var>pattern</var></dt><dd><p>Search both name and description (<code>-s</code>), just the names (<code>-n</code>), or just the +descriptions (<code>-d</code>) for <code><pattern></code>. <code><pattern></code> is by default interpreted +as a literal string; if flanked by slashes, it is instead interpreted as a +regular expression. Formula descriptions are cached; the cache is created on +the first search, making that search slower than subsequent ones.</p></dd> +<dt><code>diy</code> [<code>--name=</code><var>name</var>] [<code>--version=</code><var>version</var>]</dt><dd><p>Automatically determine the installation prefix for non-Homebrew software.</p> + +<p>Using the output from this command, you can install your own software into +the Cellar and then link it into Homebrew's prefix with <code>brew link</code>.</p> + +<p>The options <code>--name=</code><var>name</var> and <code>--version=</code><var>version</var> each take an argument +and allow you to explicitly set the name and version of the package you are +installing.</p></dd> +<dt class="flush"><code>doctor</code></dt><dd><p>Check your system for potential problems. Doctor exits with a non-zero status +if any problems are found.</p></dd> +<dt><code>fetch</code> [<code>--force</code>] [<code>--retry</code>] [<code>-v</code>] [<code>--devel</code>|<code>--HEAD</code>] [<code>--deps</code>] [<code>--build-from-source</code>|<code>--force-bottle</code>] <var>formulae</var></dt><dd><p>Download the source packages for the given <var>formulae</var>. +For tarballs, also print SHA-256 checksums.</p> + +<p>If <code>--HEAD</code> or <code>--devel</code> is passed, fetch that version instead of the +stable version.</p> + +<p>If <code>-v</code> is passed, do a verbose VCS checkout, if the URL represents a VCS. +This is useful for seeing if an existing VCS cache has been updated.</p> + +<p>If <code>--force</code> is passed, remove a previously cached version and re-fetch.</p> + +<p>If <code>--retry</code> is passed, retry if a download fails or re-download if the +checksum of a previously cached version no longer matches.</p> + +<p>If <code>--deps</code> is passed, also download dependencies for any listed <var>formulae</var>.</p> + +<p>If <code>--build-from-source</code> is passed, download the source rather than a +bottle.</p> + +<p>If <code>--force-bottle</code> is passed, download a bottle if it exists for the current +version of macOS, even if it would not be used during installation.</p></dd> +<dt><code>gist-logs</code> [<code>--new-issue</code>|<code>-n</code>] <var>formula</var></dt><dd><p>Upload logs for a failed build of <var>formula</var> to a new Gist.</p> + +<p><var>formula</var> is usually the name of the formula to install, but it can be specified +in several different ways. See <a href="#SPECIFYING-FORMULAE" title="SPECIFYING FORMULAE" data-bare-link="true">SPECIFYING FORMULAE</a>.</p> + +<p>If <code>--new-issue</code> is passed, automatically create a new issue in the appropriate +GitHub repository as well as creating the Gist.</p> + +<p>If no logs are found, an error message is presented.</p></dd> +<dt class="flush"><code>home</code></dt><dd><p>Open Homebrew's own homepage in a browser.</p></dd> +<dt><code>home</code> <var>formula</var></dt><dd><p>Open <var>formula</var>'s homepage in a browser.</p></dd> +<dt><code>info</code> <var>formula</var></dt><dd><p>Display information about <var>formula</var>.</p></dd> +<dt><code>info</code> <code>--github</code> <var>formula</var></dt><dd><p>Open a browser to the GitHub History page for formula <var>formula</var>.</p> + +<p>To view formula history locally: <code>brew log -p <formula></code>.</p></dd> +<dt><code>info</code> <code>--json=</code><var>version</var> (<code>--all</code>|<code>--installed</code>|<var>formulae</var>)</dt><dd><p>Print a JSON representation of <var>formulae</var>. Currently the only accepted value +for <var>version</var> is <code>v1</code>.</p> + +<p>Pass <code>--all</code> to get information on all formulae, or <code>--installed</code> to get +information on all installed formulae.</p> + +<p>See the docs for examples of using the JSON: +<a href="https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying-Brew.md" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying-Brew.md</a></p></dd> +<dt><code>install</code> [<code>--debug</code>] [<code>--env=</code><var>std</var>|<var>super</var>] [<code>--ignore-dependencies</code>] [<code>--only-dependencies</code>] [<code>--cc=</code><var>compiler</var>] [<code>--build-from-source</code>] [<code>--devel</code>|<code>--HEAD</code>] [<code>--keep-tmp</code>] <var>formula</var></dt><dd><p>Install <var>formula</var>.</p> + +<p><var>formula</var> is usually the name of the formula to install, but it can be specified +in several different ways. See <a href="#SPECIFYING-FORMULAE" title="SPECIFYING FORMULAE" data-bare-link="true">SPECIFYING FORMULAE</a>.</p> + +<p>If <code>--debug</code> is passed and brewing fails, open an interactive debugging +session with access to IRB or a shell inside the temporary build directory.</p> + +<p>If <code>--env=std</code> is passed, use the standard build environment instead of superenv.</p> + +<p>If <code>--env=super</code> is passed, use superenv even if the formula specifies the +standard build environment.</p> + +<p>If <code>--ignore-dependencies</code> is passed, skip installing any dependencies of +any kind. If they are not already present, the formula will probably fail +to install.</p> + +<p>If <code>--only-dependencies</code> is passed, install the dependencies with specified +options but do not install the specified formula.</p> + +<p>If <code>--cc=</code><var>compiler</var> is passed, attempt to compile using <var>compiler</var>. +<var>compiler</var> should be the name of the compiler's executable, for instance +<code>gcc-4.2</code> for Apple's GCC 4.2, or <code>gcc-4.9</code> for a Homebrew-provided GCC +4.9.</p> + +<p>If <code>--build-from-source</code> or <code>-s</code> is passed, compile the specified <var>formula</var> from +source even if a bottle is provided. Dependencies will still be installed +from bottles if they are available.</p> + +<p>If <code>HOMEBREW_BUILD_FROM_SOURCE</code> is set, regardless of whether <code>--build-from-source</code> was +passed, then both <var>formula</var> and the dependencies installed as part of this process +are built from source even if bottles are available.</p> + +<p>If <code>--devel</code> is passed, and <var>formula</var> defines it, install the development version.</p> + +<p>If <code>--HEAD</code> is passed, and <var>formula</var> defines it, install the HEAD version, +aka master, trunk, unstable.</p> + +<p>If <code>--keep-tmp</code> is passed, the temporary files created during installation +are not deleted.</p> + +<p>To install a newer version of HEAD use +<code>brew rm <foo> && brew install --HEAD <foo></code>.</p></dd> +<dt><code>install</code> <code>--interactive</code> [<code>--git</code>] <var>formula</var></dt><dd><p>Download and patch <var>formula</var>, then open a shell. This allows the user to +run <code>./configure --help</code> and otherwise determine how to turn the software +package into a Homebrew formula.</p> + +<p>If <code>--git</code> is passed, Homebrew will create a Git repository, useful for +creating patches to the software.</p></dd> +<dt><code>irb</code> [<code>--examples</code>]</dt><dd><p>Enter the interactive Homebrew Ruby shell.</p> + +<p>If <code>--examples</code> is passed, several examples will be shown.</p></dd> +<dt class="flush"><code>leaves</code></dt><dd><p>Show installed formulae that are not dependencies of another installed formula.</p></dd> +<dt><code>ln</code>, <code>link</code> [<code>--overwrite</code>] [<code>--dry-run</code>] [<code>--force</code>] <var>formula</var></dt><dd><p>Symlink all of <var>formula</var>'s installed files into the Homebrew prefix. This +is done automatically when you install formulae but can be useful for DIY +installations.</p> + +<p>If <code>--overwrite</code> is passed, Homebrew will delete files which already exist in +the prefix while linking.</p> + +<p>If <code>--dry-run</code> or <code>-n</code> is passed, Homebrew will list all files which would +be linked or which would be deleted by <code>brew link --overwrite</code>, but will not +actually link or delete any files.</p> + +<p>If <code>--force</code> is passed, Homebrew will allow keg-only formulae to be linked.</p></dd> +<dt><code>linkapps</code> [<code>--local</code>] [<var>formulae</var>]</dt><dd><p>Find installed formulae that provide <code>.app</code>-style macOS apps and symlink them +into <code>/Applications</code>, allowing for easier access.</p> + +<p>If no <var>formulae</var> are provided, all of them will have their apps symlinked.</p> + +<p>If provided, <code>--local</code> will symlink them into the user's <code>~/Applications</code> +directory instead of the system directory.</p></dd> +<dt><code>list</code>, <code>ls</code> [<code>--full-name</code>]</dt><dd><p>List all installed formulae. If <code>--full-name</code> is passed, print formulae +with fully-qualified names. If <code>--full-name</code> is not passed, any other +options (e.g. <code>-t</code>) are passed to <code>ls</code> which produces the actual output.</p></dd> +<dt><code>list</code>, <code>ls</code> <code>--unbrewed</code></dt><dd><p>List all files in the Homebrew prefix not installed by Homebrew.</p></dd> +<dt><code>list</code>, <code>ls</code> [<code>--versions</code> [<code>--multiple</code>]] [<code>--pinned</code>] [<var>formulae</var>]</dt><dd><p>List the installed files for <var>formulae</var>. Combined with <code>--verbose</code>, recursively +list the contents of all subdirectories in each <var>formula</var>'s keg.</p> + +<p>If <code>--versions</code> is passed, show the version number for installed formulae, +or only the specified formulae if <var>formulae</var> are given. With <code>--multiple</code>, +only show formulae with multiple versions installed.</p> + +<p>If <code>--pinned</code> is passed, show the versions of pinned formulae, or only the +specified (pinned) formulae if <var>formulae</var> are given. +See also <code>pin</code>, <code>unpin</code>.</p></dd> +<dt><code>log</code> [<var>git-log-options</var>] <var>formula</var> ...</dt><dd><p>Show the git log for the given formulae. Options that <code>git-log</code>(1) +recognizes can be passed before the formula list.</p></dd> +<dt><code>migrate</code> [<code>--force</code>] <var>formulae</var></dt><dd><p>Migrate renamed packages to new name, where <var>formulae</var> are old names of +packages.</p> + +<p>If <code>--force</code> is passed, then treat installed <var>formulae</var> and passed <var>formulae</var> +like if they are from same taps and migrate them anyway.</p></dd> +<dt><code>missing</code> [<var>formulae</var>]</dt><dd><p>Check the given <var>formulae</var> for missing dependencies. If no <var>formulae</var> are +given, check all installed brews.</p></dd> +<dt><code>options</code> [<code>--compact</code>] (<code>--all</code>|<code>--installed</code>|<var>formulae</var>)</dt><dd><p>Display install options specific to <var>formulae</var>.</p> + +<p>If <code>--compact</code> is passed, show all options on a single line separated by +spaces.</p> + +<p>If <code>--all</code> is passed, show options for all formulae.</p> + +<p>If <code>--installed</code> is passed, show options for all installed formulae.</p></dd> +<dt><code>outdated</code> [<code>--quiet</code>|<code>--verbose</code>|<code>--json=v1</code>] [<code>--fetch-HEAD</code>]</dt><dd><p>Show formulae that have an updated version available.</p> + +<p>By default, version information is displayed in interactive shells, and +suppressed otherwise.</p> + +<p>If <code>--quiet</code> is passed, list only the names of outdated brews (takes +precedence over <code>--verbose</code>).</p> + +<p>If <code>--verbose</code> is passed, display detailed version information.</p> + +<p>If <code>--json=</code><var>version</var> is passed, the output will be in JSON format. The only +valid version is <code>v1</code>.</p> + +<p>If <code>--fetch-HEAD</code> is passed, fetch the upstream repository to detect if +the HEAD installation of the formula is outdated. Otherwise, the +repository's HEAD will be checked for updates when a new stable or devel +version has been released.</p></dd> +<dt><code>pin</code> <var>formulae</var></dt><dd><p>Pin the specified <var>formulae</var>, preventing them from being upgraded when +issuing the <code>brew upgrade</code> command. See also <code>unpin</code>.</p></dd> +<dt><code>postinstall</code> <var>formula</var></dt><dd><p>Rerun the post-install steps for <var>formula</var>.</p></dd> +<dt><code>prune</code> [<code>--dry-run</code>]</dt><dd><p>Remove dead symlinks from the Homebrew prefix. This is generally not +needed, but can be useful when doing DIY installations. Also remove broken +app symlinks from <code>/Applications</code> and <code>~/Applications</code> that were previously +created by <code>brew linkapps</code>.</p> + +<p>If <code>--dry-run</code> or <code>-n</code> is passed, show what would be removed, but do not +actually remove anything.</p></dd> +<dt><code>reinstall</code> <var>formula</var></dt><dd><p>Uninstall and then install <var>formula</var>.</p></dd> +<dt><code>search</code>, <code>-S</code></dt><dd><p>Display all locally available formulae for brewing (including tapped ones). +No online search is performed if called without arguments.</p></dd> +<dt><code>search</code> [<code>--desc</code>] <var>text</var>|<code>/</code><var>text</var><code>/</code></dt><dd><p>Perform a substring search of formula names for <var>text</var>. If <var>text</var> is +surrounded with slashes, then it is interpreted as a regular expression. +The search for <var>text</var> is extended online to some popular taps.</p> + +<p>If <code>--desc</code> is passed, browse available packages matching <var>text</var> including a +description for each.</p></dd> +<dt><code>search</code> (<code>--debian</code>|<code>--fedora</code>|<code>--fink</code>|<code>--macports</code>|<code>--opensuse</code>|<code>--ubuntu</code>) <var>text</var></dt><dd><p>Search for <var>text</var> in the given package manager's list.</p></dd> +<dt><code>sh</code> [<code>--env=std</code>]</dt><dd><p>Instantiate a Homebrew build environment. Uses our years-battle-hardened +Homebrew build logic to help your <code>./configure && make && make install</code> +or even your <code>gem install</code> succeed. Especially handy if you run Homebrew +in an Xcode-only configuration since it adds tools like <code>make</code> to your <code>PATH</code> +which otherwise build-systems would not find.</p></dd> +<dt><code>style</code> [<code>--fix</code>] [<code>--display-cop-names</code>] [<var>files</var>|<var>taps</var>|<var>formulae</var>]</dt><dd><p>Check formulae or files for conformance to Homebrew style guidelines.</p> + +<p><var>formulae</var> and <var>files</var> may not be combined. If both are omitted, style will run +style checks on the whole Homebrew <code>Library</code>, including core code and all +formulae.</p> + +<p>If <code>--fix</code> is passed, style violations will be automatically fixed using +RuboCop's <code>--auto-correct</code> feature.</p> + +<p>If <code>--display-cop-names</code> is passed, the RuboCop cop name for each violation +is included in the output.</p> + +<p>Exits with a non-zero status if any style violations are found.</p></dd> +<dt><code>switch</code> <var>name</var> <var>version</var></dt><dd><p>Symlink all of the specific <var>version</var> of <var>name</var>'s install to Homebrew prefix.</p></dd> +<dt class="flush"><code>tap</code></dt><dd><p>List all installed taps.</p></dd> +<dt><code>tap</code> [<code>--full</code>] <var>user</var><code>/</code><var>repo</var> [<var>URL</var>]</dt><dd><p>Tap a formula repository.</p> + +<p>With <var>URL</var> unspecified, taps a formula repository from GitHub using HTTPS. +Since so many taps are hosted on GitHub, this command is a shortcut for +<code>tap <user>/<repo> https://github.com/<user>/homebrew-<repo></code>.</p> + +<p>With <var>URL</var> specified, taps a formula repository from anywhere, using +any transport protocol that <code>git</code> handles. The one-argument form of <code>tap</code> +simplifies but also limits. This two-argument command makes no +assumptions, so taps can be cloned from places other than GitHub and +using protocols other than HTTPS, e.g., SSH, GIT, HTTP, FTP(S), RSYNC.</p> + +<p>By default, the repository is cloned as a shallow copy (<code>--depth=1</code>), but +if <code>--full</code> is passed, a full clone will be used. To convert a shallow copy +to a full copy, you can retap passing <code>--full</code> without first untapping.</p> + +<p><code>tap</code> is re-runnable and exits successfully if there's nothing to do. +However, retapping with a different <var>URL</var> will cause an exception, so first +<code>untap</code> if you need to modify the <var>URL</var>.</p></dd> +<dt><code>tap</code> <code>--repair</code></dt><dd><p>Migrate tapped formulae from symlink-based to directory-based structure.</p></dd> +<dt><code>tap</code> <code>--list-official</code></dt><dd><p>List all official taps.</p></dd> +<dt><code>tap</code> <code>--list-pinned</code></dt><dd><p>List all pinned taps.</p></dd> +<dt><code>tap-info</code></dt><dd><p>Display a brief summary of all installed taps.</p></dd> +<dt><code>tap-info</code> (<code>--installed</code>|<var>taps</var>)</dt><dd><p>Display detailed information about one or more <var>taps</var>.</p> + +<p>Pass <code>--installed</code> to display information on all installed taps.</p></dd> +<dt><code>tap-info</code> <code>--json=</code><var>version</var> (<code>--installed</code>|<var>taps</var>)</dt><dd><p>Print a JSON representation of <var>taps</var>. Currently the only accepted value +for <var>version</var> is <code>v1</code>.</p> + +<p>Pass <code>--installed</code> to get information on installed taps.</p> + +<p>See the docs for examples of using the JSON: +<a href="https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying-Brew.md" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying-Brew.md</a></p></dd> +<dt><code>tap-pin</code> <var>tap</var></dt><dd><p>Pin <var>tap</var>, prioritizing its formulae over core when formula names are supplied +by the user. See also <code>tap-unpin</code>.</p></dd> +<dt><code>tap-unpin</code> <var>tap</var></dt><dd><p>Unpin <var>tap</var> so its formulae are no longer prioritized. See also <code>tap-pin</code>.</p></dd> +<dt><code>uninstall</code>, <code>rm</code>, <code>remove</code> [<code>--force</code>] <var>formula</var></dt><dd><p>Uninstall <var>formula</var>.</p> + +<p>If <code>--force</code> is passed, and there are multiple versions of <var>formula</var> +installed, delete all installed versions.</p></dd> +<dt><code>unlink</code> [<code>--dry-run</code>] <var>formula</var></dt><dd><p>Remove symlinks for <var>formula</var> from the Homebrew prefix. This can be useful +for temporarily disabling a formula: +<code>brew unlink foo && commands && brew link foo</code>.</p> + +<p>If <code>--dry-run</code> or <code>-n</code> is passed, Homebrew will list all files which would +be unlinked, but will not actually unlink or delete any files.</p></dd> +<dt><code>unlinkapps</code> [<code>--local</code>] [<code>--dry-run</code>] [<var>formulae</var>]</dt><dd><p>Remove symlinks created by <code>brew linkapps</code> from <code>/Applications</code>.</p> + +<p>If no <var>formulae</var> are provided, all linked apps will be removed.</p> + +<p>If provided, <code>--local</code> will remove symlinks from the user's <code>~/Applications</code> +directory instead of the system directory.</p> + +<p>If <code>--dry-run</code> or <code>-n</code> is passed, Homebrew will list all symlinks which +would be removed, but will not actually delete any files.</p></dd> +<dt><code>unpack</code> [<code>--git</code>|<code>--patch</code>] [<code>--destdir=</code><var>path</var>] <var>formulae</var></dt><dd><p>Unpack the source files for <var>formulae</var> into subdirectories of the current +working directory. If <code>--destdir=</code><var>path</var> is given, the subdirectories will +be created in the directory named by <code><path></code> instead.</p> + +<p>If <code>--patch</code> is passed, patches for <var>formulae</var> will be applied to the +unpacked source.</p> + +<p>If <code>--git</code> is passed, a Git repository will be initalized in the unpacked +source. This is useful for creating patches for the software.</p></dd> +<dt><code>unpin</code> <var>formulae</var></dt><dd><p>Unpin <var>formulae</var>, allowing them to be upgraded by <code>brew upgrade</code>. See also +<code>pin</code>.</p></dd> +<dt><code>untap</code> <var>tap</var></dt><dd><p>Remove a tapped repository.</p></dd> +<dt><code>update</code> [<code>--merge</code>] [<code>--force</code>]</dt><dd><p>Fetch the newest version of Homebrew and all formulae from GitHub using +<code>git</code>(1).</p> + +<p>If <code>--merge</code> is specified then <code>git merge</code> is used to include updates +(rather than <code>git rebase</code>).</p> + +<p>If <code>--force</code> is specified then always do a slower, full update check even +if unnecessary.</p></dd> +<dt><code>upgrade</code> [<var>install-options</var>] [<code>--cleanup</code>] [<code>--fetch-HEAD</code>] [<var>formulae</var>]</dt><dd><p>Upgrade outdated, unpinned brews.</p> + +<p>Options for the <code>install</code> command are also valid here.</p> + +<p>If <code>--cleanup</code> is specified then remove previously installed <var>formula</var> version(s).</p> + +<p>If <code>--fetch-HEAD</code> is passed, fetch the upstream repository to detect if +the HEAD installation of the formula is outdated. Otherwise, the +repository's HEAD will be checked for updates when a new stable or devel +version has been released.</p> + +<p>If <var>formulae</var> are given, upgrade only the specified brews (but do so even +if they are pinned; see <code>pin</code>, <code>unpin</code>).</p></dd> +<dt><code>uses</code> [<code>--installed</code>] [<code>--recursive</code>] [<code>--include-build</code>] [<code>--include-optional</code>] [<code>--skip-recommended</code>] [<code>--devel</code>|<code>--HEAD</code>] <var>formulae</var></dt><dd><p>Show the formulae that specify <var>formulae</var> as a dependency. When given +multiple formula arguments, show the intersection of formulae that use +<var>formulae</var>.</p> + +<p>Use <code>--recursive</code> to resolve more than one level of dependencies.</p> + +<p>If <code>--installed</code> is passed, only list installed formulae.</p> + +<p>By default, <code>uses</code> shows all formulae that specify <var>formulae</var> as a required +or recommended dependency. To include the <code>:build</code> type dependencies, pass +<code>--include-build</code>. Similarly, pass <code>--include-optional</code> to include <code>:optional</code> +dependencies. To skip <code>:recommended</code> type dependencies, pass <code>--skip-recommended</code>.</p> + +<p>By default, <code>uses</code> shows usages of <code>formula</code> by stable builds. To find +cases where <code>formula</code> is used by development or HEAD build, pass +<code>--devel</code> or <code>--HEAD</code>.</p></dd> +<dt class="flush"><code>--cache</code></dt><dd><p>Display Homebrew's download cache. See also <code>HOMEBREW_CACHE</code>.</p></dd> +<dt><code>--cache</code> <var>formula</var></dt><dd><p>Display the file or directory used to cache <var>formula</var>.</p></dd> +<dt><code>--cellar</code></dt><dd><p>Display Homebrew's Cellar path. <em>Default:</em> <code>$(brew --prefix)/Cellar</code>, or if +that directory doesn't exist, <code>$(brew --repository)/Cellar</code>.</p></dd> +<dt><code>--cellar</code> <var>formula</var></dt><dd><p>Display the location in the cellar where <var>formula</var> would be installed, +without any sort of versioned directory as the last path.</p></dd> +<dt class="flush"><code>--env</code></dt><dd><p>Show a summary of the Homebrew build environment.</p></dd> +<dt><code>--prefix</code></dt><dd><p>Display Homebrew's install path. <em>Default:</em> <code>/usr/local</code></p></dd> +<dt><code>--prefix</code> <var>formula</var></dt><dd><p>Display the location in the cellar where <var>formula</var> is or would be installed.</p></dd> +<dt><code>--repository</code></dt><dd><p>Display where Homebrew's <code>.git</code> directory is located. For standard installs, +the <code>prefix</code> and <code>repository</code> are the same directory.</p></dd> +<dt><code>--repository</code> <var>user</var><code>/</code><var>repo</var></dt><dd><p>Display where tap <var>user</var><code>/</code><var>repo</var>'s directory is located.</p></dd> +<dt><code>--version</code></dt><dd><p>Print the version number of Homebrew to standard output and exit.</p></dd> +</dl> + + +<h2 id="DEVELOPER-COMMANDS">DEVELOPER COMMANDS</h2> + +<dl> +<dt><code>audit</code> [<code>--strict</code>] [<code>--online</code>] [<code>--new-formula</code>] [<code>--display-cop-names</code>] [<code>--display-filename</code>] [<var>formulae</var>]</dt><dd><p>Check <var>formulae</var> for Homebrew coding style violations. This should be +run before submitting a new formula.</p> + +<p>If no <var>formulae</var> are provided, all of them are checked.</p> + +<p>If <code>--strict</code> is passed, additional checks are run, including RuboCop +style checks.</p> + +<p>If <code>--online</code> is passed, additional slower checks that require a network +connection are run.</p> + +<p>If <code>--new-formula</code> is passed, various additional checks are run that check +if a new formula is eligable for Homebrew. This should be used when creating +new formulae and implies <code>--strict</code> and <code>--online</code>.</p> + +<p>If <code>--display-cop-names</code> is passed, the RuboCop cop name for each violation +is included in the output.</p> + +<p>If <code>--display-filename</code> is passed, every line of output is prefixed with the +name of the file or formula being audited, to make the output easy to grep.</p> + +<p><code>audit</code> exits with a non-zero status if any errors are found. This is useful, +for instance, for implementing pre-commit hooks.</p></dd> +<dt><code>bottle</code> [<code>--verbose</code>] [<code>--no-rebuild</code>] [<code>--keep-old</code>] [<code>--skip-relocation</code>] [<code>--root-url=<root_url></code>] [<code>--force-core-tap</code>]:</dt><dd><p></p></dd> +<dt><code>bottle</code> <code>--merge</code> [<code>--no-commit</code>] [<code>--keep-old</code>] [<code>--write</code>]:</dt><dd><p></p> + +<p>Generate a bottle (binary package) from a formula installed with +<code>--build-bottle</code>.</p></dd> +<dt><code>bump-formula-pr</code> [<code>--devel</code>] [<code>--dry-run</code>] [<code>--audit</code>|<code>--strict</code>] <code>--url=</code><var>url</var> <code>--sha256=</code><var>sha-256</var> <var>formula</var>:</dt><dd><p></p></dd> +<dt><code>bump-formula-pr</code> [<code>--devel</code>] [<code>--dry-run</code>] [<code>--audit</code>|<code>--strict</code>] <code>--tag=</code><var>tag</var> <code>--revision=</code><var>revision</var> <var>formula</var></dt><dd><p>Creates a pull request to update the formula with a new url or a new tag.</p> + +<p>If a <var>url</var> is specified, the <var>sha-256</var> checksum of the new download must +also be specified.</p> + +<p>If a <var>tag</var> is specified, the git commit <var>revision</var> corresponding to that +tag must also be specified.</p> + +<p>If <code>--devel</code> is passed, bump the development rather than stable version. +The development spec must already exist.</p> + +<p>If <code>--dry-run</code> is passed, print what would be done rather than doing it.</p> + +<p>If <code>--audit</code> is passed, run <code>brew audit</code> before opening the PR.</p> + +<p>If <code>--strict</code> is passed, run <code>brew audit --strict</code> before opening the PR.</p> + +<p>Note that this command cannot be used to transition a formula from a +url-and-sha256 style specification into a tag-and-revision style +specification, nor vice versa. It must use whichever style specification +the preexisting formula already uses.</p></dd> +<dt><code>create</code> <var>URL</var> [<code>--autotools</code>|<code>--cmake</code>] [<code>--no-fetch</code>] [<code>--set-name</code> <var>name</var>] [<code>--set-version</code> <var>version</var>] [<code>--tap</code> <var>user</var><code>/</code><var>repo</var>]</dt><dd><p>Generate a formula for the downloadable file at <var>URL</var> and open it in the editor. +Homebrew will attempt to automatically derive the formula name +and version, but if it fails, you'll have to make your own template. The <code>wget</code> +formula serves as a simple example. For the complete API have a look at</p> + +<p><a href="http://www.rubydoc.info/github/Homebrew/brew/master/Formula" data-bare-link="true">http://www.rubydoc.info/github/Homebrew/brew/master/Formula</a></p> + +<p>If <code>--autotools</code> is passed, create a basic template for an Autotools-style build. +If <code>--cmake</code> is passed, create a basic template for a CMake-style build.</p> + +<p>If <code>--no-fetch</code> is passed, Homebrew will not download <var>URL</var> to the cache and +will thus not add the SHA256 to the formula for you.</p> + +<p>The options <code>--set-name</code> and <code>--set-version</code> each take an argument and allow +you to explicitly set the name and version of the package you are creating.</p> + +<p>The option <code>--tap</code> takes a tap as its argument and generates the formula in +the specified tap.</p></dd> +<dt class="flush"><code>edit</code></dt><dd><p>Open all of Homebrew for editing.</p></dd> +<dt><code>edit</code> <var>formula</var></dt><dd><p>Open <var>formula</var> in the editor.</p></dd> +<dt><code>linkage</code> [<code>--test</code>] [<code>--reverse</code>] <var>formula-name</var></dt><dd><p>Checks the library links of an installed formula.</p> + +<p>Only works on installed formulae. An error is raised if it is run on +uninstalled formulae.</p> + +<p>If <code>--test</code> is passed, only display missing libraries and exit with a +non-zero exit code if any missing libraries were found.</p> + +<p>If <code>--reverse</code> is passed, print the dylib followed by the binaries +which link to it for each library the keg references.</p></dd> +<dt class="flush"><code>man</code></dt><dd><p>Generate Homebrew's manpages.</p></dd> +</dl> + + +<p> <code>pull</code> [<code>--bottle</code>] [<code>--bump</code>] [<code>--clean</code>] [<code>--ignore-whitespace</code>] [<code>--resolve</code>] [<code>--branch-okay</code>] [<code>--no-pbcopy</code>] [<code>--no-publish</code>] <var>patch-source</var> [<var>patch-source</var>]</p> + +<pre><code>Gets a patch from a GitHub commit or pull request and applies it to Homebrew. +Optionally, installs the formulae changed by the patch. + +Each <patch-source> may be one of: + * The ID number of a PR (Pull Request) in the homebrew/core GitHub + repository + * The URL of a PR on GitHub, using either the web page or API URL + formats. In this form, the PR may be on Homebrew/brew, + Homebrew/homebrew-core or any tap. + * The URL of a commit on GitHub + * A "http://bot.brew.sh/job/..." string specifying a testing job ID +</code></pre> + +<p> If <code>--bottle</code> was passed, handle bottles, pulling the bottle-update + commit and publishing files on Bintray. + If <code>--bump</code> was passed, for one-formula PRs, automatically reword + commit message to our preferred format. + If <code>--clean</code> was passed, do not rewrite or otherwise modify the + commits found in the pulled PR. + If <code>--ignore-whitespace</code> was passed, silently ignore whitespace + discrepancies when applying diffs. + If <code>--resolve</code> was passed, when a patch fails to apply, leave in + progress and allow user to + resolve, instead of aborting. + If <code>--branch-okay</code> was passed, do not warn if pulling to a branch + besides master (useful for testing). + If <code>--no-pbcopy</code> was passed, do not copy anything to the system + If <code>--no-publish</code> was passed, do not publish bottles to Bintray.</p> + +<dl> +<dt><code>tap_readme</code> [<code>-v</code>] <var>name</var></dt><dd><p>Generate the README.md file for a new tap.</p></dd> +<dt><code>test</code> [<code>--devel</code>|<code>--HEAD</code>] [<code>--debug</code>] [<code>--keep-tmp</code>] <var>formula</var></dt><dd><p>A few formulae provide a test method. <code>brew test</code> <var>formula</var> runs this +test method. There is no standard output or return code, but it should +generally indicate to the user if something is wrong with the installed +formula.</p> + +<p>To test the development or head version of a formula, use <code>--devel</code> or +<code>--HEAD</code>.</p> + +<p>If <code>--debug</code> is passed and the test fails, an interactive debugger will be +launched with access to IRB or a shell inside the temporary test directory.</p> + +<p>If <code>--keep-tmp</code> is passed, the temporary files created for the test are +not deleted.</p> + +<p>Example: <code>brew install jruby && brew test jruby</code></p></dd> +<dt><code>tests</code> [<code>-v</code>] [<code>--coverage</code>] [<code>--generic</code>] [<code>--no-compat</code>] [<code>--only=</code><test_script/test_method>] [<code>--seed</code> <var>seed</var>] [<code>--trace</code>] [<code>--online</code>] [<code>--official-cmd-taps</code>]</dt><dd><p>Run Homebrew's unit and integration tests.</p></dd> +<dt><code>update-test</code> [<code>--commit=<sha1></code>] [<code>--before=<date></code>] [<code>--keep-tmp</code>]</dt><dd><p>Runs a test of <code>brew update</code> with a new repository clone.</p> + +<p>If no arguments are passed, use <code>origin/master</code> as the start commit.</p> + +<p>If <code>--commit=<sha1></code> is passed, use <code><sha1></code> as the start commit.</p> + +<p>If <code>--before=<date></code> is passed, use the commit at <code><date></code> as the +start commit.</p> + +<p>If <code>--keep-tmp</code> is passed, retain the temporary directory containing +the new repository clone.</p></dd> +</dl> + + +<h2 id="EXTERNAL-COMMANDS">EXTERNAL COMMANDS</h2> + +<p>Homebrew, like <code>git</code>(1), supports external commands. These are executable +scripts that reside somewhere in the <code>PATH</code>, named <code>brew-</code><var>cmdname</var> or +<code>brew-</code><var>cmdname</var><code>.rb</code>, which can be invoked like <code>brew</code> <var>cmdname</var>. This allows you +to create your own commands without modifying Homebrew's internals.</p> + +<p>Instructions for creating your own commands can be found in the docs: +<a href="https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/External-Commands.md" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/External-Commands.md</a></p> + +<h2 id="SPECIFYING-FORMULAE">SPECIFYING FORMULAE</h2> + +<p>Many Homebrew commands accept one or more <var>formula</var> arguments. These arguments +can take several different forms:</p> + +<dl> +<dt>The name of a formula</dt><dd><p>e.g. <code>git</code>, <code>node</code>, <code>wget</code>.</p></dd> +<dt>The fully-qualified name of a tapped formula</dt><dd><p>Sometimes a formula from a tapped repository may conflict with one in +<code>homebrew/core</code>. +You can still access these formulae by using a special syntax, e.g. +<code>homebrew/dupes/vim</code> or <code>homebrew/versions/node4</code>.</p></dd> +<dt>An arbitrary URL</dt><dd><p>Homebrew can install formulae via URL, e.g. +<code>https://raw.github.com/Homebrew/homebrew-core/master/Formula/git.rb</code>. +The formula file will be cached for later use.</p></dd> +</dl> + + +<h2 id="ENVIRONMENT">ENVIRONMENT</h2> + +<dl> +<dt><code>AWS_ACCESS_KEY_ID</code>, <code>AWS_SECRET_ACCESS_KEY</code></dt><dd><p>When using the <code>S3</code> download strategy, Homebrew will look in +these variables for access credentials (see +<a href="https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-environment" data-bare-link="true">https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-environment</a> +to retrieve these access credentials from AWS). If they are not set, +the <code>S3</code> download strategy will download with a public +(unsigned) URL.</p></dd> +<dt class="flush"><code>BROWSER</code></dt><dd><p>If set, and <code>HOMEBREW_BROWSER</code> is not, use <code>BROWSER</code> as the web browser +when opening project homepages.</p></dd> +<dt class="flush"><code>EDITOR</code></dt><dd><p>If set, and <code>HOMEBREW_EDITOR</code> and <code>VISUAL</code> are not, use <code>EDITOR</code> as the text editor.</p></dd> +<dt class="flush"><code>GIT</code></dt><dd><p>When using Git, Homebrew will use <code>GIT</code> if set, +a Homebrew-built Git if installed, or the system-provided binary.</p> + +<p>Set this to force Homebrew to use a particular git binary.</p></dd> +<dt><code>HOMEBREW_BOTTLE_DOMAIN</code></dt><dd><p>If set, instructs Homebrew to use the given URL as a download mirror for bottles.</p></dd> +<dt><code>HOMEBREW_ARTIFACT_DOMAIN</code></dt><dd><p>If set, instructs Homebrew to use the given URL as a download mirror for bottles and binaries.</p></dd> +<dt><code>HOMEBREW_AUTO_UPDATE_SECS</code></dt><dd><p>If set, Homebrew will only check for autoupdates once per this seconds interval.</p> + +<p><em>Default:</em> <code>60</code>.</p></dd> +<dt><code>HOMEBREW_BROWSER</code></dt><dd><p>If set, uses this setting as the browser when opening project homepages, +instead of the OS default browser.</p></dd> +<dt><code>HOMEBREW_BUILD_FROM_SOURCE</code></dt><dd><p>If set, instructs Homebrew to compile from source even when a formula +provides a bottle. This environment variable is intended for use by +Homebrew developers. Please do not file issues if you encounter errors when +using this environment variable.</p></dd> +<dt><code>HOMEBREW_CACHE</code></dt><dd><p>If set, instructs Homebrew to use the given directory as the download cache.</p> + +<p><em>Default:</em> <code>~/Library/Caches/Homebrew</code>.</p></dd> +<dt><code>HOMEBREW_CURL_VERBOSE</code></dt><dd><p>If set, Homebrew will pass <code>--verbose</code> when invoking <code>curl</code>(1).</p></dd> +<dt><code>HOMEBREW_DEBUG</code></dt><dd><p>If set, any commands that can emit debugging information will do so.</p></dd> +<dt><code>HOMEBREW_DEBUG_INSTALL</code></dt><dd><p>When <code>brew install -d</code> or <code>brew install -i</code> drops into a shell, +<code>HOMEBREW_DEBUG_INSTALL</code> will be set to the name of the formula being +brewed.</p></dd> +<dt><code>HOMEBREW_DEBUG_PREFIX</code></dt><dd><p>When <code>brew install -d</code> or <code>brew install -i</code> drops into a shell, +<code>HOMEBREW_DEBUG_PREFIX</code> will be set to the target prefix in the Cellar +of the formula being brewed.</p></dd> +<dt><code>HOMEBREW_DEVELOPER</code></dt><dd><p>If set, Homebrew will tweak behaviour to be more relevant for Homebrew +developers (active or budding) e.g. turning warnings into errors.</p></dd> +<dt><code>HOMEBREW_EDITOR</code></dt><dd><p>If set, Homebrew will use this editor when editing a single formula, or +several formulae in the same directory.</p> + +<p><em>Note:</em> <code>brew edit</code> will open all of Homebrew as discontinuous files and +directories. TextMate can handle this correctly in project mode, but many +editors will do strange things in this case.</p></dd> +<dt><code>HOMEBREW_FORCE_VENDOR_RUBY</code></dt><dd><p>If set, Homebrew will always use its vendored, relocatable Ruby 2.0 version +even if the system version of Ruby is >=2.0.</p></dd> +<dt><code>HOMEBREW_GITHUB_API_TOKEN</code></dt><dd><p>A personal access token for the GitHub API, which you can create at +<a href="https://github.com/settings/tokens" data-bare-link="true">https://github.com/settings/tokens</a>. If set, GitHub will allow you a +greater number of API requests. See +<a href="https://developer.github.com/v3/#rate-limiting" data-bare-link="true">https://developer.github.com/v3/#rate-limiting</a> for more information. +Homebrew uses the GitHub API for features such as <code>brew search</code>.</p> + +<p><em>Note:</em> Homebrew doesn't require permissions for any of the scopes.</p></dd> +<dt><code>HOMEBREW_LOGS</code></dt><dd><p>If set, Homebrew will use the given directory to store log files.</p></dd> +<dt><code>HOMEBREW_MAKE_JOBS</code></dt><dd><p>If set, instructs Homebrew to use the value of <code>HOMEBREW_MAKE_JOBS</code> as +the number of parallel jobs to run when building with <code>make</code>(1).</p> + +<p><em>Default:</em> the number of available CPU cores.</p></dd> +<dt><code>HOMEBREW_NO_ANALYTICS</code></dt><dd><p>If set, Homebrew will not send analytics. See: <a href="https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Analytics.md#analytics" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Analytics.md#analytics</a></p></dd> +<dt><code>HOMEBREW_NO_AUTO_UPDATE</code></dt><dd><p>If set, Homebrew will not auto-update before running <code>brew install</code>, +<code>brew upgrade</code> or <code>brew tap</code>.</p></dd> +<dt><code>HOMEBREW_NO_EMOJI</code></dt><dd><p>If set, Homebrew will not print the <code>HOMEBREW_INSTALL_BADGE</code> on a +successful build.</p> + +<p><em>Note:</em> Homebrew will only try to print emoji on Lion or newer.</p></dd> +<dt><code>HOMEBREW_NO_INSECURE_REDIRECT</code></dt><dd><p>If set, Homebrew will not permit redirects from secure HTTPS +to insecure HTTP.</p> + +<p>While ensuring your downloads are fully secure, this is likely +to cause from-source Sourceforge, some GNU & GNOME based +formulae to fail to download.</p></dd> +<dt><code>HOMEBREW_NO_GITHUB_API</code></dt><dd><p>If set, Homebrew will not use the GitHub API for e.g searches or +fetching relevant issues on a failed install.</p></dd> +<dt><code>HOMEBREW_INSTALL_BADGE</code></dt><dd><p>Text printed before the installation summary of each successful build. +Defaults to the beer emoji.</p></dd> +<dt><code>HOMEBREW_SVN</code></dt><dd><p>When exporting from Subversion, Homebrew will use <code>HOMEBREW_SVN</code> if set, +a Homebrew-built Subversion if installed, or the system-provided binary.</p> + +<p>Set this to force Homebrew to use a particular <code>svn</code> binary.</p></dd> +<dt><code>HOMEBREW_TEMP</code></dt><dd><p>If set, instructs Homebrew to use <code>HOMEBREW_TEMP</code> as the temporary directory +for building packages. This may be needed if your system temp directory and +Homebrew Prefix are on different volumes, as macOS has trouble moving +symlinks across volumes when the target does not yet exist.</p> + +<p>This issue typically occurs when using FileVault or custom SSD +configurations.</p></dd> +<dt><code>HOMEBREW_VERBOSE</code></dt><dd><p>If set, Homebrew always assumes <code>--verbose</code> when running commands.</p></dd> +<dt class="flush"><code>VISUAL</code></dt><dd><p>If set, and <code>HOMEBREW_EDITOR</code> is not, use <code>VISUAL</code> as the text editor.</p></dd> +</dl> + + +<h2 id="USING-HOMEBREW-BEHIND-A-PROXY">USING HOMEBREW BEHIND A PROXY</h2> + +<p>Homebrew uses several commands for downloading files (e.g. <code>curl</code>, <code>git</code>, <code>svn</code>). +Many of these tools can download via a proxy. It's common for these tools +to read proxy parameters from environment variables.</p> + +<p>For the majority of cases setting <code>http_proxy</code> is enough. You can set this in +your shell profile, or you can use it before a brew command:</p> + +<pre><code>http_proxy=http://<host>:<port> brew install foo +</code></pre> + +<p>If your proxy requires authentication:</p> + +<pre><code>http_proxy=http://<user>:<password>@<host>:<port> brew install foo +</code></pre> + +<h2 id="SEE-ALSO">SEE ALSO</h2> + +<p>Homebrew Documentation: <a href="https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/</a></p> + +<p><code>git</code>(1), <code>git-log</code>(1)</p> + +<h2 id="AUTHORS">AUTHORS</h2> + +<p>Homebrew's lead maintainer is Mike McQuaid.</p> + +<p>Homebrew's current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Tomasz Pajor, Baptiste Fontaine, Zhiming Wang, Brett Koonce, ilovezfs, Martin Afanasjew, Uladzislau Shablinski, Dominyk Tiller, Tim Smith and Alex Dunn.</p> + +<p>Former maintainers with significant contributions include Jack Nagel, Adam Vandenberg, Max Howell and Homebrew's creator: Max Howell.</p> + +<h2 id="BUGS">BUGS</h2> + +<p>See our issues on GitHub:</p> + +<ul> +<li><p>Homebrew/brew <a href="https://github.com/Homebrew/brew/issues" data-bare-link="true">https://github.com/Homebrew/brew/issues</a></p></li> +<li><p>Homebrew/homebrew-core <a href="https://github.com/Homebrew/homebrew-core/issues" data-bare-link="true">https://github.com/Homebrew/homebrew-core/issues</a></p></li> +</ul> + + +</div> diff --git a/docs/images/analytics.png b/docs/images/analytics.png Binary files differnew file mode 100644 index 000000000..d13725d15 --- /dev/null +++ b/docs/images/analytics.png diff --git a/docs/images/brew-test-bot-failed-jenkins.png b/docs/images/brew-test-bot-failed-jenkins.png Binary files differnew file mode 100644 index 000000000..bdfa8205f --- /dev/null +++ b/docs/images/brew-test-bot-failed-jenkins.png diff --git a/docs/images/brew-test-bot-failed-pr.png b/docs/images/brew-test-bot-failed-pr.png Binary files differnew file mode 100644 index 000000000..2487ac446 --- /dev/null +++ b/docs/images/brew-test-bot-failed-pr.png diff --git a/docs/images/brew-test-bot-failed-test.png b/docs/images/brew-test-bot-failed-test.png Binary files differnew file mode 100644 index 000000000..0820910e7 --- /dev/null +++ b/docs/images/brew-test-bot-failed-test.png diff --git a/docs/images/brew-test-bot-passed-jenkins.png b/docs/images/brew-test-bot-passed-jenkins.png Binary files differnew file mode 100644 index 000000000..be0467581 --- /dev/null +++ b/docs/images/brew-test-bot-passed-jenkins.png diff --git a/docs/images/brew-test-bot-passed-pr.png b/docs/images/brew-test-bot-passed-pr.png Binary files differnew file mode 100644 index 000000000..06acd5880 --- /dev/null +++ b/docs/images/brew-test-bot-passed-pr.png diff --git a/docs/images/brew-test-bot-triggered-pr.png b/docs/images/brew-test-bot-triggered-pr.png Binary files differnew file mode 100644 index 000000000..3643dcdbb --- /dev/null +++ b/docs/images/brew-test-bot-triggered-pr.png |
