blob: 123568913e2b50268863ff6bffbbdda3c193d86a [file] [log] [blame]
Before you start here, read `INSTALL.Unix` (or `INSTALL.Windows`) 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.
You may need:
* `Sphinx <>`_
* `LaTex <>`_
* `GNU Texinfo <>`_
* `GNU help2man <>`_
* `GnuPG <>`_
* `md5sum <>`_
* `sha1sum <>`_
The first of these optional dependencies are required for building the
documentation. The last three are needed to build releases.
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
`src/fauxton/`. 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.
Debian-based (inc. Ubuntu) Systems
sudo apt-get install help2man python-sphinx \
texlive-latex-base texlive-latex-recommended \
texlive-latex-extra texlive-fonts-recommended texinfo gnupg
Gentoo-based Systems
sudo emerge texinfo gnupg coreutils pkgconfig help2man
sudo USE=latex emerge sphinx
RedHat-based (Fedora, Centos, RHEL) Systems
sudo yum install help2man python-sphinx python-docutils \
python-pygments texlive-latex texlive-latex-fonts texinfo gnupg
Mac OS X
Install `Homebrew <>`_, 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
If you don't already have pip installed, install it::
sudo easy_install pip
Now, install the required Python packages::
sudo pip install sphinx
sudo pip install docutils
sudo pip install pygments
Download `MacTeX <>`_ and follow the instructions
to get a working LaTeX install on your system.
pkg install help2man texinfo gnupg py27-sphinx texlive-full tex-formats
Follow the instructions in `INSTALL.Windows` and build all components from
source, using the same Visual C++ compiler and runtime.
Configure the source by running::
If you intend to run the test suites::
./configure -c
If you want to build it into different destination than `/usr/local`.:
./configure --prefix=/<your directory path>
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.
To run all the tests use run::
make check
You can also run each test suite individually via ``eunit`` and ``javascript``
make eunit
make javascript
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 suites=couch_btree_tests
# 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 EUNIT_OPT environment variable to specify exact `rebar eunit`
make eunit EUNIT_OPTS="apps=couch,chttpd"
JavaScript tests accepts only `suites` option, but in the same way::
# Run all JavaScript tests
make javascript
# Run only basic and design_options tests
make javascript suites="basic design_options"
Note that tests are delimited here by whitespace, not by comma. You can get list
of all possible test targets with the following command::
make list-js-suites
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.
Testing a cluster
We use `Docker <>`_ to safely run a local three node
cluster all inside a single docker container.
Assuming you have Docker installed and running::
make docker-image
This will create a docker image (tagged 'couchdb/dev-cluster') capable
of running a joined three node cluster.
To start it up::
make docker-start
A three node cluster should now be running (you can now use ``docker ps``
to find the exposed ports of the nodes).
To stop it::
make docker-stop
The release procedure is documented here::
Unix-like Systems
Prepare the release artifacts by running::
make distcheck
You can prepare signed release artifacts by running::
make distsign
The release artifacts can be found in the root source directory.
Microsoft Windows
Prepare the release artifacts by running::
make dist
The release artifacts can be found in the `etc/windows` directory.
Until the build system has been improved, you must make sure that you run this
command from a clean source checkout. If you do not, your test database and log
files will be bundled up in the release artifacts.