diff --git a/Library/Homebrew/brew.rb b/Library/Homebrew/brew.rb index 5894a41b2b..4302b65367 100644 --- a/Library/Homebrew/brew.rb +++ b/Library/Homebrew/brew.rb @@ -151,9 +151,22 @@ rescue BuildError => e e.dump(verbose: args.verbose?) if e.formula.head? || e.formula.deprecated? || e.formula.disabled? + reason = if e.formula.head? + "was built from an unstable upstream --HEAD" + elsif e.formula.deprecated? + "is deprecated" + elsif e.formula.disabled? + "is disabled" + end $stderr.puts <<~EOS - Please create pull requests instead of asking for help on Homebrew's GitHub, - Twitter or any other official channels. + #{e.formula.name}'s formula #{reason}. + This build failure is expected behaviour. + Do not create issues about this on Homebrew's GitHub repositories. + Any opened issues will be immediately closed without response. + Do not ask for help from MacHomebrew on Twitter. + You may ask for help in Homebrew's discussions but are unlikely to receive a response. + Try to figure out the problem yourself and submit a fix as a pull request. + We will review it but may or may not accept it. EOS end diff --git a/Library/Homebrew/diagnostic.rb b/Library/Homebrew/diagnostic.rb index 11149ca2b9..3ba875be8d 100644 --- a/Library/Homebrew/diagnostic.rb +++ b/Library/Homebrew/diagnostic.rb @@ -113,11 +113,15 @@ module Homebrew def please_create_pull_requests(what = "unsupported configuration") <<~EOS - You will encounter build failures with some formulae. - Please create pull requests instead of asking for help on Homebrew's GitHub, - Twitter or any other official channels. You are responsible for resolving - any issues you experience while you are running this - #{what}. + It is expected behaviour that some formulae will fail to build in this #{what}. + It is expected behaviour that Homebrew will be buggy and slow. + Do not create any issues about this on Homebrew's GitHub repositories. + Do not create any issues even if you think this message is unrelated. + Any opened issues will be immediately closed without response. + Do not ask for help from MacHomebrew on Twitter. + You may ask for help in Homebrew's discussions but are unlikely to receive a response. + Try to figure out the problem yourself and submit a fix as a pull request. + We will review it but may or may not accept it. EOS end @@ -878,8 +882,9 @@ module Homebrew <<~EOS Your Homebrew's prefix is not #{Homebrew::DEFAULT_PREFIX}. - Some of Homebrew's bottles (binary packages) can only be used with the default - prefix (#{Homebrew::DEFAULT_PREFIX}). + + Many of Homebrew's bottles (binary packages) can only be used with the default prefix. + Consider uninstalling Homebrew and reinstalling into the default prefix. #{please_create_pull_requests} EOS end diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb index 3c1c31a67b..a0919625fb 100644 --- a/Library/Homebrew/formula.rb +++ b/Library/Homebrew/formula.rb @@ -3306,7 +3306,7 @@ class Formula when :default_prefix lambda do |_| T.cast(self, PourBottleCheck).reason(+<<~EOS) - The bottle needs to be installed into #{Homebrew::DEFAULT_PREFIX}. + The bottle (and many others) needs to be installed into #{Homebrew::DEFAULT_PREFIX}. EOS T.cast(self, PourBottleCheck).satisfy { HOMEBREW_PREFIX.to_s == Homebrew::DEFAULT_PREFIX } end diff --git a/Library/Homebrew/formula_installer.rb b/Library/Homebrew/formula_installer.rb index b375f8dfc0..b96764e008 100644 --- a/Library/Homebrew/formula_installer.rb +++ b/Library/Homebrew/formula_installer.rb @@ -268,12 +268,18 @@ class FormulaInstaller if message message += <<~EOS - You can try to install from source with: + If you're feeling brave, you can try to install from source with: brew install --build-from-source #{formula} - Please note building from source is unsupported. You will encounter build - failures with some formulae. If you experience any issues please create pull - requests instead of asking for help on Homebrew's GitHub, Twitter or any other - official channels. + + It is expected behaviour that most formulae will fail to build from source. + It is expected behaviour that Homebrew will be buggy and slow when building from source. + Do not create any issues about failures building from source on Homebrew's GitHub repositories. + Do not create any issues building from source even if you think this message is unrelated. + Any opened issues will be immediately closed without response. + Do not ask for help building from source from MacHomebrew on Twitter. + You may ask for help building from source in Homebrew's discussions but are unlikely to receive a response. + If building from source fails, try to figure out the problem yourself and submit a fix as a pull request. + We will review it but may or may not accept it. EOS raise CannotInstallFormulaError, message end diff --git a/docs/Homebrew-on-Linux.md b/docs/Homebrew-on-Linux.md index cc18fb166b..ee38edea86 100644 --- a/docs/Homebrew-on-Linux.md +++ b/docs/Homebrew-on-Linux.md @@ -15,16 +15,17 @@ The Homebrew package manager may be used on Linux and [Windows Subsystem for Lin ## Features -- Can install software to your home directory and so does not require *sudo* - Install software not packaged by your host distribution - Install up-to-date versions of software when your host distribution is old - Use the same package manager to manage your macOS, Linux, and Windows systems ## Install -Instructions for a supported install of Homebrew on Linux are on the [homepage](https://brew.sh). +Instructions for the best, supported install of Homebrew on Linux are on the [homepage](https://brew.sh). -The installation script installs Homebrew to `/home/linuxbrew/.linuxbrew` using *sudo* if possible and within your home directory at `~/.linuxbrew` otherwise. Homebrew does not use *sudo* after installation. Using `/home/linuxbrew/.linuxbrew` allows the use of more binary packages (bottles) than installing in your personal home directory. +The installation script installs Homebrew to `/home/linuxbrew/.linuxbrew` using *sudo* if possible and within your home directory at `~/.linuxbrew` otherwise. Homebrew does not use *sudo* after installation. Using `/home/linuxbrew/.linuxbrew` allows the use of most binary packages (bottles) which will not work when installing in e.g. your personal home directory. + +Technically, you can install Homebrew wherever you want. However, you shouldn't install outside the default, supported, best prefix. Many things will need to be built from source outside the default prefix. Building from source is slow, energy-inefficient, buggy and unsupported. The main reason Homebrew just works is **because** we use bottles (binary packages) and most of these require using the default prefix. If you decide to use another prefix: don't open any issues, even if you think they are unrelated to your prefix choice. They will be closed without response. The prefix `/home/linuxbrew/.linuxbrew` was chosen so that users without admin access can ask an admin to create a `linuxbrew` role account and still benefit from precompiled binaries. If you do not yourself have admin privileges, consider asking your admin staff to create a `linuxbrew` role account for you with home directory set to `/home/linuxbrew`. @@ -68,15 +69,15 @@ To install build tools, paste at a terminal prompt: sudo yum install libxcrypt-compat # needed by Fedora 30 and up ``` -### ARM +### ARM (unsupported) -Homebrew can run on 32-bit ARM (Raspberry Pi and others) and 64-bit ARM (AArch64), but no binary packages (bottles) are available. Support for ARM is on a best-effort basis. Pull requests are welcome to improve the experience on ARM platforms. +Homebrew can run on 32-bit ARM (Raspberry Pi and others) and 64-bit ARM (AArch64), but as they lack binary packages (bottles) they are unsupported. Pull requests are welcome to improve the experience on ARM platforms. You may need to install your own Ruby using your system package manager, a PPA, or `rbenv/ruby-build` as we no longer distribute a Homebrew Portable Ruby for ARM. -### 32-bit x86 +### 32-bit x86 (incompatible) -Homebrew does not currently support 32-bit x86 platforms. It would be possible for Homebrew to work on 32-bit x86 platforms with some effort. An interested and dedicated person could maintain a fork of Homebrew to develop support for 32-bit x86. +Homebrew does not run at all on 32-bit x86 platforms. ### Windows Subsystem for Linux (WSL) 1 diff --git a/docs/Installation.md b/docs/Installation.md index e097bbe75d..b71bebac22 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -2,7 +2,7 @@ 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 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 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. +This script installs Homebrew to its default, supported, best prefix (`/usr/local` for macOS Intel, `/opt/homebrew` for Apple Silicon and `/home/linuxbrew/.linuxbrew` for Linux) so that [you don’t need `sudo` after Homebrew's initial installation](FAQ.md#why-does-homebrew-say-sudo-is-bad) when you `brew install`. This prefix is required for most bottles (binary packages) to be used. It is a careful script; it can be run even if you have stuff 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 @@ -36,21 +36,21 @@ export HOMEBREW_INSTALL_FROM_API=1 This will make Homebrew install formulae and casks in homebrew/core and homebrew/cask taps using Homebrew’s API instead of local checkouts of these repositories. +## Unattended installation + +If you want a non-interactive run of the Homebrew installer that doesn't prompt for passwords (e.g. in automation scripts), prepend [`NONINTERACTIVE=1`](https://github.com/Homebrew/install/#install-homebrew-on-macos-or-linux) to the installation command. + ## Alternative Installs ### Linux or Windows 10 Subsystem for Linux Check out [the Homebrew on Linux installation documentation](Homebrew-on-Linux.md). -### Untar anywhere +### Untar anywhere (unsupported) -Just extract (or `git clone`) Homebrew wherever you want. Just avoid: +Technically, you can just extract (or `git clone`) Homebrew wherever you want. However, you shouldn't install outside the default, supported, best prefix. Many things will need to be built from source outside the default prefix. Building from source is slow, energy-inefficient, buggy and unsupported. The main reason Homebrew just works is **because** we use bottles (binary packages) and most of these require using the default prefix. If you decide to use another prefix: don't open any issues, even if you think they are unrelated to your prefix choice. They will be closed without response. -* Directories with names that contain spaces. Homebrew itself can handle spaces, but many build scripts cannot. -* `/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 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!* +**TL;DR: pick another prefix at your peril!** ```sh mkdir homebrew && curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew @@ -70,22 +70,24 @@ brew update --force --quiet chmod -R go-w "$(brew --prefix)/share/zsh" ``` -### Multiple installations +Make sure you avoid installing into: + +* Directories with names that contain spaces. Homebrew itself can handle spaces, but many build scripts cannot. +* `/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. + +### Multiple installations (unsupported) 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. to have a system set of libs in the default prefix and tweaked formulae for development in `~/homebrew`. -### Unattended installation - -If you want a non-interactive run of the Homebrew installer that doesn't prompt for passwords (e.g. in automation scripts), prepend [`NONINTERACTIVE=1`](https://github.com/Homebrew/install/#install-homebrew-on-macos-or-linux) to the installation command. - ## Uninstallation Uninstallation is documented in the [FAQ](FAQ.md). 1 For 32-bit or PPC support see [Tigerbrew](https://github.com/mistydemeo/tigerbrew). -2 11 or higher is recommended, while 10.11–10.15 are supported on a best-effort basis. For 10.4–10.6 see [Tigerbrew](https://github.com/mistydemeo/tigerbrew). +2 macOS 11 (Ventura) or higher is best and supported, 10.11 (El Capitan) – 10.14 (Mojave) are unsupported but may work and 10.10 (Yosemite) and older will not run Homebrew at all. For 10.4 (Tiger) – 10.6 (Snow Leopard) see [Tigerbrew](https://github.com/mistydemeo/tigerbrew). -3 Most formulae require a compiler. A handful require a full Xcode installation. You can install Xcode, the CLT, or both; Homebrew supports all three configurations. Downloading Xcode may require an Apple Developer account on older versions of Mac OS X. Sign up for free at [Apple's website](https://developer.apple.com/register/index.action). +3 You may need to install Xcode, the CLT, or both depending on the formula, to install a bottle (binary package) which is the only supported configuration. Downloading Xcode may require an Apple Developer account on older versions of Mac OS X. Sign up for free at [Apple's website](https://developer.apple.com/register/index.action). -4 The one-liner installation method found on [brew.sh](https://brew.sh) requires the Bourne-again shell, i.e. `bash`. Notably, `zsh`, `fish`, `tcsh` and `csh` will not work. +4 The one-liner installation method found on [brew.sh](https://brew.sh) uses the Bourne-again shell at `/bin/bash`. Notably, `zsh`, `fish`, `tcsh` and `csh` will not work.