This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/2.x by this push:
new c4df56e979 doc: Clarify and enhance `GraalVmProcessor` configuration
example (#3786)
c4df56e979 is described below
commit c4df56e979e00a06624147fdc0fd04a7d0638307
Author: Piotr P. Karwasz <[email protected]>
AuthorDate: Thu Jul 3 16:02:29 2025 +0200
doc: Clarify and enhance `GraalVmProcessor` configuration example (#3786)
This update refines the `GraalVmProcessor` configuration example in
response to feedback from #3755. The goal is to make the example more reliable
and aligned with common Maven project setups. Key improvements include:
* **Ensuring consistent parameter usage:**
The example now adds `-Alog4j.graalvm.groupId` and
`-Alog4j.graalvm.artifactId` to **all executions** of the Maven Compiler
Plugin. This guarantees correct behavior regardless of the execution ID used in
user projects.
* **Simplifying plugin execution setup:**
Instead of introducing a dedicated `generate-log4j-plugin-descriptor`
execution, the example now modifies the existing `default-compile` execution.
This reflects the most typical use case, where annotation processing and
compilation occur together.
These changes aim to make the setup easier to adopt while reducing
configuration errors.
---
.../antora/modules/ROOT/pages/manual/plugins.adoc | 29 ++++++++++++----------
1 file changed, 16 insertions(+), 13 deletions(-)
diff --git a/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
b/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
index 233b6fd322..6b751f0736 100644
--- a/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
@@ -211,8 +211,8 @@ annotation processor creates such a file at compile-time.
[WARNING]
====
-The `GraalVmProcessor` needs to know the `groupId` and `artifactId`
coordinates of your project.
-These must be supplied to the processor using the `log4j.graalvm.groupId` and
`log4j.graalvm.artifactId` annotation processor options.
+The `GraalVmProcessor` requires your project's `groupId` and `artifactId` to
correctly generate the GraalVM reachability metadata file in the recommended
location.
+Provide these values to the processor using the `log4j.graalvm.groupId` and
`log4j.graalvm.artifactId` annotation processor options.
====
You need to configure your build tool as follows to use both plugin processors:
@@ -227,15 +227,23 @@ Maven::
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>${maven-compiler-plugin.version}</version>
+ <configuration>
+ <compilerArgs>
+ <!-- Provide the project coordinates to `GraalVmProcessor`: -->
+ <arg>-Alog4j.graalvm.groupId=${project.groupId}</arg>
+ <arg>-Alog4j.graalvm.artifactId=${project.artifactId}</arg>
+ </compilerArgs>
+ </configuration>
<executions>
<execution>
- <id>generate-log4j-plugin-descriptor</id>
- <goals>
- <goal>compile</goal>
- </goals>
- <phase>process-classes</phase>
+ <!--
+ ~ Explicitly list the annotation processors for the default compile
execution.
+ ~ This is required starting with JDK 23, where annotation processors
are not enabled automatically.
+ ~ Explicit configuration also improves build reliability and clarity.
+ ~ For more details, see:
https://inside.java/2024/06/18/quality-heads-up/
+ -->
+ <id>default-compile</id>
<configuration>
- <proc>only</proc>
<annotationProcessorPaths>
<!-- Include `log4j-core` providing
1.
`org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` that
generates `Log4j2Plugins.dat`
@@ -252,11 +260,6 @@ Maven::
<!-- Process sources using `GraalVmProcessor` to generate a GraalVM
reachability metadata file -->
<processor>org.apache.logging.log4j.core.config.plugins.processor.GraalVmProcessor</processor>
</annotationProcessors>
- <compilerArgs>
- <!-- Provide the project coordinates to `GraalVmProcessor`: -->
- <arg>-Alog4j.graalvm.groupId=${project.groupId}</arg>
- <arg>-Alog4j.graalvm.artifactId=${project.artifactId}</arg>
- </compilerArgs>
</configuration>
</execution>
</executions>
