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