feat(dev): add Clouseau to the developer setup

.devcontainer/devcontainer.json

@@ -5,11 +5,11 @@
         "context": "..",
         "args": {
             // Useful choices include:
-            // apache/couchdbci-debian:bullseye-erlang-25.0.2
-            // apache/couchdbci-debian:bullseye-erlang-24.3.4.2
-            // apache/couchdbci-debian:bullseye-erlang-23.3.4.15
+            // apache/couchdbci-debian:bullseye-erlang-26.1.2
+            // apache/couchdbci-debian:bullseye-erlang-25.3.2.7
+            // apache/couchdbci-debian:bookworm-erlang-24.3.4.14
             //
-            "COUCHDB_IMAGE": "apache/couchdbci-debian:bullseye-erlang-24.3.4.10"
+            "COUCHDB_IMAGE": "apache/couchdbci-debian:bullseye-erlang-24.3.4.14"
         }
     },
 
@@ -23,7 +23,7 @@
     // Your code will live inside the volume created for the container under /workspace.
     "workspaceMount": "target=/workspaces/couchdb,type=volume",
     "workspaceFolder": "/workspaces/couchdb",
-    "postCreateCommand": "./configure --enable-nouveau && make",
+    "postCreateCommand": "./configure --enable-nouveau --enable-clouseau && make",
 
     "customizations": {
         "vscode": {

Makefile

@@ -157,6 +157,7 @@ check: all
 	@$(MAKE) eunit
 	@$(MAKE) mango-test
 	@$(MAKE) elixir
+	@$(MAKE) elixir-search
 	@$(MAKE) weatherreport-test
 	@$(MAKE) nouveau-test
 
@@ -263,12 +264,17 @@ elixir: elixir-init devclean
 		--no-eval 'mix test --trace --include test/elixir/test/config/suite.elixir --exclude test/elixir/test/config/skip.elixir $(EXUNIT_OPTS)'
 
 .PHONY: elixir-search
-# target: elixir-search - Run search tests, requires a running Clouseau instance
+# target: elixir-search - Run search tests, requires a configured Clouseau instance
 elixir-search: export MIX_ENV=integration
 elixir-search: elixir-init devclean
+ifeq ($(with_clouseau), 1)
 	@dev/run -n 1 -q -a adm:pass \
+		--with-clouseau \
 		--locald-config test/config/test-config.ini \
 		--no-eval 'mix test --trace --include test/elixir/test/config/search.elixir'
+else
+	@echo "Warning: Clouseau is not enabled, \`elixir-search\` cannot be run."
+endif
 
 .PHONY: elixir-source-checks
 # target: elixir-source-checks - Check source code formatting of Elixir test files
@@ -313,19 +319,24 @@ list-eunit-suites:
 build-test:
 	@test/build/test-configure.sh
 
+ifeq ($(with_clouseau), 1)
+_WITH_CLOUSEAU="--with-clouseau"
+endif
 
 .PHONY: mango-test
 # target: mango-test - Run Mango tests
 mango-test: export COUCHDB_TEST_ADMIN_PARTY_OVERRIDE=1
 mango-test: devclean all
-	@cd src/mango && \
-		python3 -m venv .venv && \
-		.venv/bin/python3 -m pip install -r requirements.txt
-	@cd src/mango && \
-		../../dev/run "$(TEST_OPTS)" \
+	@python3 -m venv src/mango/.venv && \
+		src/mango/.venv/bin/python3 -m pip install -r src/mango/requirements.txt
+	@dev/run \
+		"$(TEST_OPTS)" \
+		"$(_WITH_CLOUSEAU)" \
 		-n 1 \
 		--admin=adm:pass \
-		'COUCH_USER=adm COUCH_PASS=pass .venv/bin/python3 -m nose2 $(MANGO_TEST_OPTS)'
+		--no-eval "\
+COUCH_USER=adm COUCH_PASS=pass \
+src/mango/.venv/bin/nose2 -s src/mango/test -c src/mango/unittest.cfg $(MANGO_TEST_OPTS)"
 
 
 .PHONY: weatherreport-test

Makefile.win

@@ -143,6 +143,7 @@ check: all
 	@$(MAKE) eunit
 	@$(MAKE) mango-test
 	@$(MAKE) elixir
+	@$(MAKE) elixir-search
 	@$(MAKE) nouveau-test
 
 ifdef apps
@@ -203,6 +204,8 @@ python-black-update: .venv/bin/black
 		--exclude="build/|buck-out/|dist/|_build/|\.git/|\.hg/|\.mypy_cache/|\.nox/|\.tox/|\.venv/|src/erlfmt|src/rebar/pr2relnotes.py|src/fauxton" \
 		build-aux dev\run dev\format_*.py src\mango\test src\docs\src\conf.py src\docs\ext .
 
+-include install.mk
+
 ifeq ($(with_nouveau), 0)
   exclude_nouveau=--exclude nouveau
 endif
@@ -239,12 +242,17 @@ elixir: elixir-init devclean
 		--no-eval 'mix test --trace --include test\elixir\test\config\suite.elixir --exclude test\elixir\test\config\skip.elixir $(EXUNIT_OPTS)'
 
 .PHONY: elixir-search
-# target: elixir-search - Run search tests, requires a running Clouseau instance
+# target: elixir-search - Run search tests, requires a configured Clouseau instance
 elixir-search: export MIX_ENV=integration
 elixir-search: elixir-init devclean
+ifeq ($(with_clouseau), 1)
 	@dev\run -n 1 -q -a adm:pass \
+		--with-clouseau \
 		--locald-config test/config/test-config.ini \
 		--no-eval 'mix test --trace --include test/elixir/test/config/search.elixir'
+else
+	@echo "Warning: Clouseau is not enabled, `elixir-search` cannot be run."
+endif
 
 .PHONY: elixir-source-checks
 # target: elixir-source-checks - Check source code formatting of Elixir test files
@@ -278,19 +286,24 @@ list-eunit-apps:
 list-eunit-suites:
 	@powershell -Command 'Get-ChildItem -Path src -Recurse -Filter "*_tests?.erl" | ForEach-Object { "{0}" -f $$_.BaseName } | Sort'
 
+ifeq ($(with_clouseau), 1)
+_WITH_CLOUSEAU="--with-clouseau"
+endif
 
 .PHONY: mango-test
 # target: mango-test - Run Mango tests
 mango-test: export COUCHDB_TEST_ADMIN_PARTY_OVERRIDE=1
 mango-test: devclean all
-	@cd src\mango && \
-		python.exe -m venv .venv && \
-		.venv\Scripts\pip.exe install -r requirements.txt
-	@cd src\mango && \
-		..\..\dev\run "$(TEST_OPTS)" \
+	@$(PYTHON) -m venv src\mango\.venv && \
+		src\mango\.venv\Scripts\pip.exe install -r src\mango\requirements.txt
+	@dev\run \
+		"$(TEST_OPTS)" \
+		"$(_WITH_CLOUSEAU)" \
 		-n 1 \
 		--admin=adm:pass \
-		"env COUCH_USER=adm COUCH_PASS=pass .venv\Scripts\nose2 $(MANGO_TEST_OPTS)"
+		"\
+env COUCH_USER=adm COUCH_PASS=pass \
+src\mango\.venv\Scripts\nose2 -s src\mango\test -c src\mango\unittest.cfg $(MANGO_TEST_OPTS)"
 
 
 ################################################################################
@@ -350,10 +363,9 @@ dist: all derived
 
 .PHONY: release
 # target: release - Create an Erlang release including CouchDB!
--include install.mk
 release: all
 	@echo 'Installing CouchDB into rel\couchdb\ ...'
-	-@rmdir /s/q rel\couchdb
+	-@rmdir /s/q rel\couchdb >NUL 2>&1 || true
 	@$(REBAR) generate
 	@copy src\couch\priv\couchjs.exe rel\couchdb\bin
 
@@ -406,48 +418,48 @@ install: release
 # target: clean - Remove build artifacts
 clean:
 	@$(REBAR) -r clean
-	-@rmdir /s/q .rebar
-	-@del /f/q bin\couchjs.exe
-	-@rmdir /s/q src\*\ebin
-	-@rmdir /s/q src\*\.rebar
-	-@del /f/q/s src\*.dll
-	-@del /f/q src\couch\priv\*.exe
-	-@del /f/q share\server\main.js share\server\main-ast-bypass.js share\server\main-coffee.js
-	-@rmdir /s/q tmp
-	-@rmdir /s/q dev\data
-	-@rmdir /s/q dev\lib
-	-@rmdir /s/q dev\logs
-	-@rmdir /s/q src\mango\.venv
-	-@del /f/q src\couch\priv\couch_js\config.h
-	-@del /f/q dev\boot_node.beam dev\pbkdf2.pyc log\crash.log
+	-@rmdir /s/q .rebar >NUL 2>&1 || true
+	-@del /f/q bin\couchjs.exe >NUL 2>&1 || true
+	-@rmdir /s/q src\*\ebin >NUL 2>&1 || true
+	-@rmdir /s/q src\*\.rebar >NUL 2>&1 || true
+	-@del /f/q/s src\*.dll >NUL 2>&1 || true
+	-@del /f/q src\couch\priv\*.exe >NUL 2>&1 || true
+	-@del /f/q share\server\main.js share\server\main-ast-bypass.js share\server\main-coffee.js >NUL 2>&1 || true
+	-@rmdir /s/q tmp >NUL 2>&1 || true
+	-@rmdir /s/q dev\data >NUL 2>&1 || true
+	-@rmdir /s/q dev\lib >NUL 2>&1 || true
+	-@rmdir /s/q dev\logs >NUL 2>&1 || true
+	-@rmdir /s/q src\mango\.venv >NUL 2>&1 || true
+	-@del /f/q src\couch\priv\couch_js\config.h >NUL 2>&1 || true
+	-@del /f/q dev\boot_node.beam dev\pbkdf2.pyc log\crash.log >NUL 2>&1 || true
 ifeq ($(with_nouveau), 1)
 	@cd nouveau && .\gradlew clean
 endif
 
 .PHONY: distclean
 # target: distclean - Remove build and release artifacts
 distclean: clean
-	-@del install.mk
-	-@del config.erl
-	-@del rel\couchdb.config
+	-@del install.mk >NUL 2>&1 || true
+	-@del config.erl >NUL 2>&1 || true
+	-@del rel\couchdb.config >NUL 2>&1 || true
 ifneq ($(IN_RELEASE), true)
 # when we are in a release, don’t delete the
 # copied sources, generated docs, or fauxton
-	-@rmdir /s/q rel\couchdb
-	-@rmdir /s/q share\www
-	-@rmdir /s/q src\docs
+	-@rmdir /s/q rel\couchdb >NUL 2>&1 || true
+	-@rmdir /s/q share\www >NUL 2>&1 || true
+	-@rmdir /s/q src\docs >NUL 2>&1 || true
 endif
 
 
 .PHONY: devclean
 # target: devclean - Remove dev cluster artifacts
 devclean:
-	-@rmdir /s/q dev\lib\node1\data
-	-@rmdir /s/q dev\lib\node2\data
-	-@rmdir /s/q dev\lib\node3\data
-	-@rmdir /s/q dev\lib\node1\etc
-	-@rmdir /s/q dev\lib\node2\etc
-	-@rmdir /s/q dev\lib\node3\etc
+	-@rmdir /s/q dev\lib\node1\data >NUL 2>&1 || true
+	-@rmdir /s/q dev\lib\node2\data >NUL 2>&1 || true
+	-@rmdir /s/q dev\lib\node3\data >NUL 2>&1 || true
+	-@rmdir /s/q dev\lib\node1\etc >NUL 2>&1 || true
+	-@rmdir /s/q dev\lib\node2\etc >NUL 2>&1 || true
+	-@rmdir /s/q dev\lib\node3\etc >NUL 2>&1 || true
 
 
 ################################################################################

README-DEV.rst

@@ -152,9 +152,9 @@ Configure the source by running::
 
     ./configure
 
-If you intend to run the test suites::
+If you intend to run the test suites with Clouseau::
 
-    ./configure -c
+    ./configure --enable-clouseau
 
 If you don't want to build Fauxton or documentation specify
 ``--disable-fauxton`` and/or ``--disable-docs`` arguments for ``configure`` to
@@ -237,14 +237,8 @@ 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>`_
-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
+Note that this requires Clouseau to be configured for running, see
+above.
 
 Mango Integration Tests
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -262,7 +256,7 @@ the implementation.  Consult its documentation for more information.
 
 Tests that rely on text indexes are run only if the ``search`` feature
 is reported to be available (i.e. a working Clouseau instance is
-connected), otherwise they will be skipped.
+configured and working), otherwise they will be skipped.
 
 Note that the databases that are created during the tests will be all
 removed after each of the suites completed.  However, with the help of
@@ -272,6 +266,58 @@ to keep those databases around for further investigation::
     MANGO_TESTS_KEEP_DBS=please \
       make mango-test MANGO_TEST_OPTS='03-operator-test'
 
+Running Clouseau
+~~~~~~~~~~~~~~~~
+
+When configured with the ``./configure`` script, the ``./dev/run``
+script is capable of launching Clouseau instances alongside the
+CouchDB nodes and hooking them up.  This is what the ``mango-test``
+and ``elixir-search`` targets also use to run their respective test
+suites, and let Clouseau automatically manage them.
+
+Although the ``./configure`` and the ``./dev/run`` scripts try to take
+care of the details of the Clouseau deployment, it is still the
+responsibility of the user to provide a suitable Java environment for
+running.  Clouseau can run with JRE 1.7 and 1.8 only.  Also, when
+Nouveau is in use, which uses a more recent Java environment, the old
+JDK has to be installed separately and the ``CLOUSEAU_JAVA_HOME``
+environment variable has to be set to point its location.
+
+Fortunately, the ```asdf`` tool <https://asdf-vm.com/>` provides a
+convenient way to install old versions of JDK through its ```java``
+plugin <https://github.com/halcyon/asdf-java>`::
+
+    asdf plugin add java
+
+Then use ``asdf`` to install it::
+
+    asdf install java zulu-jre-8.74.0.17
+
+Finally, use ``asdf`` to set the ``CLOUSEAU_JAVA_HOME`` environment
+variable::
+
+    export CLOUSEAU_JAVA_HOME=$(asdf where java zulu-jre-8.74.0.17)
+
+If the use of ``asdf`` is not an option, `the Zulu site
+<https://cdn.azul.com/zulu/bin/>` could be used directly to get the
+distribution package for the appropriate JRE version.  But this is
+just one of the possibilities to access installers for old Java
+environments.
+
+Once both Clouseau and the corresponding Java environment are set,
+they are not put in use automatically.  In order to do so, the
+``./dev/run`` script needs to be run with Clouseau enabled as
+follows::
+
+    dev/run --with-clouseau
+
+When a specific Erlang cookie string is set in
+``rel/overlay/etc/vm.args``, the ``--erlang-cookie`` flag could be
+used to configure Clouseau to work with that::
+
+    dev/run --with-clouseau --erlang-cookie=brumbrum
+
+
 Static Code Analysis
 ~~~~~~~~~~~~~~~~~~~~