This is an automated email from the ASF dual-hosted git repository.
tuhaihe pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudberry-pxf.git
The following commit(s) were added to refs/heads/main by this push:
new 5872786b Fix confusing build failure when javac is missing (#151)
5872786b is described below
commit 5872786bbdefcdfc0d482697d28a9649e4205f22
Author: Dianjin Wang <[email protected]>
AuthorDate: Thu Sep 10 15:25:03 2026 +0800
Fix confusing build failure when javac is missing (#151)
* Fix confusing build failure when javac is missing
The server module needs javac, but Gradle starts happily on a JRE and
only fails later at :pxf-api:compileJava with "Toolchain installation
... does not provide the required capabilities: [JAVA_COMPILER]", which
never mentions a JDK. Check for javac before invoking Gradle so the
build stops with an actionable message instead.
Installing the JDK afterwards is not enough on its own: the Gradle
daemon caches JVM metadata for its whole lifetime, so a daemon started
while only the JRE was present replays the same error. Both the new
check and the README now say to run ./gradlew --stop.
Also correct the JDK prerequisites: record that 8, 11, 17 and 21 are
supported, as the java-compatibility-test CI matrix already exercises,
note that 1.8 support will be removed in PXF 3.0, and fix the example
JAVA_HOME, which used a RHEL-style path that does not exist on
Debian/Ubuntu.
Fixes #150
* Improve the build troubleshooting
* Address the comment
---
README.md | 13 ++++++++++---
TROUBLESHOOTING.md | 41 +++++++++++++++++++++++++++++++++++++++++
server/Makefile | 25 ++++++++++++++++++++++++-
3 files changed, 75 insertions(+), 4 deletions(-)
diff --git a/README.md b/README.md
index fcb51ad4..0be14cd2 100755
--- a/README.md
+++ b/README.md
@@ -69,11 +69,16 @@ To build PXF, you must have:
source /usr/local/cloudberry-db/cloudberry-env.sh # For Cloudberry 2.1+
```
-3. JDK 1.8 or JDK 11 to compile/run
+3. A full JDK -- 1.8, 11, 17, or 21 -- to compile/run. A JRE is not enough, as
the
+ server module needs `javac`.
+
+ > [!NOTE]
+ > Support for JDK 1.8 will be removed in PXF 3.0. Use JDK 11 or later for
new setups.
Export your `JAVA_HOME`:
```
- export JAVA_HOME=/usr/lib/jvm/java-11-openjdk
+ export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 # Debian/Ubuntu
+ export JAVA_HOME=/usr/lib/jvm/java-11-openjdk # RHEL/Rocky
```
4. Go (1.25 or later)
@@ -96,6 +101,8 @@ To build PXF, you must have:
PXF uses Makefiles to build its components. PXF server component uses Gradle
that is wrapped into the Makefile for convenience.
+If the build fails, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md#build-issues).
+
> [!NOTE]
> To comply with Apache Software Foundation release guidelines,
> `gradle-wrapper.jar` is not included in the source distribution. It will be
> downloaded automatically during the initial build. Please ensure you have an
> active and stable internet connection.
@@ -163,7 +170,7 @@ We provide a Docker-based development environment that
includes Cloudberry, Hado
- Start IntelliJ. Click "Open" and select the directory to which you cloned
the `pxf` repo.
- Select `File > Project Structure`.
-- Make sure you have a JDK (version 1.8) selected.
+- Make sure you have a JDK selected (1.8, 11, 17, or 21). CI builds with JDK
11 by default.
- In the `Project Settings > Modules` section, select `Import Module`, pick
the `pxf/server` directory and import as a Gradle module. You may see an error
saying that there's
no JDK set for Gradle. Just cancel and retry. It goes away the second time.
- Import a second module, giving the `pxf/automation` directory, select
"Import module from external model", pick `Maven` then click Finish.
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
index a7d09ceb..4b7cf79e 100644
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -1,5 +1,46 @@
# Troubleshooting
+## Build Issues
+
+### Gradle reports `does not provide the required capabilities:
[JAVA_COMPILER]`
+
+```
+Execution failed for task ':pxf-api:compileJava'.
+> Error while evaluating property 'javaCompiler' of task
':pxf-api:compileJava'.
+ > Toolchain installation '/usr/lib/jvm/java-11-openjdk-amd64' does not
provide
+ the required capabilities: [JAVA_COMPILER]
+```
+
+The JVM Gradle is running on has no `javac`, so it is a JRE rather than a JDK.
+Gradle itself starts fine on a JRE, which is why the build gets as far as
+`:pxf-api:compileJava` before failing. Install a JDK and point `JAVA_HOME` at
it:
+
+```
+# Debian/Ubuntu
+sudo apt-get install -y openjdk-11-jdk
+export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
+
+# RHEL/Rocky
+sudo dnf install -y java-11-openjdk-devel
+export JAVA_HOME=/usr/lib/jvm/java-11-openjdk
+```
+
+Two things make this easy to misdiagnose:
+
+* On Debian/Ubuntu the JRE is installed into
`/usr/lib/jvm/java-11-openjdk-amd64`,
+ the same directory a JDK would use, so `java -version` and `ls /usr/lib/jvm`
both
+ look healthy while `javac` is absent. The `maven` package depends on
+ `default-jre-headless` and does **not** pull in a JDK. (On RHEL/Rocky,
+ `dnf install maven` does install one, via `maven-jdk-binding`.)
+* Installing the JDK is not sufficient on its own. The Gradle daemon caches JVM
+ installation metadata for its whole lifetime and never re-checks the
filesystem,
+ and because the JDK lands in the same *path*, Gradle reuses the daemon left
behind
+ by the failed build and reports the identical error. Stop it first:
+
+ ```
+ cd server && ./gradlew --stop
+ ```
+
## Out of Memory Issues
###
diff --git a/server/Makefile b/server/Makefile
index bfd0ee34..ee268517 100644
--- a/server/Makefile
+++ b/server/Makefile
@@ -27,8 +27,31 @@ PXF_API_VERSION ?= $(shell cat $(PXF_ROOT_DIR)/api_version)
PXF_GRADLE_PROPERTIES = -Pversion=$(PXF_VERSION)
-PapiVersion=$(PXF_API_VERSION)
+# Gradle can start on a JRE, but compiling PXF needs a JDK. Detect a JRE-only
+# installation here so the build fails with an actionable message instead of
+# Gradle's "does not provide the required capabilities: [JAVA_COMPILER]".
+JAVAC := $(if $(JAVA_HOME),$(JAVA_HOME)/bin/javac,$(shell command -v javac
2>/dev/null))
+
+.PHONY: check-jdk
+check-jdk:
+ @if [ ! -x "$(JAVAC)" ]; then \
+ echo "ERROR: no Java compiler (javac) found -- a JDK is
required to build PXF, a JRE is not enough."; \
+ if [ -n "$(JAVA_HOME)" ]; then \
+ echo " JAVA_HOME=$(JAVA_HOME) has no bin/javac,
so it points at a JRE."; \
+ else \
+ echo " JAVA_HOME is not set and javac is not on
PATH."; \
+ fi; \
+ echo " Install a JDK and point JAVA_HOME at it, for
example:"; \
+ echo " Debian/Ubuntu: sudo apt-get install -y
openjdk-11-jdk"; \
+ echo " RHEL/Rocky: sudo dnf install -y
java-11-openjdk-devel"; \
+ echo " export
JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64"; \
+ echo " If a build already failed here, also run
'./gradlew --stop'."; \
+ echo " See TROUBLESHOOTING.md for details."; \
+ exit 2; \
+ fi
+
.PHONY: prepare-gradle-wrapper
-prepare-gradle-wrapper:
+prepare-gradle-wrapper: check-jdk
@APP_HOME="$(CURDIR)" bash ./gradlew-install.sh
help:
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
