Skip to content

Latest commit

 

History

History
247 lines (154 loc) · 6.4 KB

README-DEV.rst

File metadata and controls

247 lines (154 loc) · 6.4 KB
Raw

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 may need:

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/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.

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.

FreeBSD

pkg install help2man texinfo gnupg py27-sphinx texlive-full tex-formats

Windows

Follow the instructions in INSTALL.Windows 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 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.

Testing

To run all the tests use run:

make check

You can also run each test suite individually via eunit and javascript targets:

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 options:

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

Releasing

The release procedure is documented here:

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

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.