Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 256 lines (176 sloc) 8.161 kb
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
1 Homebrew
2 ========
b1fd407 @mxcl More tweaks to the README
mxcl authored
3 Homebrew is a package management system for OS X. In other words it is a tool
4 that helps you manage the installation of other open source software on your
5 Mac.
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
6
0faff99 @mxcl Refactored README
mxcl authored
7 Here's why you may prefer Homebrew to the alternatives:
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
8
56f49c2 @mxcl The term zeroconf only applies to networking apparently
mxcl authored
9 1. Zero configuration installation
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
10 Copy the contents of this directory to /usr/local. Homebrew is now ready
11 for use.
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
12
b1fd407 @mxcl More tweaks to the README
mxcl authored
13 2. Or… install anywhere!
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
14 You can actually stick this directory anywhere. Like ~/.local or /opt or
15 /lol if you like. You can even move this directory somewhere else later.
16 Homebrew never changes any files outside of its prefix.
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
17
b1fd407 @mxcl More tweaks to the README
mxcl authored
18 3. The GoboLinux approach
19 Packages are installed into their own prefix (eg. /usr/local/Cellar/wget)
50ec7c7 @mxcl Add IRC channel to README
mxcl authored
20 and then symlinked into the Homebrew prefix (eg. /usr/local).
0faff99 @mxcl Refactored README
mxcl authored
21
c07b37d @mxcl The README is too long
mxcl authored
22 This way the filesystem is the package database and packages can be
23 managed with existing command line tools. For example, you can
b1fd407 @mxcl More tweaks to the README
mxcl authored
24 uninstall with rm -rf, list with find, query with du. It also means you
c07b37d @mxcl The README is too long
mxcl authored
25 can install multiple versions of software or libraries and switch
b1fd407 @mxcl More tweaks to the README
mxcl authored
26 on demand.
0faff99 @mxcl Refactored README
mxcl authored
27
c07b37d @mxcl The README is too long
mxcl authored
28 Of course, you don't have to do anything by hand, we also provide a
b1fd407 @mxcl More tweaks to the README
mxcl authored
29 convenient and fully-featured four-letter tool called brew.
0faff99 @mxcl Refactored README
mxcl authored
30
b1fd407 @mxcl More tweaks to the README
mxcl authored
31 4. You don't have to sudo
c07b37d @mxcl The README is too long
mxcl authored
32 It's up to you.
0faff99 @mxcl Refactored README
mxcl authored
33
c07b37d @mxcl The README is too long
mxcl authored
34 5. Create new package descriptions in seconds
35 Package descriptions (formula) are simple Ruby scripts. Generate a
36 template with:
0faff99 @mxcl Refactored README
mxcl authored
37
a7ba35a @mxcl README updates
mxcl authored
38 brew create http://foo.com/tarball-0.8.9.tgz
0faff99 @mxcl Refactored README
mxcl authored
39
b1fd407 @mxcl More tweaks to the README
mxcl authored
40 Or edit an existing formula:
0faff99 @mxcl Refactored README
mxcl authored
41
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
42 brew edit foo
3cf1226 @mxcl Refactor--object orientate where sensible
mxcl authored
43
c07b37d @mxcl The README is too long
mxcl authored
44 6. Package descriptions not required
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
45 MacPorts doesn't support the beta version? Need an older version? Need
a7ba35a @mxcl README updates
mxcl authored
46 custom compile flags? The Homebrew tool-chain is carefully segregated so
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
47 you can build stuff by hand but still end up with package management.
3cf1226 @mxcl Refactor--object orientate where sensible
mxcl authored
48
a7ba35a @mxcl README updates
mxcl authored
49 Just install to the Cellar and then call brew link to symlink that
b1fd407 @mxcl More tweaks to the README
mxcl authored
50 installation into your PATH, eg.
bfbcdb2 @mxcl brew diy command
mxcl authored
51
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
52 ./configure --prefix=/usr/local/Cellar/wget/1.10
53 make install
54 brew ln wget
bfbcdb2 @mxcl brew diy command
mxcl authored
55
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
56 Or Homebrew can figure out the prefix:
3cf1226 @mxcl Refactor--object orientate where sensible
mxcl authored
57
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
58 ./configure `brew diy`
59 cmake . `brew diy`
0faff99 @mxcl Refactored README
mxcl authored
60
b1fd407 @mxcl More tweaks to the README
mxcl authored
61 7. Optimization
a7ba35a @mxcl README updates
mxcl authored
62 We optimize for (Snow) Leopard Intel, binaries are stripped, compile flags
63 are tuned to your exact Mac model. Slow software sucks.
0faff99 @mxcl Refactored README
mxcl authored
64
b1fd407 @mxcl More tweaks to the README
mxcl authored
65 8. Making the most of OS X
a7ba35a @mxcl README updates
mxcl authored
66 A touch of RubyCocoa, a cheeky sysctl query or two and a smattering of
67 FSEvent monitoring. In these manic days of cross-platform development,
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
68 it's can be a welcome relief to use something that is better because
a7ba35a @mxcl README updates
mxcl authored
69 it isn't too generalized.
29c5993 @mxcl Propose git backbone as a plus too
mxcl authored
70
a7ba35a @mxcl README updates
mxcl authored
71 9. No duplication
72 MacPorts is an autarky -- you get a duplicate copy of zlib, OpenSSL,
c07b37d @mxcl The README is too long
mxcl authored
73 Python, etc. Homebrew uses what is already there, and consequently,
74 most stuff has zero dependencies and builds faster.
0faff99 @mxcl Refactored README
mxcl authored
75
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
76 We resist packaging stuff that is already packaged. So we have a [wiki page][wiki]
77 that describes how best to use RubyGems, Pip (or easy_install) and
c07b37d @mxcl The README is too long
mxcl authored
78 CPAN with OS X and Homebrew.
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
79
b1fd407 @mxcl More tweaks to the README
mxcl authored
80 10. Fork with Git
81 The formula are all on git, so just fork to add new packages, or add extra
82 remotes to get packages from more exotic maintainers.
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
83
b1fd407 @mxcl More tweaks to the README
mxcl authored
84 11. Surfing the cutting edge
a7ba35a @mxcl README updates
mxcl authored
85 If the package provides a git://, svn://, cvs:// or hg:// url you can
86 choose to install that instead and then update as often as you like.
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
87
b1fd407 @mxcl More tweaks to the README
mxcl authored
88 12. Homebrew has a beer theme
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
89 Beer goggles will help you to evangelise Homebrew more effectively.
90
e594b05 @mxcl Apparently this reads better
mxcl authored
91 13. Homebrew can help you hook up
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
92 There's no conclusive scientific evidence as yet, but I firmly believe
93 it's just a matter of time and statistics.
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
94
c07b37d @mxcl The README is too long
mxcl authored
95 I know I've made it sound so awesome you can hardly wait to embrace the fresh,
96 hoppy taste of Homebrew, but I should point out that it is really new and
97 still under heavy development. Also:
e565549 @mxcl Why you wouldn't use Homebrew
mxcl authored
98
99 1. It's a little more hands-on than the competition. For example, we don't
c07b37d @mxcl The README is too long
mxcl authored
100 set up PostgreSQL for you after installing it, but we do provide
e565549 @mxcl Why you wouldn't use Homebrew
mxcl authored
101 instructions. This isn't apathy, it's by design -- Homebrew doesn't make
102 assumptions about how you want your software to run. You have to have some
103 knowledge or be willing to learn to use Homebrew for some tasks.
104
105 2. Dependency resolution and updates are basic or not working yet.
106
084c6fa @mxcl At some point the fact we don't support PPC was glossed over
mxcl authored
107 3. We don't support PowerPC or OS X less than Tiger (though you could always
108 maintain your own fork for such things if you like…)
109
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
110 Max Howell — <http://twitter.com/mxcl>
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
111
112
113 Installation
114 ============
c07b37d @mxcl The README is too long
mxcl authored
115 You can install Homebrew anywhere:
5954dc0 @mxcl More installation information
mxcl authored
116
a56c490 @mxcl Improved installation instructions
mxcl authored
117 mkdir homebrew
118 curl -L http://github.com/mxcl/homebrew/tarball/master | tar xz --strip 1 -C homebrew
b1fd407 @mxcl More tweaks to the README
mxcl authored
119
a56c490 @mxcl Improved installation instructions
mxcl authored
120 Homebrew can already be used, try it:
5954dc0 @mxcl More installation information
mxcl authored
121
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
122 homebrew/bin/brew install pip
123 homebrew/bin/brew list pip
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
124
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
125 Notice how Pip was installed to homebrew/bin/pip — Homebrew never touches
126 files outside of its prefix.
b1fd407 @mxcl More tweaks to the README
mxcl authored
127
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
128 But… we recommend installing to /usr/local because:
129 ---------------------------------------------------
a56c490 @mxcl Improved installation instructions
mxcl authored
130 1. It's already in your PATH
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
131 2. It makes it easier to install other stuff like Ruby Gems
c07b37d @mxcl The README is too long
mxcl authored
132
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
133 Build tools all look to /usr/local for library dependencies and thus you can
134 get on with building your own gems and not worry about having to Google for
135 unnecessary build assistance.
b1fd407 @mxcl More tweaks to the README
mxcl authored
136
a56c490 @mxcl Improved installation instructions
mxcl authored
137 But… don't sudo!
138 ----------------
c07b37d @mxcl The README is too long
mxcl authored
139 Homebrew can be used with or without sudo, but, OS X was designed to
140 minimise sudo use, you only need it occasionally. For example, as long as your
141 user is in the admin group, this just works:
631d64c @mxcl Discuss CPAN, RubyGems and EasyInstall
mxcl authored
142
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
143 cpan -i MP3::Info
631d64c @mxcl Discuss CPAN, RubyGems and EasyInstall
mxcl authored
144
c07b37d @mxcl The README is too long
mxcl authored
145 Using sudo all the time is annoying, but far worse — it conditions you to type
146 in your root password without thinking about it. Homebrew compliments OS X
147 so you are unlikely to install anything that really needs to be chown:root.
148 Let this be your last sudo for some time:
631d64c @mxcl Discuss CPAN, RubyGems and EasyInstall
mxcl authored
149
a56c490 @mxcl Improved installation instructions
mxcl authored
150 sudo chown -R `whoami` /usr/local
0faff99 @mxcl Refactored README
mxcl authored
151
c07b37d @mxcl The README is too long
mxcl authored
152 _NOTE_: If you already installed, eg. MySQL into /usr/local then the recursive
153 chown _may_ break it. Fixing MySQL should be as simple as:
66e4570 Warn that chown -R /usr/local may break mysql
Bradley Grzesiak and Nick Karpenske authored
154
c07b37d @mxcl The README is too long
mxcl authored
155 sudo chown -R mysql:mysql /usr/local/mysql
a56c490 @mxcl Improved installation instructions
mxcl authored
156
157 Installing to /usr/local
158 ------------------------
159 curl -L http://github.com/mxcl/homebrew/tarball/master | tar xz --strip 1 -C /usr/local
160
c07b37d @mxcl The README is too long
mxcl authored
161 Homebrew can co-exist with any software already installed in its prefix.
162
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
163 Installing with Git
164 -------------------
a7ba35a @mxcl README updates
mxcl authored
165 cd /usr/local
166 git init
167 git remote add origin git://github.com/mxcl/homebrew.git
168 git pull origin master
169
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
170 One last important caveat
171 -------------------------
a56c490 @mxcl Improved installation instructions
mxcl authored
172 Almost everything Homebrew installs is written in C, so you need Xcode:
0faff99 @mxcl Refactored README
mxcl authored
173
a56c490 @mxcl Improved installation instructions
mxcl authored
174 <http://developer.apple.com/technology/xcode.html>
175
631d64c @mxcl Discuss CPAN, RubyGems and EasyInstall
mxcl authored
176
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
177 Uninstallation
178 ==============
179 cd `brew --prefix`
56b3ea0 @priteau rm -rf .git in the README uninstallation guide
priteau authored
180 rm -rf Cellar
181 brew prune
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
182 rm -rf Library .git .gitignore bin/brew README.md
f9fb44d @mxcl Some further uninstallation information
mxcl authored
183
184 It is worth noting that if you installed somewhere like /usr/local then these
185 uninstallation steps will leave that directory exactly like it was before
186 Homebrew was installed. Unless you manually added new stuff there, in which
187 case those things will still be there too.
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
188
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
189
190 Sample Usage
191 ============
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
192 Install wget:
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
193
7da19cd @mxcl Reflect recent changes in the README
mxcl authored
194 brew install wget
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
195
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
196 Two ways to update the package descriptions:
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
197
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
198 brew update
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
199 cd /usr/local && git pull
200
201 Two ways to delete a package:
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
202
a7ba35a @mxcl README updates
mxcl authored
203 brew uninstall wget
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
204 rm -rf /usr/local/Cellar/wget && brew prune
205
206 Two ways to list all files in a package:
207
208 brew list wget
209 find /usr/local/Cellar/wget
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
210
a7ba35a @mxcl README updates
mxcl authored
211 Two ways to search for a package to install:
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
212
a7ba35a @mxcl README updates
mxcl authored
213 brew search
0faff99 @mxcl Refactored README
mxcl authored
214 ls /usr/local/Library/Formula/
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
215
a7ba35a @mxcl README updates
mxcl authored
216 Two ways to see what is already installed:
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
217
a7ba35a @mxcl README updates
mxcl authored
218 brew list
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
219 ls /usr/local/Cellar/
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
220
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
221 Two ways to compute installed package sizes:
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
222
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
223 brew info wget
224 du /usr/local/Cellar/wget
358c5c8 @mxcl Slept on it, and fresh README corrections
mxcl authored
225
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
226 Show expensive packages:
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
227
bb1a6f1 @mxcl Smoothing out the README
mxcl authored
228 du -md1 /usr/local/Cellar
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
229
631d64c @mxcl Discuss CPAN, RubyGems and EasyInstall
mxcl authored
230
0faff99 @mxcl Refactored README
mxcl authored
231 Contributing New Formulae
232 =========================
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
233 Create a new formula thusly:
5a9cd4b @mxcl Improved documentation
mxcl authored
234
202b95a @mxcl Suggest use of the github gem when contributing
mxcl authored
235 brew create http://example.com/foo-1.2.1.tar.bz2
b90a8a4 @mxcl More instructions for brew mk process
mxcl authored
236
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
237 Homebrew automatically opens Library/Formula/foo.rb in your $EDITOR. You can
c07b37d @mxcl The README is too long
mxcl authored
238 now install it:
b90a8a4 @mxcl More instructions for brew mk process
mxcl authored
239
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
240 brew install foo
202b95a @mxcl Suggest use of the github gem when contributing
mxcl authored
241
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
242 The [wiki][] has more help and information.
202b95a @mxcl Suggest use of the github gem when contributing
mxcl authored
243
29d8557 @mxcl I'll start with a rare Belgian yeast and Sussex hops
mxcl authored
244
fafbbbe @mxcl Change license to BSD
mxcl authored
245 Licensing
246 =========
b1fd407 @mxcl More tweaks to the README
mxcl authored
247 Homebrew is mostly BSD licensed although you should refer to each file to
a7ba35a @mxcl README updates
mxcl authored
248 confirm. Individual formulae are licensed according to their authors' wishes.
fafbbbe @mxcl Change license to BSD
mxcl authored
249
250
c07b37d @mxcl The README is too long
mxcl authored
251 The Wiki
252 ========
5cd79c6 @mxcl Ever more README tweaks
mxcl authored
253 The [wiki][] probably has the answers to any other questions you may have.
202b95a @mxcl Suggest use of the github gem when contributing
mxcl authored
254
c07b37d @mxcl The README is too long
mxcl authored
255 [wiki]:http://wiki.github.com/mxcl/homebrew
Something went wrong with that request. Please try again.