brew/README

Homebrew
========
Homebrew's purpose is basically the same as MacPorts or Fink, ie. to let you
easily install other open source software on your Mac.

Here's why you may prefer Homebrew to the alternatives:

1. Zeroconf installation
   Copy the contents of this directory to /usr/local. Homebrew is now ready
   for use.

2. Or… install anywhere!
   You can actually stick this directory anywhere. Like ~/.local or /opt or 
   /lol if you like. You can even move this directory somewhere else later.

3. The GoboLinux approach
   Packages are installed to their own prefix (eg. /usr/local/Cellar/wget) and
   then symlinked into the Homebrew prefix (eg. /usr/local). 

   This way the filesystem is the package database. As is often the case with
   the simplest possible solution, it makes everything else easier and better.

   Eg. You can, if you like, rm -rf to uninstall a package. Or use find to
   list the package contents. Or du to see its size.

4. You don't have to sudo
   It's up to you. We recommend not--see the relevant later section.

5. Easy package creation
   Packages are just Ruby scripts. Generate a template with:

      brew mk http://foo.com/tarball-0.8.9.tgz

   Homebrew will automatically open it for you to tweak with TextMate or
   $EDITOR.

6. DIY package installation
   MacPorts doesn't support the beta version? Need an older version? Need
   custom compile flags? The Homebrew toolchain is carefully segregated so
   you can build stuff by hand but still end up with package management.

   Just install to the Cellar and then call brew ln to symlink that 
   installation into /usr/local, eg.

       ./configure --prefix=/usr/local/Cellar/wget/1.10
       make install
       brew ln wget

   This means you can also install multiple versions of the same package and
   switch on demand.

7. Optimisation
   We optimise for Leopard Intel, binaries are stripped, compile flags 
   tweaked. Nobody wants crappy, slow software. Apart from MacPorts and Fink.

8. Integration with existing OS X technologies
   Homebrew integrates with Ruby gems, CPAN and Python disttools. These tools
   exist already and do the job great. We don't reinvent the wheel, we just
   improve it by making these tools install with more management options.

9. Complimenting what OS X already has
   Macports is an autarky. You get a duplicate copy of libz, OpenSSL, Python
   etc. They do this to support OS X Tiger, etc. more easily. We don't support
   Tiger, we duplicate nothing. Homebrew compliments OS X, it doesn't seek to
   operate independently of it.

A. Fork with Git
   The package descriptions are all on git, so just fork to add new packages,
   or add extra remotes to get packages from more exotic maintainers.

B. Homebrew has a beer theme
   Beer goggles will help you to evangelise Homebrew more effectively.

C. Homebrew helps get you chicks
   There's no conclusive scientific evidence as yet, but I firmly believe it's
   just a matter of time and statistics.

I know I've made it sound so awesome you can hardly wait to rip MacPorts out
and embrace the fresh hoppy taste of Homebrew, but I should point out that it
is really new and still under heavy development. Thanks!

Max Howell <http://twitter.com/mxcl>


Installation
============
Homebrew is zeroconf, but almost everything it installs is built from source;
so you need Xcode:

http://developer.apple.com/technology/xcode.html

Also, a lot of build scripts assume MacPorts or Fink on OS X. Which isn't a
problem until you uninstall them and stuff you built with Homebrew breaks and
you email me with a bug report. So uninstall them (or rename their root 
folders if you don't want to burn bridges).

http://trac.macports.org/wiki/FAQ#HowdoIremoveoruninstallMacPorts
http://www.finkproject.org/faq/usage-fink.php#removing

Homebrew uses Ruby and some other stuff that is already installed on Leopard.
It is self-contained and ready to go. Just copy this directory somewhere.
Things work really well if you put it in /usr/local (especially if you are a 
developer).

ISSUE: Currently in order to update you need to clone the git repository. And
I'm not exactly sure what the best fix for that is yet.

If you install to /usr/local don't sudo
---------------------------------------
Well clearly you can sudo if you like. Homebrew is all about you doing it your
way. But the Homebrew recommendation is: don't sudo!

On OS X, this requires your user to be in the admin group, but it doesn't
require sudo:

    $ cpan -i MP3::Info

OS X is designed to minimise sudo use, you only need it for real root level 
stuff. On OS X you know your /System and /usr are as clean and pure as the day
you bought your Mac because you didn't sudo. You can sleep better at night.

If you are already the kind of guy who installed TextMate by dragging and 
dropping it to /Applications, then you won't mind if libflac and pngcrush are
installed under your user privileges too. Lets face it; Homebrew is not 
installing anything system-critical. Apple already did that.

Let this be the last sudo you do for quite some time:

    $ sudo chown -R `whoami`:staff /usr/local

I already have a bunch of junk in /usr/local
--------------------------------------------
Yeah that's typical. See what you've got, mv the local folder somewhere else,
mv Homebrew there and then just reinstall that stuff using Homebrew.

How about mate and gitx and that?
---------------------------------
They can easily coexist with Homebrew, that's the beauty of the homebrew-way.


Usage
=====
Install wget:
    brew install wget

Update package list:
    cd /usr/local && git pull origin masterbrew    [1]

Delete a package:
    brew rm wget      OR    rm -rf /usr/local/Cellar/wget && brew prune

List all files in a package:
    brew list wget    OR    find /usr/local/Cellar/wget

Search for a package to install:
    ls /usr/local/Library/Formula/

Search for a package already installed:
    ls /usr/local/Cellar/

Compute installed size of package:
    brew info wget    OR    du /usr/local/Cellar/wget
    
Show expensive packages:
    du -md1 /usr/local/Cellar
    
View the packages brew has downloaded and cached:
    ls `brew --cache`   OR  ls ~/Library/Caches/Homebrew

With Homebrew this is all Ruby. If you want to improve the package 
installation, amend the Ruby script. If you want to improve the brew command
amend the Ruby script. If you want to know exactly what is going on, read the
Ruby script.

[1] You have to install git before you can update the package list, but 
that's easy:

    brew install git


Why Compile From Source?
========================
Since we only target Intel Leopard boxes, why not just distribute binaries?
Well, I can't afford to :P And compiling from source gives more flexibility.
If you want to adapt the system and make it work with binaries; fork away. 
The bandwidth is on you though :P


CPAN, EasyInstall, RubyGems
===========================
Homebrew doesn't reinvent the wheel. These tools are already designed to make
it easy to install Perl, Python and Ruby tools and libraries. So we insist 
that you use them. However we don't think you should have to sudo, or install
to /usr, so we suggest you adapt the tools to install into Homebrew's prefix:

http://github.com/mxcl/homebrew/wiki


Contributing New Formulae
=========================
Homebrew can generate the formula with most stuff pre-done:

    brew mk http://foo.org/foobar-1.2.1.tar.bz2

You now have /usr/local/Library/Formula/foobar.rb. This may already work.
But maybe there are some juicy configure options?

    brew install foobar --help

Now you know foobar's configure options.

    brew install foobar --interactive
    
This opens an interactive bash shell at the extracted tarball. You can now 
install to the recommended prefix or just read the README and type `exit'.

Try to install it:

    brew install foobar

Fork http://github.com/mxcl/homebrew and ask mxcl to pull.

Useful commands when contributing
---------------------------------
    brew edit                         # opens Textmate with all of Homebrew as a project
    brew edit foobar                  # opens that formula for editing in Textmate
    brew install foobar --debug       # if the build fails, you can fix it
    brew [something] --verbose        # you get a proper Ruby backtrace
    brew install foobar --interactive # opens a new shell at the extract tarball


TODO
====
1. Upgrades, yeah still need this
2. Install multiple versions of tools, which is very useful for eg. Qt
3. Formula revisions, to allow upgrades irrespective of the underlying package


FAQ
===
Are you excessively interested in beer?
---------------------------------------
Yes.

Was Homebrew devised under the influence of alcohol?
-----------------------------------------------------
Yes.