57 lines
3.0 KiB
Markdown
57 lines
3.0 KiB
Markdown
# Troubleshooting
|
||
## Read this first!
|
||
|
||
Please run `brew update` and `brew doctor` *before* creating an issue!
|
||
|
||
If you create an issue, please also create a [Gist][] by running
|
||
|
||
```
|
||
brew gist-logs <formula name>
|
||
```
|
||
|
||
and include a link to the gist in the issue.
|
||
|
||
Read on for more detailed instructions.
|
||
|
||
Thank you!
|
||
|
||
## Check for common issues
|
||
* Run `brew update` — then try again.
|
||
* Run `brew doctor` — the doctor diagnoses common issues.
|
||
* Read through the [Common Issues](Common-Issues.md) page.
|
||
* If you’re installing something Java-related, maybe you need the [Java Developer Update][] or [JDK 7][]?
|
||
* Check that **Command Line Tools for Xcode (CLT)** and/or **Xcode** are up to date.
|
||
* If things fail with permissions errors, check the permissions in `/usr/local`. If you’re unsure what to do, you can `sudo chown -R $(whoami) /usr/local`.
|
||
|
||
#### Listen to Dr. Brew
|
||
|
||
* **Update Xcode and/or Command Line Tools for Xcode!** Make sure that Xcode is up-to-date in the App Store. Check that the CLT package is up-to-date (either via Xcode, Preferences or at [Apple Developer][]).
|
||
* If `brew doctor` warns about unbrewed dylibs, be advised that they are **very likely to cause build problems**.
|
||
|
||
## Check to see if the issue has been reported
|
||
* Browse open issues on the [issue tracker](https://github.com/Homebrew/homebrew/issues) to see if someone else has already reported the same problem.
|
||
* 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
|
||
|
||
1. [Create a new issue](https://github.com/Homebrew/homebrew/issues/new)
|
||
* Again, make sure you file the issue against the correct repository.
|
||
* If you are reporting a build failure, title it "\<formula name> failed to build on 10.x", where \<formula name> is the name of the formula that failed to build, and 10.x is the version of OS X you are using.
|
||
* Otherwise, choose a title that best describes the problem you are experiencing.
|
||
|
||
2. Upload a [Gist][] with relevant debugging information
|
||
* The simplest method is to run `brew gist-logs <formula name>`
|
||
* You can also create a [Gist][] manually. Include the following:
|
||
1. The output from `HOMEBREW_MAKE_JOBS=1 brew install -v <formula name> 2>&1`
|
||
2. The contents of the largest numbered log in `~/Library/Logs/Homebrew/<formula name>`, e.g. `03.make`
|
||
3. The output from `brew config` and `brew doctor`
|
||
* If you are reporting a bug rather than a build failure, please include `brew config`, `brew doctor`, and enough information to reliably reproduce the bug.
|
||
|
||
3. Include a link to the gist in your new issue
|
||
* Be sure to use the `https:` URL (i.e. the URL in your browser's address bar), not the `git:` URL.
|
||
|
||
[Gist]:https://gist.github.com
|
||
[Apple Developer]:https://developer.apple.com/downloads
|
||
[Java Developer Update]:http://support.apple.com/kb/DL1572
|
||
[JDK 7]:http://docs.oracle.com/javase/7/docs/webnotes/install/mac/mac-install-faq.html
|