diff --git a/docs/.mdl_ruleset.rb b/docs/.mdl_ruleset.rb new file mode 100644 index 0000000000..a32f752d2e --- /dev/null +++ b/docs/.mdl_ruleset.rb @@ -0,0 +1,7 @@ +rule 'HB034', 'Bare unstyled URL used' do + tags :links, :url + aliases 'no-bare-unstyled-urls' + check do |doc| + doc.matching_text_element_lines(%r{(?<=\s)https?://}) + end +end diff --git a/docs/.mdl_style.rb b/docs/.mdl_style.rb new file mode 100644 index 0000000000..3466dc4ffd --- /dev/null +++ b/docs/.mdl_style.rb @@ -0,0 +1,7 @@ +all +rule 'MD026', punctuation: ',;:' # Trailing punctuation in header +exclude_rule 'MD013' # Line length +exclude_rule 'MD029' # Ordered list item prefix +exclude_rule 'MD033' # Inline HTML +exclude_rule 'MD034' # Bare URL used (replaced by HB034) +exclude_rule 'MD046' # Code block style diff --git a/docs/.mdlrc b/docs/.mdlrc new file mode 100644 index 0000000000..7bb460e414 --- /dev/null +++ b/docs/.mdlrc @@ -0,0 +1,4 @@ +git_recurse true +ignore_front_matter true +style "#{File.dirname(__FILE__)}/.mdl_style.rb" +rulesets ["#{File.dirname(__FILE__)}/.mdl_ruleset.rb"] diff --git a/docs/Adding-Software-to-Homebrew.md b/docs/Adding-Software-to-Homebrew.md index 1d1106087b..bbdb55eb27 100644 --- a/docs/Adding-Software-to-Homebrew.md +++ b/docs/Adding-Software-to-Homebrew.md @@ -9,6 +9,7 @@ Next, you will want to go through the [Acceptable Formulae](Acceptable-Formulae. If everything checks out, you're ready to get started on a new formula! ## Writing the formula + 1. It's a good idea to find existing formulae in Homebrew that have similarities to the software you want to add. This will help you to understand how specific languages, build methods, etc. are typically handled. 1. If you're starting from scratch, the [`brew create` command](Manpage.md#create-options-url) can be used to produce a basic version of your formula. This command accepts a number of options and you may be able to save yourself some work by using an appropriate template option like `--python`. diff --git a/docs/Common-Issues.md b/docs/Common-Issues.md index 77d261f0b7..3b7f14e8f2 100644 --- a/docs/Common-Issues.md +++ b/docs/Common-Issues.md @@ -2,16 +2,22 @@ This is a list of commonly encountered problems, known issues, and their solutions. +## Running `brew` + ### `brew` complains about absence of "Command Line Tools" + You need to have the Xcode Command Line Utilities installed (and updated): run `xcode-select --install` in the terminal. ### Ruby: `bad interpreter: /usr/bin/ruby^M: no such file or directory` -You cloned with `git`, and your Git configuration is set to use Windows line endings. See this page: + +You cloned with `git`, and your Git configuration is set to use Windows line endings. See this page on [configuring Git to handle line endings](https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings). ### Ruby: `bad interpreter: /usr/bin/ruby` + You don't have a `/usr/bin/ruby` or it is not executable. It's not recommended to let this persist; you'd be surprised how many `.app`s, tools and scripts expect your macOS-provided files and directories to be *unmodified* since macOS was installed. ### `brew update` complains about untracked working tree files + After running `brew update`, you receive a Git error warning about untracked files or local changes that would be overwritten by a checkout or merge, followed by a list of files inside your Homebrew installation. This is caused by an old bug in in the `update` code that has long since been fixed. However, the nature of the bug requires that you do the following: @@ -29,44 +35,39 @@ git clean -fd ``` ### `launchctl` refuses to load launchd plist files -When trying to load a plist file into launchctl, you receive an error that resembles -``` -Bug: launchctl.c:2325 (23930):13: (dbfd = open(g_job_overrides_db_path, [...] -launch_msg(): Socket is not connected -``` +When trying to load a plist file with `launchctl`, you receive an error that resembles either: -or + Bug: launchctl.c:2325 (23930):13: (dbfd = open(g_job_overrides_db_path, [...] + launch_msg(): Socket is not connected -``` -Could not open job overrides database at: /private/var/db/launchd.db/com.apple.launchd/overrides.plist: 13: Permission denied -launch_msg(): Socket is not connected -``` +or: + + Could not open job overrides database at: /private/var/db/launchd.db/com.apple.launchd/overrides.plist: 13: Permission denied + launch_msg(): Socket is not connected These are likely due to one of four issues: 1. You are using iTerm. The solution is to use Terminal.app when interacting with `launchctl`. -2. You are using a terminal multiplexer such as `tmux` or `screen`. You should interact with `launchctl` from a separate Terminal.app shell. -3. You are attempting to run `launchctl` while logged in remotely. You should enable screen sharing on the remote machine and issue the command using Terminal.app running on that machine. -4. You are `su`'ed as a different user. +1. You are using a terminal multiplexer such as `tmux` or `screen`. You should interact with `launchctl` from a separate Terminal.app shell. +1. You are attempting to run `launchctl` while logged in remotely. You should enable screen sharing on the remote machine and issue the command using Terminal.app running on that machine. +1. You are `su`'ed as a different user. ### `brew upgrade` errors out + When running `brew upgrade`, you see something like this: -``` -$ brew upgrade -Error: undefined method `include?' for nil:NilClass -Please report this bug: - https://docs.brew.sh/Troubleshooting -/usr/local/Library/Homebrew/formula.rb:393:in `canonical_name' -/usr/local/Library/Homebrew/formula.rb:425:in `factory' -/usr/local/Library/Contributions/examples/brew-upgrade.rb:7 -/usr/local/Library/Contributions/examples/brew-upgrade.rb:7:in `map' -/usr/local/Library/Contributions/examples/brew-upgrade.rb:7 -/usr/local/bin/brew:46:in `require' -/usr/local/bin/brew:46:in `require?' -/usr/local/bin/brew:79 -``` + Error: undefined method `include?' for nil:NilClass + Please report this bug: + https://docs.brew.sh/Troubleshooting + /usr/local/Library/Homebrew/formula.rb:393:in `canonical_name' + /usr/local/Library/Homebrew/formula.rb:425:in `factory' + /usr/local/Library/Contributions/examples/brew-upgrade.rb:7 + /usr/local/Library/Contributions/examples/brew-upgrade.rb:7:in `map' + /usr/local/Library/Contributions/examples/brew-upgrade.rb:7 + /usr/local/bin/brew:46:in `require' + /usr/local/bin/brew:46:in `require?' + /usr/local/bin/brew:79 This happens because an old version of the upgrade command is hanging around for some reason. The fix: @@ -78,42 +79,40 @@ git clean -f # this will remove untracked files ### Python: `easy-install.pth` cannot be linked -``` -Warning: Could not link . Unlinking... -Error: The `brew link` step did not complete successfully -The formula built, but is not symlinked into /usr/local -You can try again using `brew link ' + Warning: Could not link . Unlinking... + Error: The `brew link` step did not complete successfully + The formula built, but is not symlinked into /usr/local + You can try again using `brew link ' -Possible conflicting files are: -/usr/local/lib/python2.7/site-packages/site.py -/usr/local/lib/python2.7/site-packages/easy-install.pth -==> Could not symlink file: /homebrew/Cellar///lib/python2.7/site-packages/site.py -Target /usr/local/lib/python2.7/site-packages/site.py already exists. You may need to delete it. -To force the link and overwrite all other conflicting files, do: - brew link --overwrite formula_name + Possible conflicting files are: + /usr/local/lib/python2.7/site-packages/site.py + /usr/local/lib/python2.7/site-packages/easy-install.pth + ==> Could not symlink file: /homebrew/Cellar///lib/python2.7/site-packages/site.py + Target /usr/local/lib/python2.7/site-packages/site.py already exists. You may need to delete it. + To force the link and overwrite all other conflicting files, do: + brew link --overwrite formula_name -To list all files that would be deleted: - brew link --overwrite --dry-run formula_name -``` + To list all files that would be deleted: + brew link --overwrite --dry-run formula_name Don't follow the advice here but fix by using `Language::Python.setup_install_args` in the formula as described in [Python for Formula Authors](Python-for-Formula-Authors.md). -### Upgrading macOS +## Upgrading macOS Upgrading macOS can cause errors like the following: - `dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.54.dylib` - `configure: error: Cannot find libz` -Following a macOS upgrade it may be necessary to reinstall the Xcode Command Line Tools and `brew upgrade` all installed formula: +Following a macOS upgrade it may be necessary to reinstall the Xcode Command Line Tools and then `brew upgrade` all installed formulae: ```sh xcode-select --install brew upgrade ``` -### Other local issues +## Other local issues If your Homebrew installation gets messed up (and fixing the issues found by `brew doctor` doesn't solve the problem), reinstalling Homebrew may help to reset to a normal state. To easily reinstall Homebrew, use [Homebrew Bundle](https://github.com/Homebrew/homebrew-bundle) to automatically restore your installed formulae and casks. To do so, run `brew bundle dump`, [uninstall](https://docs.brew.sh/FAQ#how-do-i-uninstall-homebrew), [reinstall](https://docs.brew.sh/Installation) and run `brew bundle install`. diff --git a/docs/External-Commands.md b/docs/External-Commands.md index 1376b3d48c..29b92702a5 100644 --- a/docs/External-Commands.md +++ b/docs/External-Commands.md @@ -9,6 +9,7 @@ brew mycommand --option1 --option3 without modifying Homebrew's internals. ## Command types + External commands come in two flavours: Ruby commands and shell scripts. In both cases, the command file should be executable (`chmod +x`) and live somewhere in `PATH`. @@ -16,11 +17,13 @@ In both cases, the command file should be executable (`chmod +x`) and live somew External commands can be added to a tap to allow easy distribution. See [below](#external-commands-in-taps) for more details. ### Ruby commands + An external command `extcmd` implemented as a Ruby command should be named `brew-extcmd.rb`. The command is executed by doing a `require` on the full pathname. As the command is `require`d, it has full access to the Homebrew "environment", i.e. all global variables and modules that any internal command has access to. Be wary of using Homebrew internals; they may change at any time without warning. The command may `Kernel.exit` with a status code if it needs to; if it doesn't explicitly exit then Homebrew will return `0`. ### Other executable scripts + An executable script for a command named `extcmd` should be named `brew-extcmd`. The script itself can use any suitable shebang (`#!`) line, so an external script can be written in Bash, Ruby, or even Python. Unlike the ruby commands this file must not end with a language-specific suffix (`.sh`, or `.py`). This file will be run via `exec` with some Homebrew variables set as environment variables, and passed any additional command-line arguments. | Variable | Description | @@ -38,16 +41,19 @@ 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`. ## 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. Note they are largely untested, and as always, be careful about running untested code on your machine. ### brew-gem + Install any `gem` package into a self-contained Homebrew Cellar location: Note this can also be installed with `brew install brew-gem`. ## External commands in taps + External commands can be hosted in a [tap](Taps.md) to allow users to easily install and use them. See [How to Create and Maintain a Tap](How-to-Create-and-Maintain-a-Tap.md) for more details about creating and maintaining a tap. External commands should be added to a `cmd` directory in the tap. An external command `extcmd` implemented as a Ruby command should live in `cmd/extcmd.rb` (don't forget to `chmod +x`). diff --git a/docs/FAQ.md b/docs/FAQ.md index efbf38d589..e9325489a9 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,14 +1,16 @@ # FAQ ## Is there a glossary of terms around? -All your terminology needs can be [found here](Formula-Cookbook.md#homebrew-terminology). + +The Formula Cookbook has a list of [Homebrew terminology](Formula-Cookbook.md#homebrew-terminology). ## How do I update my local packages? -First update the formulae and Homebrew itself: + +First update all package definitions (formulae) and Homebrew itself: brew update -You can now find out what is outdated with: +You can now list which of your installed packages (kegs) are outdated with: brew outdated @@ -21,6 +23,7 @@ Or upgrade a specific formula with: brew upgrade ## How do I stop certain formulae from being updated? + To stop something from being updated/upgraded: brew pin @@ -29,13 +32,15 @@ To allow that formulae to update again: brew unpin -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). +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 use `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 Homebrew? + To uninstall Homebrew, run the [uninstall script from the Homebrew/install repository](https://github.com/homebrew/install#uninstall-homebrew). -## How can I keep old versions of a formula when upgrading? -Homebrew automatically uninstalls old versions of a formula after that formula is upgraded with `brew upgrade`, and periodically performs additional cleanup every 30 days. +## How do I keep old versions of a formula when upgrading? + +Homebrew automatically uninstalls old versions of each formula that is upgraded with `brew upgrade`, and periodically performs additional cleanup every 30 days. To __disable__ automatic `brew cleanup`: @@ -50,7 +55,8 @@ When automatic `brew cleanup` is disabled, if you uninstall a formula, it will o In this case, to remove a formula entirely, you may run `brew uninstall --force `. Be careful as this is a destructive operation. ## Why does `brew upgrade ` or `brew install ` also upgrade a bunch of other stuff? -Homebrew doesn't support arbitrary mixing and matching of formula versions, so everything a formula depends on, and everything that depends on it in turn, needs to be upgraded to the latest version as that's the only combination of formulae we test. As a consequence any given `upgrade` or `install` command can upgrade many other (seemingly unrelated) formulae, if something important like `python` or `openssl` also needed an upgrade. + +Homebrew doesn't support arbitrary mixing and matching of formula versions, so everything a formula depends on, and everything that depends on it in turn, needs to be upgraded to the latest version as that's the only combination of formulae we test. As a consequence any given `upgrade` or `install` command can upgrade many other (seemingly unrelated) formulae, especially if something important like `python` or `openssl` also needed an upgrade. ## Where does stuff get downloaded? @@ -59,42 +65,45 @@ 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 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). + +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). ## Why do you compile everything? -Homebrew provides pre-compiled versions for many formulae. These -pre-compiled versions are referred to as [bottles](Bottles.md) and are available -at . -If available, bottled binaries will be used by default except under the -following conditions: +Homebrew provides pre-built binary packages for many formulae. These are referred to as [bottles](Bottles.md) and are available at . -* Options were passed to the install command, i.e. `brew install ` -will use a bottled version of the formula, but -`brew install --enable-bar ` will trigger a source build. +If available, bottled binaries will be used by default except under the following conditions: + +* Options were passed to the install command, i.e. `brew install ` will use a bottled version of the formula, but `brew install --enable-bar ` will trigger a source build. * 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 default -(although some bottles support this). +* No bottle is available for the machine's currently running OS version. (Bottles for macOS are generated only for supported macOS versions.) +* Homebrew is installed to a prefix other than the default (although some bottles support this). We aim to bottle everything. -## How do I get a formula from someone else’s branch? +## How do I get a formula from someone else’s pull request? ```sh brew install hub brew update -cd "$(brew --repository)" -hub pull someone_else +cd "$(brew --repository homebrew/core)" +hub fetch github_username +hub pr checkout pull_request_number ``` ## 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 Apple Silicon/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 formulae 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 failure, and is not supported. The default prefix is: + +* `/usr/local` for macOS on Intel, +* `/opt/homebrew` for macOS on Apple Silicon/ARM, and +* `/home/linuxbrew/.linuxbrew` for Linux. + +Do yourself a favour and install to the default prefix so that you can use our pre-built binary packages. *Pick another prefix at your peril!* ## Why is the default installation prefix `/opt/homebrew` on Apple Silicon? @@ -102,88 +111,82 @@ The prefix `/opt/homebrew` was chosen to allow installations in `/opt/homebrew` ## Why is the default installation prefix `/home/linuxbrew/.linuxbrew` on Linux? -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 `/home/linuxbrew`. +The prefix `/home/linuxbrew/.linuxbrew` was chosen so that users without admin access can still benefit from precompiled binaries via a `linuxbrew` role account. If you do not yourself have admin privileges, consider asking your admin staff to create a `linuxbrew` role account for you with home directory `/home/linuxbrew`. ## Why does Homebrew say sudo is bad? -**tl;dr** Sudo is dangerous, and you installed TextMate.app without sudo -anyway. + +**tl;dr** Sudo is dangerous, and you installed TextMate.app without sudo anyway. Homebrew refuses to work using sudo. -You should only ever sudo a tool you trust. Of course, you can trust Homebrew -😉 But do you trust the multi-megabyte Makefile that Homebrew runs? Developers -often understand C++ far better than they understand make syntax. It’s too high -a risk to sudo such stuff. It could modify (or upload) any files on your -system. And indeed, we’ve seen some build scripts try to modify `/usr` even when -the prefix was specified as something else entirely. +You should only ever sudo a tool you trust. Of course, you can trust Homebrew 😉 — but do you trust the multi-megabyte Makefile that Homebrew runs? Developers often understand C++ far better than they understand `make` syntax. It’s too high a risk to sudo such stuff. It could modify (or upload) any files on your system. And indeed, we’ve seen some build scripts try to modify `/usr` even when the prefix was specified as something else entirely. We use the macOS sandbox to stop this but this doesn't work when run as the `root` user (which also has read and write access to almost everything on the system). -Did you `chown root /Applications/TextMate.app`? Probably -not. So is it that important to `chown root wget`? +Did you `chown root /Applications/TextMate.app`? Probably not. So is it that important to `chown root wget`? -If you need to run Homebrew in a multi-user environment, consider -creating a separate user account especially for use of Homebrew. +If you need to run Homebrew in a multi-user environment, consider creating a separate user account specifically for use of Homebrew. ## Why isn’t a particular command documented? -If it’s not in `man brew`, it’s probably an external command. These are documented [here](External-Commands.md). +If it’s not in [`man brew`](Manpage.md), it’s probably an [external command](External-Commands.md) with documentation available using `--help`. ## Why haven’t you merged my pull request? -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 all maintainer feedback has been addressed and all tests are passing, bump it with a “bump” comment. Sometimes we miss requests and there are plenty of them. In the meantime, rebase your pull request so that it can be more easily merged. ## Can I edit formulae myself? -Yes! It’s easy! Just `brew edit `. 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 `. You don’t have to submit modifications back to `homebrew/core`, just edit the formula to what you personally need 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! ## Can I make new formulae? -Yes! It’s easy! Just `brew create URL`. Homebrew will then open the formula in -`EDITOR` so you can edit it, but it probably already installs; try it: `brew -install `. If you encounter any issues, run the command with the -`--debug` switch like so: `brew install --debug `, which drops you -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). +Yes! It’s easy! Just `brew create URL`. Homebrew will then open the formula in `EDITOR` so you can edit it, but it probably already installs; try it: `brew install `. If you encounter any issues, run the command with the `--debug` switch like so: `brew install --debug `, which drops you 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). ## Why was a formula deleted or disabled? -Use `brew log ` to find out! Likely because it had [unresolved issues](Acceptable-Formulae.md) and/or [our analytics](Analytics.md) identified it was not widely used. + +Use `brew log ` to find out! Likely because it had [unresolved issues](Acceptable-Formulae.md) and/or [our analytics](https://formulae.brew.sh/analytics/) indicated it was not widely used. For disabled and deprecated formulae, running `brew info ` will also provide an explanation. -## Homebrew is a poor name, it's too generic, why was it chosen? -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 😉 +## Homebrew is a poor name, it's too generic; why was it chosen? + +Homebrew's creator @mxcl wasn't 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 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 `. -You can still link in the formula if you need to with `brew link `, though this can cause unexpected behaviour if you are shadowing macOS software. +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 for including it in your `PATH`, by running `brew info `. + +You can [modify a tool's build configuration](How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md) to find keg-only dependencies. Or, you can link in the formula if you need to with `brew link `, though this can cause unexpected behaviour if you are shadowing macOS software. ## How can I specify different configure arguments for a formula? -`brew edit ` and edit the formula. Currently there is no -other way to do this. +`brew edit ` and edit the formula directly. Currently there is no other way to do this. + +## Why can’t I open a Mac app from an "unidentified developer"? -## The app can’t be opened because it is from an unidentified developer Chances are that certain apps will give you a popup message like this: Gatekeeper message -This is a [security feature from Apple](https://support.apple.com/en-us/HT202491). The single most important thing to know is that **you can allow individual apps to be exempt from that feature.** This allows the app to run while the rest of the system remains under protection. +This is a [security feature from Apple](https://support.apple.com/en-us/HT202491). The single most important thing to know is that **you can allow individual apps to be exempt from this feature.** This allows the app to run while the rest of the system remains under protection. **Always leave system-wide protection enabled,** and disable it only for specific apps as needed. -If you are sure you want to trust the app, you can disable protection for that app by right-clicking its icon and choosing `Open`: +If you're sure you want to trust the app, you can disable protection for it by right-clicking its icon and choosing *Open*: Right-click the app and choose Open -Finally, click the `Open` button if you want macOS to permanently allow the app to run on this Mac. **Don’t do this unless you’re sure you trust the app.** +In the resulting dialog, click the *Open* button to have macOS permanently allow the app to run on this Mac. **Don’t do this unless you’re sure you trust the app.** Gatekeeper message Alternatively, you may provide the [`--no-quarantine` flag](https://github.com/Homebrew/homebrew-cask/blob/HEAD/USAGE.md#options) at install time to not add this feature to a specific app. +## Why aren’t some apps included during `brew upgrade`? -## Why some apps aren’t included in `upgrade` After running `brew upgrade`, you may notice some casks you think should be upgrading, aren’t. As you’re likely aware, a lot of macOS software can upgrade itself: @@ -192,20 +195,23 @@ As you’re likely aware, a lot of macOS software can upgrade itself: That could cause conflicts when used in tandem with Homebrew Cask’s `upgrade` mechanism. -If you upgrade software through it’s built-in mechanism, that happens without Homebrew Cask’s knowledge so both versions get out of sync. If you then upgraded through Homebrew Cask and we have a lower version on the software on record, you’d get a downgrade. +When software uses its built-in mechanisms to upgrade itself, it happens without Homebrew Cask’s knowledge, causing both versions get out of sync. If you were to then upgrade through Homebrew Cask while we have a lower version of the software on record, you’d get a downgrade. There are a few ideas to fix this problem: -* Try to prevent the software’s automated updates. That won’t be a universal solution and may cause it to break. Most software on Homebrew Cask is closed-source, so we’d be guessing. This is also why pinning casks to a version isn’t available. -* Try to extract the installed software’s version and compare it to the cask, deciding what to do at that time. That’s a complicated solution that breaks other parts of our methodology, such as using versions to interpolate in `url`s (a definite win for maintainability). That solution also isn’t universal, as many software developers are inconsistent in their versioning schemes (and app bundles are meant to have two version strings) and it doesn’t work for all types of software we support. +* Try to prevent the software’s automated updates. It wouldn’t be a universal solution and may cause it to break. Most software on Homebrew Cask is closed-source, so we’d be guessing. This is also why pinning casks to a version isn’t available. +* Try to extract the installed software’s version and compare it to the cask, deciding what to do at that time. It’d be a complicated solution that would break other parts of our methodology, such as using versions to interpolate `url` values (a definite win for maintainability). This solution also isn’t universal, as many software developers are inconsistent in their versioning schemes (and app bundles are meant to have two version strings) and it doesn’t work for all types of software we support. -So we let software be. Installing it with Homebrew Cask should make it behave the same as if you had installed it manually. But we also want to support software that does not auto-upgrade, so we add [`auto_updates true`](https://github.com/Homebrew/homebrew-cask/blob/62c0495b254845a481dacac6ea7c8005e27a3fb0/Casks/alfred.rb#L10) to casks of software that can do it, which excludes them from `brew upgrade`. +So we let software be. Anything installed with Homebrew Cask should behave the same as if it were installed manually. But since we also want to support software that doesn’t self-upgrade, we add [`auto_updates true`](https://github.com/Homebrew/homebrew-cask/blob/62c0495b254845a481dacac6ea7c8005e27a3fb0/Casks/alfred.rb#L10) to casks for software that does, which excludes them from `brew upgrade`. -Casks which use [`version :latest`](https://docs.brew.sh/Cask-Cookbook#version-latest) are also excluded, because we have no way to track the version they’re in. It helps to ask the developers of such software to provide versioned releases (i.e. have the version in the path of the download `url`). +Casks which use [`version :latest`](https://docs.brew.sh/Cask-Cookbook#version-latest) are also excluded, because we have no way to track their installed version. It helps to ask the developers of such software to provide versioned releases (i.e. include the version in the path of the download `url`). -If you still want to force software to be upgraded via Homebrew Cask, you can: +If you still want to force software to be upgraded via Homebrew Cask, you can reference it specifically in the `upgrade` command: -* Reference it specifically in the `upgrade` command: `brew upgrade {{cask_name}}`. -* Use the `--greedy` flag: `brew upgrade --greedy`. + brew upgrade -Refer to the `upgrade` section of the `brew` manual page by running `man -P 'less --pattern "^ {3}upgrade"' brew`. +Or use the `--greedy` flag: + + brew upgrade --greedy + +Refer to the `upgrade` section of the [`brew` manual page](Manpage.md) for more details. diff --git a/docs/Gemfile b/docs/Gemfile index ca9b7428d0..50368eba34 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -4,5 +4,6 @@ gem "github-pages", group: :jekyll_plugins group :test do gem "html-proofer" + gem "mdl" gem "rake" end diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index c03269e605..68ce3450af 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -9,6 +9,8 @@ GEM zeitwerk (~> 2.2, >= 2.2.2) addressable (2.8.0) public_suffix (>= 2.0.2, < 5.0) + chef-utils (17.8.25) + concurrent-ruby coffee-script (2.4.1) coffee-script-source execjs @@ -226,6 +228,12 @@ GEM listen (3.7.0) rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) + mdl (0.11.0) + kramdown (~> 2.3) + kramdown-parser-gfm (~> 1.1) + mixlib-cli (~> 2.1, >= 2.1.1) + mixlib-config (>= 2.2.1, < 4) + mixlib-shellout mercenary (0.3.6) mini_portile2 (2.6.1) minima (2.5.1) @@ -233,6 +241,11 @@ GEM jekyll-feed (~> 0.9) jekyll-seo-tag (~> 2.1) minitest (5.14.4) + mixlib-cli (2.1.8) + mixlib-config (3.0.9) + tomlrb + mixlib-shellout (3.2.5) + chef-utils multipart-post (2.1.1) nokogiri (1.12.5) mini_portile2 (~> 2.6.1) @@ -272,6 +285,7 @@ GEM terminal-table (1.8.0) unicode-display_width (~> 1.1, >= 1.1.1) thread_safe (0.3.6) + tomlrb (2.0.1) typhoeus (1.4.0) ethon (>= 0.9.0) tzinfo (1.2.9) @@ -289,7 +303,8 @@ PLATFORMS DEPENDENCIES github-pages html-proofer + mdl rake BUNDLED WITH - 1.17.2 + 1.17.3 diff --git a/docs/Gems,-Eggs-and-Perl-Modules.md b/docs/Gems,-Eggs-and-Perl-Modules.md index f50bfd0d65..59ec3f6d5a 100644 --- a/docs/Gems,-Eggs-and-Perl-Modules.md +++ b/docs/Gems,-Eggs-and-Perl-Modules.md @@ -20,6 +20,7 @@ will let you add packages to Python 3.y as yourself, which is probably safer than changing the group ownership of the directory. ### So why was I using sudo? + Habit maybe? One reason is executables go in `/usr/local/bin`. Usually this isn’t a @@ -28,6 +29,7 @@ writable location. But if you installed Homebrew as we recommend on macOS Intel, install the development tools you need without risking the use of sudo. ### Python packages (eggs) without sudo using system’s Python + _This is only recommended if you **don't** use a brewed Python._ On macOS, any [Python version X.Y also searches in diff --git a/docs/Homebrew-and-Python.md b/docs/Homebrew-and-Python.md index a3514e32fb..d2c117073c 100644 --- a/docs/Homebrew-and-Python.md +++ b/docs/Homebrew-and-Python.md @@ -11,6 +11,7 @@ Homebrew provided a `python@2` formula until the end of 2019, at which point it **Important:** If you choose to use a Python which isn't either of these two (system Python or brewed Python), the Homebrew team cannot support any breakage that may occur. ## Python 3.x + Homebrew provides a formula for Python 3.x (`python@3.x`). **Important**: Python may be upgraded to a newer version at any time. Consider using a version @@ -28,6 +29,7 @@ $(brew --prefix)/opt/python/libexec/bin ``` ## Setuptools, Pip, etc. + The Python formulae install [pip](https://pip.pypa.io/) (as `pip3`) and [Setuptools](https://pypi.python.org/pypi/setuptools). Setuptools can be updated via pip3, without having to re-brew Python: @@ -43,6 +45,7 @@ python3 -m pip install --upgrade pip ``` ## `site-packages` and the `PYTHONPATH` + The `site-packages` is a directory that contains Python modules (especially bindings installed by other formulae). Homebrew creates it here: ```sh @@ -59,19 +62,23 @@ Python 3.y also searches for modules in: Homebrew's `site-packages` directory is first created if (1) any Homebrew formula with Python bindings are installed, or (2) upon `brew install python`. ### Why here? + The reasoning for this location is to preserve your modules between (minor) upgrades or re-installations of Python. Additionally, Homebrew has a strict policy never to write stuff outside of the `brew --prefix`, so we don't spam your system. ## Homebrew-provided Python bindings + Some formulae provide Python bindings. **Warning!** Python may crash (see [Common Issues](Common-Issues.md)) if you `import ` from a brewed Python if you ran `brew install ` against the system Python. If you decide to switch to the brewed Python, then reinstall all formulae with Python bindings (e.g. `pyside`, `wxwidgets`, `pygtk`, `pygobject`, `opencv`, `vtk` and `boost-python`). ## Policy for non-brewed Python bindings + These should be installed via `pip install `. To discover, you can use `pip search` or . **Note:** macOS's system Python does not provide `pip`. Follow the [pip documentation](https://pip.readthedocs.io/en/stable/installing/#install-pip) to install it for your system Python if you would like it. ## Brewed Python modules + For brewed Python, modules installed with `pip3` or `python3 setup.py install` will be installed to the `$(brew --prefix)/lib/pythonX.Y/site-packages` directory (explained above). Executable Python scripts will be in `$(brew --prefix)/bin`. The system Python may not know which compiler flags to set in order to build bindings for software installed in Homebrew so you may need to run: @@ -81,6 +88,7 @@ CFLAGS="-I$(brew --prefix)/include" LDFLAGS="-L$(brew --prefix)/lib" pip install ``` ## Virtualenv + **WARNING:** When you `brew install` formulae that provide Python bindings, you should **not be in an active virtual environment**. Activate the virtualenv *after* you've brewed, or brew in a fresh terminal window. @@ -89,4 +97,5 @@ Homebrew will still install Python modules into Homebrew's `site-packages` and * Virtualenv has a `--system-site-packages` switch to allow "global" (i.e. Homebrew's) `site-packages` to be accessible from within the virtualenv. ## Why is Homebrew's Python being installed as a dependency? + Formulae that declare an unconditional dependency on the `"python"` formula are bottled against Homebrew's Python 3.x and require it to be installed. diff --git a/docs/Homebrew-on-Linux.md b/docs/Homebrew-on-Linux.md index 4e43777eaa..e2a4c4eef9 100644 --- a/docs/Homebrew-on-Linux.md +++ b/docs/Homebrew-on-Linux.md @@ -15,18 +15,18 @@ 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 +- 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). -The installation script installs Homebrew to `/home/linuxbrew/.linuxbrew` using *sudo* if possible and in 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 more binary packages (bottles) than installing in your personal home directory. -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 `/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`. Follow the *Next steps* instructions to add Homebrew to your `PATH` and to your bash shell profile script, either `~/.profile` on Debian/Ubuntu or `~/.bash_profile` on CentOS/Fedora/Red Hat. @@ -47,26 +47,26 @@ If you're using an older distribution of Linux, installing your first package wi ## Requirements -+ **GCC** 4.7.0 or newer -+ **Linux** 2.6.32 or newer -+ **Glibc** 2.13 or newer -+ **64-bit x86_64** CPU +- **GCC** 4.7.0 or newer +- **Linux** 2.6.32 or newer +- **Glibc** 2.13 or newer +- **64-bit x86_64** CPU -Paste at a terminal prompt: +To install build tools, paste at a terminal prompt: -### Debian or Ubuntu +- **Debian or Ubuntu** -```sh -sudo apt-get install build-essential procps curl file git -``` + ```sh + sudo apt-get install build-essential procps curl file git + ``` -### Fedora, CentOS, or Red Hat +- **Fedora, CentOS, or Red Hat** -```sh -sudo yum groupinstall 'Development Tools' -sudo yum install procps-ng curl file git -sudo yum install libxcrypt-compat # needed by Fedora 30 and up -``` + ```sh + sudo yum groupinstall 'Development Tools' + sudo yum install procps-ng curl file git + sudo yum install libxcrypt-compat # needed by Fedora 30 and up + ``` ### ARM diff --git a/docs/Installation.md b/docs/Installation.md index bb2712269a..bb4d80a532 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -2,25 +2,20 @@ 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 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. ## macOS Requirements * A 64-bit Intel CPU or Apple Silicon CPU [1](#1) * macOS Catalina (10.15) (or higher) [2](#2) -* Command Line Tools (CLT) for Xcode: `xcode-select --install`, - [developer.apple.com/downloads](https://developer.apple.com/downloads) or +* Command Line Tools (CLT) for Xcode (from `xcode-select --install` or + [https://developer.apple.com/download/all/](https://developer.apple.com/download/all/)) or [Xcode](https://itunes.apple.com/us/app/xcode/id497799835) [3](#3) * The Bourne-again shell for installation (i.e. `bash`) [4](#4) ## Git Remote Mirroring -You can set `HOMEBREW_BREW_GIT_REMOTE` and/or `HOMEBREW_CORE_GIT_REMOTE` in your shell environment to use geolocalized Git mirrors to speed up Homebrew's installation with this script and, after installation, `brew update`. +You can use geolocalized Git mirrors to speed up Homebrew's installation and `brew update` by setting `HOMEBREW_BREW_GIT_REMOTE` and/or `HOMEBREW_CORE_GIT_REMOTE` in your shell environment with this script: ```bash export HOMEBREW_BREW_GIT_REMOTE="..." # put your Git mirror of Homebrew/brew here @@ -44,10 +39,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 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!* +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 mkdir homebrew && curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew @@ -69,25 +61,16 @@ chmod -R go-w "$(brew --prefix)/share/zsh" ### 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 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`. ## Uninstallation Uninstallation is documented in the [FAQ](FAQ.md). -1 For 32-bit or PPC support see -[Tigerbrew](https://github.com/mistydemeo/tigerbrew). +1 For 32-bit or PPC support see [Tigerbrew](https://github.com/mistydemeo/tigerbrew). -2 10.15 or higher is recommended. 10.10–10.14 are -supported on a best-effort basis. For 10.4-10.6 see -[Tigerbrew](https://github.com/mistydemeo/tigerbrew). +2 10.15 or higher is recommended, while 10.10–10.14 are supported on a best-effort basis. For 10.4–10.6 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 -[here](https://developer.apple.com/register/index.action). +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). -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) requires the Bourne-again shell, i.e. `bash`. Notably, `zsh`, `fish`, `tcsh` and `csh` will not work. diff --git a/docs/Rakefile b/docs/Rakefile index 8218ea9a26..042dfa64d1 100644 --- a/docs/Rakefile +++ b/docs/Rakefile @@ -7,7 +7,12 @@ task :build do sh "jekyll", "build" end -desc "Run html proofer to validate the HTML output." +desc "Run Markdownlint to validate the Markdown style." +task lint: :build do + sh "mdl", "." +end + +desc "Run HTMLProofer to validate the HTML output." task test: :build do require "html-proofer" HTMLProofer.check_directory( diff --git a/docs/Shell-Completion.md b/docs/Shell-Completion.md index f1c2768dfe..07ffd3e1b1 100644 --- a/docs/Shell-Completion.md +++ b/docs/Shell-Completion.md @@ -4,7 +4,7 @@ Homebrew comes with completion definitions for the `brew` command. Some packages `zsh`, `bash` and `fish` are currently supported. -You must then configure your shell to enable its completion support. This is because the Homebrew-managed completions are stored under `HOMEBREW_PREFIX` which your system shell may not be aware of, and since it is difficult to automatically configure `bash` and `zsh` completions in a robust manner, the Homebrew installer does not do it for you. +You must manually configure your shell to enable its completion support. This is because the Homebrew-managed completions are stored under `HOMEBREW_PREFIX` which your system shell may not be aware of, and since it is difficult to automatically configure `bash` and `zsh` completions in a robust manner, the Homebrew installer does not do it for you. Shell completions for external Homebrew commands are not automatically installed. To opt-in to using completions for external commands (if provided), they need to be linked to `HOMEBREW_PREFIX` by running `brew completions link`. @@ -28,14 +28,13 @@ then fi ``` -If you install the `bash-completion` formula, this will automatically source the completions' initialisation script (so you do not need to follow the instructions in the caveats). - -If you are using the `bash` formula as your shell (i.e. `bash` >= v4) you should use the `bash-completion@2` formula instead. +If you install the `bash-completion` formula, this will automatically source the completions' initialisation script (so you do not need to follow the instructions in the formula's caveats). +If you are using Homebrew's `bash` as your shell (i.e. `bash` >= v4) you should use the `bash-completion@2` formula instead. ## Configuring Completions in `zsh` -To make Homebrew's completions available in `zsh`, you must get the Homebrew-managed zsh site-functions on your `FPATH` before initialising `zsh`'s completion facility. Add the following to your `~/.zshrc` file: +To make Homebrew's completions available in `zsh`, you must insert the Homebrew-managed `zsh/site-functions` path into your `FPATH` before initialising `zsh`'s completion facility. Add the following to your `~/.zshrc`: ```sh if type brew &>/dev/null @@ -56,13 +55,13 @@ FPATH="$(brew --prefix)/share/zsh/site-functions:${FPATH}" You may also need to forcibly rebuild `zcompdump`: ```sh - rm -f ~/.zcompdump; compinit +rm -f ~/.zcompdump; compinit ``` Additionally, if you receive "zsh compinit: insecure directories" warnings when attempting to load these completions, you may need to run this: ```sh - chmod -R go-w "$(brew --prefix)/share" +chmod -R go-w "$(brew --prefix)/share" ``` ## Configuring Completions in `fish` diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 7114cc2b81..8914fb71d4 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -6,25 +6,26 @@ This document will help you check for common issues and make sure your issue has ## Check for common issues -* Read through the [Common Issues](Common-Issues.md). +* Read through the list of [Common Issues](Common-Issues.md). ## Check to see if the issue has been reported -* Search the [Homebrew/homebrew-core issue tracker](https://github.com/Homebrew/homebrew-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. -* 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. +* Search the appropriate issue tracker to see if someone else has already reported the same issue: + * [Homebrew/homebrew-core issue tracker](https://github.com/Homebrew/homebrew-core/issues) (formulae) + * [Homebrew/homebrew-cask issue tracker](https://github.com/Homebrew/homebrew-cask/issues) (casks) + * [Homebrew/brew issue tracker](https://github.com/Homebrew/brew/issues) (`brew` itself) +* If the formula or cask that has failed to install is part of a non-Homebrew tap, then check that tap's issue tracker instead. +* Search the [Homebrew discussion forum](https://github.com/homebrew/discussions/discussions) or [Discourse archive](https://discourse.brew.sh/) to see if any discussions have started about the issue. ## Create an issue If your problem hasn't been solved or reported, then create an issue: -1. Upload debugging information to a [Gist](https://gist.github.com): +1. Collect debugging information: + * If you have a problem with installing a formula: run `brew gist-logs ` (where `` is the name of the formula) to upload the logs to a new [Gist](https://gist.github.com). + * If your have a non-formula problem: collect the output of `brew config` and `brew doctor`. - * If you had a formula-related problem: run `brew gist-logs ` (where `` is the name of the formula). - * If you encountered a non-formula problem: upload the output of `brew config` and `brew doctor` to a new [Gist](https://gist.github.com). - -2. Create a new issue on the [Homebrew/homebrew-core issue tracker](https://github.com/Homebrew/homebrew-core/issues/new/choose) - - * Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS or Linux you are using. For example, if a formula fails to build, title your issue "\ failed to build on \<10.x>", where "\" is the name of the formula that failed to build, and "\<10.x>" is the version of macOS or Linux you are using. - * Include the URL output by `brew gist-logs ` (if applicable). - * Include links to any additional Gists you may have created (such as for the output of `brew config` and `brew doctor`). +1. Create a new issue on the issue tracker for [Homebrew/homebrew-core](https://github.com/Homebrew/homebrew-core/issues/new/choose), [Homebrew/homebrew-cask](https://github.com/Homebrew/homebrew-cask/issues/new/choose) or [Homebrew/brew](https://github.com/Homebrew/brew/issues/new/choose) and follow the instructions: + * Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS or Linux you are using. For example, if a formula fails to build, title your issue "\ failed to build on \", where "\" is the name of the formula that failed to build, and "\" is the name and version of macOS or Linux you are using. + * Include the URL provided by `brew gist-logs ` (if applicable) plus links to any additional Gists you may have created. + * Include the output of `brew config` and `brew doctor`. diff --git a/docs/Xcode.md b/docs/Xcode.md index a2467201ae..2a1751a021 100644 --- a/docs/Xcode.md +++ b/docs/Xcode.md @@ -1,10 +1,12 @@ # Xcode ## Supported Xcode versions + Homebrew supports and recommends the latest Xcode and/or Command Line Tools available for your platform (see `OS::Mac::Xcode.latest_version` and `OS::Mac::CLT.latest_version` in [`Library/Homebrew/os/mac/xcode.rb`](https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/os/mac/xcode.rb)). ## Updating for new Xcode releases + When a new Xcode release is made, the following things need to be updated: