Friday, May 14, 2010

Maven: How to prevent generate-sources phase executing twice

The Problem

So, you've been using Maven to build your project. You require to generate some sources, so you've figured out how to attach a plugin goal to the generate-sources lifecycle phase. This looks like it works great for a while running mvn package ....

When you decide to finally release your project using the maven-release-plugin, you notice that your source generation plugin executes twice, slowing your build and possibly even breaking it. You are now trying to figure out why your sources are being generated twice, or more specifically why the generate-sources lifecycle phase is being executed twice.

You predictably do a google search and scan the Maven issues. You find several complaints and reports open that mention a similar problem related to the maven-sources-plugin sources:jar goal causing the generate-sources phase to execute twice. Suprisingly these issues are marked fix or mention what looks like a workaround and no matter what you do, the plugin goals you have attached to the generate-sources phase are still being executed twice.

Here I attempt to explain what is really going on and provide you a real workaround for it.

History

An old relic of the maven-release-plugin is that in Maven's Super POM there is defined a profile with id of release-profile. It can be activated by the releaseProfile property being set, in this case to true. This was/is a way for the release plugin to activate the creation of source and javadoc jars for a release by default. The profile defines a maven-source-plugin and maven-javadoc-plugin configuration that attaches the jar goals of those plugins to the package phase.

So what this means is that when using the maven-release-plugin or activating the release-profile manually by setting the releaseProfile property, source:jar goal gets called during the build, which will trigger the execution of generate-sources lifecycle phase to run, even if it already did in the same build.

Changing the Maven Super POM to instead call source:jar-no-fork would fix this issue, yet changing the Super POM is not something taken lightly, and in fact may have never been proposed for this case.

Until the problem is permanently addressed, here I outline a workaround that prevents the duplicate generate-sources phase from running.

Workaround

I've tested the following instructions with Maven 2.0.11, 2.2.1 and 3.0-beta-1. The version of maven-source-plugin used was 2.1.1.

  1. First lets reproduce the problem on a sample project. Using the maven-archetype-plugin is the simplest way.
    mvn archetype:generate
    
  2. Next since the problem is that generate-sources phase gets run twice, we need a visual cue when this occurs. A simple solution is attach a message to this phase with the maven-antrun-plugin.

    Add the following to your test project pom.xml:
    <build>
      <plugins>
        <plugin>
          <artifactId>maven-antrun-plugin</artifactId>
          <version>1.3</version>
          <executions>
            <execution>
              <id>generate-sources-flag</id>
              <phase>generate-sources</phase>
              <goals>
                <goal>run</goal>
              </goals>
              <configuration>
                <tasks>
                  <echo>GENERATE SOURCES IS EXECUTING</echo>
                </tasks>
              </configuration>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>
    
  3. Next lets verify that the generate-sources phase is getting executed twice when activating the release-profile. The release profile defined in the super pom gets activated by setting the performRelease property on the cmd line.

    $mvn clean install -DperformRelease=true
    Using Java version: 1.6
    [INFO] Scanning for projects...
    [INFO]
    [INFO] ------------------------------------------------------------------------
    [INFO] Building nofork 1.0-SNAPSHOT
    [INFO] ------------------------------------------------------------------------
    [INFO]
    [INFO] --- maven-clean-plugin:2.4:clean (default-clean) @ nofork ---
    [INFO] Deleting /Users/plynch/dev/plynch/trial/nofork/target
    [INFO]
    [INFO] --- maven-antrun-plugin:1.3:run (generate-sources-flag) @ nofork ---
    [INFO] Executing tasks
         [echo] GENERATE SOURCES IS EXECUTING
    [INFO] Executed tasks
    [INFO]
    [INFO] --- maven-resources-plugin:2.4.2:resources (default-resources) @ nofork ---
    [WARNING] Using platform encoding (MacRoman actually) to copy filtered resources, i.e. build is platform dependent!
    [INFO] skip non existing resourceDirectory /Users/plynch/dev/plynch/trial/nofork/src/main/resources
    [INFO]
    [INFO] --- maven-compiler-plugin:2.3:compile (default-compile) @ nofork ---
    [WARNING] File encoding has not been set, using platform encoding MacRoman, i.e. build is platform dependent!
    [INFO] Compiling 1 source file to /Users/plynch/dev/plynch/trial/nofork/target/classes
    [INFO]
    [INFO] --- maven-resources-plugin:2.4.2:testResources (default-testResources) @ nofork ---
    [WARNING] Using platform encoding (MacRoman actually) to copy filtered resources, i.e. build is platform dependent!
    [INFO] skip non existing resourceDirectory /Users/plynch/dev/plynch/trial/nofork/src/test/resources
    [INFO]
    [INFO] --- maven-compiler-plugin:2.3:testCompile (default-testCompile) @ nofork ---
    [WARNING] File encoding has not been set, using platform encoding MacRoman, i.e. build is platform dependent!
    [INFO] Compiling 1 source file to /Users/plynch/dev/plynch/trial/nofork/target/test-classes
    [INFO]
    [INFO] --- maven-surefire-plugin:2.5:test (default-test) @ nofork ---
    [INFO] Surefire report directory: /Users/plynch/dev/plynch/trial/nofork/target/surefire-reports
    
    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    Running com.company.AppTest
    Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.029 sec
    
    Results :
    
    Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
    
    [INFO]
    [INFO] --- maven-jar-plugin:2.3:jar (default-jar) @ nofork ---
    [INFO] Building jar: /Users/plynch/dev/plynch/trial/nofork/target/nofork-1.0-SNAPSHOT.jar
    [INFO]
    [INFO] >>> maven-source-plugin:2.1.1:jar (attach-sources) @ nofork >>>
    [INFO]
    [INFO] --- maven-antrun-plugin:1.3:run (generate-sources-flag) @ nofork ---
    [INFO] Executing tasks
         [echo] GENERATE SOURCES IS EXECUTING
    [INFO] Executed tasks
    [INFO]
    [INFO] <<< maven-source-plugin:2.1.1:jar (attach-sources) @ nofork <<<
    [INFO]
    [INFO] --- maven-source-plugin:2.1.1:jar (attach-sources) @ nofork ---
    [INFO] Building jar: /Users/plynch/dev/plynch/trial/nofork/target/nofork-1.0-SNAPSHOT-sources.jar
    [INFO]
    [INFO] --- maven-javadoc-plugin:2.5:jar (attach-javadocs) @ nofork ---
    [WARNING] Source files encoding has not been set, using platform encoding MacRoman, i.e. build is platform dependent!
    Loading source files for package com.company...
    Constructing Javadoc information...
    Standard Doclet version 1.6.0_17
    Building tree for all the packages and classes...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/com/company//App.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/com/company//package-frame.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/com/company//package-summary.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/com/company//package-tree.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/constant-values.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/com/company//class-use/App.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/com/company//package-use.html...
    Building index for all the packages and classes...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/overview-tree.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/index-all.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/deprecated-list.html...
    Building index for all classes...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/allclasses-frame.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/allclasses-noframe.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/index.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/help-doc.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/stylesheet.css...
    [INFO] Building jar: /Users/plynch/dev/plynch/trial/nofork/target/nofork-1.0-SNAPSHOT-javadoc.jar
    [INFO]
    [INFO] --- maven-install-plugin:2.3:install (default-install) @ nofork ---
    [INFO] Installing /Users/plynch/dev/plynch/trial/nofork/target/nofork-1.0-SNAPSHOT.jar to /Volumes/D/m2r/com/company/nofork/1.0-SNAPSHOT/nofork-1.0-SNAPSHOT.jar
    [INFO] Installing /Users/plynch/dev/plynch/trial/nofork/target/nofork-1.0-SNAPSHOT-sources.jar to /Volumes/D/m2r/com/company/nofork/1.0-SNAPSHOT/nofork-1.0-SNAPSHOT-sources.jar
    [INFO] Installing /Users/plynch/dev/plynch/trial/nofork/target/nofork-1.0-SNAPSHOT-javadoc.jar to /Volumes/D/m2r/com/company/nofork/1.0-SNAPSHOT/nofork-1.0-SNAPSHOT-javadoc.jar
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 11.162s
    [INFO] Finished at: Thu May 13 10:39:58 EDT 2010
    [INFO] Final Memory: 13M/264M
    [INFO] ------------------------------------------------------------------------
    

    Notice our message gets printed twice, verifying the double execution. So lets proceed to fix the problem.
  4. Make the following additions to your pom.xml.
    1. First we override the super-pom maven-sources-plugin execution with id of attach-sources. This excution is what calls the source:jar goal. The special trick used here binds this execution to a non-existent lifecycle phase of DISABLE_FORKED_LIFECYCLE_MSOURCES-13 - a phase which will never be reached, thus essentially disabling this execution.

      <pluginManagement>
        <plugins>
          <plugin>
            <artifactId>maven-source-plugin</artifactId>
            <version>2.1.1</version>
            <executions>
              <!-- here we override the super-pom attach-sources executionid which
              calls sources:jar goal. That goals forks the lifecycle, causing
              the generate-sources phase to be called twice for the install goal.
              This causes any other plugin bound to the generate-sources phase to
              be called twice which usually has nasty side effects, let alone
              creating duplicate processing and longer build times. -->
              <execution>
                <id>attach-sources</id>
                <phase>DISABLE_FORKED_LIFECYCLE_MSOURCES-13</phase>
              </execution>
            </executions>
          </plugin>
        </plugins>
      </pluginManagement>
      
    2. Next, since we would still like releases using the release-profile profile to include a sources jar file, we define a new profile with the same id as the one in the super POM. This time however we bind the execution to the jar-no-fork goal, which does not trigger the generate-sources phase to be called twice.

      <profiles>
        <!-- MSOURCES-13 related workaround overriding super-pom -->
        <profile>
          <id>release-profile</id>
          <activation>
            <property>
              <name>performRelease</name>
              <value>true</value>
            </property>
          </activation>
          <build>
            <plugins>
              <plugin>
                <inherited>true</inherited>
                <artifactId>maven-source-plugin</artifactId>
                <executions>
                  <execution>
                    <id>attach-sources-no-fork</id>
                    <inherited>true</inherited>
                    <goals>
                      <goal>jar-no-fork</goal>
                    </goals>
                  </execution>
                </executions>
              </plugin>
            </plugins>
          </build>
        </profile>
      </profiles>
      
  5. Now we run the same command and verify that our solution worked.
    $mvn clean install -DperformRelease=true
    Using Java version: 1.6
    [INFO] Scanning for projects...
    [INFO]
    [INFO] ------------------------------------------------------------------------
    [INFO] Building nofork 1.0-SNAPSHOT
    [INFO] ------------------------------------------------------------------------
    [INFO]
    [INFO] --- maven-clean-plugin:2.4:clean (default-clean) @ nofork ---
    [INFO] Deleting /Users/plynch/dev/plynch/trial/nofork/target
    [INFO]
    [INFO] --- maven-antrun-plugin:1.3:run (generate-sources-flag) @ nofork ---
    [INFO] Executing tasks
         [echo] GENERATE SOURCES IS EXECUTING
    [INFO] Executed tasks
    [INFO]
    [INFO] --- maven-resources-plugin:2.4.2:resources (default-resources) @ nofork ---
    [WARNING] Using platform encoding (MacRoman actually) to copy filtered resources, i.e. build is platform dependent!
    [INFO] skip non existing resourceDirectory /Users/plynch/dev/plynch/trial/nofork/src/main/resources
    [INFO]
    [INFO] --- maven-compiler-plugin:2.3:compile (default-compile) @ nofork ---
    [WARNING] File encoding has not been set, using platform encoding MacRoman, i.e. build is platform dependent!
    [INFO] Compiling 1 source file to /Users/plynch/dev/plynch/trial/nofork/target/classes
    [INFO]
    [INFO] --- maven-resources-plugin:2.4.2:testResources (default-testResources) @ nofork ---
    [WARNING] Using platform encoding (MacRoman actually) to copy filtered resources, i.e. build is platform dependent!
    [INFO] skip non existing resourceDirectory /Users/plynch/dev/plynch/trial/nofork/src/test/resources
    [INFO]
    [INFO] --- maven-compiler-plugin:2.3:testCompile (default-testCompile) @ nofork ---
    [WARNING] File encoding has not been set, using platform encoding MacRoman, i.e. build is platform dependent!
    [INFO] Compiling 1 source file to /Users/plynch/dev/plynch/trial/nofork/target/test-classes
    [INFO]
    [INFO] --- maven-surefire-plugin:2.5:test (default-test) @ nofork ---
    [INFO] Surefire report directory: /Users/plynch/dev/plynch/trial/nofork/target/surefire-reports
    
    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    Running com.company.AppTest
    Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.026 sec
    
    Results :
    
    Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
    
    [INFO]
    [INFO] --- maven-jar-plugin:2.3:jar (default-jar) @ nofork ---
    [INFO] Building jar: /Users/plynch/dev/plynch/trial/nofork/target/nofork-1.0-SNAPSHOT.jar
    [INFO]
    [INFO] --- maven-source-plugin:2.1.1:jar-no-fork (attach-sources-no-fork) @ nofork ---
    [INFO] Building jar: /Users/plynch/dev/plynch/trial/nofork/target/nofork-1.0-SNAPSHOT-sources.jar
    [INFO]
    [INFO] --- maven-javadoc-plugin:2.5:jar (attach-javadocs) @ nofork ---
    [WARNING] Source files encoding has not been set, using platform encoding MacRoman, i.e. build is platform dependent!
    Loading source files for package com.company...
    Constructing Javadoc information...
    Standard Doclet version 1.6.0_17
    Building tree for all the packages and classes...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/com/company//App.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/com/company//package-frame.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/com/company//package-summary.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/com/company//package-tree.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/constant-values.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/com/company//class-use/App.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/com/company//package-use.html...
    Building index for all the packages and classes...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/overview-tree.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/index-all.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/deprecated-list.html...
    Building index for all classes...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/allclasses-frame.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/allclasses-noframe.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/index.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/help-doc.html...
    Generating /Users/plynch/dev/plynch/trial/nofork/target/apidocs/stylesheet.css...
    [INFO] Building jar: /Users/plynch/dev/plynch/trial/nofork/target/nofork-1.0-SNAPSHOT-javadoc.jar
    [INFO]
    [INFO] --- maven-install-plugin:2.3:install (default-install) @ nofork ---
    [INFO] Installing /Users/plynch/dev/plynch/trial/nofork/target/nofork-1.0-SNAPSHOT.jar to /Volumes/D/m2r/com/company/nofork/1.0-SNAPSHOT/nofork-1.0-SNAPSHOT.jar
    [INFO] Installing /Users/plynch/dev/plynch/trial/nofork/target/nofork-1.0-SNAPSHOT-sources.jar to /Volumes/D/m2r/com/company/nofork/1.0-SNAPSHOT/nofork-1.0-SNAPSHOT-sources.jar
    [INFO] Installing /Users/plynch/dev/plynch/trial/nofork/target/nofork-1.0-SNAPSHOT-javadoc.jar to /Volumes/D/m2r/com/company/nofork/1.0-SNAPSHOT/nofork-1.0-SNAPSHOT-javadoc.jar
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 24.278s
    [INFO] Finished at: Fri May 14 07:56:39 EDT 2010
    [INFO] Final Memory: 13M/264M
    [INFO] ------------------------------------------------------------------------
    
    As you can see, our verification message prints only once, yet we still get the sources jar - a good thing!

I recommend the above config be considered for adding to your organization's root pom. I also suggest the permanent solution to this issue is changing the Maven super pom release-profile to rely on jar-no-fork instead of jar goal.

Update

I'm occasionally asked how to make sure you still get a sources jar for your SNAPSHOT artifacts. Simple!

Just add the following to your normal <build> section of your pom, in addition to all of the above instructions:

  <plugins>
    <plugin>
      <artifactId>maven-source-plugin</artifactId>
      <executions>
        <execution>
          <id>attach-sources-no-fork</id>
          <inherited>true</inherited>
          <phase>generate-sources</phase>
          <goals>
            <goal>jar-no-fork</goal>
          </goals>
        </execution>
      </executions>
    </plugin>  
  </plugins>

7 comments:

drzewo said...

This works fine, unless you want to deploy your snapshot artifacts (apart from the releases) to the repository along with accompanying sources. Using your workaround results in leaving maven-source-plugin enabled only for the releases :/

Anonymous said...

using 2.0.2 version of maven-source-plugin with jar goal, deploys only once.

Anonymous said...

I would like to know if with Maven 3.0.2 it is necessary to do the same?

Tero Keski-Valkama said...

I had a similar issue with JPA 2 Metamodel automatic generation. Running Maven twice without clean caused the already compiled metamodel classes to be in the target directory, and the generate-sources phase would generate new Java-files for them, causing duplicate class errors.

The workaround is as follows:

<plugins>
<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.4.1</version>
<executions>
<execution>
<id>default-clean</id>
<phase>clean</phase>
<goals>
<goal>clean</goal>
</goals>
</execution>
<!-- Added to clean up any precompiled classes before generating sources to prevent duplicate class errors. -->
<execution>
<id>clean-before-generate-sources</id>
<phase>generate-sources</phase>
<goals>
<goal>clean</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>

Anonymous said...

How about changing phase from generate-source to compile. So that sources will be generated only at the time of compilation?

Anonymous said...

How can you ensure the profile dependent code is run before the main code?

Malte Finsterwalder said...

Thanks! Fixed my build!
I have maven 3.1.0 with all the current plugins (maven-release-plugin 2.4.1; maven-resources-plugin 2.6)

Post a Comment