From bd6fb88ddc72a0de4c27f65e60a82790a5d87f3f Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Mon, 19 Sep 2016 19:58:21 +0100 Subject: Rearrange repository files. --- docs/Troubleshooting.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 docs/Troubleshooting.md (limited to 'docs/Troubleshooting.md') diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md new file mode 100644 index 000000000..4fc77d6cd --- /dev/null +++ b/docs/Troubleshooting.md @@ -0,0 +1,26 @@ +# Troubleshooting +**Run `brew update` (twice) and `brew doctor` *before* creating an issue!** + +When creating a formula-related issue please include the link output by running: + +```shell +brew gist-logs +``` + +## Check for common issues +* Run `brew update` (twice). +* Run `brew doctor` and fix all the warnings (**outdated Xcode/CLT and unbrewed dylibs are very likely to cause problems**). +* Read through the [Common Issues](Common-Issues.md). +* If you’re installing something Java-related, maybe you need to install Java (`brew cask install java`)? +* Check that **Command Line Tools for Xcode (CLT)** and/or **Xcode** are up to date. +* If things fail with permissions errors, check the permissions of `/usr/local`'s subdirectories. If you’re unsure what to do, you can `cd /usr/local && sudo chown -R $(whoami) bin etc include lib sbin share var Frameworks`. + +## Check to see if the issue has been reported +* Check the [issue tracker](https://github.com/Homebrew/homebrew-core/issues) to see if someone else has already reported the same issue. +* Make sure you check issues on the correct repository. If the formula that failed to build is part of a tap like [homebrew/science](https://github.com/Homebrew/homebrew-science) or [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes) check there instead. + +## Create an issue +0. Upload debugging information to a [Gist](https://gist.github.com): + - If you had a formula error: run `brew gist-logs ` (where `` is the name of the formula that failed to build). + - If you encountered a non-formula bug: upload the output of `brew config` and `brew doctor` to a new [Gist](https://gist.github.com). +1. [Create a new issue](https://github.com/Homebrew/homebrew-core/issues/new) titled "\ 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 you are using and including the link output by `brew gist-logs` -- cgit v1.2.3