1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
|
Apache CouchDB DEVELOPERS
=========================
Before you start here, read `<INSTALL.Unix.md>`_ (or
`<INSTALL.Windows.md>`_) and follow the setup instructions including
the installation of all the listed dependencies for your system.
Only follow these instructions if you are building from a source checkout.
If you're unsure what this means, ignore this document.
Dependencies
------------
You need the following to run tests:
* `Python 3 <https://www.python.org/>`_
* `Elixir <https://elixir-lang.org/>`_
You need the following optionally to build documentation:
* `Sphinx <http://sphinx.pocoo.org/>`_
* `GNU help2man <http://www.gnu.org/software/help2man/>`_
* `GnuPG <http://www.gnupg.org/>`_
You need the following optionally to build releases:
* `md5sum <http://www.microbrew.org/tools/md5sha1sum/>`_
* `sha1sum <http://www.microbrew.org/tools/md5sha1sum/>`_
You need the following optionally to build Fauxton:
* `nodejs <http://nodejs.org/>`_
* `npm <https://www.npmjs.com/>`_
You will need these optional dependencies installed if:
* You are working on the documentation, or
* You are preparing a distribution archive
However, you do not need them if:
* You are building from a distribution archive, or
* You don't care about building the documentation
If you intend to build Fauxton, you will also need to install its
dependencies. After running ``./configure`` to download all of the
dependent repositories, you can read about required dependencies in
`its readme
<https://github.com/apache/couchdb-fauxton/blob/main/readme.md>`_. Typically,
installing ``npm`` and node.js are sufficient to enable a Fauxton
build.
Here is a list of *optional* dependencies for various operating systems.
Installation will be easiest, when you install them all.
Docker
~~~~~~
CouchDB maintains a ``Dockerfile`` based on Debian that includes all
the dependencies noted above in the `.devcontainer <https://github.com/apache/couchdb/tree/main/.devcontainer>`_
folder.
The ``Dockerfile`` can be used on its own, or together with the
associated ``devcontainer.json`` file to quickly provision a
development environment using `GitHub Codespaces <https://github.com/features/codespaces>`_
or `Visual Studio Code <https://code.visualstudio.com/docs/remote/containers>`_.
.. image:: https://img.shields.io/static/v1?label=Remote%20-%20Containers&message=Open&color=blue&logo=visualstudiocode
:target: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/apache/couchdb
If you already have VS Code and Docker installed, you can click the
badge above or `here
<https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/apache/couchdb>`_
to get started. Clicking these links will cause VS Code to
automatically install the Remote - Containers extension if needed,
clone the source code into a container volume, and spin up a dev
container for use.
This ``devcontainer`` will automatically run ``./configure && make``
the first time it is created. While this may take some extra time to
spin up, this tradeoff means you will be able to run things like
``./dev/run``, ``./dev/run --admin=admin:admin``, ``./dev/run
--with-admin-party-please``, and ``make check`` straight away.
Subsequent startups should be quick.
Debian-based (inc. Ubuntu) Systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
sudo apt-get install help2man python-sphinx gnupg nodejs npm \
python3 python3-venv
Gentoo-based Systems
~~~~~~~~~~~~~~~~~~~~
::
sudo emerge gnupg coreutils pkgconfig help2man sphinx python
sudo pip install hypothesis requests nose
Centos 7 and RHEL 7
~~~~~~~~~~~~~~~~~~~
::
sudo yum install help2man python-sphinx python-docutils \
python-pygments gnupg nodejs npm
Mac OS X
~~~~~~~~
Install `Homebrew <https://brew.sh/>`_, if you do not have it already.
Unless you want to install the optional dependencies, skip to the next section.
Install what else we can with Homebrew::
brew install help2man gnupg md5sha1sum node python
If you don't already have pip installed, install it::
sudo easy_install pip
Now, install the required Python packages::
sudo pip install sphinx docutils pygments sphinx_rtd_theme
FreeBSD
~~~~~~~
::
pkg install help2man gnupg py27-sphinx node
pip install nose requests hypothesis
Windows
~~~~~~~
Follow the instructions in `<INSTALL.Windows.md>`_ and build all
components from source, using the same Visual C++ compiler and
runtime.
Configuring
-----------
Configure the source by running::
./configure
If you intend to run the test suites::
./configure -c
If you don't want to build Fauxton or documentation specify
``--disable-fauxton`` and/or ``--disable-docs`` arguments for ``configure`` to
ignore their build and avoid any issues with their dependencies.
See ``./configure --help`` for more information.
Developing
----------
Formatting
~~~~~~~~~~
The ``erl`` files in ``src`` are formatted using erlfmt_. The checks are run
for every PR in the CI. To run the checks locally, run ``make erlfmt-check``.
To format the ``erl`` files in ``src``, run ``make erlfmt-format``.
To use ``erlfmt`` for specific files only, use the executable ``bin/erlfmt``
that is installed by ``configure``.
Python files throughout the repository should conform to (PEP
8-compliant) formatting rules as specified by black_. Similarly to
``erlfmt``, the related checks are run for every PR in the CI. The
same checks could also be run locally via ``make python-black``.
Files can be automatically formatted by ``make python-black-update``.
.. _erlfmt: https://github.com/WhatsApp/erlfmt
.. _black: https://github.com/psf/black
Testing
-------
To run all the tests use run::
make check
You can also run each test suite individually via the ``eunit``, ``mango-test``,
``elixir-suite``, and ``weatherreport-test`` targets::
make eunit
make mango-test
make elixir-suite
make weatherreport-test
Erlang Unit Tests
~~~~~~~~~~~~~~~~~
If you need to run specific Erlang tests, you can pass special "options"
to make targets::
# Run tests only for couch and chttpd apps
make eunit apps=couch,chttpd
# Run only tests from couch_btree_tests suite
make eunit apps=couch suites=couch_btree
# Run only only specific tests
make eunit tests=btree_open_test,reductions_test
# Ignore tests for specified apps
make eunit skip_deps=couch_log,couch_epi
The ``apps``, ``suites``, ``tests`` and ``skip_deps`` could be
combined in any way. These are mimics to ``rebar eunit`` arguments. If
you're not satisfied by these, you can use the ``EUNIT_OPTS`` variable
to specify exact ``rebar eunit`` options::
make eunit EUNIT_OPTS="apps=couch,chttpd"
Elixir Integration Tests
~~~~~~~~~~~~~~~~~~~~~~~~
All the Elixir-based integration tests could be by the `elixir-suite`
target::
make elixir-suite
There is an additional suite for Dreyfus, which is not run
automatically by either the ``elixir-suite`` or the ``check`` target
but it could be done manually via the corresponding target::
make elixir-search
Note that this requires a running Clouseau instance with the name
``clouseau@127.0.0.1``. The easiest way to get it is to clone the
`cloudant-labs/clouseau <https://github.com/cloudant-labs/clouseau>`_
repository and launch it run there once all the prerequisites (JDK,
Scala, and Maven) have been installed successfully, e.g.::
git clone https://github.com/cloudant-labs/clouseau
mvn -f clouseau/pom.xml scala:run
Mango Integration Tests
~~~~~~~~~~~~~~~~~~~~~~~
Tests for the Mango interface can be run individually with the help of
the ``mango-test`` target and they can be narrowed down to specific
test suites via the ``MANGO_TEST_OPTS`` variable::
make mango-test \
MANGO_TEST_OPTS="--pretty-assert --verbose 03-operator-test"
The value of the ``MANGO_TEST_OPTS`` variable will be passed down to
the `Nose 2 <https://nose2.io/>`_ testing framework which is used for
the implementation. Consult its documentation for more information.
Tests that rely on text indexes are run only if the ``search`` feature
is reported to be available (i.e. a working Clouseau instance is
connected), otherwise they will be skipped.
Note that the databases that are created during the tests will be all
removed after each of the suites completed. However, with the help of
the ``MANGO_TESTS_KEEP_DBS`` environment variable, it can be requested
to keep those databases around for further investigation::
MANGO_TESTS_KEEP_DBS=please \
make mango-test MANGO_TEST_OPTS='03-operator-test'
Static Code Analysis
~~~~~~~~~~~~~~~~~~~~
Code analyzer could be run by::
make dialyze
If you need to analyze only specific apps, you can specify them in familiar way
::
make dialyze apps=couch,couch_epi
See ``make help`` for more info and useful commands.
Please report any problems to the `developer's mailing list
<https://lists.apache.org/list.html?dev@couchdb.apache.org>`_.
Releasing
---------
The release procedure is documented here::
https://cwiki.apache.org/confluence/display/COUCHDB/Release+Procedure
Unix-like Systems
~~~~~~~~~~~~~~~~~
A release tarball can be built by running::
make dist
An Erlang CouchDB release includes the full Erlang Run Time System and
all dependent applications necessary to run CouchDB, standalone. The
release created is completely relocatable on the file system, and is
the recommended way to distribute binaries of CouchDB. A release can be
built by running::
make release
The release can then be found in the ``rel/couchdb`` directory.
Microsoft Windows
~~~~~~~~~~~~~~~~~
The release tarball and Erlang CouchDB release commands work on
Microsoft Windows the same as they do on Unix-like systems. To create
a full installer, the separate `couchdb-glazier repository
<https://github.com/apache/couchdb-glazier>`_ is required. Full
instructions are available in that repository's ``README`` file.
|