1Apache CouchDB DEVELOPERS
2=========================
3
4Before you start here, read `INSTALL.Unix` (or `INSTALL.Windows`) and
5follow the setup instructions including the installation of all the
6listed dependencies for your system.
7
8Only follow these instructions if you are building from a source checkout.
9
10If you're unsure what this means, ignore this document.
11
12Dependencies
13------------
14
15You need the following to run tests:
16
17* `Python 3               <https://www.python.org/>`_
18* `Elixir                 <https://elixir-lang.org/>`_
19
20You need the following optionally to build documentation:
21
22* `Sphinx                 <http://sphinx.pocoo.org/>`_
23* `GNU help2man           <http://www.gnu.org/software/help2man/>`_
24* `GnuPG                  <http://www.gnupg.org/>`_
25
26You need the following optionally to build releases:
27
28* `md5sum                 <http://www.microbrew.org/tools/md5sha1sum/>`_
29* `sha1sum                <http://www.microbrew.org/tools/md5sha1sum/>`_
30
31You need the following optionally to build Fauxton:
32
33* `nodejs                 <http://nodejs.org/>`_
34* `npm                    <https://www.npmjs.com/>`_
35
36You will need these optional dependencies installed if:
37
38* You are working on the documentation, or
39* You are preparing a distribution archive
40
41However, you do not need them if:
42
43* You are building from a distribution archive, or
44* You don't care about building the documentation
45
46If you intend to build Fauxton, you will also need to install its
47dependencies. After running ``./configure`` to download all of the
48dependent repositories, you can read about required dependencies in
49`src/fauxton/readme.md`. Typically, installing npm and node.js are
50sufficient to enable a Fauxton build.
51
52Here is a list of *optional* dependencies for various operating systems.
53Installation will be easiest, when you install them all.
54
55Docker
56~~~~~~
57
58CouchDB maintains a ``Dockerfile`` based on Debian that includes all
59the dependencies noted above in the `.devcontainer <https://github.com/apache/couchdb/tree/main/.devcontainer>`_
60folder.
61
62The ``Dockerfile`` can be used on its own, or together with the
63associated ``devcontainer.json`` file to quickly provision a
64development environment using `GitHub Codespaces <https://github.com/features/codespaces>`_
65or `Visual Studio Code <https://code.visualstudio.com/docs/remote/containers>`_.
66
67Debian-based (inc. Ubuntu) Systems
68~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
69
70::
71
72    sudo apt-get install help2man python-sphinx gnupg nodejs npm \
73         python3 python3-venv
74
75Gentoo-based Systems
76~~~~~~~~~~~~~~~~~~~~
77
78::
79
80    sudo emerge gnupg coreutils pkgconfig help2man sphinx python
81    sudo pip install hypothesis requests nose
82
83Centos 7 and RHEL 7
84~~~~~~~~~~~~~~~~~~~
85
86::
87
88    sudo yum install help2man python-sphinx python-docutils \
89        python-pygments gnupg nodejs npm
90
91
92Mac OS X
93~~~~~~~~
94
95Install `Homebrew <https://github.com/mxcl/homebrew>`_, if you do not have
96it already.
97
98Unless you want to install the optional dependencies, skip to the next section.
99
100Install what else we can with Homebrew::
101
102    brew install help2man gnupg md5sha1sum node python
103
104If you don't already have pip installed, install it::
105
106    sudo easy_install pip
107
108Now, install the required Python packages::
109
110    sudo pip install sphinx docutils pygments sphinx_rtd_theme
111
112FreeBSD
113~~~~~~~
114
115::
116
117    pkg install help2man gnupg py27-sphinx node
118    pip install nose requests hypothesis
119
120Windows
121~~~~~~~
122
123Follow the instructions in `INSTALL.Windows` and build all components from
124source, using the same Visual C++ compiler and runtime.
125
126Configuring
127-----------
128
129Configure the source by running::
130
131    ./configure
132
133If you intend to run the test suites::
134
135    ./configure -c
136
137If you don't want to build Fauxton or documentation specify
138``--disable-fauxton`` and/or ``--disable-docs`` arguments for ``configure`` to
139ignore their build and avoid any issues with their dependencies.
140
141See ``./configure --help`` for more information.
142
143Testing
144-------
145
146To run all the tests use run::
147
148    make check
149
150You can also run each test suite individually via ``eunit`` and ``javascript``
151targets::
152
153    make eunit
154    make javascript
155
156If you need to run specific Erlang tests, you can pass special "options"
157to make targets::
158
159    # Run tests only for couch and chttpd apps
160    make eunit apps=couch,chttpd
161
162    # Run only tests from couch_btree_tests suite
163    make eunit apps=couch suites=couch_btree
164
165    # Run only only specific tests
166    make eunit tests=btree_open_test,reductions_test
167
168    # Ignore tests for specified apps
169    make eunit skip_deps=couch_log,couch_epi
170
171The ``apps``, ``suites``, ``tests`` and ``skip_deps`` could be combined in any
172way. These are mimics to ``rebar eunit`` arguments. If you're not satisfied by
173these, you can use EUNIT_OPT environment variable to specify exact `rebar eunit`
174options::
175
176    make eunit EUNIT_OPTS="apps=couch,chttpd"
177
178JavaScript tests accepts only `suites` option, but in the same way::
179
180    # Run all JavaScript tests
181    make javascript
182
183    # Run only basic and design_options tests
184    make javascript suites="basic design_options"
185
186    # Ignore specific test suites via command line
187    make javascript ignore_js_suites="all_docs bulk_docs"
188
189    # Ignore specific test suites in makefile
190    ignore_js_suites=all_docs,bulk_docs
191
192Note that tests on the command line are delimited here by whitespace,
193not by comma.You can get list of all possible test targets with the
194following command::
195
196    make list-js-suites
197
198Code analyzer could be run by::
199
200    make dialyze
201
202If you need to analyze only specific apps, you can specify them in familiar way
203::
204
205    make dialyze apps=couch,couch_epi
206
207See ``make help`` for more info and useful commands.
208
209Please report any problems to the developer's mailing list.
210
211Releasing
212---------
213
214The release procedure is documented here::
215
216    https://cwiki.apache.org/confluence/display/COUCHDB/Release+Procedure
217
218Unix-like Systems
219~~~~~~~~~~~~~~~~~
220
221A release tarball can be built by running::
222
223    make dist
224
225An Erlang CouchDB release includes the full Erlang Run Time System and
226all dependent applications necessary to run CouchDB, standalone. The
227release created is completely relocatable on the file system, and is
228the recommended way to distribute binaries of CouchDB. A release can be
229built by running::
230
231    make release
232
233The release can then be found in the rel/couchdb directory.
234
235Microsoft Windows
236~~~~~~~~~~~~~~~~~
237
238The release tarball and Erlang CouchDB release commands work on
239Microsoft Windows the same as they do on Unix-like systems. To create
240a full installer, the separate couchdb-glazier repository is required.
241Full instructions are available in that repository's README file.
242
243