You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by va...@apache.org on 2023/02/21 18:55:14 UTC
[couchdb] 01/04: Fix and extend developer instructions
This is an automated email from the ASF dual-hosted git repository.
vatamane pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit b3890b5d3ce1d7715f18d4db6f74de087cb7b5e7
Author: Gabor Pali <ga...@ibm.com>
AuthorDate: Mon Feb 20 15:46:41 2023 +0100
Fix and extend developer instructions
- Various whitespace and formatting fixes.
- Fix the reference to `EUNIT_OPTS`. The variable name has a
typo (it is missing the 'S' from the end) and it is not an
environment variable but a make(1) variable.
- Create subsections of the different kind of tests.
- Update Homebrew home page link.
- Fix Fauxton readme link. The source code for Fauxton now lives
in a separate repository, make the corresponding link reflect
this.
---
README-DEV.rst | 87 ++++++++++++++++++++++++++++++++++++----------------------
1 file changed, 54 insertions(+), 33 deletions(-)
diff --git a/README-DEV.rst b/README-DEV.rst
index 7ef844096..d8fd299d8 100644
--- a/README-DEV.rst
+++ b/README-DEV.rst
@@ -1,9 +1,9 @@
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.
+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.
@@ -31,7 +31,7 @@ You need the following optionally to build releases:
You need the following optionally to build Fauxton:
* `nodejs <http://nodejs.org/>`_
-* `npm <https://www.npmjs.com/>`_
+* `npm <https://www.npmjs.com/>`_
You will need these optional dependencies installed if:
@@ -46,8 +46,10 @@ However, you do not need them if:
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.
+`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.
@@ -68,16 +70,20 @@ 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.
+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.
+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
@@ -108,8 +114,7 @@ Centos 7 and RHEL 7
Mac OS X
~~~~~~~~
-Install `Homebrew <https://github.com/mxcl/homebrew>`_, if you do not have
-it already.
+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.
@@ -136,8 +141,9 @@ FreeBSD
Windows
~~~~~~~
-Follow the instructions in `INSTALL.Windows` and build all components from
-source, using the same Visual C++ compiler and runtime.
+Follow the instructions in `<INSTALL.Windows.md>`_ and build all
+components from source, using the same Visual C++ compiler and
+runtime.
Configuring
-----------
@@ -185,6 +191,9 @@ You can also run each test suite individually via the ``eunit``, ``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::
@@ -200,28 +209,39 @@ to make targets::
# 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::
+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"
-There is an additional Elixir-based integration test suite for
-Dreyfus, which is not run automatically by the ``check`` target but it
-could be done manually via the corresponding target::
+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)
+``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
+Static Code Analysis
+~~~~~~~~~~~~~~~~~~~~
+
Code analyzer could be run by::
make dialyze
@@ -233,7 +253,8 @@ If you need to analyze only specific apps, you can specify them in familiar way
See ``make help`` for more info and useful commands.
-Please report any problems to the developer's mailing list.
+Please report any problems to the `developer's mailing list
+<ht...@couchdb.apache.org>`_.
Releasing
---------
@@ -257,13 +278,13 @@ built by running::
make release
-The release can then be found in the rel/couchdb directory.
+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 is required.
-Full instructions are available in that repository's README file.
-
+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.