DEVELOPERS

Apache CouchDB DEVELOPERS
=========================

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.

Dependencies
------------

You will need the following installed:

 * GNU Libtool            (http://www.gnu.org/software/libtool/)
 * GNU Automake (>=1.6.3) (http://www.gnu.org/software/automake/)
 * GNU Autoconf (>=2.63)  (http://www.gnu.org/software/autoconf/)
 * GNU Autoconf Archive   (http://www.gnu.org/software/autoconf-archive/)
 * pkg-config             (http://www.freedesktop.org/wiki/Software/pkg-config)

You may also need:

 * Sphinx                 (http://sphinx.pocoo.org/)
 * LaTex                  (http://www.latex-project.org/)
 * GNU Texinfo            (http://www.gnu.org/software/texinfo/)
 * GNU help2man           (http://www.gnu.org/software/help2man/)
 * GnuPG                  (http://www.gnupg.org/)
 * md5sum                 (http://www.microbrew.org/tools/md5sha1sum/)
 * sha1sum                (http://www.microbrew.org/tools/md5sha1sum/)

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


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
    sudo apt-get install python-sphinx
    sudo apt-get install texlive-latex-base
    sudo apt-get install texlive-latex-recommended
    sudo apt-get install texlive-latex-extra
    sudo apt-get install texlive-fonts-recommended
    sudo apt-get install texinfo
    sudo apt-get install gnupg

Gentoo-based Systems
~~~~~~~~~~~~~~~~~~~~

    sudo emerge texinfo
    sudo emerge gnupg
    sudo emerge coreutils
    sudo emerge pkgconfig
    sudo emerge help2man
    sudo USE=latex emerge sphinx

RedHat-based (Fedora, Centos, RHEL) Systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    sudo yum install help2man
    sudo yum install python-sphinx
    sudo yum install python-docutils
    sudo yum install python-pygments
    sudo yum install texlive-latex
    sudo yum install texlive-latex-fonts
    sudo yum install texinfo
    sudo yum install gnupg

Mac OS X
~~~~~~~~

Install Homebrew, if you do not have it already:

    https://github.com/mxcl/homebrew

Unless you want to install the optional dependencies, skip to the next section.

Install what else we can with Homebrew:

    brew install help2man
    brew install gnupg
    brew install 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 MaxTeX from here:

    http://www.tug.org/mactex/

Follow the instructions to get a working LaTeX install on your system.

Windows
~~~~~~~

Follow the instructions in INSTALL.Windows and build all components from
source, using the same Visual C++ compiler and runtime.

Bootstrapping
-------------

Bootstrap the pristine source by running:

    ./bootstrap

You must repeat this step every time you update your source checkout.

Configuring
-----------

Configure the source by running:

    ./configure

Note that this will not fail when the optional dependencies are missing.

To ensure the optional dependencies are installed, run:

    ./configure --enable-strictness

If you don't care about docs and want to skip the whole thing, run:

    ./configure --disable-docs

If you're working on the build system itself, you can run:

    ./configure --disable-tests

This skips the tests allowing quicker `make' cycles.

If you want to build it into different destination than `/usr/local`.

    ./configure --prefix=/<your directory path>

Testing
-------

Check the test suite by running:

    make check

Generate a coverage report by running:

    make cover

Please report any problems to the developer's mailing list.

Releasing
---------

The release procedure is documented here:

    https://wiki.apache.org/couchdb/Release_Procedure

Unix-like Systems
~~~~~~~~~~~~~~~~~

Prepare the release artefacts by running:

    make distcheck

You can prepare signed release artefacts by running:

    make distsign

The release artefacts can be found in the root source directory.

Microsoft Windows
~~~~~~~~~~~~~~~~~

Prepare the release artefacts by running:

    make dist

The release artefacts 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 artefact.