Skip to content

Bug Fixing Checklist

mxcl edited this page Sep 25, 2012 · 20 revisions

PLEASE,
PLEASE,
PLEASE brew doctor BEFORE CREATING A TICKET!

Thank you!

1) Check for Common Issues

  • brew update — then try again.
  • brew doctor — the doctor diagnoses common issues.
  • Try using the old environment, e.g. brew install --env=std graphviz.
  • If you’re installing something Java-related, maybe you need the [Java Developer Update][Apple Connect]?
  • Check that Xcode and/or the “Command Line Tools for Xcode” (CLT) are up to date*
  • If things fail with permissions errors you should check the permissions in /usr/local. If you’re unsure what to do, you can:
sudo chown -R $(whoami) /usr/local /usr/local/.git

But really you should know what you’re doing.

* brew --config will list these versions. If you have Xcode installed, check the App Store for upgrades and in Preferences for CLT upgrades. If you only have the CLT installed, then check [Apple Connect][].

Listen to Dr. Brew

  • Update your Xcode and Command Line Tools for Xcode! Make sure that Xcode is up-to-date in the App Store. Check the CLT package is up-to-date (either via Xcode, Preferences or at [Apple Connect][]).
  • If brew doctor warns about unbrewed dylibs, these seriously cause build trouble. Yes, we know it’s hard to know what to do with this warning. But it’s hard to advise!

2) Ticket the Bug

  • Create a new gist, and add the following items:
    • The output from
HOMEBREW_MAKE_JOBS=1 VERBOSE=1 brew install foo
  • The output from
brew doctor
  • If the build failed during configure, add config.log to the gist:
cat ~/Library/Logs/Homebrew/config.log | pbcopy
  • File an issue with a link to your gist. Be sure to post the http: link (copy from the browser bar :P), not the git: link.

An easy way to copy the output from commands is to clear your terminal (⌘K) and then run the command. Then select-all (⌘A) and copy (⌘C).

It can be helpful if you try to post the error message (and the link to your gist) in the ticket. Please don’t post more than a few lines of output in the ticket! If unsure, just link to your gist.

If you post output in the ticket itself, put it in a triple-backtick-block, like so:

Build output goes here!

```


We all suck at writing bug reports. [Let’s get better together](http://allanmcrae.com/2011/05/how-to-file-a-bug-report/).

[Apple Connect]:http://connect.apple.com