From 4763123932435d463e99e9375e5c2f47e0e0ae16 Mon Sep 17 00:00:00 2001
From: Andy Wilkinson <andy.wilkinson@broadcom.com>
Date: Tue, 3 Dec 2024 11:10:53 +0000
Subject: [PATCH] Recommend using Maven's <annotationProcessorPaths>

Closes gh-43329
---
 .../developing-auto-configuration.adoc        | 25 ++++----------
 .../annotation-processor.adoc                 | 33 ++++++++++++-------
 2 files changed, 29 insertions(+), 29 deletions(-)

diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/developing-auto-configuration.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/developing-auto-configuration.adoc
index 07885f8e501..f2d4a9592ab 100644
--- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/developing-auto-configuration.adoc
+++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/developing-auto-configuration.adoc
@@ -283,18 +283,7 @@ If you do it that way, the library is not provided and, by default, Spring Boot
 Spring Boot uses an annotation processor to collect the conditions on auto-configurations in a metadata file (`META-INF/spring-autoconfigure-metadata.properties`).
 If that file is present, it is used to eagerly filter auto-configurations that do not match, which will improve startup time.
 
-When building with Maven, it is recommended to add the following dependency in a module that contains auto-configurations:
-
-[source,xml]
-----
-<dependency>
-	<groupId>org.springframework.boot</groupId>
-	<artifactId>spring-boot-autoconfigure-processor</artifactId>
-	<optional>true</optional>
-</dependency>
-----
-
-If you have defined auto-configurations directly in your application, make sure to configure the `spring-boot-maven-plugin` to prevent the `repackage` goal from adding the dependency into the uber jar:
+When building with Maven, configure the compiler plugin (3.12.0 or later) to add `spring-boot-autoconfigure-processor` to the annotation processor paths:
 
 [source,xml]
 ----
@@ -302,15 +291,15 @@ If you have defined auto-configurations directly in your application, make sure
 	<build>
 		<plugins>
 			<plugin>
-				<groupId>org.springframework.boot</groupId>
-				<artifactId>spring-boot-maven-plugin</artifactId>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-compiler-plugin</artifactId>
 				<configuration>
-					<excludes>
-						<exclude>
+					<annotationProcessorPaths>
+						<path>
 							<groupId>org.springframework.boot</groupId>
 							<artifactId>spring-boot-autoconfigure-processor</artifactId>
-						</exclude>
-					</excludes>
+						</path>
+					</annotationProcessorPaths>
 				</configuration>
 			</plugin>
 		</plugins>
diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/annotation-processor.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/annotation-processor.adoc
index 9e2f80f33bb..02ff8371349 100644
--- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/annotation-processor.adoc
+++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/annotation-processor.adoc
@@ -9,20 +9,31 @@ The jar includes a Java annotation processor which is invoked as your project is
 [[appendix.configuration-metadata.annotation-processor.configuring]]
 == Configuring the Annotation Processor
 
-To use the processor, include a dependency on `spring-boot-configuration-processor`.
-
-With Maven the dependency should be declared as optional, as shown in the following example:
+When building with Maven, configure the compiler plugin (3.12.0 or later) to add `spring-boot-configuration-processor` to the annotation processor paths:
 
 [source,xml]
 ----
-<dependency>
-	<groupId>org.springframework.boot</groupId>
-	<artifactId>spring-boot-configuration-processor</artifactId>
-	<optional>true</optional>
-</dependency>
+<project>
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-compiler-plugin</artifactId>
+				<configuration>
+					<annotationProcessorPaths>
+						<path>
+							<groupId>org.springframework.boot</groupId>
+							<artifactId>spring-boot-configuration-processor</artifactId>
+						</path>
+					</annotationProcessorPaths>
+				</configuration>
+			</plugin>
+		</plugins>
+	</build>
+</project>
 ----
 
-With Gradle, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example:
+With Gradle, a dependency should be declared in the `annotationProcessor` configuration, as shown in the following example:
 
 [source,gradle]
 ----
@@ -64,8 +75,8 @@ You could also let the AspectJ plugin run all the processing and disable annotat
 [NOTE]
 ====
 If you are using Lombok in your project, you need to make sure that its annotation processor runs before `spring-boot-configuration-processor`.
-To do so with Maven, you can list the annotation processors in the right order using the `annotationProcessors` attribute of the Maven compiler plugin.
-If you are not using this attribute, and annotation processors are picked up by the dependencies available on the classpath, make sure that the `lombok` dependency is defined before the  `spring-boot-configuration-processor` dependency.
+To do so with Maven, list the annotation processors in the required order using the `annotationProcessors` attribute of the Maven compiler plugin.
+With Gradle, declare the dependencies in the `annotationProcessor` configuration in the required order.
 ====