admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

Merge pull request #8652 from jonchang/doc-cleanup

Browse Source 
docs: various updates
This commit is contained in:
Jonathan Chang 2020-09-09 23:00:53 +10:00 committed by GitHub
commit 21e05e2c1d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 46 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/Analytics.md
View File

@ -1,6 +1,6 @@
# Anonymous Aggregate User Behaviour Analytics # 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. Homebrew gathers anonymous aggregate user behaviour analytics using Google Analytics. You will be notified the first time you run `brew update` or install Homebrew. Analytics are not enabled until after this notice is shown, to ensure that you can [opt out](Analytics.md#opting-out) without ever sending analytics data.
## 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:
@ -14,14 +14,14 @@ Homebrew's anonymous user and event data have a 14 month retention period. This
## 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/2.5.0 (Macintosh; Intel Mac OS X 10.15.6) curl/7.64.1`.
- The Google Analytics version, i.e. `1` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#v) - The [Google Analytics version](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#v), i.e. `1`.
- 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](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#tid), e.g. `UA-75654628-1`.
- 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](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#cid), 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 versus event counts. The ID is specific to the Homebrew package manager, and does not permit Homebrew maintainers to e.g. track you across websites you visit.
- If 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](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#aip) is enabled, i.e. `1`.
- The Homebrew application name, e.g. `Homebrew` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#an) - The Homebrew [application name](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#an), e.g. `Homebrew`.
- The Homebrew application version, e.g. `0.9.9` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#av) - The Homebrew [application version](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#av), e.g. `2.5.0`.
- The Homebrew analytics hit type, e.g. `event` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#t) - The Homebrew [analytics hit type](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#t), e.g. `event`.
Homebrew's analytics records the following different events: Homebrew's analytics records the following different events:
@ -42,7 +42,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?
Summaries of installation and error analytics are publicly available [here](https://brew.sh/analytics/). A JSON API is also available. Summaries of installation and error analytics are publicly available [here](https://brew.sh/analytics/). A JSON API is also available. The majority of Homebrew maintainers are not granted more detailed analytics data beyond these public resources.
## How? ## How?
The code is viewable in [`analytics.rb`](https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/utils/analytics.rb) and [`analytics.sh`](https://github.com/Homebrew/brew/blob/HEAD/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/HEAD/Library/Homebrew/utils/analytics.rb) and [`analytics.sh`](https://github.com/Homebrew/brew/blob/HEAD/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.

2
docs/Building-Against-Non-Homebrew-Dependencies.md
View File

@ -8,4 +8,4 @@ As Homebrew became primarily a binary package manager, most users were fulfillin
## Today ## Today
If you wish to build against custom non-Homebrew dependencies that are provided by Homebrew (e.g. a non-Homebrew, non-macOS `ruby`) then you must [create and maintain your own tap](How-to-Create-and-Maintain-a-Tap.md) as these formulae will not be accepted in Homebrew/homebrew-core. Once you have done that you can specify `env :std` in the formula which will allow e.g. `which ruby` to access your existing `PATH` variable and allow compilation to link against this Ruby. If you wish to build against custom non-Homebrew dependencies that are provided by Homebrew (e.g. a non-Homebrew, non-macOS `ruby`) then you must [create and maintain your own tap](How-to-Create-and-Maintain-a-Tap.md) as these formulae will not be accepted in Homebrew/homebrew-core. Once you have done that you can specify `env :std` in the formula which will allow e.g. `which ruby` to access your existing `PATH` variable and allow compilation to link against this Ruby. You can also [include a custom Requirement](https://github.com/Homebrew/brew/tree/HEAD/Library/Homebrew/requirements) in your formula that more accurately describes the non-Homebrew software you build against.

21
docs/Custom-GCC-and-cross-compilers.md
View File

@ -1,22 +1,11 @@
# 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`. Installing a custom version of GCC or Autotools into your `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 your `PATH` by default, or are prefixed with the target architecture, again to avoid conflicting with Apple or Homebrew compilers.
specific versions of build tools, e.g. `clang`.
Installing a custom version of GCC or `autotools` into the `PATH` has the Rather than merging formulae 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.
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 - Homebrew provides a `gcc` formula for use with Xcode 4.2+.
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 provides older GCC formulae, e.g. `gcc@7` - Homebrew provides older GCC formulae, e.g. `gcc@7`
- Homebrew provides some cross-compilers and toolchains, but these are named to avoid clashing with the default tools, e.g. `x86_64-elf-gcc`
- Homebrew provides the LLVM Clang, which is bundled with the `llvm` formula. - Homebrew provides the LLVM Clang, which is bundled with the `llvm` formula.
- [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.

10
docs/External-Commands.md
View File

@ -37,16 +37,6 @@ For example, see the [header of `brew-services.rb`](https://github.com/Homebrew/
## Homebrew organisation external commands ## Homebrew organisation external commands
### homebrew-livecheck
Check if there is a new upstream version of a formula.
See the [`README`](https://github.com/Homebrew/homebrew-livecheck/blob/HEAD/README.md) for more info and usage.
Install using:
```sh
brew tap homebrew/livecheck
```
### homebrew-command-not-found ### homebrew-command-not-found
Ubuntu's `command-not-found equivalent` for Homebrew. Ubuntu's `command-not-found equivalent` for Homebrew.
See the [`README`](https://github.com/Homebrew/homebrew-command-not-found/blob/HEAD/README.md) for more info and usage. See the [`README`](https://github.com/Homebrew/homebrew-command-not-found/blob/HEAD/README.md) for more info and usage.

77
docs/FAQ.md
View File

@ -1,5 +1,8 @@
# FAQ # FAQ
## Is there a glossary of terms around?
All your terminology needs can be [found here](Formula-Cookbook.md#homebrew-terminology).
## How do I update my local packages? ## How do I update my local packages?
First update the formulae and Homebrew itself: First update the formulae and Homebrew itself:
@ -26,38 +29,21 @@ To allow that formulae to update again:
brew unpin <formula> brew unpin <formula>
Note that pinned, outdated formulae that another formula depends on need to be upgraded when required as we do not allow formulae to be built against non-latest versions. Note that pinned, outdated formulae that another formula depends on need to be upgraded when required, as we do not allow formulae to be built against outdated versions. If this is not desired, you can instead `brew extract` to [maintain your own copy of the formula in a tap](How-to-Create-and-Maintain-a-Tap.md).
## How do I uninstall old versions of a formula?
Homebrew's default behaviour automatically uninstalls old versions of a formula every 30 days.
To remove them manually, simply use:
brew cleanup <formula>
or clean up everything at once:
brew cleanup
or to see what would be cleaned up:
brew cleanup -n
or to __disable__ automatic `brew cleanup`:
export HOMEBREW_NO_INSTALL_CLEANUP=1
## How do I uninstall Homebrew? ## How do I uninstall Homebrew?
To uninstall Homebrew, run the [uninstall script from the Homebrew/install repository](https://github.com/homebrew/install#uninstall-homebrew). To uninstall Homebrew, run the [uninstall script from the Homebrew/install repository](https://github.com/homebrew/install#uninstall-homebrew).
## How do I uninstall a formula? ## How can I keep old versions of a formula when upgrading?
If you do not uninstall all of the versions that Homebrew has installed, Homebrew automatically uninstalls old versions of a formula after that formula is upgraded with `brew upgrade`, and periodically performs additional cleanup every 30 days.
Homebrew will continue to attempt to install the newest version it knows
about when you run `brew upgrade`. This can be surprising.
To remove a formula entirely, you may run `brew uninstall --force <formula>`. To __disable__ automatic `brew cleanup`:
Be careful as this is a destructive operation. export HOMEBREW_NO_INSTALL_CLEANUP=1
When automatic `brew cleanup` is disabled, if you uninstall a formula, it will only remove the latest version you have installed. It will not remove all versions of the formula that you may have installed in the past. Homebrew will continue to attempt to install the newest version it knows about when you run `brew upgrade`. This can be surprising.
In this case, to remove a formula entirely, you may run `brew uninstall --force <formula>`. Be careful as this is a destructive operation.
## Where does stuff get downloaded? ## Where does stuff get downloaded?
@ -66,12 +52,7 @@ Be careful as this is a destructive operation.
Which is usually: `~/Library/Caches/Homebrew` Which is usually: `~/Library/Caches/Homebrew`
## My Mac `.app`s don’t find `/usr/local/bin` utilities! ## 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 GUI apps on macOS don’t have `/usr/local/bin` in their `PATH` by default. If you're on Mountain Lion or later, you can fix this by running `sudo launchctl config user path "/usr/local/bin:$PATH"` and then rebooting, as documented in `man launchctl`. Note that this sets the launchctl `PATH` for *all users*. For earlier versions of macOS, see [this page](https://developer.apple.com/legacy/library/qa/qa1067/_index.html).
default. If you’re on Mountain Lion or later, you can fix this by
running `sudo launchctl config user path "/usr/local/bin:$PATH"` and
then rebooting, as documented in `man launchctl`. Note that this sets
the launchctl PATH for *all users*. For earlier versions of macOS, see
[this page](https://developer.apple.com/legacy/library/qa/qa1067/_index.html).
## How do I contribute to Homebrew? ## How do I contribute to Homebrew?
Read our [contribution guidelines](https://github.com/Homebrew/brew/blob/HEAD/CONTRIBUTING.md#contributing-to-homebrew). Read our [contribution guidelines](https://github.com/Homebrew/brew/blob/HEAD/CONTRIBUTING.md#contributing-to-homebrew).
@ -104,10 +85,6 @@ cd $(brew --repository)
hub pull someone_else hub pull someone_else
``` ```
Or:
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`?
1. **It’s easier**<br>`/usr/local/bin` is already in your 1. **It’s easier**<br>`/usr/local/bin` is already in your
@ -121,9 +98,7 @@ Or:
there are no files in `/usr/local` by default, so there there are no files in `/usr/local` by default, so there
is no need to worry about messing up existing or system tools. is no need to worry about messing up existing or system tools.
**If you plan to install gems that depend on **If you plan to install gems that depend on formulae then save yourself a bunch of hassle and install to `/usr/local`!**
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". 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".
@ -156,7 +131,7 @@ If it’s not in `man brew`, it’s probably an external command. These are docu
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. 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? ## Can I edit formulae myself?
Yes! It’s easy! Just `brew edit <formula>`. You don’t have to submit modifications back to `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/core`, just edit the formula as you personally need it and `brew install <formula>`. 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 formula in Yes! It’s easy! Just `brew create URL`. Homebrew will then open the formula in
@ -191,25 +166,19 @@ $ brew link foo
Linking /usr/local/Cellar/foo/0.1… 17 symlinks created Linking /usr/local/Cellar/foo/0.1… 17 symlinks created
``` ```
## Why was a formula deleted? ## Why was a formula deleted or disabled?
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](Acceptable-Formulae.md) and/or [our analytics](Analytics.md) identified it was not widely used.
our analytics identified it was not widely used.
For disabled and deprecated formulae, running `brew info <formula>` will also provide an explanation.
## Homebrew is a poor name, it's too 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 Homebrew's creator @mxcl was too concerned with the beer theme and didn't consider that the project may actually prove popular. By the time Max realised that it was popular, it was too late. However, today, the first Google hit for "homebrew" is not beer related 😉
project may actually prove popular. By the time Max realised that it
was popular, it was too late. However, today, the first Google hit for
“homebrew” is not beer related ;&#8209;)
## 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 and is not linked into `/usr/local`. This means most tools will not find it. You can see why a formula was installed as keg-only, and instructions to include it in your `PATH`, by running `brew info <formula>`.
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 You can still link in the formula if you need to with `brew link <formula>`, though this can cause unexpected behaviour if you are shadowing macOS software.
to with `brew link`.
## How can I specify different configure arguments for a formula? ## How can I specify different configure arguments for a formula?
`brew edit <formula>` and edit the formula. Currently there is no `brew edit <formula>` and edit the formula. Currently there is no
other way to do this. other way to do this.
## Is there a glossary of terms around?
All your terminology needs can be [found here](Formula-Cookbook.md#homebrew-terminology).

2
docs/Migrating-A-Formula-To-A-Tap.md
View File

@ -7,3 +7,5 @@ There are times when we may wish to migrate a formula from one tap into another
3. Put a link for each pull request in the other pull request so the maintainers can merge them both at once. 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! Congratulations, you've moved a formula to a tap!
For Homebrew maintainers, formulae should only ever be migrated into and within the Homebrew organisation (e.g. from Homebrew/core to Homebrew/cask, or from a third-party tap to Homebrew/core), and never out of it.

6
docs/Node-for-Formula-Authors.md
View File

@ -32,11 +32,11 @@ Node modules which are compatible with the latest Node version should declare a
depends_on "node" depends_on "node"
``` ```
If your formula requires being executed with an older Node version you should use one of the versioned node formulae (e.g. `node@6`). If your formula requires being executed with an older Node version you should use one of the versioned node formulae (e.g. `node@12`).
### 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 an 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).
```ruby ```ruby
depends_on "python" => :build depends_on "python" => :build
@ -75,8 +75,6 @@ This will install your Node module in npm's global module style with a custom pr
bin.install_symlink Dir["#{libexec}/bin/*"] bin.install_symlink Dir["#{libexec}/bin/*"]
``` ```
**Note:** Because of a required workaround for `npm@5` calling `npm pack` we currently don't support installing modules (from non-npm registry tarballs), which require a prepublish step (e.g. for transpiling sources). See [Homebrew/brew#2820](https://github.com/Homebrew/brew/pull/2820) for more information.
### Installing module dependencies locally with `local_npm_install_args` ### 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 then `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: In your formula's `install` method, do any installation steps which need to be done before the `npm install` step and then `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:

3
docs/README.md
View File

@ -26,12 +26,13 @@
- [Python](Homebrew-and-Python.md) - [Python](Homebrew-and-Python.md)
- [How To Build Software Outside Homebrew With Homebrew `keg_only` dependencies](How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md) - [How To Build Software Outside Homebrew With Homebrew `keg_only` dependencies](How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md)
- [Xcode](Xcode.md) - [Xcode](Xcode.md)
- [Kickstarter Supporters](Kickstarter-Supporters.md)
- [Creating a Homebrew Issue](Creating-a-Homebrew-Issue.md) - [Creating a Homebrew Issue](Creating-a-Homebrew-Issue.md)
- [Updating Software in Homebrew](Updating-Software-in-Homebrew.md) - [Updating Software in Homebrew](Updating-Software-in-Homebrew.md)
- [Adding Software to Homebrew](Adding-Software-to-Homebrew.md) - [Adding Software to Homebrew](Adding-Software-to-Homebrew.md)
- [Kickstarter Supporters](Kickstarter-Supporters.md)
## Contributors ## Contributors
- [How To Open A Pull Request (and get it merged)](How-To-Open-a-Homebrew-Pull-Request.md) - [How To Open A Pull Request (and get it merged)](How-To-Open-a-Homebrew-Pull-Request.md)

1
docs/Troubleshooting.md
View File

@ -12,6 +12,7 @@ This document will help you check for common issues and make sure your issue has
* Search the [Homebrew/homebrew-core issue tracker](https://github.com/Homebrew/homebrew-core/issues) or [Homebrew/linuxbrew-core issue tracker](https://github.com/Homebrew/linuxbrew-core/issues) to see if someone else has already reported the same issue. * Search the [Homebrew/homebrew-core issue tracker](https://github.com/Homebrew/homebrew-core/issues) or [Homebrew/linuxbrew-core issue tracker](https://github.com/Homebrew/linuxbrew-core/issues) to see if someone else has already reported the same issue.
* If a formula that has failed to build is part of a non-core tap or a cask is part of [homebrew/cask](https://github.com/Homebrew/homebrew-cask/issues) check those issue trackers instead. * If a formula that has failed to build is part of a non-core tap or a cask is part of [homebrew/cask](https://github.com/Homebrew/homebrew-cask/issues) check those issue trackers instead.
* Search the [Homebrew discussion forum](https://github.com/homebrew/discussions/discussions) or [Discourse](https://discourse.brew.sh/) to see if any discussions have started about the issue.
## Create an issue ## Create an issue