Fauxton: better styling for the logs
[couchdb.git] / INSTALL.Windows
1 Apache CouchDB INSTALL.Windows
2 ==============================
3
4 For a high-level guide to Microsoft Windows.
5
6 Troubleshooting
7 ---------------
8
9 There is a troubleshooting guide:
10
11     http://wiki.apache.org/couchdb/Troubleshooting
12
13 There is a wiki for general documentation:
14
15     http://wiki.apache.org/couchdb/
16
17 And some Windows-specific tips:
18
19     http://wiki.apache.org/couchdb/Quirks_on_Windows
20
21 There are collection of friendly mailing lists:
22
23     http://couchdb.apache.org/community/lists.html
24
25 Please work through these in order if you experience any problems.
26
27 Dependencies
28 ------------
29
30 You will need the following installed:
31
32  * Erlang OTP (>=14B01, <R17)    (http://erlang.org/)
33  * ICU        (>=4.*)            (http://icu-project.org/)
34  * OpenSSL    (>=0.9.8r)         (http://www.openssl.org/)
35  * Mozilla SpiderMonkey (=1.8.5) (http://www.mozilla.org/js/spidermonkey/)
36  * libcurl    (>=7.20)           (http://curl.haxx.se/libcurl/)
37  * Cygwin                        (http://www.cygwin.com/)
38  * Microsoft SDK 7.0 or 7.1      (http://www.microsoft.com/en-us/download/details.aspx?id=8279)
39  * Python (>= 2.68) for docs     (http://python.org/)
40  * Python Sphinx (>=1.1.3)       (http://pypi.python.org/pypi/Sphinx)
41
42 General Notes
43 -------------
44
45  * When installing Cygwin, be sure to select all the `development` tools.
46
47  * When installing Erlang, you must build it from source.
48
49  * The CouchDB build requires a number of the Erlang build scripts.
50
51  * All dependent libraries should be built with the same version of
52    microsoft SDK.
53
54  * Do not try to link against libraries built with, or included in,
55    Cygwin or MingW. They are not compatible with the Erlang/OTP or CouchDB
56    build scripts.
57
58  * ICU version 4.6 and later will build cleanly using MSBuild.
59
60  * Python and Sphinx are optional for building the online documentation.
61    Use cygwin-provided Python and install Sphinx via easy_install or pip.
62    Further information is here http://pypi.python.org/pypi/setuptools#id4
63
64 Setting Up Cygwin
65 -----------------
66
67 Before starting any Cygwin terminals, run:
68
69     set CYGWIN=nontsec
70
71 To set up your environment, run:
72
73     [VS_BIN]/vcvars32.bat
74
75 Replace [VS_BIN] with the path to your Visual Studio `bin` directory.
76
77 You must check that:
78
79     * The `which link` command points to the Microsoft linker.
80
81     * The `which cl` command points to the Microsoft compiler.
82
83     * The `which mc` command points to the Microsoft message compiler.
84
85     * The `which mt` command points to the Microsoft manifest tool.
86
87     * The `which nmake` command points to the Microsoft make tool.
88
89 If you do not do this, the build may fail due to Cygwin ones found in `/usr/bin`
90 being used instead.
91
92 Building Erlang
93 ---------------
94
95 You must include Win32 OpenSSL, built statically from source. Use
96 exactly the same version as required by the Erlang/OTP build process.
97
98 However, you can skip the GUI tools by running:
99
100    echo "skipping gs" > lib/gs/SKIP
101
102    echo "skipping ic" > lib/ic/SKIP
103
104    echo "skipping jinterface" > lib/jinterface/SKIP
105
106 Follow the rest of the Erlang instructions as described.
107
108 After running:
109
110    ./otp_build release -a
111
112 You should run:
113
114    ./release/win32/Install.exe -s
115
116 This will set up the release/win32/bin directory correctly. The CouchDB
117 installation scripts currently write their data directly into this
118 location.
119
120 To set up your environment for building CouchDB, run:
121
122     eval `./otp_build env_win32`
123
124 To set up the `ERL_TOP` environment variable, run:
125
126     export ERL_TOP=[ERL_TOP]
127
128 Replace `[ERL_TOP]` with the Erlang source directory name.
129
130 Remember to use `/cygdrive/c/` instead of `c:/` as the directory prefix.
131
132 To set up your path, run:
133
134     export PATH=$ERL_TOP/release/win32/erts-5.8.5/bin:$PATH
135
136 If everything was successful, you should be ready to build CouchDB.
137
138 Relax.
139
140 Building CouchDB
141 ----------------
142
143 Note that `win32-curl` is only required if you wish to run the developer
144 tests.
145
146 The documentation step may be skipped using `--disable-docs` if you wish.
147
148 Once you have satisfied the dependencies you should run:
149
150     ./configure \
151         --with-js-include=/cygdrive/c/path_to_spidermonkey_include \
152         --with-js-lib=/cygdrive/c/path_to_spidermonkey_lib \
153         --with-win32-icu-binaries=/cygdrive/c/path_to_icu_binaries_root \
154         --with-erlang=$ERL_TOP/release/win32/usr/include \
155         --with-win32-curl=/cygdrive/c/path/to/curl/root/directory \
156         --with-openssl-bin-dir=/cygdrive/c/openssl/bin \
157         --with-msvc-redist-dir=/cygdrive/c/dir/with/vcredist_platform_executable \
158         --disable-init \
159         --disable-launchd \
160         --prefix=$ERL_TOP/release/win32
161
162 This command could take a while to complete.
163
164 If everything was successful you should see the following message:
165
166     You have configured Apache CouchDB, time to relax.
167
168 Relax.
169
170 To install CouchDB you should run:
171
172     make install
173
174 If everything was successful you should see the following message:
175
176     You have installed Apache CouchDB, time to relax.
177
178 Relax.
179
180 To build the .exe installer package, you should run:
181
182     make dist
183
184 Alternatively, you may run CouchDB directly from the build tree, but
185 to avoid any contamination do not run `make dist` after this.
186
187 First Run
188 ---------
189
190 You can start the CouchDB server by running:
191
192     $ERL_TOP/release/win32/bin/couchdb.bat
193
194 When CouchDB starts it should eventually display the following message:
195
196     Apache CouchDB has started, time to relax.
197
198 Relax.
199
200 To check that everything has worked, point your web browser to:
201
202     http://127.0.0.1:5984/_utils/index.html
203
204 From here you should run the verification tests in Firefox.