Initial log4j-docgen usage

apache · Feb 21, 2024 · b0f4e46 · b0f4e46
1 parent b4ef5dd
commit b0f4e46
Show file tree

Hide file tree

Showing 41 changed files with 674 additions and 392 deletions.
diff --git a/log4j-1.2-api/.log4j-plugin-processing-activator b/log4j-1.2-api/.log4j-plugin-processing-activator
@@ -0,0 +1 @@
+This file is here to activate the `plugin-processing` Maven profile.
diff --git a/log4j-1.2-api/pom.xml b/log4j-1.2-api/pom.xml
@@ -16,17 +16,21 @@
   ~ limitations under the License.
   -->
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+
   <modelVersion>4.0.0</modelVersion>
+
   <parent>
     <groupId>org.apache.logging.log4j</groupId>
     <artifactId>log4j</artifactId>
     <version>${revision}</version>
     <relativePath>../log4j-parent</relativePath>
   </parent>
+
   <artifactId>log4j-1.2-api</artifactId>
-  <packaging>jar</packaging>
+
   <name>Apache Log4j 1.x Compatibility API</name>
   <description>The Apache Log4j 1.x Compatibility API</description>
+
   <properties>
     <module.name>org.apache.log4j</module.name>
 
@@ -45,6 +49,7 @@
     <Fragment-Host>org.apache.logging.log4j.core</Fragment-Host>
     <!-- we have an `bnd.bnd` file to override the parent's defaults -->
   </properties>
+
   <dependencies>
     <!-- Used for JMS appenders (needs an implementation of course) -->
     <dependency>
@@ -138,27 +143,6 @@
     </dependency>
   </dependencies>
 
-  <build>
-    <plugins>
-
-      <!-- Enable Log4j plugin processing -->
-      <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
-        <artifactId>maven-compiler-plugin</artifactId>
-        <configuration>
-          <annotationProcessorPaths combine.children="append">
-            <path>
-              <groupId>org.apache.logging.log4j</groupId>
-              <artifactId>log4j-core</artifactId>
-              <version>${project.version}</version>
-            </path>
-          </annotationProcessorPaths>
-        </configuration>
-      </plugin>
-
-    </plugins>
-  </build>
-
   <profiles>
 
     <!-- Fixes incompatible with Java 8 -->

diff --git a/log4j-cassandra/.log4j-plugin-processing-activator b/log4j-cassandra/.log4j-plugin-processing-activator
@@ -0,0 +1 @@
+This file is here to activate the `plugin-processing` Maven profile.
diff --git a/log4j-cassandra/pom.xml b/log4j-cassandra/pom.xml
@@ -16,7 +16,9 @@
   ~ limitations under the License.
   -->
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
   <modelVersion>4.0.0</modelVersion>
+
   <parent>
     <groupId>org.apache.logging.log4j</groupId>
     <artifactId>log4j</artifactId>
@@ -25,8 +27,10 @@
   </parent>
 
   <artifactId>log4j-cassandra</artifactId>
+
   <name>Apache Log4j Cassandra</name>
   <description>Cassandra appender for Log4j.</description>
+
   <properties>
 
     <!--
@@ -108,26 +112,4 @@
     </dependency>
   </dependencies>
 
-  <build>
-    <plugins>
-      <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
-        <artifactId>maven-compiler-plugin</artifactId>
-        <configuration>
-          <!--
-            ~ Modules that contain `log4j-core` plugins, must be compiled with:
-            ~
-            ~   org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor
-            -->
-          <annotationProcessorPaths combine.children="append">
-            <path>
-              <groupId>org.apache.logging.log4j</groupId>
-              <artifactId>log4j-core</artifactId>
-              <version>${project.version}</version>
-            </path>
-          </annotationProcessorPaths>
-        </configuration>
-      </plugin>
-    </plugins>
-  </build>
 </project>
diff --git a/log4j-core-java9/pom.xml b/log4j-core-java9/pom.xml
@@ -30,6 +30,8 @@
   <properties>
     <maven.compiler.release>9</maven.compiler.release>
     <maven.deploy.skip>true</maven.deploy.skip>
+    <maven.install.skip>true</maven.install.skip>
+    <sign.skip>true</sign.skip>
   </properties>
   <dependencies>
     <!-- Naturally, all implementations require the log4j-api JAR -->

diff --git a/log4j-core-test/.log4j-plugin-processing-activator b/log4j-core-test/.log4j-plugin-processing-activator
@@ -0,0 +1 @@
+This file is here to activate the `plugin-processing` Maven profile.
diff --git a/log4j-core-test/pom.xml b/log4j-core-test/pom.xml
@@ -16,7 +16,9 @@
   ~ limitations under the License.
   -->
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+
   <modelVersion>4.0.0</modelVersion>
+
   <parent>
     <groupId>org.apache.logging.log4j</groupId>
     <artifactId>log4j</artifactId>
@@ -25,9 +27,10 @@
   </parent>
 
   <artifactId>log4j-core-test</artifactId>
-  <packaging>jar</packaging>
+
   <name>Apache Log4j Core Tests</name>
   <description>The Apache Log4j Implementation Tests</description>
+
   <properties>
     <!-- Ignore less important (high rank) bugs for test artifacts -->
     <spotbugs.maxRank>9</spotbugs.maxRank>
@@ -351,21 +354,6 @@
   <build>
     <plugins>
 
-      <!-- Enable Log4j plugin processing -->
-      <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
-        <artifactId>maven-compiler-plugin</artifactId>
-        <configuration>
-          <annotationProcessorPaths combine.children="append">
-            <path>
-              <groupId>org.apache.logging.log4j</groupId>
-              <artifactId>log4j-core</artifactId>
-              <version>${project.version}</version>
-            </path>
-          </annotationProcessorPaths>
-        </configuration>
-      </plugin>
-
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-surefire-plugin</artifactId>

diff --git a/log4j-core/pom.xml b/log4j-core/pom.xml
@@ -16,20 +16,28 @@
   ~ limitations under the License.
   -->
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+
   <modelVersion>4.0.0</modelVersion>
+
   <parent>
     <groupId>org.apache.logging.log4j</groupId>
     <artifactId>log4j</artifactId>
     <version>${revision}</version>
     <relativePath>../log4j-parent</relativePath>
   </parent>
+
   <artifactId>log4j-core</artifactId>
-  <packaging>jar</packaging>
+
   <name>Apache Log4j Core</name>
   <description>The Apache Log4j Implementation</description>
+
   <properties>
+
     <javadoc.skip>false</javadoc.skip>
 
+    <!-- Tests are located elsewhere, no need to do any processing for the `src/test` directory: -->
+    <maven.test.skip>true</maven.test.skip>
+
     <!--
       ~ OSGi and JPMS options
       -->
@@ -82,6 +90,7 @@
       javax.mail.api;substitute="javax.mail-api";transitive=false;static=true
     </bnd-extra-module-options>
   </properties>
+
   <dependencies>
     <dependency>
       <groupId>javax.activation</groupId>
@@ -200,13 +209,16 @@
       <optional>true</optional>
     </dependency>
   </dependencies>
+
   <build>
     <plugins>
 
       <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>build-helper-maven-plugin</artifactId>
         <executions>
+
+          <!-- Add Java 9+ code for the MRJ -->
           <execution>
             <id>add-source</id>
             <goals>
@@ -219,43 +231,82 @@
               </sources>
             </configuration>
           </execution>
+
+          <!-- Attach the generated `log4j-plugins.xml` -->
+          <execution>
+            <id>attach-plugin-descriptor</id>
+            <goals>
+              <goal>attach-artifact</goal>
+            </goals>
+            <phase>package</phase>
+            <configuration>
+              <artifacts>
+                <artifact>
+                  <file>${project.build.directory}/log4j-plugins.xml</file>
+                  <type>xml</type>
+                  <classifier>log4j-plugins</classifier>
+                </artifact>
+              </artifacts>
+            </configuration>
+          </execution>
+
         </executions>
       </plugin>
 
+      <!-- We can't use `plugin-processing` Maven profile activated by `.log4j-plugin-processing-activator` file, because...
+           `log4j-core` contains `PluginProcessor`, that is responsible for generating `META-INF/org/apache/.../Log4j2Plugins.dat` from `@Plugin`-annotated members.
+           `log4j-core` also contains `@Plugin`-annotated members too.
+           That is, we need `log4j-core` to build `log4j-core`.
+           To work around this chicken-and-egg problem, we build as follows:
+
+           1. Compile sources using the `default-compile` default compilation execution.
+              This will generate the `PluginProcessor` class.
+
+           2. Make a second compilation pass using the generated `PluginProcessor`. -->
       <plugin>
         <artifactId>maven-compiler-plugin</artifactId>
-        <configuration>
-          <annotationProcessorPaths combine.self="override" />
-        </configuration>
         <executions>
+
+          <!-- Compile sources as usual -->
           <execution>
-            <!-- disable annotation processing for first pass -->
             <id>default-compile</id>
             <configuration>
-              <annotationProcessorPaths>
+              <annotationProcessorPaths combine.children="append">
+                <!-- `org.apache.logging.log4j.docgen.processor.DescriptorGenerator` for generating `log4j-plugins.xml`: -->
                 <path>
-                  <groupId>com.google.errorprone</groupId>
-                  <artifactId>error_prone_core</artifactId>
-                  <version>${error-prone.version}</version>
+                  <groupId>org.apache.logging.log4j</groupId>
+                  <artifactId>log4j-docgen</artifactId>
+                  <version>${log4j-docgen.version}</version>
                 </path>
               </annotationProcessorPaths>
+              <compilerArgs combine.children="append">
+                <!-- Provide `org.apache.logging.log4j.docgen.processor.DescriptorGenerator` arguments: -->
+                <arg>-Alog4j.docgen.descriptorFilePath=${project.build.directory}/log4j-plugins.xml</arg>
+                <arg>-Alog4j.docgen.groupId=${project.groupId}</arg>
+                <arg>-Alog4j.docgen.artifactId=${project.artifactId}</arg>
+                <arg>-Alog4j.docgen.version=${project.version}</arg>
+                <arg>-Alog4j.docgen.description=${project.description}</arg>
+              </compilerArgs>
             </configuration>
           </execution>
+
+          <!-- Process sources using `PluginProcessor` to generate `META-INF/org/apache/.../Log4j2Plugins.dat` -->
           <execution>
-            <!-- then do a processing-only pass to generate plugins .dat file -->
             <id>process-plugins</id>
             <goals>
               <goal>compile</goal>
             </goals>
             <phase>process-classes</phase>
             <configuration>
+              <annotationProcessorPaths combine.self="override" />
               <annotationProcessors>
                 <processor>org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor</processor>
               </annotationProcessors>
               <compilerArgs combine.self="override" />
               <proc>only</proc>
             </configuration>
           </execution>
+
         </executions>
       </plugin>
 
@@ -291,4 +342,5 @@
 
     </plugins>
   </build>
+
 </project>
diff --git a/.../src/main/java/org/apache/logging/log4j/core/appender/rolling/action/ScriptCondition.java b/.../src/main/java/org/apache/logging/log4j/core/appender/rolling/action/ScriptCondition.java
@@ -89,8 +89,8 @@ public List<PathWithAttributes> selectFilesToDelete(
      *            <li>pathList - a {@code java.util.List} containing {@link org.apache.logging.log4j.core.appender.rolling.action.PathWithAttributes} objects. (The script is
      *            free to modify and return this list.)</li>
      *            <li>substitutor - a {@link org.apache.logging.log4j.core.lookup.StrSubstitutor} that can be used to look up variables embedded in the base
-     *            dir or other properties
-     *            <li>statusLogger - the {@link StatusLogger} that can be used to log events during script execution
+     *            dir or other properties</li>
+     *            <li>statusLogger - the {@link StatusLogger} that can be used to log events during script execution</li>
      *            <li>any properties declared in the configuration</li>
      *            </ul>
      * @param configuration the configuration

diff --git a/log4j-couchdb/.log4j-plugin-processing-activator b/log4j-couchdb/.log4j-plugin-processing-activator
@@ -0,0 +1 @@
+This file is here to activate the `plugin-processing` Maven profile.
diff --git a/log4j-couchdb/pom.xml b/log4j-couchdb/pom.xml
@@ -16,7 +16,9 @@
   ~ limitations under the License.
   -->
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
   <modelVersion>4.0.0</modelVersion>
+
   <parent>
     <groupId>org.apache.logging.log4j</groupId>
     <artifactId>log4j</artifactId>
@@ -25,8 +27,10 @@
   </parent>
 
   <artifactId>log4j-couchdb</artifactId>
+
   <name>Apache Log4j CouchDB</name>
   <description>CouchDB appender for Log4j.</description>
+
   <properties>
 
     <!--
@@ -81,26 +85,4 @@
     </dependency>
   </dependencies>
 
-  <build>
-    <plugins>
-      <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
-        <artifactId>maven-compiler-plugin</artifactId>
-        <configuration>
-          <!--
-            ~ Modules that contain `log4j-core` plugins, must be compiled with:
-            ~
-            ~   org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor
-            -->
-          <annotationProcessorPaths combine.children="append">
-            <path>
-              <groupId>org.apache.logging.log4j</groupId>
-              <artifactId>log4j-core</artifactId>
-              <version>${project.version}</version>
-            </path>
-          </annotationProcessorPaths>
-        </configuration>
-      </plugin>
-    </plugins>
-  </build>
 </project>
diff --git a/log4j-docker/.log4j-plugin-processing-activator b/log4j-docker/.log4j-plugin-processing-activator
@@ -0,0 +1 @@
+This file is here to activate the `plugin-processing` Maven profile.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		This file is here to activate the `plugin-processing` Maven profile.