Merge pull request #11717 from MikeMcQuaid/docs-usr-local

docs: update /usr/local references.

docs/Bottles.md

@@ -48,7 +48,7 @@ By default this is omitted and the Homebrew default bottle URL root is used. Thi
 
 ### Cellar (`cellar`)
 Optionally contains the value of `HOMEBREW_CELLAR` in which the bottles were built.
-Most compiled software contains references to its compiled location so cannot be simply relocated anywhere on disk. If this value is `:any` or `:any_skip_relocation` this means that the bottle can be safely installed in any Cellar as it did not contain any references to its installation Cellar. This can be omitted if a bottle is compiled (as all default Homebrew ones are) for the default `HOMEBREW_CELLAR` of `/usr/local/Cellar`.
+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`.
 
 ### Rebuild version (`rebuild`)
 Optionally contains the rebuild version of the bottle.

docs/External-Commands.md

@@ -26,10 +26,10 @@ An executable script for a command named `extcmd` should be named `brew-extcmd`.
 | Variable               | Description                                                                                                                                                                 |
 |------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `HOMEBREW_CACHE`       | Where Homebrew caches downloaded tarballs to, by default `~/Library/Caches/Homebrew`.                                                                                       |
+| `HOMEBREW_PREFIX`      | Where Homebrew installs software. `/usr/local` by default for macOS Intel, `/opt/homebrew` for Apple Silicon and `/home/linuxbrew/.linuxbrew` for Linux.                    |
 | `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`  | The Git repository directory (i.e. where Homebrew’s `.git` directory lives). Usually either the same as `HOMEBREW_PREFIX` or a `Homebrew` subdirectory`.                    |
-| `HOMEBREW_REPOSITORY`  | If installed from a Git clone, the repository directory (i.e. where Homebrew’s `.git` directory lives).                                                                       |
 
 ## Providing `--help`
 
@@ -37,28 +37,6 @@ All internal and external Homebrew commands can provide styled `--help` output b
 
 For example, see the [header of `brew-services.rb`](https://github.com/Homebrew/homebrew-services/blob/a58a1fe9145de4e50e1cbfb5b0e8a30087826393/cmd/brew-services.rb#L1-L23) which is output with `brew services --help`.
 
-## Homebrew organisation external commands
-
-### homebrew-command-not-found
-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.
-
-Install using:
-
-```sh
-brew tap homebrew/command-not-found
-```
-
-### homebrew-aliases
-Allows you to alias your Homebrew commands.
-See the [`README`](https://github.com/Homebrew/homebrew-aliases/blob/HEAD/README.md) for more info and usage.
-
-Install using:
-
-```sh
-brew tap homebrew/aliases
-```
-
 ## Unofficial external commands
 These commands have been contributed by Homebrew users but are not included in the main Homebrew organisation, nor are they installed by the installer script. You can install them manually, as outlined above.
 

docs/FAQ.md

@@ -54,8 +54,8 @@ Homebrew doesn't support arbitrary mixing and matching of formula versions, so e
 
 Which is usually: `~/Library/Caches/Homebrew`
 
-## My Mac `.app`s don’t find `/usr/local/bin` utilities!
+## My Mac `.app`s don’t find Homebrew utilities!
-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).
+GUI apps on macOS don’t have Homebrew's prefix in their `PATH` by default. If you're on Mountain Lion or later, you can fix this by running `sudo launchctl config user path "$(brew --prefix)/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?
 Read our [contribution guidelines](https://github.com/Homebrew/brew/blob/HEAD/CONTRIBUTING.md#contributing-to-homebrew).
@@ -74,8 +74,8 @@ will use a bottled version of the formula, but
 * The `--build-from-source` option is invoked.
 * The machine is not running a supported version of macOS as all
 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 default
-`/usr/local` (although some bottles support this).
+(although some bottles support this).
 
 We aim to bottle everything.
 
@@ -90,24 +90,11 @@ hub pull someone_else
 
 ## Why should I install Homebrew in the default location?
 
-Homebrew's pre-built binary packages (known as [bottles](Bottles.md)) of many packages can only be used if you install in the default installation prefix, otherwise they have to be built from source. Building from source takes a long time, is prone to fail, and is not supported. Do yourself a favour and install to the default prefix so that you can use our pre-built binary packages. The default prefix is `/usr/local` for macOS on Intel, `/opt/homebrew` for macOS on ARM, and `/home/linuxbrew/.linuxbrew` for Linux. *Pick another prefix at your peril!*
+Homebrew's pre-built binary packages (known as [bottles](Bottles.md)) of many packages can only be used if you install in the default installation prefix, otherwise they have to be built from source. Building from source takes a long time, is prone to fail, and is not supported. Do yourself a favour and install to the default prefix so that you can use our pre-built binary packages. The default prefix is `/usr/local` for macOS on Intel, `/opt/homebrew` for macOS on Apple Silicon/ARM, and `/home/linuxbrew/.linuxbrew` for Linux. *Pick another prefix at your peril!*
 
-## Why does Homebrew prefer I install to `/usr/local`?
+## Why is the default installation prefix `/opt/homebrew` on Apple Silicon?
 
-1.  **It’s easier**<br>`/usr/local/bin` is already in your
+The prefix `/opt/homebrew` was chosen to allow installations in `/opt/homebrew` for Apple Silicon and `/usr/local` for Rosetta 2 to coexist and use bottles.
-    `PATH`.
-2.  **It’s easier**<br>Tons of build scripts break if their dependencies
-    aren’t in either `/usr` or `/usr/local`. We
-    fix this for Homebrew formulae (although we don’t always test for
-    it), but you’ll find that many RubyGems and Python setup scripts
-    break which is something outside our control.
-3.  **It’s safe**<br>Apple has assigned this directory for non-system utilities. This means
-    there are no files in `/usr/local` by default, so there
-    is no need to worry about messing up existing or system tools.
-
-**If you plan to install gems that depend on formulae then save yourself a bunch of hassle and install to `/usr/local`!**
-
-It is not always straightforward to tell `gem` to look in non-standard directories for headers and libraries. If you choose `/usr/local`, many things will "just work".
 
 ## Why is the default installation prefix `/home/linuxbrew/.linuxbrew` on Linux?
 
@@ -154,29 +141,6 @@ into a debugging shell.
 If you want your new formula to be part of `homebrew/core` or want
 to learn more about writing formulae, then please read the [Formula Cookbook](Formula-Cookbook.md).
 
-## Can I install my own stuff to `/usr/local`?
-Yes, `brew` is designed to not get in your way so you can use it how you
-like.
-
-Install your own stuff, but be aware that if you install common
-libraries like libexpat yourself, it may cause trouble when trying to
-build certain Homebrew formula. As a result `brew doctor` will warn you
-about this.
-
-Thus it’s probably better to install your own stuff to the Cellar and
-then `brew link` it. Like so:
-
-```sh
-$ cd foo-0.1
-$ brew diy
-./configure --prefix=/usr/local/Cellar/foo/0.1
-$ ./configure --prefix=/usr/local/Cellar/foo/0.1
-[snip]
-$ make && make install
-$ brew link foo
-Linking /usr/local/Cellar/foo/0.1… 17 symlinks created
-```
-
 ## Why was a formula deleted or disabled?
 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.
 
@@ -186,7 +150,7 @@ For disabled and deprecated formulae, running `brew info <formula>` will also pr
 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 😉
 
 ## What does "keg-only" mean?
-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>`.
+It means the formula is installed only into the Cellar and is not linked into the default prefix. 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>`.
 
 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.
 

docs/Gems,-Eggs-and-Perl-Modules.md

@@ -23,7 +23,7 @@ is probably safer than changing the group ownership of the directory.
 Habit maybe?
 
 One reason is executables go in `/usr/local/bin`. Usually this isn’t a
-writable location. But if you installed Homebrew as we recommend,
+writable location. But if you installed Homebrew as we recommend on macOS Intel,
 `/usr/local` will be writable without sudo. So now you are good to
 install the development tools you need without risking the use of sudo.
 

docs/How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md

@@ -8,7 +8,7 @@ As an example:
 
 *OpenSSL isn’t symlinked into my `PATH` and non-Homebrew builds can’t find it!*
 
-This is because Homebrew keeps it locked inside its individual prefix, rather than symlinking to the publicly-available location, usually `/usr/local`.
+This is because Homebrew keeps it locked inside its individual prefix, rather than symlinking to the publicly-available location.
 
 ## Advice on potential workarounds
 

docs/Installation.md

@@ -3,10 +3,10 @@
 Instructions for a supported install of Homebrew are on the [homepage](https://brew.sh).
 
 This script installs Homebrew to its preferred prefix (`/usr/local`
-for macOS Intel, `/opt/homebrew` for Apple Silicon) so that
+for macOS Intel, `/opt/homebrew` for Apple Silicon and `/home/linuxbrew/.linuxbrew` for Linux) so that
 [you don’t need sudo](FAQ.md#why-does-homebrew-say-sudo-is-bad) when you
 `brew install`. It is a careful script; it can be run even if you have stuff
-installed in `/usr/local` already. It tells you exactly what it will do before
+installed in the preferred prefix already. It tells you exactly what it will do before
 it does it too. You have to confirm everything it will do before it starts.
 
 ## macOS Requirements
@@ -44,8 +44,7 @@ Just extract (or `git clone`) Homebrew wherever you want. Just avoid:
 * `/tmp` subdirectories because Homebrew gets upset.
 * `/sw` and `/opt/local` because build scripts get confused when Homebrew is there instead of Fink or MacPorts, respectively.
 
-However do yourself a favour and install to `/usr/local` on macOS Intel, `/opt/homebrew` on macOS ARM,
+However do yourself a favour and use the installer to install to the default prefix. Some things may
-and `/home/linuxbrew/.linuxbrew` on Linux. Some things may
 not build when installed elsewhere. One of the reasons Homebrew just
 works relative to the competition is **because** we recommend installing
 here. *Pick another prefix at your peril!*
@@ -56,7 +55,7 @@ mkdir homebrew && curl -L https://github.com/Homebrew/brew/tarball/master | tar
 
 ### Multiple installations
 
-Create a Homebrew installation wherever you extract the tarball. Whichever `brew` command is called is where the packages will be installed. You can use this as you see fit, e.g. a system set of libs in `/usr/local` and tweaked formulae for development in `~/homebrew`.
+Create a Homebrew installation wherever you extract the tarball. Whichever `brew` command is called is where the packages will be installed. You can use this as you see fit, e.g. a system set of libs in the default prefix and tweaked formulae for development in `~/homebrew`.
 
 ## Uninstallation
 

docs/Tips-N'-Tricks.md

@@ -5,22 +5,16 @@
 The supported method of installing specific versions of
 some formulae is to see if there is a versioned formula (e.g. `gcc@7`) available. If the version you’re looking for isn’t available, consider using `brew extract`.
 
-## Quickly remove something from `/usr/local`
+## Quickly remove something from Homebrew's prefix
 
 ```sh
 brew unlink <formula>
 ```
 
-This can be useful if a package can't build against the version of something you have linked into `/usr/local`.
+This can be useful if a package can't build against the version of something you have linked into Homebrew's prefix.
 
 And of course, you can simply `brew link <formula>` again afterwards!
 
-## Install into Homebrew without formulae
-
-```sh
-./configure --prefix=/usr/local/Cellar/foo/1.2 && make && make install && brew link foo
-```
-
 ## Pre-downloading a file for a formula
 Sometimes it's faster to download a file via means other than those
 strategies that are available as part of Homebrew. For example,