Smoothing out the README
We are more Markdown compliant, but it's still too verbose IMO.
This commit is contained in:
Max Howell
parent
422ec29363
commit
6006c51804
310
README
310
README
@ -1,95 +1,108 @@
|
|||||||
Homebrew
|
Homebrew
|
||||||
========
|
========
|
||||||
Homebrew's purpose is basically the same as MacPorts or Fink, ie. to let you
|
Homebrew's purpose is fundamentally the same as MacPorts or Fink, ie. to let
|
||||||
easily install other open source software on your Mac.
|
you easily install other open source software on your Mac.
|
||||||
|
|
||||||
Here's why you may prefer Homebrew to the alternatives:
|
Here's why you may prefer Homebrew to the alternatives:
|
||||||
|
|
||||||
1. Zeroconf installation
|
1. Zeroconf installation
|
||||||
Copy the contents of this directory to /usr/local. Homebrew is now ready
|
Copy the contents of this directory to /usr/local. Homebrew is now ready
|
||||||
for use.
|
for use.
|
||||||
|
|
||||||
2. Or… install anywhere!
|
2. Or… install anywhere!
|
||||||
You can actually stick this directory anywhere. Like ~/.local or /opt or
|
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.
|
/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
|
3. The GoboLinux approach
|
||||||
Packages are installed to their own prefix (eg. /usr/local/Cellar/wget) and
|
Packages are installed to their own prefix (eg. /usr/local/Cellar/wget)
|
||||||
then symlinked into the Homebrew prefix (eg. /usr/local).
|
and then symlinked into the Homebrew prefix (eg. /usr/local).
|
||||||
|
|
||||||
This way the filesystem is the package database. As is often the case with
|
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.
|
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
|
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.
|
list the package contents. Or du to see its size.
|
||||||
|
|
||||||
4. You don't have to sudo
|
4. You don't have to sudo
|
||||||
It's up to you. We recommend not--see the relevant later section.
|
It's up to you. We recommend not--see the relevant later section.
|
||||||
|
|
||||||
5. Easy package creation
|
5. Easy package creation
|
||||||
Packages are just Ruby scripts. Generate a template with:
|
Packages are just Ruby scripts. Generate a template with:
|
||||||
|
|
||||||
brew mk http://foo.com/tarball-0.8.9.tgz
|
brew mk http://foo.com/tarball-0.8.9.tgz
|
||||||
|
|
||||||
Homebrew will automatically open it for you to tweak with TextMate or
|
Homebrew will automatically open it for you to tweak with TextMate or
|
||||||
$EDITOR.
|
$EDITOR.
|
||||||
|
|
||||||
It is also trivially easy to modify and customise existing formulae.
|
|
||||||
|
|
||||||
6. DIY package installation
|
It is trivially easy to modify or customize existing formulae, and there
|
||||||
MacPorts doesn't support the beta version? Need an older version? Need
|
is a quick edit command too:
|
||||||
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
|
brew edit foo
|
||||||
installation into /usr/local, eg.
|
|
||||||
|
|
||||||
./configure --prefix=/usr/local/Cellar/wget/1.10
|
6. DIY package installation
|
||||||
make install
|
MacPorts doesn't support the beta version? Need an older version? Need
|
||||||
brew ln wget
|
custom compile flags? The Homebrew toolchain is carefully segregated so
|
||||||
|
you can build stuff by hand but still end up with package management.
|
||||||
|
|
||||||
Or Homebrew can figure out the prefix:
|
Just install to the Cellar and then call brew ln to symlink that
|
||||||
|
installation into /usr/local, eg.
|
||||||
|
|
||||||
./configure `brew diy`
|
./configure --prefix=/usr/local/Cellar/wget/1.10
|
||||||
cmake . `brew diy`
|
make install
|
||||||
|
brew ln wget
|
||||||
|
|
||||||
This means you can also install multiple versions of the same package and
|
Or Homebrew can figure out the prefix:
|
||||||
switch on demand.
|
|
||||||
|
|
||||||
7. Optimisation
|
./configure `brew diy`
|
||||||
We optimise for Leopard Intel, binaries are stripped, compile flags
|
cmake . `brew diy`
|
||||||
tweaked. Nobody wants crappy, slow software. Apart from MacPorts and Fink.
|
|
||||||
|
|
||||||
8. Making the most of OS X
|
This means you can also install multiple versions of the same package and
|
||||||
Homebrew knows how many cores you have thanks to RubyCocoa, so it makes
|
switch on demand.
|
||||||
sure when it builds it uses all of them, (unless you don't want it to of
|
|
||||||
course).
|
|
||||||
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
|
7. Optimization
|
||||||
Macports is an autarky. You get a duplicate copy of libz, OpenSSL, Python
|
We optimise for Leopard Intel, binaries are stripped, compile flags
|
||||||
etc. They do this to support OS X Tiger, etc. more easily. We don't support
|
tweaked. Nobody wants crappy, slow software. Apart from MacPorts and Fink.
|
||||||
Tiger, we duplicate nothing. Homebrew compliments OS X, it doesn't seek to
|
|
||||||
operate independently of it.
|
|
||||||
|
|
||||||
A. Fork with Git
|
8. Making the most of OS X
|
||||||
The package descriptions are all on git, so just fork to add new packages,
|
Homebrew knows how many cores you have thanks to RubyCocoa, so it makes
|
||||||
or add extra remotes to get packages from more exotic maintainers.
|
sure when it builds it uses all of them, (unless you don't want it to of
|
||||||
|
course).
|
||||||
|
|
||||||
B. Homebrew has a beer theme
|
Homebrew knows exactly which Mac you have, and optimizes the software it
|
||||||
Beer goggles will help you to evangelise Homebrew more effectively.
|
builds as well it possibly can.
|
||||||
|
|
||||||
C. Homebrew helps get you chicks
|
Homebrew can integrate with Ruby gems, CPAN and Python disttools. These
|
||||||
There's no conclusive scientific evidence as yet, but I firmly believe it's
|
tools exist already and do the job great. We don't reinvent the wheel, we
|
||||||
just a matter of time and statistics.
|
just improve it by making these tools install with more management
|
||||||
|
options.
|
||||||
|
|
||||||
|
9. No duplication
|
||||||
|
MacPorts is an autarky. You get a duplicate copy of zlib, OpenSSL, Python,
|
||||||
|
etc. To cut a long story short, Homebrew doesn't. As a result everything
|
||||||
|
you install has less dependencies and builds much faster.
|
||||||
|
|
||||||
|
10. 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.
|
||||||
|
|
||||||
|
11. Surfing the cutting edge
|
||||||
|
If the package provides a git:// or svn:// 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 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
|
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
|
and embrace the fresh, hoppy taste of Homebrew, but I should point out that it
|
||||||
is really new and still under heavy development. Thanks!
|
is really new and still under heavy development. Thanks!
|
||||||
|
|
||||||
Max Howell <http://twitter.com/mxcl>
|
Max Howell -- <http://twitter.com/mxcl>
|
||||||
|
|
||||||
|
|
||||||
Installation
|
Installation
|
||||||
@ -97,153 +110,147 @@ Installation
|
|||||||
Homebrew is zeroconf, but almost everything it installs is built from source;
|
Homebrew is zeroconf, but almost everything it installs is built from source;
|
||||||
so you need Xcode:
|
so you need Xcode:
|
||||||
|
|
||||||
http://developer.apple.com/technology/xcode.html
|
<http://developer.apple.com/technology/xcode.html>
|
||||||
|
|
||||||
Also, a lot of build scripts assume MacPorts or Fink on OS X. Which isn't a
|
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
|
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
|
you email me with a bug report. So uninstall them (or rename their root
|
||||||
folders if you don't want to burn bridges).
|
folders if you don't want to burn bridges).
|
||||||
|
|
||||||
http://trac.macports.org/wiki/FAQ#HowdoIremoveoruninstallMacPorts
|
<http://trac.macports.org/wiki/FAQ#uninstall>
|
||||||
http://www.finkproject.org/faq/usage-fink.php#removing
|
<http://www.finkproject.org/faq/usage-fink.php#removing>
|
||||||
|
|
||||||
Homebrew uses Ruby and some other stuff that is already installed on Leopard.
|
Homebrew is self-contained and ready to go. Copy this directory anywhere you
|
||||||
It is self-contained and ready to go. Just copy this directory somewhere.
|
like. But we recommend installing to /usr/local because:
|
||||||
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
|
1. It is already in your path
|
||||||
I'm not exactly sure what the best fix for that is yet.
|
2. Build scripts always look in /usr/local for dependencies so it makes it
|
||||||
|
easier for you personally to build and install software
|
||||||
|
|
||||||
If you install to /usr/local don't sudo
|
You can move the location of Homebrew at a later time, although this *will*
|
||||||
---------------------------------------
|
break some tools because they compile they hardcode their installtion prefixes
|
||||||
|
into their binaries. Homebrew does make more effort than competing solutions
|
||||||
|
to prevent this though.
|
||||||
|
|
||||||
|
If you install outside of your home directory -- don't sudo
|
||||||
|
-----------------------------------------------------------
|
||||||
Well clearly you can sudo if you like. Homebrew is all about you doing it your
|
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!
|
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
|
On OS X, this requires your user to be in the admin group, but it doesn't
|
||||||
require sudo:
|
require sudo:
|
||||||
|
|
||||||
$ cpan -i MP3::Info
|
cpan -i MP3::Info
|
||||||
|
|
||||||
OS X is designed to minimise sudo use, you only need it for real root level
|
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
|
stuff. You know your /System and /usr are as clean and pure as the day you
|
||||||
you bought your Mac because you didn't sudo. You can sleep better at night.
|
bought your Mac because you didn't sudo. Sleep better at night!
|
||||||
|
|
||||||
If you are already the kind of guy who installed TextMate by dragging and
|
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
|
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
|
installed under your user privileges too. Lets face it; Homebrew is not
|
||||||
installing anything system-critical. Apple already did that.
|
installing anything system-critical. Apple already did that.
|
||||||
|
|
||||||
Let this be the last sudo you do for quite some time:
|
Let this be the last sudo you do for quite some time:
|
||||||
|
|
||||||
$ sudo chown -R `whoami`:staff /usr/local
|
sudo chown -R `whoami`:staff `brew --prefix`
|
||||||
|
|
||||||
I already have a bunch of junk in /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,
|
Yeah, that's typical. You can either just merge this folder into what is
|
||||||
mv Homebrew there and then just reinstall that stuff using Homebrew.
|
already there -- it's perfectly safe, Homebrew will never touch the other
|
||||||
|
files. Or you can make a note of what is already there and reinstall those
|
||||||
|
packages using Homebrew after deleting /usr/local.
|
||||||
|
|
||||||
How about mate and gitx and that?
|
How about mate and gitx and that?
|
||||||
---------------------------------
|
---------------------------------
|
||||||
They can easily coexist with Homebrew, that's the beauty of the homebrew-way.
|
These tools install from TextMate and GitX into /usr/local/bin. They (and
|
||||||
|
other similar tools) can co-exist with Homebrew without requiring further
|
||||||
|
effort from yourself.
|
||||||
|
|
||||||
|
|
||||||
Usage
|
Uninstallation
|
||||||
=====
|
==============
|
||||||
|
cd `brew --prefix`
|
||||||
|
rm -rf Cellar Library
|
||||||
|
rm bin/brew .gitignore README
|
||||||
|
|
||||||
|
|
||||||
|
Sample Usage
|
||||||
|
============
|
||||||
Install wget:
|
Install wget:
|
||||||
|
|
||||||
brew install wget
|
brew install wget
|
||||||
|
|
||||||
Update package list:
|
Update package list:
|
||||||
cd /usr/local && git pull origin masterbrew [1]
|
|
||||||
|
|
||||||
Delete a package:
|
cd /usr/local && git pull
|
||||||
brew rm wget OR rm -rf /usr/local/Cellar/wget && brew prune
|
|
||||||
|
|
||||||
List all files in a package:
|
Two ways to delete a package:
|
||||||
brew list wget OR find /usr/local/Cellar/wget
|
|
||||||
|
brew rm 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
|
||||||
|
|
||||||
Search for a package to install:
|
Search for a package to install:
|
||||||
|
|
||||||
ls /usr/local/Library/Formula/
|
ls /usr/local/Library/Formula/
|
||||||
|
|
||||||
Search for a package already installed:
|
Search for a package already installed:
|
||||||
|
|
||||||
ls /usr/local/Cellar/
|
ls /usr/local/Cellar/
|
||||||
|
|
||||||
Compute installed size of package:
|
Two ways to compute installed package sizes:
|
||||||
brew info wget OR du /usr/local/Cellar/wget
|
|
||||||
|
brew info wget
|
||||||
|
du /usr/local/Cellar/wget
|
||||||
|
|
||||||
Show expensive packages:
|
Show expensive packages:
|
||||||
|
|
||||||
du -md1 /usr/local/Cellar
|
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
|
A more thorough exploration of the brew command is available at the [Homebrew
|
||||||
installation, amend the Ruby script. If you want to improve the brew command
|
wiki][wiki].
|
||||||
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
|
CPAN, EasyInstall, RubyGems
|
||||||
===========================
|
===========================
|
||||||
Homebrew doesn't reinvent the wheel. These tools are already designed to make
|
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
|
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
|
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:
|
to /usr, so we suggest you adapt the tools to install into Homebrew's prefix.
|
||||||
|
|
||||||
http://github.com/mxcl/homebrew/wiki
|
There are preliminary instructions on the [wiki][].
|
||||||
|
|
||||||
|
|
||||||
Contributing New Formulae
|
Contributing New Formulae
|
||||||
=========================
|
=========================
|
||||||
Homebrew can generate the formula with most stuff pre-done:
|
Formulae are simply Ruby scripts. Generate a formula with most bits filled-in:
|
||||||
|
|
||||||
brew mk http://foo.org/foobar-1.2.1.tar.bz2
|
brew mk http://foo.org/foobar-1.2.1.tar.bz2
|
||||||
|
|
||||||
You now have /usr/local/Library/Formula/foobar.rb. This may already work.
|
Check it over and try to install it:
|
||||||
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
|
brew install foobar
|
||||||
|
|
||||||
Fork http://github.com/mxcl/homebrew and ask mxcl to pull.
|
Check the [wiki][] for more detailed information and tips about contribution.
|
||||||
|
|
||||||
Useful commands when contributing
|
If you want your formula to become part of this distribution, fork
|
||||||
---------------------------------
|
<http://github.com/mxcl/homebrew> and ask mxcl to pull. Alternatively maintain
|
||||||
brew edit # opens Textmate with all of Homebrew as a project
|
your own distribution. Maybe you want to support Tiger? Or use special compile
|
||||||
brew edit foobar # opens that formula for editing in Textmate
|
flags? Go ahead that's what git is all about! :)
|
||||||
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
|
Important Missing Bits
|
||||||
====
|
======================
|
||||||
1. Upgrades, yeah still need this
|
1. Package upgrades
|
||||||
2. Install multiple versions of tools, which is very useful for eg. Qt
|
2. Dependency resolution
|
||||||
3. Formula revisions, to allow upgrades irrespective of the underlying package
|
|
||||||
|
Coming soon!
|
||||||
|
|
||||||
|
|
||||||
Licensing
|
Licensing
|
||||||
@ -254,10 +261,11 @@ Individual formulae are licensed according to their authors wishes.
|
|||||||
|
|
||||||
FAQ
|
FAQ
|
||||||
===
|
===
|
||||||
Are you excessively interested in beer?
|
1. Are you excessively interested in beer?
|
||||||
---------------------------------------
|
Yes.
|
||||||
Yes.
|
|
||||||
|
|
||||||
Was Homebrew devised under the influence of alcohol?
|
2. Was Homebrew devised under the influence of alcohol?
|
||||||
-----------------------------------------------------
|
Yes.
|
||||||
Yes.
|
|
||||||
|
|
||||||
|
[wiki]: http://wiki.github.com/mxcl/homebrew
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user