Sculptor Maven Plugin

Overview

Sculptor comes with its own Maven plugin with the Maven coordinates org.sculptorgenerator:sculptor-maven-plugin. This plugin has the following responsibilities:

• The plugin goal clean deletes all unmodified one-shot artifacts and the generated/ folders which have been created by the last Sculptor generator execution.
• The plugin goal generate executes the Sculptor generator to create the one-shot artifacts and the artifacts in the generated/ folders.
• The plugin goal generate-images executes the “dot” command from the graph visualization software GraphViz to create image files (.png) from the .dot files generated by the last Sculptor generator run.

The plugin provides the following features:

• The plugin keeps track of all artifacts created during code generation. This information is used to delete the generated artifacts when the code generator is executed again or when the Maven clean plugin is executed.
• To skip unneccessary Sculptor generator executions the plugin checks if one of the generator-related files (e.g. pom.xml, Sculptor models or generator configuration) is modified.
• The plugin registers itself with the Eclipse m2e plugin (Eclipse Maven support) to provide the following information:
  • metadata for the Sculptor Mven plugins Maven lifecycle mapping
  • directories of the Maven project which should be used as classpath entries within an Eclipse project
• The plugin maintains its own classpath which is independent from the projects classpath.

Usage

To activate the Sculptor Maven plugin within a maven project the following has to be added to the projects POM:

<build>
	<plugins>
		<plugin>
			<groupId>org.sculptorgenerator</groupId>
			<artifactId>sculptor-maven-plugin</artifactId>
			<version>${sculptor.version}</version>
			<executions>
				<execution>
					<id>cleanup</id>
					<goals>
						<goal>clean</goal>
					</goals>
				</execution>
				<execution>
					<id>code-generation</id>
					<goals>
						<goal>generate</goal>
					</goals>
				</execution>
				<execution>
					<id>image-generation</id>
					<goals>
						<goal>generate-images</goal>
					</goals>
				</execution>
			</executions>
		</plugin>
	</plugins>
</build>

This registers the Sculptor plugins goals (with their default lifecyle phase) to the Maven projects lifecycle:

• For mvn clean the plugins clean goal is executed to delete all artifacts created during the last code generation.
• For mvn generate-sources (or any phase later) the plugins generate goal is executed to run Sculptors code generator.
• For mvn generate-resources (or any phase later) the plugins generate-images goal is executed to use the dot command for generating images from the .dot files created during the last code generation.

The details of this plugin reference can be reduced by defining the Sculptor plugin in the <pluginManagement> section of a parent POM, e.g.

<build>
	<pluginManagement>
		<plugins>
			<plugin>
				<groupId>org.sculptorgenerator</groupId>
				<artifactId>sculptor-maven-plugin</artifactId>
				<version>${sculptor.version}</version>
				<executions>
					<execution>
						<id>cleanup</id>
						<goals>
							<goal>clean</goal>
						</goals>
					</execution>
					<execution>
						<id>code-generation</id>
						<goals>
							<goal>generate</goal>
						</goals>
					</execution>
					<execution>
						<id>image-generation</id>
						<goals>
							<goal>generate-images</goal>
						</goals>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</pluginManagement>
</build>

To activate the plugin (which is defined this way) only the following has to be added to the projects POM:

<build>
	<plugins>
		<plugin>
			<groupId>org.sculptorgenerator</groupId>
			<artifactId>sculptor-maven-plugin</artifactId>
		</plugin>
	</plugins>
</build>

The plugin keeps track of the artifacts created by the Sculptor generator. This information is used to delete the generated artifacts when the Sculptor generator is executed again or when the Maven clean plugin is executed. The corresponding information is retrieved from the hidden file .sculptor-status. This file is deleted when mvn clean is executed.

Configuration

The Sculptor Maven plugin goals provide the following configuration properties with reasonable defaults (conventon over configuration):

These properties are used within the <configuration> tag in the Sculptor Maven plugin definition, e.g.

<plugin>
	<groupId>org.sculptorgenerator</groupId>
	<artifactId>sculptor-maven-plugin</artifactId>
	<executions>
		<execution>
			<id>code-generation</id>
			<goals>
				<goal>generate</goal>
			</goals>
			<configuration>
				<verbose>true</verbose>
				<checkFilesets>
					<checkFileset>
						<directory>${basedir}</directory>
						<includes>
							<include>src/**</include>
						</includes>
						<excludes>
							<exclude>**/.gitignore</exclude>
						</excludes>
					</checkFileset>
				</checkFilesets>
				<properties>
					<sculptor.generatorPropertiesLocation>
						${basedir}/src/sculptor/generator.properties
					</sculptor.generatorPropertiesLocation>
				</propperties>
			</configuration>
		</execution>
	</executions>
</plugin>

Some of these properties can be added to the commandline as system properties, e.g.

mvn clean test -Dverbose=true -Dsculptor.graphviz.skip=true

Classpath

The plugin uses its own classloader which is separated from the current Maven projects one.

To add additional dependencies to the the plugins classpath (e.g. for cross-project references) add these dependencies in the plugins/plugin section of the project pom.xml:

<plugin>
	<groupId>org.sculptorgenerator</groupId>
	<artifactId>sculptor-maven-plugin</artifactId>
	<executions>
		<execution>
			<id>code-generation</id>
			<goals>
				<goal>generate</goal>
			</goals>
		</execution>
		<dependencies>
			<dependency>
				<groupId>org.foo.common</groupId>
				<artifactId>foo-common</artifactId>
				<version>1.0</version>
				<classifier>client</classifier>
			</dependency>
		</dependencies>
	</executions>
</plugin>

Logging

Sculptor uses the SLF4J logging abstraction which supports various logging frameworks (e.g. java.util.logging, logback, log4j).

Maven 3.1 and newer

Starting with version 3.1 Maven ships with the SLF4J Simple Logger. So adding the Java system property -Dorg.slf4j.simpleLogger.log.org.sculptor=debug to the Maven command line activates the debug logging of Sculptors generator library:

mvn clean generate-sources -Dorg.slf4j.simpleLogger.log.org.sculptor=debug

Maven 3.0

With Maven 3.0 Sculptor uses the Logback logging framework. So adding the Java system property -Dlogback.configurationFile=</path/to/logback.xml> to the Maven command line activates debug logging of Sculptors generator library. The corresponding logback.xml defines a logger with the name “org.sculptor”:

<?xml version="1.0" encoding="UTF-8"?>
<configuration> 
  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> 
    <encoder> 
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> 
    </encoder> 
  </appender>  

  <logger name="org.sculptor" level="DEBUG"/>

  <root level="WARN">
    <appender-ref ref="STDOUT"/> 
  </root> 
</configuration>