classicvalues / maven-qstools-plugin

Utility belt for jboss developer materials

Quickstarts tools maven plugin

Author: Rafael Benevides Summary: Maven plugin that helps JBoss Developer materials maintenance

What is it?

This a Maven Plugin that helps JBoss Developer materials maintenance.

You can use it to verify if your project/quickstart follow the JBoss Developer Guidelines. It will run all JBoss Developer Guideline checkers and generate a report that provides information about any violations that your project/quickstarts has.

For Maven BOMs,it can be used to verify if your Maven BOM has all dependencies being resolved.

You can also use QSTools to synchronize an Maven Archetype with and existing project.

System requirements

All you need is Apache Maven 3.0.X and a working internet connection.

Checking the quickstarts made easy

Select a Maven project and run:

mvn -U org.jboss.maven.plugins:qstools:check

This will check your project and all modules to seek for potential violations.

The report will be generated at: MAVEN_PROJECT/target/site/qschecker.html

Configuring QSTools

QSTools configuration is made by editing the online file https://github.com/jboss-developer/maven-qstools-plugin/blob/master/config/qstools_config.yaml

You can use a local config file by overwriting qstools property:

mvn -U org.jboss.maven.plugins:qstools:check
     -Dqstools.configFileURL=file:///Users/rafaelbenevides/path/qstools_config.yaml

Using a custom stacks.yaml definition

Stacks is used to check the BOM versions used on you project.

If you need to use a custom Stacks.yaml definition you can overwrite the stacks url adding the property qstools.stacks.url to the command line:

mvn -U org.jboss.maven.plugins:qstools:check
   -Dqstools.stacks.url=file:/somewhere/on/your/disk/stacks.yaml

or

mvn -U org.jboss.maven.plugins:qstools:(check)
   -Dqstools.stacks.url=http://www.somewhere.net/somepath/stacks.yaml

Automatically fixing the quickstarts

QSTools can fix most of the violations.

You can run:

mvn -U org.jboss.maven.plugins:qstools:fix

NOTE: It's high recommended that you have your changes saved before running this plugin because it modifies your pom files.

Setup JBoss Maven approved repositories

QSTools can add/remove the section on pom.xml files. It uses Approved JBoss Maven Repositories list.

You can run:

mvn -U org.jboss.maven.plugins:qstools:repositories

NOTE: It's high recommended that you have your changes saved before running this plugin because it modifies your pom files.

If you need to update quickstarts BOMs

This goal will check the Expected BOM Version and update the BOM versions to the expected version.

It will also replace any community BOMs by the Product BOMs if it is specified under project-boms-migration sections of QSTools configuration file

NOTE: It's high recommended that you have your changes saved before running this plugin because it modifies your pom files.

To run the plugin:

mvn -U org.jboss.maven.plugins:qstools:updateBoms

Checking the BOM dependencies

This goal will check the given BOM project if all declared dependencies under section is resolvable.

To run the plugin:

mvn -U org.jboss.maven.plugins:qstools:bom-check

If you need to ignore certain known dependencies from being checked, you can use the qstools.bom-check.ignoredDependencies property.

Example:

mvn -U org.jboss.maven.plugins:qstools:bom-check 
   -Dqstools.bom-check.ignoredDependencies=<groupId 1>:<artifactId 1>:jar:<version 1>,<groupId 2>:<artifactId 2>:jar:<version 2>

By default, the project build will fail if some managed dependency is not resolvable. You can overwrite this behavior by using qstools.bom-check.failbuild property. This will run on REPORT ONLY mode.

Example:

mvn -U org.jboss.maven.plugins:qstools:bom-check 
   -Dqstools.bom-check.failbuild=false

To specify a custom settings.xml file you must use org.apache.maven.user-settings property. This is because Shrinkwrap Resolver doesn't consume settings.xml you specified on command line (-s settings.xml) or in the IDE. It reads settings.xml files at their standard locations, which are ~/.m2/settings.xml and $M2_HOME/conf/settings.xml unless overridden in the API or via System property.

Example:

mvn -U org.jboss.maven.plugins:qstools:bom-check 
   -Dorg.apache.maven.user-settings=<your custom settings.xml>

Synchronizing Archetypes with Quickstarts

QSTools can be used on archetype to synchronize the archetype-resources with a given project

This is an example of configuration:

    <plugins>
        <plugin>
            <groupId>org.jboss.maven.plugins</groupId>
            <artifactId>qstools</artifactId>
            <version>1.7.0-SNAPSHOT</version>
            <configuration>
                <projectGitRepo>git://github.com/jboss-developer/jboss-eap-quickstarts.git</projectGitRepo>
                <projectPath>kitchensink-ear</projectPath>
                <rootPackage>org.jboss.as.quickstarts.kitchensink_ear</rootPackage>
                <multiModuleProject>true</multiModuleProject>
                <applyPatch>A-patch-file.patch</applyPatch>
                <branch>[a branch name or a commit hash]</branch>
                <-- Replace the following strings by {archetypeId} or __artifactId__ in file name
                <archetypeExpressionReplaceValues>
                    <archetypeExpressionReplaceValue>jboss-as-kitchensink-ear</archetypeExpressionReplaceValue>
                    <archetypeExpressionReplaceValue>kitchensink-ear-quickstart</archetypeExpressionReplaceValue>
                    <archetypeExpressionReplaceValue>kitchensink-quickstart</archetypeExpressionReplaceValue>
                    <archetypeExpressionReplaceValue>KitchensinkEarQuickstart</archetypeExpressionReplaceValue>
                    <archetypeExpressionReplaceValue>JBoss EAP Quickstart: kitchensink-ear</archetypeExpressionReplaceValue>
                </archetypeExpressionReplaceValues>
                <!-- Expressions that will be ignored during the replacement -->
                <ignoredArchetypeExpressionReplaceValues>
                          <ignoredArchetypeExpressionReplaceValue>https://github.com/wildfly/quickstart/tree/master/</ignoredArchetypeExpressionReplaceValue>
                </ignoredArchetypeExpressionReplaceValues>
                <!-- Replace the html5mobi string by {tableSuffix} -->
                <replaceValueWithExpression>
                    <html5mobi>tableSuffix</html5mobi>
                </replaceValueWithExpression>
            </configuration>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>archetypeSync</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>

The archetypeExpressionReplaceValues argument is used to replace the given expression to the ${artifactId} expression or __artifactId__ in file name.

In some situations will may want to ignore a line to be replaced. You can specify the line content on the ignoredArchetypeExpressionReplaceValues argument.

Plugin Documentation

The plugin documentation generated from mvn site is available here

Troubleshooting

You can turn on debugging messages:

mvn -U org.jboss.maven.plugins:qstools:check -X