Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Refactored README

Trying to sell Homebrew more in first section.

Reworked text in later sections.
  • Loading branch information...
commit 0faff99c7edf774d5056a79ced5d8e98a6f46c5c 1 parent 8e357f3
Max Howell mxcl authored

Showing 1 changed file with 108 additions and 109 deletions. Show diff stats Hide diff stats

  1. +108 109 README
217 README
... ... @@ -1,33 +1,78 @@
1 1 Homebrew
2 2 ========
3   -A simple package management system for OS X Leopard. Packages are brewed in
4   -individual, versioned kegs. For example:
  3 +Homebrew's purpose is the same as MacPorts or Fink, ie. to let you easily
  4 +install other open source software on your Mac.
5 5
6   -/usr/local/Cellar/wget/1.11.4/bin/wget
7   -/usr/local/Cellar/wget/1.11.4/share/man/man1/wget.1
8   -…
  6 +Here's why you may prefer Homebrew to the alternatives:
9 7
10   -And symlinks are created to allow a normal POSIX tree:
  8 +1. Zeroconf installation
  9 + Copy the contents of this directory to /usr/local. Homebrew is now ready
  10 + for use.
11 11
12   -/usr/local/bin/wget -> /usr/local/Cellar/wget/1.11.4/bin/wget
13   -/usr/local/etc/wgetrc -> /usr/local/Cellar/wget/1.11.4/etc/wgetrc
14   -…
  12 +2. Or… install anywhere!
  13 + You can actually stick this directory anywhere. Like ~/.local or /opt or
  14 + /lol if you like. You can even move this directory somewhere else later.
15 15
16   -This way the filesystem is the package database. Everything else is now easy.
17   -We are made of win.
  16 +3. The GoboLinux approach
  17 + Packages are installed to their own prefix (eg. /usr/local/Cellar/wget) and
  18 + then symlinked into the Homebrew prefix (eg. /usr/local).
  19 +
  20 + This way the filesystem is the package database. As is often the case with
  21 + the simplest possible solution, it makes everything else easier and better.
  22 +
  23 + Eg. You can, if you like, rm -rf to uninstall a package. Or use find to
  24 + list the package contents. Or du to see its size.
  25 +
  26 +4. You don't have to sudo
  27 + It's up to you. We recommend not to--see the relevant later section.
  28 +
  29 +5. Easy package creation
  30 + Packages are just Ruby scripts. Generate a template with:
  31 +
  32 + brew mk http://foo/tarball-0.89.tgz
  33 +
  34 + Homebrew will automatically open it for you to tweak with TextMate or
  35 + $EDITOR.
  36 +
  37 + Or skip going via a package entirely, just install into the Cellar and use
  38 + "brew ln" to symlink it into the main tree.
  39 +
  40 +6. Optimisation
  41 + We optimise for Leopard Intel, binaries are stripped, compile flags
  42 + tweaked. Nobody wants crappy, slow software. Apart from MacPorts and Fink.
  43 +
  44 +7. Integration with existing OS X technologies
  45 + Homebrew integrates with Ruby gems, CPAN and Python disttools. These tools
  46 + exist already and do the job great. We don't reinvent the wheel, we just
  47 + improve it by making these tools install with more management options.
  48 +
  49 +8. Complimenting what OS X already has
  50 + Macports is an autarky. You get a duplicate copy of libz, OpenSSL, Python
  51 + etc. They do this to support OS X Tiger, etc. more easily. We don't support
  52 + Tiger, we duplicate nothing. Homebrew compliments OS X, it doesn't seek to
  53 + operate independently of it.
  54 +
  55 +9. Homebrew has a beer theme
  56 + Beer goggles will help you to evangelise Homebrew more effectively.
  57 +
  58 +X. Homebrew helps get you chicks
  59 + There's no conclusive scientific evidence as yet, but I firmly believe it's
  60 + just a matter of statistics and time.
18 61
19 62 Max Howell <http://twitter.com/mxcl>
20 63
21 64
22 65 Installation
23 66 ============
24   -Firstly, we build from source, so you need Xcode.
  67 +Homebrew is zeroconf, but almost everything it installs is built from source;
  68 +so you need Xcode:
25 69
26 70 http://developer.apple.com/technology/xcode.html
27 71
28   -Next, uninstall MacPorts and Fink (or just rename their root folders). Many
29   -build scripts blindly look in /opt/local etc. and end up linking to that stuff
30   -anyway! If you just want to trial Homebrew then you'll get away with not moving MacPorts or Fink, it's just not recommended.
  72 +Also, a lot of build scripts assume MacPorts or Fink on OS X. Which isn't a
  73 +problem until you uninstall them and stuff you built with Homebrew breaks and
  74 +you email me with a bug report. So uninstall them (or rename their root
  75 +folders if you don't want to burn bridges).
31 76
32 77 http://trac.macports.org/wiki/FAQ#HowdoIremoveoruninstallMacPorts
33 78 http://www.finkproject.org/faq/usage-fink.php#removing
@@ -37,30 +82,37 @@ It is self-contained and ready to go. Just copy this directory somewhere.
37 82 Things work really well if you put it in /usr/local (especially if you are a
38 83 developer).
39 84
40   -You can stick this directory in your home directory if you like. In that case
41   -a typical (POSIX) choice would be: /User/mxcl/.local
42   -
43   -If you don't install to /usr/local (but seriously it's great!) then you'll
44   -need to edit your ~/.profile file to add Homebrew's bin directory to the PATH.
45   -
46   -Don't sudo
47   -----------
  85 +If you install to /usr/local don't sudo
  86 +---------------------------------------
48 87 Well clearly you can sudo if you like. Homebrew is all about you doing it your
49   -way. But we recommend that you don't sudo. Apple designed the OS X heirarchy
50   -so that you can do things like:
  88 +way. But the Homebrew recommendation is: don't sudo!
  89 +
  90 +On OS X, this requires your user to be in the admin group, but it doesn't
  91 +require sudo:
51 92
52 93 $ cpan -i MP3::Info
53 94
54   -Without having to sudo (although you still need an admin user account).
55   -Clearly they intended for you to install new stuff that they didn't provide
56   -without becoming root.
  95 +OS X is designed to minimise sudo use, you only need it for real root level
  96 +stuff. On OS X you know your /System and /usr are as clean and pure as the day
  97 +you bought your Mac because you didn't sudo. You can sleep better at night.
  98 +
  99 +If you are already the kind of guy who installed TextMate by dragging and
  100 +dropping it to /Applications, then you won't mind if libflac and pngcrush are
  101 +installed under your user privileges too. Lets face it; Homebrew is not
  102 +installing anything system-critical. Apple already did that.
57 103
58   -Sudo is dangerous, it can break your system. All the tools Homebrew installs
59   -are not system critical. Sudo just makes Homebrew more difficult and more
60   -dangerous for you to play with.
  104 +Let this be the last sudo you do for quite some time:
61 105
62   -If you don't sudo, you know for sure that /usr and /System haven't been
63   -tampered with. Thus you'll sleep better at night.
  106 + $ sudo chown -r `whoami`:staff /usr/local
  107 +
  108 +I already have a bunch of junk in /usr/local
  109 +--------------------------------------------
  110 +Yeah that's typical. See what you've got, mv the local folder somewhere else,
  111 +mv Homebrew there and then just reinstall that stuff using Homebrew.
  112 +
  113 +How about mate and gitx and that?
  114 +---------------------------------
  115 +They can easily coexist with Homebrew, that's the beauty of the homebrew-way.
64 116
65 117
66 118 Usage
@@ -68,69 +120,38 @@ Usage
68 120 Install wget:
69 121 brew install wget
70 122
71   -Update recipes list:
72   - cd /usr/local && git pull origin masterbrew
  123 +Update package list:
  124 + cd /usr/local && git pull origin masterbrew [1]
73 125
74 126 Delete a package:
75   - 1. rm -rf /usr/local/Cellar/wget && brew prune
76   - 2. brew rm wget
  127 + brew rm wget OR rm -rf /usr/local/Cellar/wget && brew prune
77 128
78 129 List all files in a package:
79   - 1. find /usr/local/Cellar/wget
80   - 2. brew list wget
  130 + brew list wget OR find /usr/local/Cellar/wget
81 131
82 132 Search for a package to install:
83   - ls /usr/local/Library/Formula/*wget*
  133 + ls /usr/local/Library/Formula/
84 134
85 135 Search for a package already installed:
86   - ls /usr/local/Cellar/*wget*
87   -
88   -List all packages available to install:
89   - ls /usr/local/Library/Formula
  136 + ls /usr/local/Cellar/
90 137
91 138 Compute installed size of package:
92   - du -h /usr/local/Cellar/wget
  139 + brew info wget OR du /usr/local/Cellar/wget
93 140
94 141 Show expensive packages:
95 142 du -md1 /usr/local/Cellar
96 143
97   -You get the idea.
98   -
99   -Maybe we should overload more of this stuff with the brew command, but frankly
100   -I feel that this way *you* will understand the capabilities of the system
101   -better. And you basically know everything that is going on.
102   -
103   -With apt, you type apt-get install wget. Now what is happening? With Homebrew
104   -you are running a ruby script. You know what is happening. You can easily and
105   -quickly read the source and modify it and then push the patch to github if
106   -anything you need is missing or something is not working. This is real open
107   -source.
  144 +With Homebrew this is all Ruby. If you want to improve the package
  145 +installation, amend the Ruby script. If you want to improve the brew command
  146 +amend the Ruby script. If you want to know exactly what is going on, read the
  147 +Ruby script.
108 148
109   -NOTE you have to install git before you can update the package list, but
  149 +[1] You have to install git before you can update the package list, but
110 150 that's easy:
111 151
112 152 brew install git
113 153
114 154
115   -Why Not MacPorts?
116   -=================
117   -1. MacPorts installs its own libz, its own openssl, etc. It's an autarky.
118   - This makes no sense to me. OS X comes with all that stuff.
119   -2. MacPorts support Tiger, and PPC. We don't, so things are better optimised.
120   -3. cmake has like 100 dependencies in MacPorts, with Homebrew it has one
121   -
122   -
123   -Homebrew Will Never Build:
124   -==========================
125   -1. KDE, or GNOME, or anything that vast
126   -2. Anything that should be distributed in a .app bundle
127   -3. Anything that needs to install outside of the Homebrew tree
128   -4. Stuff OS X already does, eg. rubygems (duplication sucks)
129   -
130   -I say never, but if you really want these things you can fork the tree and
131   -do it yourself. It's just my tree will never build those things.
132   -
133   -
134 155 Why Compile From Source?
135 156 ========================
136 157 Since we only target Intel Leopard boxes, why not just distribute binaries?
@@ -149,29 +170,14 @@ to /usr, so we suggest you adapt the tools to install into Homebrew's prefix:
149 170 http://github.com/mxcl/homebrew/wiki
150 171
151 172
152   -How do I Notify Someone that a Package is out of Date?
153   -======================================================
154   -Chances are that if the package hasn't been updated for a few days, then the
155   -previous maintainer has vanished. You have to do it. Don't worry, unlike every
156   -other packaging system ever, it's easy with Homebrew:
157   -
158   -1. Edit the relevant ruby file in /usr/local/Formula
159   -2. Fork Homebrew on github (or git diff > patch)
160   -3. Send mxcl a pull request
161   -
162   -Congratulations, you have contributed to an open source project!
163   -
164   -
165   -Contributing
166   -============
167   -New Formulae
168   -------------
169   -Firstly generate the formula:
  173 +Contributing New Formulae
  174 +=========================
  175 +Homebrew can generate the formula with most stuff pre-done:
170 176
171 177 brew mk http://foo.org/foobar-1.2.1.tar.bz2
172 178
173   -You now have /usr/local/Library/Formula/foobar.rb.
174   -Now it would be useful to amend the formula based on its configure options:
  179 +You now have /usr/local/Library/Formula/foobar.rb. This may already work.
  180 +But maybe there are some juicy configure options?
175 181
176 182 brew install foobar --help
177 183
@@ -186,22 +192,15 @@ Try to install it:
186 192
187 193 brew install foobar
188 194
189   -If it worked, fork http://github.com/mxcl/homebrew and ask me to pull. If it
190   -didn't you may need to dig a little deeper.
191   -
192   -I'll try to optimise the package when I pull, but it would be nice if you did
193   -that for me ;)
194   -
195   -HomeBrew is not an autarky so any dependencies outside of OS X that a package
196   -may require may be installed separately. We have functions to help with that.
  195 +Fork http://github.com/mxcl/homebrew and ask mxcl to pull.
197 196
198 197 Other useful commands when contributing
199 198 ---------------------------------------
200   - brew edit # opens Textmate with all of Homebrew as a project
201   - brew edit foobar # opens that formula for editing in Textmate
202   - brew install foobar --debug # if the build fails, you can fix it
203   - brew [something] --verbose # you get a proper ruby backtrace
204   - brew install foobar --interactive # you are dumped at a shell with the extracted tarball as PWD
  199 + brew edit # opens Textmate with all of Homebrew as a project
  200 + brew edit foobar # opens that formula for editing in Textmate
  201 + brew install foobar --debug # if the build fails, you can fix it
  202 + brew [something] --verbose # you get a proper ruby backtrace
  203 + brew install foobar --interactive # opens a new shell at the extract tarball
205 204
206 205 Code
207 206 ----

0 comments on commit 0faff99

Please sign in to comment.
Something went wrong with that request. Please try again.