mirrors/brew
1
0
Fork 0
mirror of https://github.com/Homebrew/brew.git synced 2025-07-14 16:09:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

Strengthen "don't create issues" language

Browse Source 
We're still getting a non-trivial number of issues from configurations
we don't support and don't plan to.

Let people know that we know their experience will not be good and what
to expect if they file issues.

Co-authored-by: Eric Knibbe <enk3@outlook.com>
This commit is contained in:
Mike McQuaid 2022-10-06 10:01:02 +01:00
parent 38cb504898
commit 53b1c0f48e
No known key found for this signature in database
GPG Key ID: 3338A31AFDB1D829
6 changed files with 65 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
Library/Homebrew/brew.rb
View File

@ -151,9 +151,22 @@ rescue BuildError => e
e.dump(verbose: args.verbose?) e.dump(verbose: args.verbose?)
if e.formula.head? || e.formula.deprecated? || e.formula.disabled? 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 $stderr.puts <<~EOS
Please create pull requests instead of asking for help on Homebrew's GitHub, #{e.formula.name}'s formula #{reason}.
Twitter or any other official channels. 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 EOS
end end

19
Library/Homebrew/diagnostic.rb
View File

@ -113,11 +113,15 @@ module Homebrew
def please_create_pull_requests(what = "unsupported configuration") def please_create_pull_requests(what = "unsupported configuration")
<<~EOS <<~EOS
You will encounter build failures with some formulae. It is expected behaviour that some formulae will fail to build in this #{what}.
Please create pull requests instead of asking for help on Homebrew's GitHub, It is expected behaviour that Homebrew will be buggy and slow.
Twitter or any other official channels. You are responsible for resolving Do not create any issues about this on Homebrew's GitHub repositories.
any issues you experience while you are running this Do not create any issues even if you think this message is unrelated.
#{what}. 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 EOS
end end
@ -878,8 +882,9 @@ module Homebrew
<<~EOS <<~EOS
Your Homebrew's prefix is not #{Homebrew::DEFAULT_PREFIX}. 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} #{please_create_pull_requests}
EOS EOS
end end

2
Library/Homebrew/formula.rb
View File

@ -3306,7 +3306,7 @@ class Formula
when :default_prefix when :default_prefix
lambda do |_| lambda do |_|
T.cast(self, PourBottleCheck).reason(+<<~EOS) 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 EOS
T.cast(self, PourBottleCheck).satisfy { HOMEBREW_PREFIX.to_s == Homebrew::DEFAULT_PREFIX } T.cast(self, PourBottleCheck).satisfy { HOMEBREW_PREFIX.to_s == Homebrew::DEFAULT_PREFIX }
end end

16
Library/Homebrew/formula_installer.rb
View File

@ -268,12 +268,18 @@ class FormulaInstaller
if message if message
message += <<~EOS 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} 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 It is expected behaviour that most formulae will fail to build from source.
requests instead of asking for help on Homebrew's GitHub, Twitter or any other It is expected behaviour that Homebrew will be buggy and slow when building from source.
official channels. 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 EOS
raise CannotInstallFormulaError, message raise CannotInstallFormulaError, message
end end

15
docs/Homebrew-on-Linux.md
View File

@ -15,16 +15,17 @@ The Homebrew package manager may be used on Linux and [Windows Subsystem for Lin
## Features ## Features
- Can install software to your home directory and so does not require *sudo*
- Install software not packaged by your host distribution - Install software not packaged by your host distribution
- Install up-to-date versions of software when your host distribution is old - 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 - Use the same package manager to manage your macOS, Linux, and Windows systems
## Install ## 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`. 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 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. 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 ### Windows Subsystem for Linux (WSL) 1

34
docs/Installation.md
View File

@ -2,7 +2,7 @@
Instructions for a supported install of Homebrew are on the [homepage](https://brew.sh). 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 ## 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. 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 ## Alternative Installs
### Linux or Windows 10 Subsystem for Linux ### Linux or Windows 10 Subsystem for Linux
Check out [the Homebrew on Linux installation documentation](Homebrew-on-Linux.md). 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. **TL;DR: pick another prefix at your peril!**
* `/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!*
```sh ```sh
mkdir homebrew && curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew 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" 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`. 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
Uninstallation is documented in the [FAQ](FAQ.md). Uninstallation is documented in the [FAQ](FAQ.md).
<a name="1"><sup>1</sup></a> For 32-bit or PPC support see [Tigerbrew](https://github.com/mistydemeo/tigerbrew). <a name="1"><sup>1</sup></a> For 32-bit or PPC support see [Tigerbrew](https://github.com/mistydemeo/tigerbrew).
<a name="2"><sup>2</sup></a> 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). <a name="2"><sup>2</sup></a> 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).
<a name="3"><sup>3</sup></a> 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). <a name="3"><sup>3</sup></a> 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).
<a name="4"><sup>4</sup></a> 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. <a name="4"><sup>4</sup></a> 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.