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

docs: update /usr/local references.

Browse Source 
Update or remove these based on our latest state.
This commit is contained in:
Mike McQuaid 2021-07-14 10:11:27 +01:00
parent cb84000e72
commit 0a8167d2dc
No known key found for this signature in database
GPG Key ID: 3338A31AFDB1D829
7 changed files with 19 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/Bottles.md
View File

@ -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.

26
docs/External-Commands.md
View File

@ -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` | If installed from a Git clone, the repository directory (i.e. where Homebrew’s `.git` directory lives). |
| `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`. |
## 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.

52
docs/FAQ.md
View File

@ -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!
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).
## My Mac `.app`s don’t find Homebrew utilities!
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
`/usr/local` (although some bottles support this).
* Homebrew is installed to a prefix other than the default
(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
`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".
The prefix `/opt/homebrew` was chosen to allow `/opt/homebrew` Apple Silicon and `/usr/local` Rosetta 2 installation to coexist and both use bottles.
## 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.

2
docs/Gems,-Eggs-and-Perl-Modules.md
View File

@ -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.

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

@ -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

9
docs/Installation.md
View File

@ -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,
and `/home/linuxbrew/.linuxbrew` on Linux. Some things may
However do yourself a favour and use the installer to install to the default prefix. 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

10
docs/Tips-N'-Tricks.md
View File

@ -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,