Maven Shade plugin: ensure your sources are relocated too!

Maven Shade plugin is an awesome piece of code enabling to build fatjar, relocate code and transform contents. However, it is quite often configured too quickly and the sources don't match the bundled code.

One common case is the following one:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.2.1</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>shade</goal>
      </goals>
      <configuration>
        <relocations>
          <relocation>
            <pattern>org.apache.superlib</pattern>
            <shadedPattern>com.company.coolstuff</shadedPattern>
          </relocation>
        </relocations>
      </configuration>
    </execution>
  </executions>
</plugin>

In this snippet, we want to include the project dependencies and relocate org.apache.superlib in com.company.coolstuff. This is great and will work smoothly. However, if you open the sources jar generated by maven-sources-plugin for example, then the content will not exactly match that.

There are a few options to let the user still get the sources properly in his IDE but the simplest is to enable the dedicated option: shadeSourcesContent.

After the update it should look like:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.2.1</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>shade</goal>
      </goals>
      <configuration>
        <shadeSourcesContent>true</shadeSourcesContent>
        <relocations>
          <relocation>
            <pattern>org.apache.superlib</pattern>
            <shadedPattern>com.company.coolstuff</shadedPattern>
          </relocation>
        </relocations>
      </configuration>
    </execution>
  </executions>
</plugin>

With this little - too much unknown - option, the shade plugin will also create a shaded sources jar attached to the project and your consumers/users will be happy to be able to debug without having to even notice you shaded a library :).

What is important in this post is not really the fact Maven Shade plugin added an awesome option (was ~2 years ago but if you used maven shade before, the same output was quite some work to do) but more that each time you do a choice in a library, you must always keep in mind your users and try to see how they will use your deliveries. It is the only important outcome at the end.