Skip to content
Snippets Groups Projects
Commit ab4d1a15 authored by EricFromCanada's avatar EricFromCanada
Browse files

docs: grammar edits, sentence-case secondary headings 

Also changes some heading levels so only one primary
heading appears per page.
parent aa260cb0
No related branches found
No related tags found
No related merge requests found
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 243 additions and 334 deletions
docs/Acceptable-Formulae.md
+ 8
− 8
View file @ ab4d1a15
...@@ -53,19 +53,19 @@ Because that circumvents our hash-checks, makes finding/fixing bugs ...@@ -53,19 +53,19 @@ Because that circumvents our hash-checks, makes finding/fixing bugs
harder, often breaks patches and disables the caching. Almost always you harder, often breaks patches and disables the caching. Almost always you
can add a resource to the formula file to handle the can add a resource to the formula file to handle the
separate download and then the installer script will not attempt to load 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 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. point it to the downloaded archive in order to avoid loading.
### We don’t like binary formulae ### We don’t like binary formulae
Our policy is that formulae in the core repository Our policy is that formulae in the core repository
([homebrew/core](https://github.com/Homebrew/homebrew-core)) must be open-source ([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). and either built from source or produce cross-platform binaries (e.g. Java).
Binary-only formulae should go to Binary-only formulae should go to
[Homebrew Cask](https://github.com/caskroom/homebrew-cask). [Homebrew Cask](https://github.com/caskroom/homebrew-cask).
### Stable versions ### Stable versions
Formulae in the core repository must have a stable version tagged by Formulae in the core repository must have a stable version tagged by
the upstream project. Tarballs are preferred to git checkouts, and the upstream project. Tarballs are preferred to Git checkouts, and
tarballs should include the version in the filename whenever possible. tarballs should include the version in the filename whenever possible.
We don’t accept software without a tagged version because they regularly break We don’t accept software without a tagged version because they regularly break
...@@ -78,9 +78,9 @@ etc. ...@@ -78,9 +78,9 @@ etc.
If not, then put bindings in the formula they bind to. This is more 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 useful to people. Just install the stuff! Having to faff around with
foo-ruby foo-perl etc. sucks. foo-ruby, foo-perl etc. sucks.
### Niche (or self-submitted) Stuff<a name="Niche_Stuff"></a> ### Niche (or self-submitted) stuff
The software in question must be: The software in question must be:
* maintained (e.g. upstream is still making new releases) * maintained (e.g. upstream is still making new releases)
...@@ -94,9 +94,9 @@ get maintained and partly because we have to draw the line somewhere. ...@@ -94,9 +94,9 @@ 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. 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! Don’t forget Homebrew is all Git underneath! Maintain your own tap if you have to!
There may be exceptions to these rules in the main repository, we may 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. 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 Please trust that we need to use our discretion based on our experience
running a package manager. running a package manager.
...@@ -110,5 +110,5 @@ Make it build a command-line tool or a library. ...@@ -110,5 +110,5 @@ Make it build a command-line tool or a library.
### Sometimes there are exceptions ### Sometimes there are exceptions
Even if all criteria are met we may not accept the formula. Even if all criteria are met we may not accept the formula.
Documentation tends to lag behind current decision-making. Although some Documentation tends to lag behind current decision-making. Although some
rejections may seem arbitrary or strange they are based from years of rejections may seem arbitrary or strange they are based on years of
experience making Homebrew work acceptably for our users. experience making Homebrew work acceptably for our users.
docs/Analytics.md
+ 16
− 16
View file @ ab4d1a15
...@@ -5,29 +5,29 @@ Homebrew has begun gathering anonymous aggregate user behaviour analytics and re ...@@ -5,29 +5,29 @@ Homebrew has begun gathering anonymous aggregate user behaviour analytics and re
## Why? ## 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: 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. - 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. - 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? ## What?
Homebrew's analytics record some shared information for every event: 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 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 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) - 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) - 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) - If 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 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 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) - 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: 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`) - 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 `install` event category and the Homebrew formula from a non-private GitHub tap you have requested to install plus 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 the formulae that need fixing 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 `event` hit type with the `BuildError` event category and 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` - an `exception` hit type with the `exception` event category and 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. 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 from 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: 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:
...@@ -39,7 +39,7 @@ As far as we can tell it would be impossible for Google to match the randomly ge ...@@ -39,7 +39,7 @@ As far as we can tell it would be impossible for Google to match the randomly ge
Homebrew's analytics are sent throughout Homebrew's execution to Google Analytics over HTTPS. Homebrew's analytics are sent throughout Homebrew's execution to Google Analytics over HTTPS.
## Who? ## Who?
Homebrew's analytics are accessible to Homebrew's current maintainers. Contact @mikemcquaid if you are a maintainer and need access. Homebrew's analytics are accessible to Homebrew's current maintainers. Contact @MikeMcQuaid if you are a maintainer and need access.
## How? ## How?
The code is viewable in [analytics.rb](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb) and [analytics.sh](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. The code is viewable in [analytics.rb](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb) and [analytics.sh](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.
......
docs/Bottles.md
+ 10
− 10
View file @ ab4d1a15
...@@ -3,9 +3,9 @@ ...@@ -3,9 +3,9 @@
Bottles 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. Bottles 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.
## Usage ## 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`. 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 so 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`. 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 during installation (bottles are all compiled with default options), if the bottle is not up to date (e.g. lacking a checksum) or if the bottle's `cellar` is not `:any` nor equal to the current `HOMEBREW_CELLAR`.
## Creation ## 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). 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).
...@@ -13,7 +13,7 @@ Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md). This happens mo ...@@ -13,7 +13,7 @@ Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md). This happens mo
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! 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!
## Format ## 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). 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) ## Bottle DSL (Domain Specific Language)
Bottles have a DSL to be used in formulae which is contained in the `bottle do ... end` block. Bottles have a DSL to be used in formulae which is contained in the `bottle do ... end` block.
...@@ -48,25 +48,25 @@ By default this is omitted and the Homebrew default bottle URL root is used. Thi ...@@ -48,25 +48,25 @@ By default this is omitted and the Homebrew default bottle URL root is used. Thi
### Cellar (`cellar`) ### Cellar (`cellar`)
Optionally contains the value of `HOMEBREW_CELLAR` in which the bottles were built. 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` 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 (`prefix`) ### Prefix (`prefix`)
Optionally contains the value of `HOMEBREW_PREFIX` in which the bottles were built. 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. See description of `cellar`. When `cellar` is `:any` or `:any_skip_relocation` the prefix should be omitted.
### Rebuild version (`rebuild`) ### Rebuild version (`rebuild`)
Optionally contains the rebuild version of the bottle. 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. 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.
### Checksum (`sha256`) ### Checksum (`sha256`)
Contains the SHA-256 of bottle for a particular version of macOS. Contains the SHA-256 hash of a bottle for a particular version of macOS.
## Formula DSL ## Formula DSL
Additionally there is a method available in the formula DSL. Additionally there is a method available in the formula DSL.
### Pour Bottle (`pour_bottle?`) ### Pour bottle (`pour_bottle?`)
Optionally returns a boolean to decide whether a bottle should be used for this formula. 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`. 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: A full example:
...@@ -77,5 +77,5 @@ pour_bottle? do ...@@ -77,5 +77,5 @@ pour_bottle? do
end end
``` ```
## Planned Improvements ## Planned improvements
Most bottle features have been (and planned improvements will be) implemented by @MikeMcQuaid. Contact him directly with questions. Most bottle features have been (and planned improvements will be) implemented by @MikeMcQuaid. Contact him directly with questions.
docs/Brew-Test-Bot-For-Core-Contributors.md
+ 2
− 2
View file @ ab4d1a15
...@@ -10,7 +10,7 @@ This job automatically builds any pull requests submitted to Homebrew/homebrew-c ...@@ -10,7 +10,7 @@ This job automatically builds any pull requests submitted to Homebrew/homebrew-c
## [Homebrew Testing](https://bot.brew.sh/job/Homebrew%20Testing/) ## [Homebrew Testing](https://bot.brew.sh/job/Homebrew%20Testing/)
This job is manually triggered to run [`brew test-bot`](https://github.com/Homebrew/homebrew-test-bot/blob/master/cmd/brew-test-bot.rb) with user-specified parameters. On a successful build it automatically uploads bottles. This job is manually triggered to run [`brew test-bot`](https://github.com/Homebrew/homebrew-test-bot/blob/master/cmd/brew-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/homebrew-test-bot/blob/master/cmd/brew-test-bot.rb) with the same parameters. It's often useful to pass a pull request URL, a commit URL, a commit SHA-1 and/or formula names to have `brew-test-bot` test them, report the results and produce bottles. You can manually start this job with parameters to run [`brew test-bot`](https://github.com/Homebrew/homebrew-test-bot/blob/master/cmd/brew-test-bot.rb) with the same parameters. It's often useful to pass a pull request URL, a commit URL, a commit SHA-1 and/or formula names to have the Brew Test Bot test them, report the results and produce bottles.
## Bottling ## Bottling
To pull and bottle a pull request with `brew pull`: To pull and bottle a pull request with `brew pull`:
...@@ -19,7 +19,7 @@ To pull and bottle a pull request with `brew pull`: ...@@ -19,7 +19,7 @@ To pull and bottle a pull request with `brew pull`:
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. 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. 3. Run `git push` to push the commits.
To bottle a test build : To bottle a test build:
1. Ensure the job has already completed successfully. 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. 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.
......
docs/Common-Issues.md
+ 8
− 8
View file @ ab4d1a15
...@@ -6,14 +6,14 @@ This is a list of commonly encountered problems, known issues, and their solutio ...@@ -6,14 +6,14 @@ This is a list of commonly encountered problems, known issues, and their solutio
You need to have the Xcode Command Line Utilities installed (and updated): run `xcode-select --install` in the terminal. 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".) (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` ### 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> 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` ### 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. 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 `.app`s, 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 ### `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. 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: 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:
...@@ -27,7 +27,7 @@ cd $(brew --repository)/Library ...@@ -27,7 +27,7 @@ cd $(brew --repository)/Library
git clean -fd git clean -fd
``` ```
### invalid multibyte escape: /^\037\213/ ### Ruby: `invalid multibyte escape: /^\037\213/`
You see an error similar to: You see an error similar to:
...@@ -38,7 +38,7 @@ invalid multibyte escape: /^\037\235/ ...@@ -38,7 +38,7 @@ 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. 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. The incompatibilities have been addressed in more recent versions of Homebrew, and instead of making assumptions about `/usr/bin/ruby`, it uses the executable inside macOS's Ruby framework or a vendored Ruby.
To recover from this situation, do the following: To recover from this situation, do the following:
...@@ -125,7 +125,7 @@ Upgrading macOS can cause errors like the following: ...@@ -125,7 +125,7 @@ Upgrading macOS can cause errors like the following:
- `dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.54.dylib` - `dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.54.dylib`
- `configure: error: Cannot find libz` - `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: Following a macOS upgrade it may be necessary to reinstall the Xcode Command Line Tools and `brew upgrade` all installed formula:
```bash ```bash
xcode-select --install xcode-select --install
......
docs/Custom-GCC-and-cross-compilers.md
+ 3
− 3
View file @ ab4d1a15
# Custom GCC and Cross Compilers # Custom GCC and Cross Compilers
Homebrew depends on having an up-to-date version of Xcode because it comes with Homebrew depends on having an up-to-date version of Xcode because it comes with
specific versions of build tools e.g. `clang`. specific versions of build tools, e.g. `clang`.
Installing a custom version of GCC or `autotools` into the `$PATH` has the 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 potential to break lots of compiles so we prefer the Apple- or Homebrew-provided
compilers. compilers.
Cross-compilers based on GCC will typically be "keg-only" and therefore not Cross-compilers based on GCC will typically be "keg-only" and therefore not
...@@ -16,6 +16,6 @@ GCC or cross-compiler suite, please link it in here. ...@@ -16,6 +16,6 @@ GCC or cross-compiler suite, please link it in here.
* Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing * Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing
C++11 support on earlier versions. C++11 support on earlier versions.
* Homebrew provides older GCC formulae e.g. `gcc@4.8` and `gcc@6` * Homebrew provides older GCC formulae, e.g. `gcc@4.8` and `gcc@6`.
* [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V * [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V
toolchain including binutils and gcc. toolchain including binutils and gcc.
docs/External-Commands.md
+ 13
− 14
View file @ ab4d1a15
...@@ -8,31 +8,30 @@ $ brew mycommand --option1 --option3 formula ...@@ -8,31 +8,30 @@ $ brew mycommand --option1 --option3 formula
without modifying Homebrew's internals. without modifying Homebrew's internals.
## Command Types ## Command types
External commands come in two flavors: Ruby commands and shell scripts. 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`. In both cases, the command file should be executable (`chmod +x`) and live somewhere in `$PATH`.
### Ruby Commands ### 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. 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. 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 ### 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. A shell script for a command named `extcmd` should be named `brew-extcmd`. This file will be run via `exec` with some Homebrew variables set as environment variables, and passed any additional command-line arguments.
| Variable | Description |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| HOMEBREW_CACHE | Where Homebrew caches downloaded tarballs to, by default ~/Library/Caches/Homebrew. |
| HOMEBREW_CELLAR | The location of the Homebrew Cellar, where software is staged. This will be $HOMEBREW_PREFIX/Cellar if that directory exists, or $HOMEBREW_REPOSITORY/Cellar otherwise. |
| HOMEBREW_LIBRARY_PATH | The directory containing Homebrew’s own application code. |
| HOMEBREW_PREFIX | Where Homebrew installs software. This is always the grandparent directory of the `brew` executable, /usr/local by default. |
| HOMEBREW_REPOSITORY | If installed from a Git clone, the repo directory (i.e., where Homebrew’s .git directory lives). |
| Variable | Description |
|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `HOMEBREW_CACHE` | Where Homebrew caches downloaded tarballs to, by default `~/Library/Caches/Homebrew`. |
| `HOMEBREW_CELLAR` | The location of the Homebrew Cellar, where software is staged. This will be `$HOMEBREW_PREFIX/Cellar` if that directory exists, or `$HOMEBREW_REPOSITORY/Cellar` otherwise. |
| `HOMEBREW_LIBRARY_PATH`| The directory containing Homebrew’s own application code. |
| `HOMEBREW_PREFIX` | Where Homebrew installs software. This is always the grandparent directory of the `brew` executable, `/usr/local` by default. |
| `HOMEBREW_REPOSITORY` | If installed from a Git clone, the repository directory (i.e. where Homebrew’s .git directory lives). |
Note that the script itself can use any suitable shebang (`#!`) line, so an external “shell script” can be written for sh, bash, Ruby, or anything else. 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 ## 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. 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. Note they are largely untested, and as always, be careful about running untested code on your machine.
...@@ -55,7 +54,7 @@ Note this can also be installed with `brew install brew-gem`. ...@@ -55,7 +54,7 @@ Note this can also be installed with `brew install brew-gem`.
Get Growl notifications for Homebrew: <https://github.com/secondplanet/homebrew-growl> Get Growl notifications for Homebrew: <https://github.com/secondplanet/homebrew-growl>
### brew-services ### 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> Simple support for starting 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>
Install using: Install using:
```sh ```sh
......
docs/FAQ.md
+ 14
− 22
View file @ ab4d1a15
...@@ -17,8 +17,6 @@ Or upgrade a specific formula with: ...@@ -17,8 +17,6 @@ Or upgrade a specific formula with:
brew upgrade $FORMULA brew upgrade $FORMULA
<a name="cleanup"></a>
## How do I stop certain formulae from being updated? ## How do I stop certain formulae from being updated?
To stop something from being updated/upgraded: To stop something from being updated/upgraded:
...@@ -38,12 +36,10 @@ or clean up everything at once: ...@@ -38,12 +36,10 @@ or clean up everything at once:
brew cleanup brew cleanup
to see what would be cleaned up: or to see what would be cleaned up:
brew cleanup -n brew cleanup -n
<a name="uninstall"></a>
## How do I uninstall Homebrew? ## How do I uninstall Homebrew?
To uninstall Homebrew, paste the command below in a terminal prompt. To uninstall Homebrew, paste the command below in a terminal prompt.
...@@ -53,15 +49,12 @@ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/ ...@@ -53,15 +49,12 @@ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/
Download the [uninstall script](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. and run `./uninstall --help` to view more uninstall options.
<a name="uninstall-package"></a>
## How do I uninstall a formula? ## How do I uninstall a formula?
If you do not uninstall all of the versions that Homebrew has installed, 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 Homebrew will continue to attempt to install the newest version it knows
about when you do (`brew upgrade --all`). This can be surprising. about when you run `brew upgrade --all`. This can be surprising.
To remove a formula entirely, you may do To remove a formula entirely, you may run `brew uninstall formula_name --force`.
(`brew uninstall formula_name --force`).
Be careful as this is a destructive operation. Be careful as this is a destructive operation.
...@@ -85,13 +78,13 @@ Read [CONTRIBUTING.md](https://github.com/Homebrew/brew/blob/master/CONTRIBUTING ...@@ -85,13 +78,13 @@ Read [CONTRIBUTING.md](https://github.com/Homebrew/brew/blob/master/CONTRIBUTING
## Why do you compile everything? ## Why do you compile everything?
Homebrew provides pre-compiled versions for many formulae. These Homebrew provides pre-compiled versions for many formulae. These
pre-compiled versions are referred to as **bottles** and are available pre-compiled versions are referred to as [bottles](Bottles.md) and are available
at <https://bintray.com/homebrew/bottles>. at <https://bintray.com/homebrew/bottles>.
If available, bottled binaries will be used by default except under the If available, bottled binaries will be used by default except under the
following conditions: following conditions:
* Options were passed to the install command i.e. `brew install $FORMULA` * Options were passed to the install command, i.e. `brew install $FORMULA`
will use a bottled version of $FORMULA, but will use a bottled version of $FORMULA, but
`brew install $FORMULA --enable-bar` will trigger a source build. `brew install $FORMULA --enable-bar` will trigger a source build.
* The `--build-from-source` option is invoked. * The `--build-from-source` option is invoked.
...@@ -99,7 +92,7 @@ will use a bottled version of $FORMULA, but ...@@ -99,7 +92,7 @@ will use a bottled version of $FORMULA, but
* The machine is not running a supported version of macOS as all * The machine is not running a supported version of macOS as all
bottled builds are generated only for supported macOS versions. bottled builds are generated only for supported macOS versions.
* Homebrew is installed to a prefix other than the standard * Homebrew is installed to a prefix other than the standard
`/usr/local` (although some bottles support this) `/usr/local` (although some bottles support this).
In order to completely disable bottled builds, simply add a value for In order to completely disable bottled builds, simply add a value for
the environment variable `HOMEBREW_BUILD_FROM_SOURCE` to the environment variable `HOMEBREW_BUILD_FROM_SOURCE` to
...@@ -123,7 +116,6 @@ Or: ...@@ -123,7 +116,6 @@ Or:
`brew pull https://github.com/Homebrew/homebrew-core/pull/1234` `brew pull https://github.com/Homebrew/homebrew-core/pull/1234`
## Why does Homebrew prefer I install to `/usr/local`? ## 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 1. **It’s easier**<br>`/usr/local/bin` is already in your
`PATH`. `PATH`.
...@@ -142,13 +134,13 @@ brews then save yourself a bunch of hassle and install to ...@@ -142,13 +134,13 @@ brews then save yourself a bunch of hassle and install to
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". 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> ## Why does Homebrew say sudo is bad?
**tl;dr** Sudo is dangerous, and you installed TextMate.app without sudo **tl;dr** Sudo is dangerous, and you installed TextMate.app without sudo
anyway. anyway.
Homebrew is designed to work without using sudo. You can decide to use 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 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 into a bug then this is likely to be the cause. Please don’t file a bug
report unless you can reproduce it after reinstalling Homebrew from report unless you can reproduce it after reinstalling Homebrew from
scratch without using sudo. scratch without using sudo.
...@@ -179,7 +171,7 @@ If it’s been a while, bump it with a “bump” comment. Sometimes we miss req ...@@ -179,7 +171,7 @@ If it’s been a while, bump it with a “bump” comment. Sometimes we miss req
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! 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? ## Can I make new formulae?
Yes! It’s easy! Just `brew create URL` Homebrew will then open the 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 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, 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`, run the command with the `-d` switch like so: `brew install -d $FORMULA`,
...@@ -193,7 +185,7 @@ Yes, brew is designed to not get in your way so you can use it how you ...@@ -193,7 +185,7 @@ Yes, brew is designed to not get in your way so you can use it how you
like. like.
Install your own stuff, but be aware that if you install common Install your own stuff, but be aware that if you install common
libraries, like libexpat yourself, it may cause trouble when trying to libraries like libexpat yourself, it may cause trouble when trying to
build certain Homebrew formula. As a result `brew doctor` will warn you build certain Homebrew formula. As a result `brew doctor` will warn you
about this. about this.
...@@ -215,13 +207,13 @@ Linking /usr/local/Cellar/foo/0.1… 17 symlinks created ...@@ -215,13 +207,13 @@ Linking /usr/local/Cellar/foo/0.1… 17 symlinks created
Use `brew log $FORMULA` to find out! Likely because it had unresolved issues or Use `brew log $FORMULA` to find out! Likely because it had unresolved issues or
our analytics identified it was not widely used. our analytics identified it was not widely used.
## Homebrew is a poor name, it is generic, why was it chosen? ## Homebrew is a poor name, it's too generic, why was it chosen?
@mxcl was too concerned with the beer theme and didn’t consider that the @mxcl was too concerned with the beer theme and didn’t consider that the
project may actually prove popular. By the time he realized it was too project may actually prove popular. By the time he realized it was, it was too
late. However, today, the first google hit for “homebrew” is not beer late. However, today, the first Google hit for “homebrew” is not beer
related ;-) related ;-)
## What does *keg-only* mean? ## What does "keg-only" mean?
It means the formula is installed only into the Cellar; it is not linked 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 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 this for stupid reasons. You can still link in the formula if you need
......
docs/Formula-Cookbook.md
+ 95
− 174
View file @ ab4d1a15
This diff is collapsed.
docs/Gems,-Eggs-and-Perl-Modules.md
+ 16
− 18
View file @ ab4d1a15
...@@ -21,19 +21,19 @@ Habit maybe? ...@@ -21,19 +21,19 @@ Habit maybe?
One reason is executables go in `/usr/local/bin`. Usually this isn’t a One reason is executables go in `/usr/local/bin`. Usually this isn’t a
writable location. But if you installed Homebrew as we recommend, writable location. But if you installed Homebrew as we recommend,
`/usr/local` will be writable without sudo. So now you are good to `/usr/local` will be writable without sudo. So now you are good to
install the development tools you need without risking a sudo. install the development tools you need without risking the use of sudo.
### Python packages (eggs) without sudo
Rather than changing the rights on /Library/Python, we recommend the Rather than changing the rights on /Library/Python, we recommend the
## Python packages (eggs) without sudo
following options: following options:
### With a brewed Python - you don’t need sudo ### With a brewed Python
Note, `easy_install` is deprecated. We install `pip` (or `pip3` for Note, `easy_install` is deprecated. We install `pip` (or `pip3` for
python3) along with python/python3. python3) along with python/python3.
We set up distutils such that `pip install` will always put modules in 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)/lib/pythonX.Y/site-packages` and scripts in
`$(brew --prefix)/share/python`. Therefore, you won’t need `sudo`! `$(brew --prefix)/share/python`. Therefore, you won’t need sudo!
Do `brew info python` or `brew info python3` for precise information Do `brew info python` or `brew info python3` for precise information
about the paths. Note, a brewed Python still searches for modules in about the paths. Note, a brewed Python still searches for modules in
...@@ -50,7 +50,7 @@ That dir might not yet exist, but you can create it: ...@@ -50,7 +50,7 @@ That dir might not yet exist, but you can create it:
`mkdir -p ~/Library/Python/2.7/lib/python/site-packages` `mkdir -p ~/Library/Python/2.7/lib/python/site-packages`
To teach `easy_install` and `pip` to install there, either use the To teach `easy_install` and `pip` to install there, either use the
`—user` switch or create a `~/.pydistutils.cfg` file with the `--user` switch or create a `~/.pydistutils.cfg` file with the
following content: following content:
[install] [install]
...@@ -60,10 +60,9 @@ following content: ...@@ -60,10 +60,9 @@ following content:
[Virtualenv](http://www.virtualenv.org/en/latest/) ships `pip` and [Virtualenv](http://www.virtualenv.org/en/latest/) ships `pip` and
creates isolated Python environments with separate site-packages, creates isolated Python environments with separate site-packages,
therefore you won’t need `sudo`. therefore you won’t need sudo.
Rubygems without sudo ## Rubygems without sudo
---------------------
**If you use rbenv or RVM then you should ignore this stuff** **If you use rbenv or RVM then you should ignore this stuff**
...@@ -74,19 +73,19 @@ without sudo. You should add this to your path. See the caveats in the ...@@ -74,19 +73,19 @@ without sudo. You should add this to your path. See the caveats in the
### With system’s Ruby ### With system’s Ruby
To make Ruby install to `/usr/local`, we need to add 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 `gem: -n/usr/local/bin` to your `~/.gemrc`. It’s YAML, so do it manually
or use this: or use this:
echo "gem: -n/usr/local/bin" >> ~/.gemrc echo "gem: -n/usr/local/bin" >> ~/.gemrc
**However all versions of RubyGems before 1.3.6 are buggy** and ignore **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 the above setting. Sadly a fresh install of Snow Leopard comes with
1.3.5. Currently the only known way to get around this is to upgrade 1.3.5. Currently the only known way to get around this is to upgrade
rubygems as root: rubygems as root:
`sudo gem update --system` `sudo gem update --system`
### An Alternative ### An alternative
Just install everything into the Homebrew prefix like this: Just install everything into the Homebrew prefix like this:
...@@ -94,16 +93,15 @@ Just install everything into the Homebrew prefix like this: ...@@ -94,16 +93,15 @@ Just install everything into the Homebrew prefix like this:
### It doesn’t work! I get some “permissions” error when I try to install stuff! ### 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 *Note, maybe you shouldn’t do this on Lion, since Apple has decided it
is not a good default.* is not a good default.*
If you ever did a `sudo gem`, etc. before then a lot of files will have If you ever did a `sudo gem`, etc. before then a lot of files will have
been created chown root. Fix with: been created owned by root. Fix with:
`sudo chown -R $USER /Library/Ruby /Library/Perl /Library/Python` `sudo chown -R $USER /Library/Ruby /Library/Perl /Library/Python`
Perl CPAN Modules without sudo ## Perl CPAN modules without sudo
------------------------------
The Perl module local::lib works similarly to rbenv/RVM (although for The Perl module local::lib works similarly to rbenv/RVM (although for
modules only, not perl installations). A simple solution that only modules only, not perl installations). A simple solution that only
...@@ -112,7 +110,7 @@ pollutes your /Library/Perl a little is to install ...@@ -112,7 +110,7 @@ pollutes your /Library/Perl a little is to install
`sudo cpan local::lib` `sudo cpan local::lib`
Note that will install some other dependencies like `Module::Install`. Note that this will install some other dependencies like `Module::Install`.
Then put the appropriate incantation in your shell’s startup, e.g. for Then put the appropriate incantation in your shell’s startup, e.g. for
`.bash_profile` you insert the below, for others see the `.bash_profile` you insert the below, for others see the
[local::lib](https://metacpan.org/pod/local::lib) docs. [local::lib](https://metacpan.org/pod/local::lib) docs.
...@@ -126,11 +124,11 @@ subdirectories will be in your `PATH` and `PERL5LIB` etc. ...@@ -126,11 +124,11 @@ subdirectories will be in your `PATH` and `PERL5LIB` etc.
### Avoiding sudo altogether for Perl ### Avoiding sudo altogether for Perl
If you don’t even want (or can’t) use sudo for bootstrapping 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. ~/perl5 and add the relevant path to `PERL5LIB` before the .bashrc eval incantation.
`local::lib`, just manually install `local::lib` in
Another alternative is to use `perlbrew` to install a separate copy of Perl in your home directory, or wherever you like :
```bash ```bash
Another alternative is to use `perlbrew` to install a separate copy of Perl in your home directory, or wherever you like:
curl -L https://install.perlbrew.pl | bash curl -L https://install.perlbrew.pl | bash
perlbrew install perl-5.16.2 perlbrew install perl-5.16.2
echo ".~/perl5/perlbrew/etc/bashrc" >> ~/.bashrc echo ".~/perl5/perlbrew/etc/bashrc" >> ~/.bashrc
......
docs/Homebrew-and-Python.md
+ 3
− 3
View file @ ab4d1a15
...@@ -4,7 +4,7 @@ This page describes how Python is handled in Homebrew for users. See [Python for ...@@ -4,7 +4,7 @@ This page describes how Python is handled in Homebrew for users. See [Python for
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 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). 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. **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.
...@@ -62,9 +62,9 @@ These should be installed via `pip install <x>`. To discover, you can use `pip s ...@@ -62,9 +62,9 @@ These should be installed via `pip install <x>`. To discover, you can use `pip s
## Brewed Python modules ## 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`. For brewed Python, modules installed with `pip` or `python setup.py install` will be installed to the `$(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: 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 run:
`CFLAGS=-I$(brew --prefix)/include LDFLAGS=-L$(brew --prefix)/lib pip install <package>`. `CFLAGS=-I$(brew --prefix)/include LDFLAGS=-L$(brew --prefix)/lib pip install <package>`.
......
docs/How-To-Open-a-Homebrew-Pull-Request.md
+ 2
− 2
View file @ ab4d1a15
...@@ -35,7 +35,7 @@ To make a new branch and submit it for review, create a GitHub pull request with ...@@ -35,7 +35,7 @@ To make a new branch and submit it for review, create a GitHub pull request with
2. Retrieve new changes to the `master` branch with `brew update`. 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`. 3. Create a new branch from the latest `master` branch with `git checkout -b <YOUR_BRANCH_NAME> origin/master`.
4. Make your changes. For formulae, use `brew edit` or your favorite text editor, following all the guidelines in the [Formula Cookbook](Formula-Cookbook.md). 4. Make your changes. For formulae, use `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. * 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 by doing the following, and ensure they all pass without issue. For changed formulae, make sure you do the `brew audit` step while your changed formula is installed. 5. Test your changes by doing the following, and ensure they all pass without issue. For changed formulae, make sure you do the `brew audit` step while your changed formula is installed.
* `brew tests` * `brew tests`
* `brew install --build-from-source <CHANGED_FORMULA>` * `brew install --build-from-source <CHANGED_FORMULA>`
...@@ -44,7 +44,7 @@ To make a new branch and submit it for review, create a GitHub pull request with ...@@ -44,7 +44,7 @@ To make a new branch and submit it for review, create a GitHub pull request with
6. Make a separate commit for each changed formula with `git add` and `git commit`. 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>`. 7. Upload your new commits to the branch on your fork with `git push --set-upstream <YOUR_USERNAME> <YOUR_BRANCH_NAME>`.
8. Go to the relevant repository (e.g. <https://github.com/Homebrew/brew>, <https://github.com/Homebrew/homebrew-core>, etc.) 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. 8. Go to the relevant repository (e.g. <https://github.com/Homebrew/brew>, <https://github.com/Homebrew/homebrew-core>, etc.) 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)`". * 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. 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.
Thank you! Thank you!
......
docs/How-to-Create-and-Maintain-a-Tap.md
+ 3
− 3
View file @ ab4d1a15
...@@ -5,8 +5,8 @@ can be created by anyone to provide their own formulae and/or external commands ...@@ -5,8 +5,8 @@ can be created by anyone to provide their own formulae and/or external commands
to any Homebrew user. to any Homebrew user.
## Creating a tap ## Creating a tap
A tap is usually a git repository available online, but you can use anything as 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 long as it’s a protocol that Git understands, or even just a directory with
files in it. files in it.
If hosted on GitHub, we recommend that the repository’s name start with If hosted on GitHub, we recommend that the repository’s name start with
`homebrew-`. `homebrew-`.
...@@ -41,7 +41,7 @@ no core formula with the same name, or with `brew install user/repo/foo` to ...@@ -41,7 +41,7 @@ no core formula with the same name, or with `brew install user/repo/foo` to
avoid conflicts. avoid conflicts.
## Maintaining a tap ## Maintaining a tap
A tap is just a git repository so you don’t have to do anything specific when 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. making modifications, apart from committing and pushing your changes.
### Updating ### Updating
......
docs/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md
+ 8
− 9
View file @ ab4d1a15
# How to build software outside Homebrew with Homebrew `keg-only` dependencies # How to build software outside Homebrew with Homebrew `keg_only` dependencies
## What does `keg-only` mean? ## What does "keg-only" mean?
The [FAQ](FAQ.md) briefly explains this. The [FAQ](FAQ.md) briefly explains this.
...@@ -10,20 +10,19 @@ As an example: ...@@ -10,20 +10,19 @@ As an example:
This is because Homebrew keeps it locked inside its individual prefix, rather than symlinking to the publicly-available location, usually `/usr/local`. 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. ## 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. 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. *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. `brew link --force` creates a warning in `brew doctor` to let both you and maintainers know that a link exists that 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? ## How do I use those tools outside of Homebrew?
Useful, reliable alternatives exist should you wish to use `keg_only` tools outside of Homebrew. Useful, reliable alternatives exist should you wish to use `keg_only` tools outside of Homebrew.
### Build flags: ### Build flags
You can set flags to give configure scripts or Makefiles a nudge in the right direction. An example of flag setting: You can set flags to give configure scripts or Makefiles a nudge in the right direction. An example of flag setting:
...@@ -37,7 +36,7 @@ An example using `pip`: ...@@ -37,7 +36,7 @@ An example using `pip`:
CFLAGS=-I$(brew --prefix)/opt/icu4c/include LDFLAGS=-L$(brew --prefix)/opt/icu4c/lib pip install pyicu CFLAGS=-I$(brew --prefix)/opt/icu4c/include LDFLAGS=-L$(brew --prefix)/opt/icu4c/lib pip install pyicu
``` ```
### `$PATH` modification: ### `$PATH` modification
You can temporarily prepend your `$PATH` with the tool’s bin directory, such as: You can temporarily prepend your `$PATH` with the tool’s bin directory, such as:
...@@ -49,11 +48,11 @@ This will prepend that folder to your `$PATH`, ensuring any build script that se ...@@ -49,11 +48,11 @@ This will prepend that folder to your `$PATH`, ensuring any build script that se
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. 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: ### `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. 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: An example of this is:
```shell ```shell
export PKG_CONFIG_PATH=$(brew --prefix)/opt/openssl/lib/pkgconfig export PKG_CONFIG_PATH=$(brew --prefix)/opt/openssl/lib/pkgconfig
......
docs/Installation.md
+ 2
− 2
View file @ ab4d1a15
...@@ -5,7 +5,7 @@ The suggested and easiest way to install Homebrew is on the ...@@ -5,7 +5,7 @@ The suggested and easiest way to install Homebrew is on the
The standard script installs Homebrew to `/usr/local` so that The standard script installs Homebrew to `/usr/local` so that
[you don’t need sudo](FAQ.md) when you [you don’t need sudo](FAQ.md) when you
`brew install`. It is a careful script, it can be run even if you have stuff `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 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. it does it too. And you have to confirm everything it will do before it starts.
...@@ -44,7 +44,7 @@ you can assume you will have trouble if you don’t conform. Also, you can find ...@@ -44,7 +44,7 @@ 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 PowerPC and Tiger branches from other users in the fork network. See
[Interesting Taps & Forks](Interesting-Taps-&-Forks.md). [Interesting Taps & Forks](Interesting-Taps-&-Forks.md).
<a name="2"><sup>2</sup></a> 10.10 or higher is recommended. 10.5 - 10.9 are <a name="2"><sup>2</sup></a> 10.10 or higher is recommended. 10.5–10.9 are
supported on a best-effort basis. For 10.4 and 10.5, see supported on a best-effort basis. For 10.4 and 10.5, see
[Tigerbrew](https://github.com/mistydemeo/tigerbrew). [Tigerbrew](https://github.com/mistydemeo/tigerbrew).
......
docs/Interesting-Taps-&-Forks.md
+ 7
− 7
View file @ ab4d1a15
# Interesting Taps & Forks # Interesting Taps & Forks
A Tap is homebrew-speak for a git repository containing extra formulae. 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. Homebrew has the capability to add (and remove) multiple taps to your local installation with the `brew tap` and `brew untap` commands. 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 ## 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/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.
...@@ -35,7 +35,7 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst ...@@ -35,7 +35,7 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst
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! 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 ## Other interesting taps
* [InstantClientTap/instantclient](https://github.com/InstantClientTap/homebrew-instantclient): A tap for Oracle Instant Client. The packages need to be downloaded manually. * [InstantClientTap/instantclient](https://github.com/InstantClientTap/homebrew-instantclient): A tap for Oracle Instant Client. The packages need to be downloaded manually.
...@@ -47,12 +47,12 @@ You can be added as a maintainer for one of the Homebrew organization taps and a ...@@ -47,12 +47,12 @@ You can be added as a maintainer for one of the Homebrew organization taps and a
* [titanous/gnuradio](https://github.com/titanous/homebrew-gnuradio): GNU Radio and friends running on macOS. * [titanous/gnuradio](https://github.com/titanous/homebrew-gnuradio): GNU Radio and friends running on macOS.
## Interesting Forks ## Interesting forks
* [mistydemeo/tigerbrew](https://github.com/mistydemeo/tigerbrew): Experimental Tiger PowerPC version * [mistydemeo/tigerbrew](https://github.com/mistydemeo/tigerbrew): Experimental Tiger PowerPC version
* [Linuxbrew/brew](https://github.com/Linuxbrew/brew): Experimental Linux version * [Linuxbrew/brew](https://github.com/Linuxbrew/brew): Experimental Linux version
## Technical Details ## Technical details
Your taps are git repositories located at `$(brew --repository)/Library/Taps`. Your taps are Git repositories located at `$(brew --repository)/Library/Taps`.
docs/Kickstarter-Supporters.md
+ 1
− 1
View file @ ab4d1a15
...@@ -173,7 +173,7 @@ These brilliant people supported our Kickstarter by giving us £15 or more: ...@@ -173,7 +173,7 @@ These brilliant people supported our Kickstarter by giving us £15 or more:
* [Nick Rogers](https://twitter.com/zikolas) * [Nick Rogers](https://twitter.com/zikolas)
* [Abe Estrada](https://abeestrada.com) * [Abe Estrada](https://abeestrada.com)
* [Mattias Larsson](https://www.yahoo.com/) * [Mattias Larsson](https://www.yahoo.com/)
* [Dave Ross](http://davidmichaelross.com) * [Dave Ross](http://davidmichaelross.com)
* [Andrian Budantsov](http://andrian.io/) * [Andrian Budantsov](http://andrian.io/)
* [Jason Smith](https://twitter.com/waitingallday) * [Jason Smith](https://twitter.com/waitingallday)
* [Martin Coxall](https://twitter.com/grabcocque) * [Martin Coxall](https://twitter.com/grabcocque)
......
docs/Maintainer-Guidelines.md
+ 14
− 14
View file @ ab4d1a15
...@@ -7,7 +7,7 @@ definitely not a beginner’s guide. ...@@ -7,7 +7,7 @@ definitely not a beginner’s guide.
Maybe you were looking for the [Formula Cookbook](Formula-Cookbook.md)? Maybe you were looking for the [Formula Cookbook](Formula-Cookbook.md)?
## Quick Checklist ## Quick checklist
This is all that really matters: This is all that really matters:
- Ensure the name seems reasonable. - Ensure the name seems reasonable.
...@@ -20,7 +20,7 @@ This is all that really matters: ...@@ -20,7 +20,7 @@ This is all that really matters:
- Ensure that any dependencies are accurate and minimal. We don't need to - Ensure that any dependencies are accurate and minimal. We don't need to
support every possible optional feature for the software. support every possible optional feature for the software.
- Use the GitHub squash & merge workflow where bottles aren't required. - 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. - Use `brew pull` otherwise, which adds messages to auto-close pull requests and pull bottles built by the Brew Test Bot.
- Thank people for contributing. - Thank people for contributing.
Checking dependencies is important, because they will probably stick around Checking dependencies is important, because they will probably stick around
...@@ -53,23 +53,23 @@ For now, if someone submits a formula like this, we’ll leave them in ...@@ -53,23 +53,23 @@ For now, if someone submits a formula like this, we’ll leave them in
their own tree. their own tree.
### Merging, rebasing, cherry-picking ### Merging, rebasing, cherry-picking
Merging should be done in the brew repo to preserve history & GPG commit signing, Merging should be done in the `Homebrew/brew` repository to preserve history & GPG commit signing,
and squash/merge via GitHub should be used for formulae where those formulae 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. 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). 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 Don’t `rebase` until you finally `push`. Once `master` is pushed, you can’t
`rebase` : **you’re a maintainer now!** `rebase`: **you’re a maintainer now!**
Cherry-picking changes the date of the commit, which kind of sucks. Cherry-picking changes the date of the commit, which kind of sucks.
Don’t `merge` unclean branches. So if someone is still learning `git` Don’t `merge` unclean branches. So if someone is still learning `git` and
their branch is filled with nonsensical merges, then `rebase` and squash their branch is filled with nonsensical merges, then `rebase` and squash
the commits. Our main branch history should be useful to other people, the commits. Our main branch history should be useful to other people,
not confusing. not confusing.
### Testing ### Testing
We need to at least check it builds. Use [Brew Test Bot](Brew-Test-Bot.md) for this. We need to at least check that it builds. Use the [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 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 library) trust the original contributor, it worked for them, so chances are it
...@@ -80,14 +80,14 @@ open source works. Ideally, request a `test do` block to test that ...@@ -80,14 +80,14 @@ open source works. Ideally, request a `test do` block to test that
functionality is consistently available. functionality is consistently available.
If the formula uses a repository, then the `url` parameter should have a 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 tag or revision. `url`s have versions and are stable (not yet
implemented!). implemented!).
## Common “Gotchas” ## Common “gotchas”
1. [Ensure you have set your username and email address 1. [Ensure you have set your username and email address
properly](https://help.github.com/articles/setting-your-email-in-git/) 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, 2. Sign off cherry-picks if you amended them ([GitX-dev](https://github.com/rowanj/gitx)
otherwise there is a command line flag for it) 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 3. If the commit fixes a bug, use “Fixes \#104” syntax to close the bug
report and link to the commit report and link to the commit
...@@ -97,7 +97,7 @@ libraries that macOS provides but have bugs, and the bugs are fixed in a ...@@ -97,7 +97,7 @@ 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 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. some other formula. The rest should be in the `homebrew/dupes` tap.
Still determine if it possible to avoid the duplicate. Be thorough. Duped Still determine if it's possible to avoid the duplicate. Be thorough. Duped
libraries and tools cause bugs that are tricky to solve. Once the formula is libraries and tools cause bugs that are tricky to solve. Once the formula is
pulled, we can’t go back on that willy-nilly. pulled, we can’t go back on that willy-nilly.
...@@ -108,9 +108,9 @@ Dupes we have allowed: ...@@ -108,9 +108,9 @@ Dupes we have allowed:
- `libxml` \<— macOS version is old and buggy - `libxml` \<— macOS version is old and buggy
- `libpng` \<— Ditto - `libpng` \<— Ditto
#### Add comments ### Add comments
It may be enough to refer to an issue ticket, but make sure changes that It may be enough to refer to an issue ticket, but make sure changes are clear so that
if you came to them unaware of the surrounding issues would make sense if you came to them unaware of the surrounding issues they would make sense
to you. Many times on other projects I’ve seen code removed because the 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. new guy didn’t know why it was there. Regressions suck.
......
docs/Maintainers-Avoiding-Burnout.md
+ 7
− 7
View file @ ab4d1a15
...@@ -5,14 +5,14 @@ access** to Homebrew’s repository and help merge the contributions of ...@@ -5,14 +5,14 @@ access** to Homebrew’s repository and help merge the contributions of
others. You may find what is written here interesting, but it’s others. You may find what is written here interesting, but it’s
definitely not for everyone. definitely not for everyone.
# 1. Use Homebrew ## 1. Use Homebrew
Maintainers of Homebrew should be using it regularly. This is partly because 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 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 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. you should also decide not to be a maintainer and find other things to work on.
# 2. No Guilt About Leaving ## 2. No Guilt About Leaving
All maintainers can stop working on Homebrew at any time without any guilt or 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 explanation (like a job). We may still ask for your help with questions after
...@@ -23,10 +23,10 @@ Like a job, you should probably take a break from Homebrew at least a few times ...@@ -23,10 +23,10 @@ Like a job, you should probably take a break from Homebrew at least a few times
a year. a year.
This also means contributors should be consumers. If an owner finds they are 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 not using a project in the real world, they should reconsider their involvement
with the project. with the project.
# 3. Prioritise Maintainers Over Users ## 3. Prioritise Maintainers Over Users
It's important to be user-focused but ultimately, as long as you follow #1 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. above, Homebrew's minimum number of users will be the number of maintainers.
...@@ -36,7 +36,7 @@ need takes priority over the burnout of maintainers. If users do not like the ...@@ -36,7 +36,7 @@ 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 direction of the project, the easiest way to influence it is to make
significant, high-quality code contributions and become a maintainer. significant, high-quality code contributions and become a maintainer.
# 4. Learn To Say No ## 4. Learn To Say No
Homebrew gets a lot of feature requests, non-reproducible bug reports, usage 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 questions and PRs we won't accept. These should be closed out as soon as we
...@@ -46,4 +46,4 @@ work to be done. ...@@ -46,4 +46,4 @@ work to be done.
--- ---
Thanks to https://gist.github.com/ryanflorence/124070e7c4b3839d4573 which influenced this document _Thanks to https://gist.github.com/ryanflorence/124070e7c4b3839d4573 which influenced this document_
docs/Node-for-Formula-Authors.md
+ 11
− 11
View file @ ab4d1a15
# Node for formula authors # Node for Formula Authors
This document explains how to successfully use Node and npm in a Node module based Homebrew formula. This document explains how to successfully use Node and npm in a Node module based Homebrew formula.
# Running `npm install` ## 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: 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. Your formula should use these instead of invoking `npm install` explicitly. The syntax for a standard Node module installation is:
```ruby ```ruby
system "npm", "install", *Language::Node.std_npm_install_args(libexec) system "npm", "install", *Language::Node.std_npm_install_args(libexec)
...@@ -12,7 +12,7 @@ system "npm", "install", *Language::Node.std_npm_install_args(libexec) ...@@ -12,7 +12,7 @@ system "npm", "install", *Language::Node.std_npm_install_args(libexec)
where `libexec` is the destination prefix (usually the `libexec` variable). where `libexec` is the destination prefix (usually the `libexec` variable).
# Download URL ## 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 don't include the files from the `.npmignore` (such as tests) resulting in a smaller download size and that any possible transpilation step is already done (e.g. no need to compile CoffeeScript files as a build step). 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 don't include the files from the `.npmignore` (such as tests) resulting in a smaller download size and that any possible transpilation step is already done (e.g. no need to compile CoffeeScript files as a build step).
...@@ -24,7 +24,7 @@ https://registry.npmjs.org/<name>/-/<name>-<version>.tgz ...@@ -24,7 +24,7 @@ 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. 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 ## Dependencies
Node modules which are compatible with the latest Node version should declare a dependency on the `node` formula. Node modules which are compatible with the latest Node version should declare a dependency on the `node` formula.
...@@ -36,15 +36,15 @@ If your formula requires being executed with an older Node version you must vend ...@@ -36,15 +36,15 @@ If your formula requires being executed with an older Node version you must vend
### Special requirements for native addons ### Special requirements for native addons
If your node module is a native addon or has a native addon somewhere in its 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). If your Node module is a native addon or has a native addon somewhere in its dependency tree you have to declare an additional dependency. Since the compilation of the native addon results in an invocation of `node-gyp` we need an additional build time dependency on `:python` (because gyp depends on Python 2.7).
```ruby ```ruby
depends_on :python => :build 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). 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 ## 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. 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.
...@@ -82,9 +82,9 @@ In your formula's `install` method, do any installation steps which need to be d ...@@ -82,9 +82,9 @@ In your formula's `install` method, do any installation steps which need to be d
system "npm", "install", *Language::Node.local_npm_install_args 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` on your own, following the [general Homebrew formula instructions](https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md). 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` on your own, following the [general Homebrew formula instructions](Formula-Cookbook.md).
# Example ## Example
Installing a standard Node module based formula would look like this: Installing a standard Node module based formula would look like this:
...@@ -112,4 +112,4 @@ class Foo < Formula ...@@ -112,4 +112,4 @@ class Foo < Formula
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. 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) formulae.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment