My project can generate some additional help files automatically from the source code.
How do I have maven install these files into the generated JavaDoc package?
I couldn't fingure out how to have Maven:
run some class to generate the additional documentation, e.g. compile and launch src/main/java/mypackage/ListOptions.java aka mypackage.ListOptions to produce a list of all available options/modules/examples/etc. .
install the output files (I only could get Maven to install files from src/main/javadoc/resources into the site/apidocs/resources subfolder; but I want this documentation to live in the top level site/apidocs folder; more precisely I don't care about the site part at all, but about having a complete documetation in mypackage-0.1.0-SNAPSHOT-javadoc.jar; including non-Javadoc-generated auxillary information linked from javadoc).
Minimal example - Plugin configuration for maven:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
<configuration>
<docfilessubdirs>true</docfilessubdirs>
</configuration>
</plugin>
Directory layout:
./pom.xml
./src/main/java/foobar/GenerateNonstatic.java
./src/main/javadoc/staticfile.js
./src/main/javadoc/resources/insubfolder.png
mvn package produces: javadoc in ./target/apidocs and ./target/foobar-0.0.1-SNAPSHOT-javadoc.jar. The file target/apidocs/resources/insubfolder.png ends up in folder target/apidocs/resources (and the .jar), but the staticfile.js is not installed.
How to run GenerateNonstatic.java to have the output included in the javadoc .jar is unclear to me. I don't see a hook to have exec:exec it run after javadoc, and before ./target/foobar-0.0.1-SNAPSHOT-javadoc.jar is built...
Long story, short answer. Both the javadoc:javadoc and javadoc:jar mojos have their drawbacks. The first is meant to build the javadoc for reporting; the latter will build the javadoc (into a different directory) and produce a jar package.
Some of the suggested answers did not work well because of this - they would execute javadoc twice.
But I noticed that javadoc does not care if the folder already exists or contains files.
So my solution is simple: generate the desired additional files in prepare-package, and the regular javadoc:jar task adds the regular javadoc and pacakges it nicely.
This will work as long as you don't intend to modify files generated by javadoc (which I, fortunately, don't - I only add additional documentation.
The resulting pom.xml is like this:
<plugins>
<!-- copy additional javadoc resources -->
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>2.7</version>
<executions>
<execution>
<id>copy-resources</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/apidocs</outputDirectory>
<resources>
<resource>
<directory>${basedir}/src/main/javadoc</directory>
<excludes>
<!-- overview.html is integrated by javadoc -->
<exclude>${basedir}/src/main/javadoc/overview.html</exclude>
</excludes>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
<!-- Generate additional files for javadoc -->
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>1.3.2</version>
<executions>
<execution>
<id>generate-extra-javadoc</id>
<phase>prepare-package</phase>
<goals>
<!-- java is okay, but you only can have one -->
<goal>exec</goal>
</goals>
<configuration>...</configuration>
</execution>
</executions>
</plugin>
<!-- Build JavaDoc -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.1</version>
<executions>
<execution>
<id>attach-javadocs</id>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
Eric,
If you are uncomfortable modifying the javadoc executable, another option is to break apart your javadoc call into 2 separate steps (javadoc and jar) and make your call between them by manipulating the Maven build lifecycle via <phase> tag:
phase: generate-sources => maven-javadoc-plugin:javadoc
phase: compile => exec-maven-plugin:java
phase: package => maven-javadoc-plugin:jar
note: use exec:java, not exec:exec to run java classes
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<executions>
<execution>
<id>generate-javadocs</id>
<phase>generate-sources</phase>
<goals>
<goal>javadoc</goal>
</goals>
</execution>
<execution>
<id>attach-javadocs</id>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>1.3.2</version>
<executions>
<execution>
<id>generate-nonstatic-javadocs</id>
<phase>compile</phase>
<goals>
<goal>java</goal>
</goals>
<configuration>
<mainClass>foobar.GenerateNonstatic</mainClass>
</configuration>
</execution>
</executions>
</plugin>
To answer your first question: Run a commandline command with the Exec-Maven-Plugin or use the Maven-Ant-Plugin and embed custom tasks.
Eric,
Your example is indeed helpful. Please do try to always include concrete examples as much as possible when asking the question.
The simplest approach would be to write your own Alternate Javadoc tool and pass that into Maven via the <javadocExecutable> tag. This example comes from the link above:
<project>
...
<reporting> (or <build>)
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.1</version>
<configuration>
<javadocExecutable>C:\jdk1.6.0\bin\javadoc.exe</javadocExecutable>
...
</configuration>
</plugin>
...
</plugins>
</reporting> (or </build>)
...
</project>
Hope that helps.
Related
I have a pom file that correctly generates the grpc and protobuf source files I need in target/generated-sources when run from the command line. But when I build in vscode those directories are empty and references to the protobufs are undefined. Here's the section of my pom file that builds the grpc source.
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<version>0.5.0</version>
<configuration>
<protocArtifact>com.google.protobuf:protoc:3.2.0:exe:${os.detected.classifier}</protocArtifact>
<pluginId>grpc-java</pluginId>
<pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
</configuration>
<executions>
<execution>
<goals>
<goal>compile</goal>
<goal>compile-custom</goal>
</goals>
</execution>
</executions>
</plugin>
I added the following based on what I read in other posts to prevent vscode/eclipse from removing the generated source directories
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<executions>
<execution>
<id>add-source</id>
<phase>generate-sources</phase>
<goals>
<goal>add-source</goal>
</goals>
<configuration>
<sources>
<source>target/generated-sources/protobuf/grpc-java</source>
<source>/target/generated-sources/protobuf/java</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
When vs-code builds, the target generated-source directories are there, but there is no source in them. We had a similar problem with intellij but were able to work around it by running the maven command line build before opening intellij but that does not seem to work for vscode.
Use protoc-jar-maven-plugin instead.
Sample usage please view protoc-jar-maven-plugin.
Say I have the following package structure:
When I generate the javadoc, I will get the following under index.html:
I find that inconvenient for two reasons:
You can't really explore the classes by package, since all the list is flat (it's not like navigating a tree of folders)
The package-info.java only appears at the level of com.company.framework package (which contains no class) and the other two sub-packages which actually contain classes have an empty description.
I would like to somehow "aggregate" (or collapse?) the package so that I can get only com.company.framework, and then expanding this I can get just a and b.
Is that achievable using Javadoc?
My setup if needed:
maven plugin:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.1.0</version>
<configuration>
<javadocExecutable>${java.home}/bin/javadoc</javadocExecutable>
<overview>${basedir}/javadoc/overview.html</overview>
</configuration>
<executions>
<execution>
<id>aggregate</id>
<goals>
<goal>aggregate</goal>
</goals>
<configuration>
<reportOutputDirectory>${basedir}/framework-doc/</reportOutputDirectory>
</configuration>
</execution>
</executions>
</plugin>
The command I use to build the javadoc:
mvn javadoc:aggregate
Finally, the right place to look for was the Grouping Packages functionality of the javadoc maven plugin.
Official documentation: here
Sample:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.1.0</version>
<configuration>
<javadocExecutable>${java.home}/bin/javadoc</javadocExecutable>
<overview>${basedir}/javadoc/overview.html</overview>
<groups>
<group>
<title>Package A</title>
<packages>com.company.framework.a*</packages>
</group>
</groups>
</configuration>
<executions>
<execution>
<id>aggregate</id>
<goals>
<goal>aggregate</goal>
</goals>
<configuration>
<reportOutputDirectory>${basedir}/framework-doc/</reportOutputDirectory>
</configuration>
</execution>
</executions>
</plugin>
I am having problems building a maven project. I have a requirement to produce deterministic jar files, which must be binary-consistent across different builds and versions, in case there are no source code changes in between these builds. For the purpose, I have used this article for guidance.
I have successfully managed to build my jars and they are consistent up to my requirements. Here is my configuration:
<plugin>
<artifactId>maven-antrun-plugin</artifactId>
<version>1.7</version>
<executions>
<execution>
<id>step-1-remove-timestamp</id>
<phase>prepare-package</phase>
<configuration>
<target>
<touch datetime="01/01/2015 00:10:00 am">
<fileset dir="target/classes"/>
<fileset dir="src"/>
</touch>
</target>
</configuration>
<goals>
<goal>run</goal>
</goals>
</execution>
<execution>
<id>step-3-rename-assembly</id>
<phase>package</phase>
<configuration>
<target>
<copy file="${project.build.directory}/${project.build.finalName}-deterministic.zip"
tofile="${project.build.directory}/${project.build.finalName}.jar"/>
</target>
</configuration>
<goals>
<goal>run</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<version>2.2.1</version>
<configuration>
<descriptors>
<descriptor>src/main/assembly/zip.xml</descriptor>
</descriptors>
</configuration>
<executions>
<execution>
<id>step-2-make-assembly</id>
<phase>prepare-package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
In the above code I build and package the jar as a zip, then copy the zip over the expected jar artifact.
The problem with the above, is that maven still executes the maven-jar-plugin, so the manually assembled jar is overwritten by the one of the maven-jar-plugin. I do not want to use this jar, since it is not consistent with my requirements.
So, I have disabled the maven-jar-plugin execution, by explicitly setting it to run for an invalid phase, like below: (saw that from other posts here)
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>2.5</version>
<executions>
<execution>
<id>default-jar</id>
<phase>never</phase>
<configuration>
<finalName>unwanted</finalName>
<classifier>unwanted</classifier>
</configuration>
</execution>
</executions>
</plugin>
Everything seems fine, until I discovered my main jar artifact is never installed in the .m2 directory. To correct this, I also added the maven-helper-plugin so that I manually attach any artifacts I produce from the assembler plugin:
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>1.9.1</version>
<executions>
<execution>
<id>attach-instrumented-jar</id>
<phase>verify</phase>
<goals>
<goal>attach-artifact</goal>
</goals>
<configuration>
<artifacts>
<artifact>
<file>${project.build.directory}/${project.build.finalName}.jar</file>
<type>jar</type>
</artifact>
</artifacts>
</configuration>
</execution>
</executions>
</plugin>
This leads to an error I am unable to solve:
[ERROR] Failed to execute goal org.codehaus.mojo:build-helper-maven-plugin:1.9.1:attach-artifact (attach-instrumented-jar) on project my-project: Execution attach-instrumented-jar of goal org.codehaus.mojo:build-helper-maven-plugin:1.9.1:attach-artifact failed: For artifact {full-name-of-my-project.jar}: An attached artifact must have a different ID than its corresponding main artifact. -> [Help 1]
Is there a way to overcome this issue? I've checked for solutions, and most recommend using classifiers, but I want to install the main artifact as would the maven-jar-plugin. Other software we are developing will require the standard jar dependency, and we want to avoid complicating our setup by introducing classifiers unreasonably.
After some more trial and failures I happened to come with a working solution.
I am posting it here with the hopes to either be useful, or to have any issues with pointed to me, as I am not really confident if this is a reliable approach.
So, the error I received
An attached artifact must have a different ID than its corresponding main artifact.
meant to me that I cannot manually install "again" the main artifact. Since that artifact is not produced anymore by the maven-jar-plugin, it never gets scheduled for installation even if the file is present (the antrun copy task produces a jar with the same name).
Surprisingly, it needed a few little tricks to make this work again:
Re-enabled the maven-jar-plugin as it should be:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>2.5</version>
<executions>
<execution>
<id>default-jar</id>
<phase>package</phase>
</execution>
</executions>
</plugin>
This will produce the standard jar on the package phase, and most importantly, makes maven aware for it to be installed during the install phase.
Tweak the maven-antrun-plugin copy tasks to overwrite the already produced jar with the deterministic zip. The setup is nearly identical as in my question, so I am only adding the differences:
<plugin>
<artifactId>maven-antrun-plugin</artifactId>
<version>1.7</version>
<executions>
<execution>...</execution>
<execution>
<id>step-3-rename-assembly-and-sources</id>
<phase>package</phase>
<configuration>
<target>
<copy file="${project.build.directory}/${project.build.finalName}-deterministic.zip"
tofile="${project.build.directory}/${project.build.finalName}.jar"
overwrite="true"/>
</target>
</configuration>
</execution>
. . .
</executions>
</plugin>
The copy operation now has overwrite="true" specified. Originally, the copy operation seemed to ignore files in the destination if they already exist, and what happened is that the maven-jar-plugin had already produced the default jar artifact when the copying occured. With this option set, the maven-antrun-plugin now overrides the former jar with the deterministic one, and the latter becomes a subject of the maven install phase.
Removed the setup from the build-helper-maven-plugin, so that the main jar artifact is not copied a second time:
<artifact>
<file>${project.build.directory}/${project.build.finalName}.jar</file>
<type>jar</type>
</artifact>
That's it, the correct jar is installed in the .m2 dir.
In case you don't have a plugin to create and attach main artifact for you, there is a more generic solution with Groovy Maven plugin:
<plugin>
<groupId>org.codehaus.gmaven</groupId>
<artifactId>groovy-maven-plugin</artifactId>
<version>2.1</version>
<executions>
<execution>
<id>set-main-artifact</id>
<phase>package</phase>
<goals>
<goal>execute</goal>
</goals>
<configuration>
<source>
project.artifact.setFile(new File(project.build.directory, project.build.finalName + ".zip"))
</source>
</configuration>
</execution>
</executions>
</plugin>
Inspired by post https://stackoverflow.com/a/31513690/2053580 many thanks to https://stackoverflow.com/users/1314907/lukasz-guminski
I'd like to use the Maven Enforcer plugin to check to see if I have duplicate classes on my path.
I've tried the example from here.
But when I run it like this:
mvn enforcer:enforce
I get this error:
Failed to execute goal
org.apache.maven.plugins:maven-enforcer-plugin:1.0.1:enforce
(default-cli) on project datapopulator: The parameters 'rules' for
goal org.apache.maven.plugins:maven-enforcer-plugin:1.0.1:enforce are
missing or invalid
Is there a way to use this correctly?
EDIT #1
If changing my config to this:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>1.0.1</version>
<executions>
<execution>
<id>enforce-versions</id>
<goals>
<goal>enforce</goal>
</goals>
<configuration>
<rules>
<AlwaysPass />
</rules>
<fail>true</fail>
</configuration>
</execution>
</executions>
</plugin>
Produces the same error.
The reason why your first version did not work is because there is a difference between a plug-in configuration inside the execution tag and a plug-in configuration outside the execution tag. The execution is only used when your plug-in is triggered by a special phase of the complete Maven build.
The Maven guide to configuration explains it better:
Configurations inside the tag differ from those that are outside in that they cannot be used from a direct command line invocation. Instead they are only applied when the lifecycle phase they are bound to are invoked. Alternatively, if you move a configuration section outside of the executions section, it will apply globally to all invocations of the plugin.
Try this, moving the configuration outside executions, so it isn't bound to the life cycle phase.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>1.0.1</version>
<executions>
<execution>
<id>enforce-versions</id>
<goals>
<goal>enforce</goal>
</goals>
</execution>
</executions>
<configuration>
<rules>
<AlwaysPass />
</rules>
<fail>true</fail>
</configuration>
</plugin>
Now when you do mvn enforcer:enforce, it picks the rules from your pom.xml.
See these answers
You can use the special default command line execution id, default-cli to invoke it (see Maven Docs), see my example below. This works at least with 3.1.1 and the article cited says it should work with 2.2.0+
mvn enforcer:enforce
However if you are using above Maven 3.1.1 (I can confirm it works in 3.3.3 with enforcer v 1.4.1) you can specify the execution id you wish using the new # syntax (see Maven JIRA and the answers above);
e.g. for the example below use
mvn enforcer:enforce#dependency-convergence
Here's a snippet from my pom;
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>1.4.1</version>
<executions>
<execution>
<id>dependency-convergence</id>
<phase>install</phase>
<goals>
<goal>enforce</goal>
</goals>
<configuration>
<rules>
<DependencyConvergence />
</rules>
<fail>true</fail>
</configuration>
</execution>
<execution>
<id>default-cli</id>
<goals>
<goal>enforce</goal>
</goals>
<configuration>
<rules>
<DependencyConvergence/>
</rules>
<fail>true</fail>
</configuration>
</execution>
</executions>
</plugin>
...
I don't know why it won't work with the config being in an execution, but this worked for me:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>1.0</version>
<configuration>
<rules>
<banDuplicateClasses>
<findAllDuplicates>true</findAllDuplicates>
</banDuplicateClasses>
</rules>
<fail>false</fail>
</configuration>
<dependencies>
<dependency>
<groupId>org.codehaus.mojo</groupId>
<artifactId>extra-enforcer-rules</artifactId>
<version>1.0-alpha-1</version>
</dependency>
</dependencies>
</plugin>
What's the best way to setup the eclipse project compiler configuration for Java 6 annotation processors?
My solution is to setup the org.eclipse.jdt.apt.core.prefs and factorypath files manually. This is a bit cumbersome:
Reference the processor jar in the factorypath file
Configure the eclipse annotation processor output directory (org.eclipse.jdt.apt.genSrcDir property in org.eclipse.jdt.apt.core.prefs)
Add the eclipse annotation processor output directory as source folder
One problem is that eclipse generated sources will be compiled with maven. Only maven clean compile is reliable as it removes the eclipse generated source files. (Eclipse and javac generated source files could be out of sync.)
Is there are better solution to configure maven without eclipse generated source files at the maven source path?
<project>
<properties>
<eclipse.generated.src>${project.build.directory}/eclipse</eclipse.generated.src>
</properties>
<build>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>1.4</version>
<executions>
<execution>
<id>add-source</id>
<phase>generate-sources</phase>
<goals> <goal>add-source</goal> </goals>
<configuration>
<sources>
<source>${eclipse.generated.src}</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-eclipse-plugin</artifactId>
<configuration>
<additionalConfig>
<file> <name>.factorypath</name>
<content><![CDATA[<factorypath>
<factorypathentry kind="VARJAR" id="M2_REPO/processor/processor.jar" enabled="true" runInBatchMode="false"/>
</factorypath>
]]> </content>
</file>
<file>
<name>.settings/org.eclipse.jdt.apt.core.prefs</name>
<content><![CDATA[
eclipse.preferences.version=1
org.eclipse.jdt.apt.aptEnabled=true
org.eclipse.jdt.apt.genSrcDir=${eclipse.generated.src}
org.eclipse.jdt.apt.reconcileEnabled=true
]]> </content>
</file>
</additionalConfig>
</configuration>
</plugin>
</plugins>
</build>
</project>
Update: You could try using the apt-maven-plugin. It currently provides three goals:
apt-process Executes apt on project sources.
apt:test-process Executes apt on project test sources.
apt:eclipse Generates Eclipse files for apt integration.
You can configure the goals to run as part of your build as follows:
<build>
...
<plugins>
...
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>apt-maven-plugin</artifactId>
<version>1.0-alpha-2</version>
<executions>
<execution>
<goals>
<goal>process</goal>
<goal>test-process</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
...
</build>
By default the output directory is set to ${project.build.directory}/generated-sources/apt,
There is an open Jira against the compiler plugin to add APT support for Java 6, you can go and vote for it if this is something you want to to see in future versions.
I am using http://code.google.com/p/maven-annotation-plugin/ wich is simpler to configure. You can use it in two ways:
generate sources during compilation (configuration below)
generate sources "by hand" to src/main/generated and keep them on SCM
<plugin>
<groupId>org.bsc.maven</groupId>
<artifactId>maven-processor-plugin</artifactId>
<executions>
<execution>
<id>process</id>
<goals>
<goal>process</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<compilerArguments>-encoding ${project.build.sourceEncoding}</compilerArguments>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.bsc.maven</groupId>
<artifactId>maven-processor-plugin</artifactId>
<executions>
<execution>
<id>process-test</id>
<goals>
<goal>process-test</goal>
</goals>
<phase>generate-test-sources</phase>
<configuration>
<compilerArguments>-encoding ${project.build.sourceEncoding}</compilerArguments>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.3.1</version>
<configuration>
<source>1.6</source>
<target>1.6</target>
<encoding>${project.build.sourceEncoding}</encoding>
<!-- Disable annotation processors during normal compilation -->
<compilerArgument>-proc:none</compilerArgument>
</configuration>
</plugin>
There is a simpler solution in Eclipse Juno (I'm not sure about previous versions). In Preferences / Maven / Annotation Processing there are three modes for annotation processing. It is disabled by default, but I've tested both other options and worked like a charm for me. This way, you don't need to configure APT processing for every project or modify its pom.xml.