Skip to content
This repository
Newer
Older
100644 279 lines (176 sloc) 8.969 kb
bbee9761 »
2010-07-07 The README
1 Build CouchDB
2 =============
3
4 Build CouchDB is a wrapper or master project which pulls in, from official
5 sources, CouchDB plus all of its dependencies. It is the most straightforward
6 and reliable procedure to build official CouchDB releases from source.
7
8 Build CouchDB builds an isolated, independent server. You do not need
73e18807 »
2010-07-30 Documentation clarification
9 administrator access to run it. You can run several couches (for example, 0.10,
10 0.11, 1.0 releases) side-by-side.
bbee9761 »
2010-07-07 The README
11
68d9d032 »
2010-11-01 See about anchoring
12 <a name="platforms"></a>
bbee9761 »
2010-07-07 The README
13 ## Supported Platforms
14
15 Build CouchDB is developed and tested on the following operating systems:
16
c31e458a »
2011-11-08 Updated list of supported platforms
17 * Red Hat Enterprise Linux Server release 5.5 (Tikanga)
18 * CentOS 5.5
19 * Debian GNU/Linux 5.0 (Lenny)
20 * Ubuntu
21 * 9.10 (Karmic Koala)
22 * 10.04 LTS (Lucid Lynx)
23 * 10.10 (Maverik Meerkat)
24 * 11.04 (Natty Narwhal)
25 * 11.10 (Oneiric Ocelot)
26 * Fedora 13
27 * Mac OS X
28 * OpenSUSE 11.3
29 * Scientific Linux 5.3
30 * Solaris 10, OpenSolaris
bbee9761 »
2010-07-07 The README
31
32 The following systems are planned for support in the near future:
33
34 * MS Windows Vista, Windows 7
35
36 ## Requirements
37
d4f6fe14 »
2010-08-02 Ensure people don't use wrong or invalid packages
38 You need only a few packages provided by the operating system. Copy and paste
39 the commands below.
bbee9761 »
2010-07-07 The README
40
225311f8 »
2010-08-02 Debian 5.0 (Lenny) support
41 On **Fedora**:
0849f75d »
2010-07-30 Fedora 13 support
42
24fda672 »
2012-02-17 Make is necessary on CentOS 6.2; closes #15
43 sudo yum install gcc gcc-c++ make libtool zlib-devel openssl-devel rubygem-rake
0849f75d »
2010-07-30 Fedora 13 support
44
09097223 »
2010-11-01 Document that RHEL is fully-supported
45 On **Red Hat Enterprise Linux**:
46
892c96a7 »
2011-06-01 I believe build-couchdb works out of the box with RHEL/CentOS
47 The procedure is the same as Fedora, but also install the `ruby-rdoc` package.
09097223 »
2010-11-01 Document that RHEL is fully-supported
48
225311f8 »
2010-08-02 Debian 5.0 (Lenny) support
49 On **Debian**, first install `sudo` and add yourself to `/etc/sudoers`.
50
51 su -
52 apt-get install sudo
354b3400 »
2010-09-11 Correct visudo command
53 visudo
225311f8 »
2010-08-02 Debian 5.0 (Lenny) support
54
55 On **Ubuntu and Debian**:
56
bbf245e5 »
2011-11-07 No more libreadline
57 sudo apt-get install make gcc zlib1g-dev libssl-dev rake
225311f8 »
2010-08-02 Debian 5.0 (Lenny) support
58
d9032e22 »
2010-08-08 OpenSUSE 11.3 support
59 On **OpenSUSE**:
60
61 sudo zypper install flex lksctp-tools-devel zip \
62 rubygem-rake gcc-c++ make m4 zlib-devel \
59cb634b »
2011-06-17 Remove libcurl instructions since it is built-in
63 libopenssl-devel libtool automake
d9032e22 »
2010-08-08 OpenSUSE 11.3 support
64
bfe5f7e1 »
2010-08-19 Added pre-usage library requirements and steps to install dependencie…
65 On **Scientific Linux**
66
9ce0a803 »
2010-08-20 Removed js yum dependency because tracemonkey compiles with appropria…
67 sudo yum install --enablerepo=dag gcc gcc-c++ libtool zlib-devel openssl-devel \
b4579656 »
2010-08-20 Added formatting to readme file
68 autoconf213
bfe5f7e1 »
2010-08-19 Added pre-usage library requirements and steps to install dependencie…
69
94e9f7a9 »
2010-08-28 Initial Solaris support
70 On **Solaris**
71
aa65cdec »
2010-11-01 Clearer Solaris documentation
72 This build only supports the OpenCSW toolchain. If you do not use OpenCSW, I
73 wish you the best. If you have success, let me know!
74
75 The SunStudio tools are required:
76
94e9f7a9 »
2010-08-28 Initial Solaris support
77 sudo pkg install ss-dev
78
aa65cdec »
2010-11-01 Clearer Solaris documentation
79 Also, OpenCSW packages are needed.
80
81 pkgadd -d http://mirror.opencsw.org/opencsw/pkg_get.pkg # Answer all questions affirmatively
82
83 Add CSW to your path. **This must always be in the PATH.** Every time you log
84 in, you must set the correct `$PATH` (or make it automatic in `.profile`).
85
86 PATH=/opt/csw/bin:$PATH
87
88 Change the package archive (ibiblio URL is down) by running
89 `vi /opt/csw/etc/pkg-get.conf` and setting
90 `url=ftp://ftp.ibiblio.org/pub/mirrors/opencsw/current`. Save and exit, then
91 run:
92
93 pkg-get updatecatalog
bfe5f7e1 »
2010-08-19 Added pre-usage library requirements and steps to install dependencie…
94
aa65cdec »
2010-11-01 Clearer Solaris documentation
95 Finally, install Rake from OpenCSW:
bfe5f7e1 »
2010-08-19 Added pre-usage library requirements and steps to install dependencie…
96
aa65cdec »
2010-11-01 Clearer Solaris documentation
97 sudo pkg-get install ruby rake # Also perhaps "git"
bfe5f7e1 »
2010-08-19 Added pre-usage library requirements and steps to install dependencie…
98
f2ea8a04 »
2012-04-11 More detailed guide for Mac OS X
99 On **Mac OS X**
490ef9e1 »
2010-08-10 Keep the Linuxes together
100
f2ea8a04 »
2012-04-11 More detailed guide for Mac OS X
101 Install Xcode from Mac App Store. Launch XCode.app, then go to Perferences, select Downloads tab and Install Command Line Tools (You will need Apple Developer ID to download CLT).
d9032e22 »
2010-08-08 OpenSUSE 11.3 support
102
bbee9761 »
2010-07-07 The README
103 ## Getting the Code
104
105 You will need the Git tool. Check out the code and pull in the third-party
106 submodules.
107
47be5f35 »
2011-08-15 Use the correct repository URL
108 git clone git://github.com/iriscouch/build-couchdb
bbee9761 »
2010-07-07 The README
109 cd build-couchdb
af0ac90d »
2010-07-07 Documentation updates
110 git submodule init
bbee9761 »
2010-07-07 The README
111 git submodule update
112
113 ## How to Build CouchDB
114
2e285695 »
2010-07-29 Update documentation
115 Just run Rake.
bbee9761 »
2010-07-07 The README
116
2e285695 »
2010-07-29 Update documentation
117 rake
bbee9761 »
2010-07-07 The README
118
2e285695 »
2010-07-29 Update documentation
119 CouchDB and all its dependencies will install in the `build/`. To uninstall,
35d90418 »
2010-07-11 Documentation clarification
120 simply delete that directory.
bbee9761 »
2010-07-07 The README
121
122 ## Usage
123
2e285695 »
2010-07-29 Update documentation
124 It's CouchDB! Just type `couchdb`. (But remember the path)
bbee9761 »
2010-07-07 The README
125
2e285695 »
2010-07-29 Update documentation
126 $ build/bin/couchdb
bbee9761 »
2010-07-07 The README
127 Apache CouchDB 0.12.0aa63efb6-git (LogLevel=info) is starting.
128 Apache CouchDB has started. Time to relax.
129 [info] [<0.33.0>] Apache CouchDB has started on http://127.0.0.1:5984/
130
2e285695 »
2010-07-29 Update documentation
131 You can of course call it by absolute path. If your username is `amit` and you
132 checked out the code in your home directory, you would run:
133
134 /home/amit/build-couchdb/build/bin/couchdb
135
5523fa3d »
2010-07-30 Clarify the env rake task
136 ## Conveniently Add CouchDB to the PATH
137
94705631 »
2010-12-05 Document the new env.sh
138 The build process creates a small shell script, `build/env.sh`. The script
139 will add the buid to your shell's `$PATH`. This will *only* affect that shell
140 session, other terminals or shell sessions will not change. (This is on
141 purpose, to isolate CouchDB, so that it is easy to remove, or so multiple
142 versions can be installed side-by-side.)
5523fa3d »
2010-07-30 Clarify the env rake task
143
94705631 »
2010-12-05 Document the new env.sh
144 Simply source the script when you want to use CouchDB.
145
146 . build/env.sh
147
148 Your working directory needn't be anywhere special when sourcing the file.
149 It can be processed from anywhere. The idea is, when you are working, you
150 realize you need couchdb, just type
151 `. ~/my/stuff/code/build-couchdb/build/env.sh` or whatever and it will work.
152
153 You can source the file as often as you like. Subsequent exection will not
154 do anything.
155
156 . build/env.sh
157 . build/env.sh # Sourcing with wild abandon!
158
159 If the file is read from a script or in a pipeline, it will execute silently
160 (by detecting whether it is connected to a TTY terminal).
5523fa3d »
2010-07-30 Clarify the env rake task
161
117a8ac2 »
2010-08-10 Document the new flexible building and installing features
162 ## Cheat Codes
163
164 Build CouchDB supports some fancy tricks by entering cheat codes to the Rake
165 command.
166
4516d971 »
2011-01-12 Support building any commit from the OTP repo
167 ### Build any Git branch or tag of Erlang/OTP
168
169 Add a `erl_checkout` parameter with the commit id, branch name, or tag name.
170
171 For example, to build with Erlang R13B04 release:
172
173 rake erl_checkout="OTP_R13B04"
174
175 ### Build any Git branch or tag of CouchDB
117a8ac2 »
2010-08-10 Document the new flexible building and installing features
176
177 Add a `git` parameter with the repository URL, then a space, then the branch,
06d28ae6 »
2010-11-21 typo & clarification
178 tag, or commit hash. (Remember to quote all of those so Rake sees the space.)
117a8ac2 »
2010-08-10 Document the new flexible building and installing features
179
91ade96d »
2010-11-03 Initial stab at build a plugin, with stub functionality
180 ### CouchDB Plugins
181
182 Any CouchDB plugin can be loaded remotely from Git, built, and installed
183 into the final CouchDB system.
184
81742377 »
2012-03-22 Correct the branch with GeoCouch
185 rake plugin="git://github.com/couchbase/geocouch origin/couchdb1.2.x"
14a38e8a »
2012-02-10 Update instructions for the new way to build GeoCouch as a plugin; cl…
186 # (Or perhaps origin/couchdb_1.1.x)
91ade96d »
2010-11-03 Initial stab at build a plugin, with stub functionality
187
188 Multiple plugins can be processed together:
189
190 rake plugins="git://github.com/vmx/couchdb origin/gc-separate,git://github.com/somebody/whatever some_tag"
191
192 (Both `plugin` and `plugins` supports comma-separated lists; use whichever
193 you remember better.)
194
117a8ac2 »
2010-08-10 Document the new flexible building and installing features
195 ### Install CouchDB somewhere besides `build/`.
196
8ba6b768 »
2010-12-05 Simplify users's lives by using an "install" variable which puts the …
197 Add an `install` parameter to place the final couchdb binaries anywhere.
117a8ac2 »
2010-08-10 Document the new flexible building and installing features
198
8ba6b768 »
2010-12-05 Simplify users's lives by using an "install" variable which puts the …
199 Build CouchDB makes it simple to install several couchdb versions side-by-side.
117a8ac2 »
2010-08-10 Document the new flexible building and installing features
200
14a38e8a »
2012-02-10 Update instructions for the new way to build GeoCouch as a plugin; cl…
201 rake install=stable
8ba6b768 »
2010-12-05 Simplify users's lives by using an "install" variable which puts the …
202 rake git="git://git.apache.org/couchdb.git trunk" install=trunk
117a8ac2 »
2010-08-10 Document the new flexible building and installing features
203 for tag in 1.0.1 11.0 11.1; do
8ba6b768 »
2010-12-05 Simplify users's lives by using an "install" variable which puts the …
204 rake git="git://git.apache.org/couchdb.git tags/$tag" install=$tag
117a8ac2 »
2010-08-10 Document the new flexible building and installing features
205 done
206
14a38e8a »
2012-02-10 Update instructions for the new way to build GeoCouch as a plugin; cl…
207 Note that `install` needs to be an absolute path.
06d28ae6 »
2010-11-21 typo & clarification
208
932432aa »
2010-12-05 Document how to split a couch install from its dependencies
209 For **side-by-side installs** there is a small shortcut to avoid rebuilding Erlang:
210 use the `couchdb_build` variable instead, which will install CouchDB separately
211 from its dependencies. Just remember never to move or delete the dependencies!
212
213 rake install=/dependencies/go/here couchdb_build=/but/couch/goes/here
214
9486e2c6 »
2011-11-19 Explain the "unclean" check and how to disable it
215 ### Support "unclean" builds.
216
217 Build CouchDB confirms that the Git checkout looks good before attempting a
218 build. If you see this error message, then Build CouchDB is suspicious of your
219 checkout:
220
221 This checkout is not clean:
222 <list of changed files>
223
224 Heed this warning. Why is your checkout unclean? Shouldn't you build from a
225 nice, clean checkout, with no funny business?
226
227 Nevertheless, if you wish to proceed, add an `unclean` parameter to Rake:
228
229 rake unclean=1
230
7a7671f4 »
2010-08-10 Explain the manifest option
231 ### Get a manifest of all the components
232
233 To get a better idea of exactly what is going on, add a `manifest` parameter.
234
235 rake manifest=1
236
237 That will produce additional files in `build/manifest` which indicate which
238 package (icu, erlang, spidermonkey, etc) owns which files within `build`. A
239 trick I do a lot is `cat build/manifest/couchdb | xargs rm` to "uninstall" only
240 couchdb so I can try a rebuild.
241
8ba6b768 »
2010-12-05 Simplify users's lives by using an "install" variable which puts the …
242 I have no idea how `manifest` interacts with `install` as I have never
4b34aee2 »
2010-08-22 Brevity
243 used them together.
7a7671f4 »
2010-08-10 Explain the manifest option
244
117a8ac2 »
2010-08-10 Document the new flexible building and installing features
245 [geocouch]: http://vmx.cx/cgi-bin/blog/index.cgi/geocouch-the-future-is-now:2010-05-03:en,CouchDB,Python,Erlang,geo
246
dc2ce232 »
2010-08-14 A way to keep some Erlang libraries
247 ### Do not strip down Erlang/OTP
248
249 Build CouchDB strips many modules out of the Erlang platform to reduce disk
250 usage. (You can see which ones at the top of `tasks/erlang.rake`.) To indicate
251 that a package should be kept, set the `otp_keep` variable to space-separated
252 library names.
253
254 rake otp_keep="compiler eunit"
255
256 Or, you can keep them all this way:
257
258 rake otp_keep="*"
259
e9f063a7 »
2010-09-06 Document how to build CouchDB-deps
260 ### How to build only Erlang, couchjs, and OTP so you can build your own CouchDB elsewhere
261
262 There is a special shortcut task to build everything CouchDB needs (i.e. its dependencies).
263
264 rake couchdb:deps otp_keep="*"
265
266 Be careful not to build the `couchdb` target because after it completes, it will delete Erlang components needed for building (but not running).
267 Next, there is a simple task which outputs a `sh` script used to configure any CouchDB checkout.
268
269 rake --silent environment:configure
270
271 The output will look similar to this:
272
273 export PATH="/Users/jhs/src/build-couchdb/build/bin:$PATH"
274 LDFLAGS='-R/Users/jhs/src/build-couchdb/build/lib -L/Users/jhs/src/build-couchdb/build/lib' CFLAGS='-I/Users/jhs/src/build-couchdb/build/include/js -I/Users/jhs/src/build-couchdb/build/lib/erlang/usr/include' ./configure
275
276 In the CouchDB source, paste the above code after running `./bootstrap`. Next, you can run `make` or `make dev`, or anything.
277
bbee9761 »
2010-07-07 The README
278 vim: tw=80
Something went wrong with that request. Please try again.