Tiles Maven Plugin - Version 1.8

Overview

The tiles-maven-plugin is a Maven Plugin that tries to bringing the composition that is available to dependencies to the parent structure as well.

Build Status

How do I make a Maven Tile?

Tiles are plain Maven pom artifacts which contain parts of a Maven POM; every tile can contain

• build data, for example the license tags that a company wants to report on all their artifacts

• build aspects, for example the configurations of a plugin, such as Groovy, Java or Clojure.

• release aspects, for example the distribution management section

• references to other tiles

This could, for example, allow you to have build aspects consistent across your organisation and open sourced, and the distribution of internal vs external artifacts kept in a single tile. In the current single parent hierarchy, this is all duplicated.

Composing a Maven Tile

A Maven Tile is made up of a pom.xml and a tile.xml. The pom.xml contains the normal release information. When using tiles, this would be the name/groupId/artifactId/version/description/packaging(tile) and generally only a declaration of the Maven Tiles plugin. Only if you are using a tile (and generally you use at least one - the release tile) will you specify a configuration.

pom.xml

<project>
  <groupId>io.repaint.maven</groupId>
  <artifactId>license-tile</artifactId>
  <version>1.1-SNAPSHOT</version>
  <packaging>tile</packaging>
  <description>Contains consistent license information.</description>

  <build>
    <plugins>
      <plugin>
        <groupId>io.repaint.maven</groupId>
        <artifactId>tiles-maven-plugin</artifactId>
        <version>1.8</version>
        <extensions>true</extensions>
        <configuration>
          <filtering>false</filtering>
          <tiles>
            <tile>io.repaint.tiles:github-release-tile:[1.1, 2)</tile>
          </tiles>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

With the packaging tile, the plugin will look for the attached tile.xml, do some basic validation on it and attach it as an artifact.

When the <filtering> configuration item is specified as true - then standard Maven resource filtering for @project.version@ style references is applied to the tile.xml file prior to install/deploy.

tile.xml

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <licenses>
    <license>
      <name>The Apache Software License, Version 2.0</name>
      <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
      <distribution>repo</distribution>
    </license>
  </licenses>

</project>

A tile can define the tiles plugin if it wishes to cascade tile inclusion, or it can use the extended tile.xml syntax:

tile.xml

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <licenses>
    <license>
      <name>The Apache Software License, Version 2.0</name>
      <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
      <distribution>repo</distribution>
    </license>
  </licenses>

  <tiles>
    <tile>io.repaint.tiles:ratpack-tile:[1,2)</tile>
  </tiles>

</project>

Although this will appear to not validate when editing in an IDE, the tile plugin will strip off the tiles section when processing and use it directly.

Build Smells

When migrating from a parent structure, it is worthwhile to take the opportunity to reduce your build smells. You can do this gradually or in one go, depending on how your builds are done. By default, the plugin will strip all bad smells. The following is an explanation of what is stripped and why those smells are bad. Richard and Mark will be putting together a short book with tutorials for a better approach to building using Maven, but this is the short explanation. Note, these are only cleaned from the tile.xml, not from your pom.xml.

• dependencymanagement - this was always a poor substitute for composite poms. Composite poms - aka a pom only release artifact that stores all related dependencies together. This allows your project to pull in only those dependencies that it actually requires for release, and allow them to be directly overridden. Dependency management is only for declaring the version of an artifact, and not that it is a dependency - it is better and more composable to declare this specifically in a composite pom instead. Use version ranges so changes flow through.

• pluginrepositories and repositories - see Repositories in POMs is a bad idea - this has always been a bad idea. Get rid of it as soon as possible.

• dependencies - putting them in a parent or tile prevents your user from exclusion, again composites are a much, much better idea here. Just don’t use this section anywhere other than your actual artifact or composite poms.

Almost made a build smell: - pluginmanagement - plugin management is used in parents to define all of the necessary options for a plugin but not have that plugin actually run during the release of the parent artifact, and also give the child the option of running it. The reason this is bad is that it is mostly not necessary. You should split your plugins up into tiles so that they be pulled into a build as a standalone set of functionality that will always run and be properly configured. Since they will reside in the tile.xml file, they will not be run when the tile is released. However, some plugins are never run automatically - release and enforcer are two examples. These make sense to stay in pluginManagement.

If you need to use them, add them to your configuration section:

pom.xml

<build>
  <plugins>
    <plugin>
      <groupId>io.repaint.maven</groupId>
      <artifactId>tiles-maven-plugin</artifactId>
      <version>1.7</version>
      <configuration>
        <buildSmells>dependencymanagement, dependencies, repositories, pluginrepositories</buildSmells>
        <tiles>
           <tile>groupid:antrun1-tile:1.1-SNAPSHOT</tile>
           <tile>groupid:antrun2-tile:1.1-SNAPSHOT</tile>
        </tiles>
      </configuration>
    </plugin>
  </plugins>
</build>

Composing Build functionality

As a use case, an example of how it will be used for my projects.

Richard will have:

• java6-tile - for those projects that have to remain Java 6

• java7-tile - for those projects that haven’t yet moved to Java 8

• java8-tile - for those projects that are on Java 8

• groovy-tile - which defines the build structure necessary to build a Groovy project, including GMavenPlus, GroovyDoc and Source plugins

• java-tile - for Java only projects which include all the Javadoc and Source plugins

• s3-tile - for our Servlet3 modules, which includes Sass, JSP compilation and Karma plugins and depends on the groovy-tile

• github-release-tile - for artifacts that release to Github (open source)

• nexus-release-tile - for artifacts that release to our local Nexus (not open source)

This allows me to open source all my tiles except for the nexus tile, and then decide in the final artifact where I will release it.

Mojos

There are two mojos in the plugin, attach-tile and validate. attach-tile is only used by the deploy/install process and attaches the tile.xml. validate is for your use to ensure your tile is valid before releasing it - this ensures it can be read and any errors or warnings about content will appear.

Additional Notes

Some interesting notes:

• Tiles support version ranges, so use them. [1.1, 2) allows you to update and release new versions of tiles and have them propagate out. Maven 3.2.2 allows this with the version ranges in parents, but it isn’t a good solution because of single inheritance.

• You can include as many tiles as you like in a pom and poms can refer to other tiles. The plugin will search through the poms, telling you which ones it is picking up and then load their configurations in reverse order. This means the poms closer to your artifact get their definitions being the most important ones. If you have duplicate plugins, the one closest to your pom wins.

• String interpolation for properties works. The plugin first walks the tree of tiles collecting all properties, merges them together (closest wins), and then reloads the poms and interpolates them. This means all string replacement in plugins and dependencies works as expected.

• Plugin execution is merged - if you have the same plugin in two different tiles define two different executions, they will merge.

• The plugin works fine with alternative packaging. It has been tested with war, grails-plugin and grails-app.

Final Notes

Tiles-Maven works best when you and your team own the tiles. I don’t recommend relying on open source tiles, always create your own versions and always lock down versions of third party tiles, just like you would third party dependencies.

Read More

• The Original Tiles Maven plugin - although the essential start point is the same, the code is significantly different.

• Mixin POM fragments

• Stack Overflow

• Maven Discussion