brew/README

Homebrew
========
A simple package management system for OS X Leopard. Packages are brewed in
individual, versioned kegs. For example:

/usr/local/Cellar/wget/1.11.4/bin/wget
/usr/local/Cellar/wget/1.11.4/share/man/man1/wget.1
…

And symlinks are created to allow a normal POSIX tree:

/usr/local/bin/wget -> /usr/local/Cellar/wget/1.11.4/bin/wget
/usr/local/etc/wgetrc -> /usr/local/Cellar/wget/1.11.4/etc/wgetrc
…

This way the filesystem is the package database. Everything else is now easy.
We are made of win.

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


Installation
============
Firstly, we build from source, so you need Xcode.

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

Next, uninstall MacPorts and Fink (or just rename their root folders). Many
build scripts blindly look in /opt/local etc. and end up linking to that stuff
anyway! If you just want to trial Homebrew then you'll get away with not moving MacPorts or Fink, it's just not recommended.

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).

You can stick this directory in your home directory if you like. In that case
a typical (POSIX) choice would be: /User/mxcl/.local

If you don't install to /usr/local (but seriously it's great!) then you'll
need to edit your ~/.profile file to add Homebrew's bin directory to the PATH.

Don't sudo
----------
Well clearly you can sudo if you like. Homebrew is all about you doing it your
way. But we recommend that you don't sudo. Apple designed the OS X heirarchy
so that you can do things like:

    $ cpan -i MP3::Info

Without having to sudo (although you still need an admin user account).
Clearly they intended for you to install new stuff that they didn't provide
without becoming root.

Sudo is dangerous, it can break your system. All the tools Homebrew installs 
are not system critical. Sudo just makes Homebrew more difficult and more 
dangerous for you to play with.

If you don't sudo, you know for sure that /usr and /System haven't been
tampered with. Thus you'll sleep better at night.


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

Update recipes list:
    cd /usr/local && git pull origin masterbrew

Delete a package:
 1. rm -rf /usr/local/Cellar/wget && brew prune
 2. brew rm wget

List all files in a package:
 1. find /usr/local/Cellar/wget
 2. brew list wget

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

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

List all packages available to install:
    ls /usr/local/Library/Formula

Compute installed size of package:
    du -h /usr/local/Cellar/wget
    
Show expensive packages:
    du -md1 /usr/local/Cellar

You get the idea.

Maybe we should overload more of this stuff with the brew command, but frankly
I feel that this way *you* will understand the capabilities of the system
better. And you basically know everything that is going on.

With apt, you type apt-get install wget. Now what is happening? With Homebrew
you are running a ruby script. You know what is happening. You can easily and
quickly read the source and modify it and then push the patch to github if
anything you need is missing or something is not working. This is real open
source.

NOTE you have to install git before you can update the package list, but 
that's easy:

    brew install git


Why Not MacPorts?
=================
1. MacPorts installs its own libz, its own openssl, etc. It's an autarky.
   This makes no sense to me. OS X comes with all that stuff.
2. MacPorts support Tiger, and PPC. We don't, so things are better optimised.
3. cmake has like 100 dependencies in MacPorts, with Homebrew it has one


Homebrew Will Never Build:
==========================
1. KDE, or GNOME, or anything that vast
2. Anything that should be distributed in a .app bundle
3. Anything that needs to install outside of the Homebrew tree
4. Stuff OS X already does, eg. rubygems (duplication sucks)

I say never, but if you really want these things you can fork the tree and
do it yourself. It's just my tree will never build those things.


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, Ruby and Python 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


How do I Notify Someone that a Package is out of Date?
======================================================
Chances are that if the package hasn't been updated for a few days, then the
previous maintainer has vanished. You have to do it. Don't worry, unlike every
other packaging system ever, it's easy with Homebrew:

1. Edit the relevant ruby file in /usr/local/Formula
2. Fork Homebrew on github (or git diff > patch)
3. Send mxcl a pull request

Congratulations, you have contributed to an open source project!


Contributing
============
New Formulae
------------
Firstly generate the formula:

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

You now have /usr/local/Library/Formula/foobar.rb.
Now it would be useful to amend the formula based on its 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

If it worked, fork http://github.com/mxcl/homebrew and ask me to pull. If it 
didn't you may need to dig a little deeper.

I'll try to optimise the package when I pull, but it would be nice if you did
that for me ;)

HomeBrew is not an autarky so any dependencies outside of OS X that a package
may require may be installed separately. We have functions to help with that.

Other 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 # you are dumped at a shell with the extracted tarball as PWD

Code
----
Yes please! Fork and improve :)

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.