Documentation rewrite
Much leaner README now. The website evangelises, and the Wiki is thorough.
This commit is contained in:
Max Howell
parent
9f46adeeab
commit
2652880bd9
263
README.md
263
README.md
@ -1,255 +1,36 @@
|
|||||||
Homebrew
|
Homebrew
|
||||||
========
|
========
|
||||||
Homebrew is a package management system for OS X. In other words it is a tool
|
Homebrew helps you install the UNIX tools that didn't come with OS X.
|
||||||
that helps you manage the installation of other open source software on your
|
|
||||||
Mac.
|
|
||||||
|
|
||||||
Here's why you may prefer Homebrew to the alternatives:
|
|
||||||
|
|
||||||
1. Zero configuration 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.
|
|
||||||
Homebrew never changes any files outside of its prefix.
|
|
||||||
|
|
||||||
3. The GoboLinux approach
|
|
||||||
Packages are installed into 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 and packages can be
|
|
||||||
managed with existing command line tools. For example, you can
|
|
||||||
uninstall with rm -rf, list with find, query with du. It also means you
|
|
||||||
can install multiple versions of software or libraries and switch
|
|
||||||
on demand.
|
|
||||||
|
|
||||||
Of course, you don't have to do anything by hand, we also provide a
|
|
||||||
convenient and fully-featured four-letter tool called brew.
|
|
||||||
|
|
||||||
4. You don't have to sudo
|
|
||||||
It's up to you.
|
|
||||||
|
|
||||||
5. Create new package descriptions in seconds
|
|
||||||
Package descriptions (formula) are simple Ruby scripts. Generate a
|
|
||||||
template with:
|
|
||||||
|
|
||||||
brew create http://foo.com/tarball-0.8.9.tgz
|
|
||||||
|
|
||||||
Or edit an existing formula:
|
|
||||||
|
|
||||||
brew edit foo
|
|
||||||
|
|
||||||
6. Package descriptions not required
|
|
||||||
MacPorts doesn't support the beta version? Need an older version? Need
|
|
||||||
custom compile flags? The Homebrew tool-chain 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 link to symlink that
|
|
||||||
installation into your PATH, eg.
|
|
||||||
|
|
||||||
./configure --prefix=/usr/local/Cellar/wget/1.10
|
|
||||||
make install
|
|
||||||
brew ln wget
|
|
||||||
|
|
||||||
Or Homebrew can figure out the prefix:
|
|
||||||
|
|
||||||
./configure `brew diy`
|
|
||||||
cmake . `brew diy`
|
|
||||||
|
|
||||||
7. Optimization
|
|
||||||
We optimize for (Snow) Leopard Intel, binaries are stripped, compile flags
|
|
||||||
are tuned to your exact Mac model. Slow software sucks.
|
|
||||||
|
|
||||||
8. Making the most of OS X
|
|
||||||
A touch of RubyCocoa, a cheeky sysctl query or two and a smattering of
|
|
||||||
FSEvent monitoring. In these manic days of cross-platform development,
|
|
||||||
it's can be a welcome relief to use something that is better because
|
|
||||||
it isn't too generalized.
|
|
||||||
|
|
||||||
9. No duplication
|
|
||||||
MacPorts is an autarky -- you get a duplicate copy of zlib, OpenSSL,
|
|
||||||
Python, etc. Homebrew uses what is already there, and consequently,
|
|
||||||
most stuff has zero dependencies and builds faster.
|
|
||||||
|
|
||||||
We resist packaging stuff that is already packaged. So we have a [wiki page][wiki]
|
|
||||||
that describes how best to use RubyGems, Pip (or easy_install) and
|
|
||||||
CPAN with OS X and Homebrew.
|
|
||||||
|
|
||||||
10. Fork with Git
|
|
||||||
The formula are all on git, so just fork to add new packages, or add extra
|
|
||||||
remotes to get packages from more exotic maintainers.
|
|
||||||
|
|
||||||
11. Surfing the cutting edge
|
|
||||||
If the package provides a git://, svn://, cvs:// or hg:// url you can
|
|
||||||
choose to install that instead and then update as often as you like.
|
|
||||||
|
|
||||||
12. Homebrew has a beer theme
|
|
||||||
Beer goggles will help you to evangelise Homebrew more effectively.
|
|
||||||
|
|
||||||
13. Homebrew can help you hook up
|
|
||||||
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 embrace the fresh,
|
|
||||||
hoppy taste of Homebrew, but I should point out that it is really new and
|
|
||||||
still under heavy development. Also:
|
|
||||||
|
|
||||||
1. It's a little more hands-on than the competition. For example, we don't
|
|
||||||
set up PostgreSQL for you after installing it, but we do provide
|
|
||||||
instructions. This isn't apathy, it's by design -- Homebrew doesn't make
|
|
||||||
assumptions about how you want your software to run. You have to have some
|
|
||||||
knowledge or be willing to learn to use Homebrew for some tasks.
|
|
||||||
|
|
||||||
2. Dependency resolution and updates are basic or not working yet.
|
|
||||||
|
|
||||||
3. We don't support PowerPC or OS X less than Tiger (though you could always
|
|
||||||
maintain your own fork for such things if you like…)
|
|
||||||
|
|
||||||
Max Howell — <http://twitter.com/mxcl>
|
|
||||||
|
|
||||||
|
|
||||||
Installation
|
Quick Install
|
||||||
============
|
-------------
|
||||||
You can install Homebrew anywhere:
|
Install [Xcode][xcode] and then run this script: <http://gist.github.com/323731>
|
||||||
|
|
||||||
mkdir homebrew
|
If you want to install Homebrew somewhere other than /usr/local see the
|
||||||
curl -L http://github.com/mxcl/homebrew/tarball/master | tar xz --strip 1 -C homebrew
|
[installation instructions][install].
|
||||||
|
|
||||||
Homebrew can already be used, try it:
|
|
||||||
|
|
||||||
homebrew/bin/brew install pip
|
Look dude, I know what I'm doing!
|
||||||
homebrew/bin/brew list pip
|
---------------------------------
|
||||||
|
Alright then… as long as you're sure:
|
||||||
|
|
||||||
Notice how Pip was installed to homebrew/bin/pip — Homebrew never touches
|
|
||||||
files outside of its prefix.
|
|
||||||
|
|
||||||
But… we recommend installing to /usr/local because:
|
|
||||||
---------------------------------------------------
|
|
||||||
1. It's already in your PATH
|
|
||||||
2. It makes it easier to install other stuff like Ruby Gems
|
|
||||||
|
|
||||||
Build tools all look to /usr/local for library dependencies and thus you can
|
|
||||||
get on with building your own gems and not worry about having to Google for
|
|
||||||
unnecessary build assistance.
|
|
||||||
|
|
||||||
But… don't sudo!
|
|
||||||
----------------
|
|
||||||
Homebrew can be used with or without sudo, but, OS X was designed to
|
|
||||||
minimise sudo use, you only need it occasionally. For example, as long as your
|
|
||||||
user is in the admin group, this just works:
|
|
||||||
|
|
||||||
cpan -i MP3::Info
|
|
||||||
|
|
||||||
Using sudo all the time is annoying, but far worse — it conditions you to type
|
|
||||||
in your root password without thinking about it. Homebrew compliments OS X
|
|
||||||
so you are unlikely to install anything that really needs to be chown:root.
|
|
||||||
Let this be your last sudo for some time:
|
|
||||||
|
|
||||||
sudo chown -R `whoami` /usr/local
|
|
||||||
|
|
||||||
_NOTE_: If you already installed, eg. MySQL into /usr/local then the recursive
|
|
||||||
chown _may_ break it. Fixing MySQL should be as simple as:
|
|
||||||
|
|
||||||
sudo chown -R mysql:mysql /usr/local/mysql
|
|
||||||
|
|
||||||
Installing to /usr/local
|
|
||||||
------------------------
|
|
||||||
curl -L http://github.com/mxcl/homebrew/tarball/master | tar xz --strip 1 -C /usr/local
|
|
||||||
|
|
||||||
Homebrew can co-exist with any software already installed in its prefix.
|
|
||||||
|
|
||||||
Installing with Git
|
|
||||||
-------------------
|
|
||||||
cd /usr/local
|
cd /usr/local
|
||||||
git init
|
sudo chown -R $USER .
|
||||||
git remote add origin git://github.com/mxcl/homebrew.git
|
curl -sf http://github.com/mxcl/homebrew/tarball/master | tar xz --strip 1
|
||||||
git pull origin master
|
|
||||||
|
|
||||||
One last important caveat
|
|
||||||
-------------------------
|
|
||||||
Almost everything Homebrew installs is written in C, so you need Xcode:
|
|
||||||
|
|
||||||
<http://developer.apple.com/technology/xcode.html>
|
|
||||||
|
|
||||||
|
|
||||||
Uninstallation
|
|
||||||
==============
|
|
||||||
cd `brew --prefix`
|
|
||||||
rm -rf Cellar
|
|
||||||
brew prune
|
|
||||||
rm -rf Library .git .gitignore bin/brew README.md
|
|
||||||
|
|
||||||
It is worth noting that if you installed somewhere like /usr/local then these
|
|
||||||
uninstallation steps will leave that directory exactly like it was before
|
|
||||||
Homebrew was installed. Unless you manually added new stuff there, in which
|
|
||||||
case those things will still be there too.
|
|
||||||
|
|
||||||
|
|
||||||
Sample Usage
|
|
||||||
============
|
|
||||||
Install wget:
|
|
||||||
|
|
||||||
brew install wget
|
|
||||||
|
|
||||||
Two ways to update the package descriptions:
|
|
||||||
|
|
||||||
brew update
|
|
||||||
cd /usr/local && git pull
|
|
||||||
|
|
||||||
Two ways to delete a package:
|
|
||||||
|
|
||||||
brew uninstall wget
|
|
||||||
rm -rf /usr/local/Cellar/wget && brew prune
|
|
||||||
|
|
||||||
Two ways to list all files in a package:
|
|
||||||
|
|
||||||
brew list wget
|
|
||||||
find /usr/local/Cellar/wget
|
|
||||||
|
|
||||||
Two ways to search for a package to install:
|
|
||||||
|
|
||||||
brew search
|
|
||||||
ls /usr/local/Library/Formula/
|
|
||||||
|
|
||||||
Two ways to see what is already installed:
|
|
||||||
|
|
||||||
brew list
|
|
||||||
ls /usr/local/Cellar/
|
|
||||||
|
|
||||||
Two ways to compute installed package sizes:
|
|
||||||
|
|
||||||
brew info wget
|
|
||||||
du /usr/local/Cellar/wget
|
|
||||||
|
|
||||||
Show expensive packages:
|
|
||||||
|
|
||||||
du -md1 /usr/local/Cellar
|
|
||||||
|
|
||||||
|
|
||||||
Contributing New Formulae
|
|
||||||
=========================
|
|
||||||
Create a new formula thusly:
|
|
||||||
|
|
||||||
brew create http://example.com/foo-1.2.1.tar.bz2
|
|
||||||
|
|
||||||
Homebrew automatically opens Library/Formula/foo.rb in your $EDITOR. You can
|
|
||||||
now install it:
|
|
||||||
|
|
||||||
brew install foo
|
|
||||||
|
|
||||||
The [wiki][] has more help and information.
|
|
||||||
|
|
||||||
|
|
||||||
Licensing
|
|
||||||
=========
|
|
||||||
Homebrew is mostly BSD licensed although you should refer to each file to
|
|
||||||
confirm. Individual formulae are licensed according to their authors' wishes.
|
|
||||||
|
|
||||||
|
|
||||||
The Wiki
|
The Wiki
|
||||||
========
|
--------
|
||||||
The [wiki][] probably has the answers to any other questions you may have.
|
The [wiki][] can answer your remaining questions.
|
||||||
|
|
||||||
|
|
||||||
|
Who Are You?
|
||||||
|
------------
|
||||||
|
I'm [Max Howell][mxcl] and I'm a splendid chap.
|
||||||
|
|
||||||
|
|
||||||
[wiki]:http://wiki.github.com/mxcl/homebrew
|
[wiki]:http://wiki.github.com/mxcl/homebrew
|
||||||
|
[install]:http://wiki.github.com/mxcl/homebrew/Installation
|
||||||
|
[xcode]:http://developer.apple.com/technology/xcode.html
|
||||||
|
[mxcl]:http://twitter.com/mxcl
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user