This is an automated email from the ASF dual-hosted git repository.
penghui pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new c4e688652ce [cleanup][build] Update documentation and examples from
Maven to Gradle (#25403)
c4e688652ce is described below
commit c4e688652cefd87f8bbcae46582dd0bce86406aa
Author: Matteo Merli <[email protected]>
AuthorDate: Thu Mar 26 14:38:19 2026 -0700
[cleanup][build] Update documentation and examples from Maven to Gradle
(#25403)
---
README.md | 33 +++++++++-------------
docker/build.sh | 4 +--
microbench/README.md | 26 +++++++----------
...ucketDelayedDeliveryTrackerSimpleBenchmark.java | 3 +-
.../cache/BrokerEntryCacheRollingRestartTest.java | 7 +++--
tests/README.md | 8 +++---
tests/compose/README.md | 2 +-
.../integration/profiling/PulsarProfilingTest.java | 7 ++---
8 files changed, 39 insertions(+), 51 deletions(-)
diff --git a/README.md b/README.md
index fd9efceabdd..273846a88a3 100644
--- a/README.md
+++ b/README.md
@@ -173,52 +173,51 @@ Docker image Java runtime: 17
| 2.8 / 2.9 / 2.10 | [JDK
11](https://adoptium.net/en-GB/temurin/releases?version=11&os=any&arch=any) |
| 2.7 - | [JDK
8](https://adoptium.net/en-GB/temurin/releases?version=8&os=any&arch=any) |
-- Maven 3.9.9+
- zip
There is also a guide for [setting up the tooling for building
Pulsar](https://pulsar.apache.org/contribute/setup-buildtools/).
> **Note**:
>
-> This project includes a [Maven Wrapper](https://maven.apache.org/wrapper/)
that can be used instead of a system-installed Maven.
-> Use it by replacing `mvn` by `./mvnw` on Linux and `mvnw.cmd` on Windows in
the commands below.
+> This project includes a [Gradle
Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) so no
separate Gradle installation is needed.
+> Use `./gradlew` on Linux/macOS and `gradlew.bat` on Windows.
### Build
-Compile and install:
+Compile and assemble:
```bash
-$ mvn install -DskipTests
+$ ./gradlew assemble
```
-Compile and install individual module
+Compile and assemble individual module:
```bash
-$ mvn -pl module-name (e.g: pulsar-broker) install -DskipTests
+$ ./gradlew :pulsar-broker:assemble
```
-### Minimal build (This skips most of external connectors and tiered storage
handlers)
+### Minimal build (core modules only, skips external connectors and tiered
storage handlers)
```bash
-mvn install -Pcore-modules,-main -DskipTests
+$ ./gradlew assemble -PcoreModules
```
Run Unit Tests:
```bash
-$ mvn test
+$ ./gradlew test
```
Run Individual Unit Test:
```bash
-$ mvn -pl module-name (e.g: pulsar-client) test -Dtest=unit-test-name (e.g:
ConsumerBuilderImplTest)
+$ ./gradlew :pulsar-client-original:test --tests "ConsumerBuilderImplTest"
```
Run Selected Test packages:
```bash
-$ mvn test -pl module-name (for example, pulsar-broker)
-Dinclude=org/apache/pulsar/**/*.java
+$ ./gradlew :pulsar-broker:test --tests "org.apache.pulsar.*"
```
Start standalone Pulsar service:
@@ -235,25 +234,19 @@ The commands used in the Apache Pulsar release process
can be found in the [rele
Here are some general instructions for building custom docker images:
-* Docker images must be built with Java 8 for `branch-2.7` or previous
branches because of [ISSUE-8445](https://github.com/apache/pulsar/issues/8445).
-* Java 11 is the recommended JDK version in `branch-2.8`, `branch-2.9` and
`branch-2.10`.
-* Java 17 is the recommended JDK version in `branch-2.11`, `branch-3.0` and
`branch-3.3`.
* Java 21 is the recommended JDK version since `branch-4.0`.
The following command builds the docker images
`apachepulsar/pulsar-all:latest` and `apachepulsar/pulsar:latest`:
```bash
-mvn clean install -DskipTests
-# setting DOCKER_CLI_EXPERIMENTAL=enabled is required in some environments
with older docker versions
-export DOCKER_CLI_EXPERIMENTAL=enabled
-mvn package -Pdocker,-main -am -pl docker/pulsar-all -DskipTests
+$ ./gradlew docker-all
```
After the images are built, they can be tagged and pushed to your custom
repository. Here's an example of a bash script that tags the docker images with
the current version and git revision and pushes them to
`localhost:32000/apachepulsar`.
```bash
image_repo_and_project=localhost:32000/apachepulsar
-pulsar_version=$(mvn initialize help:evaluate -Dexpression=project.version -pl
. -q -DforceStdout)
+pulsar_version=$(grep "^pulsar " gradle/libs.versions.toml | sed 's/.*= *"//'
| sed 's/"//')
gitrev=$(git rev-parse HEAD | colrm 10)
tag="${pulsar_version}-${gitrev}"
echo "Using tag $tag"
diff --git a/docker/build.sh b/docker/build.sh
index 88be44f23e7..9b7a1acc82a 100755
--- a/docker/build.sh
+++ b/docker/build.sh
@@ -19,6 +19,6 @@
#
ROOT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )"/.. >/dev/null 2>&1 && pwd )"
-cd $ROOT_DIR/docker
+cd $ROOT_DIR
-mvn package -Pdocker,-main
+./gradlew -Pdocker :docker:pulsar-docker-image:dockerBuild
:docker:pulsar-all-docker-image:dockerBuild
diff --git a/microbench/README.md b/microbench/README.md
index 047de7c425d..9138c3de2c1 100644
--- a/microbench/README.md
+++ b/microbench/README.md
@@ -28,17 +28,11 @@ This module contains microbenchmarks for Apache Pulsar.
The benchmarks are written using
[JMH](http://openjdk.java.net/projects/code-tools/jmh/). To compile & run the
benchmarks, use the following command:
```bash
-# Compile everything for creating the shaded microbenchmarks.jar file
-mvn -Pcore-modules,microbench,-main -T 1C clean package
+# Compile everything including the shaded microbenchmarks jar
+./gradlew :microbench:shadowJar
# run the benchmarks using the standalone shaded jar in any environment
-java -jar microbench/target/microbenchmarks.jar
-```
-
-For fast recompiling of the benchmarks (without compiling Pulsar modules) and
creating the shaded jar, you can use the following command:
-
-```bash
-mvn -Pmicrobench -pl microbench clean package
+java -jar microbench/build/libs/microbenchmarks.jar
```
### Running specific benchmarks
@@ -46,25 +40,25 @@ mvn -Pmicrobench -pl microbench clean package
Display help:
```shell
-java -jar microbench/target/microbenchmarks.jar -h
+java -jar microbench/build/libs/microbenchmarks.jar -h
```
Listing all benchmarks:
```shell
-java -jar microbench/target/microbenchmarks.jar -l
+java -jar microbench/build/libs/microbenchmarks.jar -l
```
Running specific benchmarks:
```shell
-java -jar microbench/target/microbenchmarks.jar ".*BenchmarkName.*"
+java -jar microbench/build/libs/microbenchmarks.jar ".*BenchmarkName.*"
```
Running specific benchmarks with machine-readable output and saving the output
to a file:
```shell
-java -jar microbench/target/microbenchmarks.jar -rf json -rff
jmh-result-$(date +%s).json ".*BenchmarkName.*" | tee jmh-result-$(date +%s).txt
+java -jar microbench/build/libs/microbenchmarks.jar -rf json -rff
jmh-result-$(date +%s).json ".*BenchmarkName.*" | tee jmh-result-$(date +%s).txt
```
The `jmh-result-*.json` file can be used to visualize the results using [JMH
Visualizer](https://jmh.morethan.io/).
@@ -72,7 +66,7 @@ The `jmh-result-*.json` file can be used to visualize the
results using [JMH Vis
Checking what benchmarks match the pattern:
```shell
-java -jar microbench/target/microbenchmarks.jar ".*BenchmarkName.*" -lp
+java -jar microbench/build/libs/microbenchmarks.jar ".*BenchmarkName.*" -lp
```
Profiling benchmarks with
[async-profiler](https://github.com/async-profiler/async-profiler):
@@ -81,7 +75,7 @@ Profiling benchmarks with
[async-profiler](https://github.com/async-profiler/asy
# example of profiling with async-profiler
# download async-profiler from
https://github.com/async-profiler/async-profiler/releases
LIBASYNCPROFILER_PATH=$HOME/async-profiler/lib/libasyncProfiler.dylib
-java -jar microbench/target/microbenchmarks.jar -prof
async:libPath=$LIBASYNCPROFILER_PATH\;output=flamegraph\;dir=profile-results
".*BenchmarkName.*"
+java -jar microbench/build/libs/microbenchmarks.jar -prof
async:libPath=$LIBASYNCPROFILER_PATH\;output=flamegraph\;dir=profile-results
".*BenchmarkName.*"
```
When profiling on Mac OS, you might need to add `\;event=itimer` to the
`-prof` argument since it's the only [async profiler CPU sampling engine that
supports Mac
OS](https://github.com/async-profiler/async-profiler/blob/master/docs/CpuSamplingEngines.md#summary).
The default value for `event` is `cpu`.
@@ -89,5 +83,5 @@ When profiling on Mac OS, you might need to add
`\;event=itimer` to the `-prof`
It's possible to add options to the async-profiler that aren't supported by
the JMH async-profiler plugin. This can be done by adding `rawCommand` option
to the `-prof` argument. This example shows how to add `all` (new in Async
Profiler 4.1), `jfrsync` (record JFR events such as garbage collection) and
`cstack=vmx` options.
```shell
-java -jar microbench/target/microbenchmarks.jar -prof
async:libPath=$LIBASYNCPROFILER_PATH\;output=jfr\;dir=profile-results\;rawCommand=all,jfrsync,cstack=vmx
".*BenchmarkName.*"
+java -jar microbench/build/libs/microbenchmarks.jar -prof
async:libPath=$LIBASYNCPROFILER_PATH\;output=jfr\;dir=profile-results\;rawCommand=all,jfrsync,cstack=vmx
".*BenchmarkName.*"
```
\ No newline at end of file
diff --git
a/microbench/src/main/java/org/apache/pulsar/broker/delayed/bucket/BucketDelayedDeliveryTrackerSimpleBenchmark.java
b/microbench/src/main/java/org/apache/pulsar/broker/delayed/bucket/BucketDelayedDeliveryTrackerSimpleBenchmark.java
index 985e714d54d..8e8b0878793 100644
---
a/microbench/src/main/java/org/apache/pulsar/broker/delayed/bucket/BucketDelayedDeliveryTrackerSimpleBenchmark.java
+++
b/microbench/src/main/java/org/apache/pulsar/broker/delayed/bucket/BucketDelayedDeliveryTrackerSimpleBenchmark.java
@@ -40,8 +40,7 @@ import org.openjdk.jmh.annotations.Warmup;
* Simplified JMH Benchmarks for BucketDelayedDeliveryTracker thread safety
improvements.
* This benchmark focuses on the core StampedLock optimistic read performance
without
* complex dependencies on the full BucketDelayedDeliveryTracker
implementation.
- * Run with: mvn exec:java -Dexec.mainClass="org.openjdk.jmh.Main"
- * -Dexec.args="BucketDelayedDeliveryTrackerSimpleBenchmark"
+ * Run with: java -jar microbench/build/libs/microbenchmarks.jar
BucketDelayedDeliveryTrackerSimpleBenchmark
*/
@BenchmarkMode(Mode.Throughput)
@OutputTimeUnit(TimeUnit.SECONDS)
diff --git
a/pulsar-broker/src/test/java/org/apache/pulsar/broker/cache/BrokerEntryCacheRollingRestartTest.java
b/pulsar-broker/src/test/java/org/apache/pulsar/broker/cache/BrokerEntryCacheRollingRestartTest.java
index 4dca51b9cec..bc45a7e7927 100644
---
a/pulsar-broker/src/test/java/org/apache/pulsar/broker/cache/BrokerEntryCacheRollingRestartTest.java
+++
b/pulsar-broker/src/test/java/org/apache/pulsar/broker/cache/BrokerEntryCacheRollingRestartTest.java
@@ -62,8 +62,11 @@ import org.testng.annotations.Test;
* as part of the regular test suite. This might change later.
* The current intent is to show how the PIP-430 caching results in better
cache hit rates in rolling restarts
* when there's an active producer producing messages to a topic.
- * To avoid OOME, run this test on the command line (after enabling the test
case) with this command:
- * ENABLE_MANUAL_TEST=true NETTY_LEAK_DETECTION=off mvn -pl pulsar-broker test
-Dtest=BrokerEntryCacheRollingRestartTest
+ * To avoid OOME, run this test on the command line
+ * (after enabling the test case) with this command:
+ * ENABLE_MANUAL_TEST=true NETTY_LEAK_DETECTION=off
+ * ./gradlew :pulsar-broker:test
+ * --tests BrokerEntryCacheRollingRestartTest
*/
@Slf4j
public class BrokerEntryCacheRollingRestartTest extends
AbstractBrokerEntryCacheMultiBrokerTest {
diff --git a/tests/README.md b/tests/README.md
index 926340cb88e..965f0e81d0c 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -23,12 +23,12 @@ This directory contains integration tests for Pulsar.
The integration tests use a framework called [Test
Containers](https://www.testcontainers.org/) to bring up a bunch of docker
containers running Pulsar services. TestNG can then be used to test
functionallity against these containers.
-The tests require that docker is installed and running. Tests will only run if
the integrationTests system property is defined. To run the tests:
+The tests require that docker is installed and running. To run the tests:
```shell
# in the top level directory
-pulsar/ $ mvn install -DskipTests -Pdocker,-main # builds the docker images
-...
-pulsar/ $ mvn -f tests/pom.xml test -DintegrationTests
+pulsar/ $ ./gradlew assemble # builds
all modules
+pulsar/ $ ./gradlew -Pdocker :tests:latest-version-image:dockerBuild # builds
the docker test image
+pulsar/ $ ./gradlew :tests:integration:integrationTest # runs
the integration tests
```
The directories are as follows:
diff --git a/tests/compose/README.md b/tests/compose/README.md
index 9b41428e83c..3f8b3111b1c 100644
--- a/tests/compose/README.md
+++ b/tests/compose/README.md
@@ -21,7 +21,7 @@
This are docker compose files to quickly bring up a pulsar
cluster. They use the pulsar testing docker image. To generate this,
-run ```mvn install -DskipTests -Pdocker,-main``` in the top-level directory
+run ```./gradlew assemble && ./gradlew -Pdocker
:docker:pulsar-all-docker-image:dockerBuild``` in the top-level directory
of the project.
To run, change directory into multi or simple, and run:
diff --git
a/tests/integration/src/test/java/org/apache/pulsar/tests/integration/profiling/PulsarProfilingTest.java
b/tests/integration/src/test/java/org/apache/pulsar/tests/integration/profiling/PulsarProfilingTest.java
index 6310a40a31e..610cb1819a8 100644
---
a/tests/integration/src/test/java/org/apache/pulsar/tests/integration/profiling/PulsarProfilingTest.java
+++
b/tests/integration/src/test/java/org/apache/pulsar/tests/integration/profiling/PulsarProfilingTest.java
@@ -46,7 +46,7 @@ import org.testng.annotations.Test;
* Example usage:
* # This has been tested on Mac with Orbstack (https://orbstack.dev/) docker
* # compile integration test dependencies
- * mvn -am -pl tests/integration -Dcheckstyle.skip=true -Dlicense.skip=true
-Dspotbugs.skip=true -DskipTests install
+ * ./gradlew assemble
* # compile apachepulsar/java-test-image with async profiler (add "clean" to
ensure a clean build with recent changes)
* ./build/build_java_test_image.sh -Ddocker.install.asyncprofiler=true
-Pdocker-wolfi
* # set environment variables
@@ -65,9 +65,8 @@ import org.testng.annotations.Test;
* kernel.perf_event_max_stack=1024
* kernel.perf_event_mlock_kb=2048
* # run the test
- * mvn -DintegrationTests -pl tests/integration -Dtest=PulsarProfilingTest
-DtestRetryCount=0 \
- * -DredirectTestOutputToFile=false test
- * By default, the .jfr files will go into tests/integration/target
+ * ./gradlew :tests:integration:integrationTest
-PintegrationTestSuiteFile=pulsar-profiling.xml -PtestRetryCount=0
+ * By default, the .jfr files will go into tests/integration/build
* You can use jfrconv from async profiler to convert them into html
flamegraphs or use other tools such
* as Eclipse Mission Control (https://adoptium.net/jmc) or IntelliJ to open
them.
*/
