Quickstarts documentation plugin

Maven plugin that generates quickstarts documentation

License

License

Categories

Categories

WildFly Container Application Servers Maven Build Tools
GroupId

GroupId

org.wildfly.maven.plugins
ArtifactId

ArtifactId

quickstart-documentation-plugin
Last Version

Last Version

2.3.0.Final
Release Date

Release Date

Type

Type

maven-plugin
Description

Description

Quickstarts documentation plugin
Maven plugin that generates quickstarts documentation
Project Organization

Project Organization

JBoss by Red Hat

Download quickstart-documentation-plugin

How to add to project

<plugin>
    <groupId>org.wildfly.maven.plugins</groupId>
    <artifactId>quickstart-documentation-plugin</artifactId>
    <version>2.3.0.Final</version>
</plugin>

Dependencies

compile (9)

Group / Artifact Type Version
org.apache.maven : maven-compat jar 3.3.1
org.apache.maven : maven-settings-builder jar 3.3.1
org.apache.maven.plugin-testing : maven-plugin-testing-harness jar 3.3.0
org.apache.maven.plugin-tools : maven-plugin-annotations jar 3.5
dk.nykredit.jackson.dataformat : jackson-dataformat-hal jar 1.0.1
org.apache.httpcomponents : httpclient jar 4.5.5
org.apache.httpcomponents : fluent-hc jar 4.5.5
org.jsoup : jsoup jar 1.11.2
org.asciidoctor : asciidoctorj jar 2.4.2

test (5)

Group / Artifact Type Version
junit : junit jar 4.12
org.mockito : mockito-core jar 2.8.47
com.github.tomakehurst : wiremock jar 2.7.1
org.slf4j : slf4j-simple jar 1.8.0-alpha2
org.assertj : assertj-core jar 3.8.0

Project Modules

There are no modules declared in this project.

JBoss Parent POM

The parent Maven POM for JBoss community projects.

Maven Central

What is it?

The JBoss parent POM provides default configuration for Maven builds.

  • Recommended/Default versions for the most commonly used Maven plugins

  • Manifest configuration for the jar and assembly plugins

  • Profiles for generating source jars, and enforcing a minimum versions of Java and Maven

  • Distribution Management and other configuration for deploying to the JBoss.org Maven repositories

How to use it?

Start out by adding the parent configuration to your pom.

<parent>
  <groupId>org.jboss</groupId>
  <artifactId>jboss-parent</artifactId>
  <version>33</version>
</parent>

The pom includes properties which allow various build configuration to be customized. For example, to override the default version of the maven-compiler-plugin, just set a property.

<properties>
  <version.compiler.plugin>3.1</version.compiler.plugin>
</properties>

Or override the default Java compiler source and target level used in the build. Note the default level is 1.8.

<properties>
  <maven.compiler.target>1.7</maven.compiler.target>
  <maven.compiler.source>1.7</maven.compiler.source>
</properties>

The minimum version of Java or Maven required to run a build can also be set via properties.

<properties>
  <maven.min.version>3.0.3</maven.min.version>
  <jdk.min.version>1.7</jdk.min.version>
</properties>

If jdk.min.version is not set, it defaults to version defined by maven.compiler.source

For the full list of properties, refer to the POM itself.

The JBoss Release Profile

The parent POM includes a Maven profile called "jboss-release". This profile contains settings for generating a full project source archive, javadoc jar files, and release deployment metadata. If using the Maven release plugin, this profile will automatically be activate during the release:perform step.

If the Maven release plugin is not used during the release process, the profile can be manually activated from the command line during a release build.

mvn -Pjboss-release deploy

The GPG Sign Profile

This POM includes a Maven profile called "gpg-sign" which provides default configuration to generate GPG signatures for the build artifacts.

mvn -Pgpg-sign deploy

In order for the gpg plugin to properly create a signature for each artifact, the properties "gpg.keyname" and "gpg.passphrase" must be available to the current build. These properties can either be set in a build profile, or on the command line.

<profile>
  <id>gpg-config</id>
  <properties>
    <gpg.keyname>[email protected]</gpg.keyname>
    <!-- Don't keep passphrase in plain text! -->
    <gpg.passphrase>secret</gpg.passphrase>
  </properties>
</profile>

Multi-Release JARs

Starting with version 30, the JBoss Parent POM provides a framework for multi-release JAR build and test.

Functional overview

The multi-release JAR support works in two parts: compilation and testing.

Compilation

Compilation works by providing extra executions of the compiler plugin in order to build the additional JAR layers. The base layer is built by the standard default-compile execution. After that, Maven profiles are activated based on the presence of extra layer source directories (e.g. src/main/java9, src/main/java10 etc.). These profiles contain additional executions of the compiler plugin which compile the sources in the layer directory, while putting the output of the previous step on the class path.

Each present layer is in turn compiled with the results of all the previous layers on the classpath in the correct order. The additional layer class files are output under the target/classes directory in the appropriate location for multi-release JAR layers.

In order to select the correct class files for the given Java version, the <release> property is used. This prevents accidental usage of APIs which are only present in later versions than the one being compiled. However there is a limitation to this strategy: Java 9 and later do not provide runtime information for non-standard Java 8 classes such as sun.misc.Unsafe. If your project needs to compile against these classes, you must use the dependency plugin as described below.

Note that by default, building Java 8 sources does not use the <release> property. To enable this feature, create a file (which may be empty) in your project root named build-release-8.

Testing

Testing using maven-surefire-plugin is supported by running the project unit tests on every supported Java version. In order to do so, it is expected that the following system property or properties are set as needed:

  • java8.home: this property must be set to the location of a Java 8 JDK installation

  • java9.home: this property must be set to the location of a Java 9 JDK installation

  • java10.home: this property must be set to the location of a Java 10 JDK installation

  • java11.home: this property must be set to the location of a Java 11 JDK installation

  • java12.home: this property must be set to the location of a Java 12 JDK installation

In order to simplify development, it is recommended to project maintainers to set these properties in your personal Maven settings.xml file.

Extra unit tests are run for a given platform whenever a newer version than that platform was used to build the project and the appropriate control file is found (see Build control files reference).

Configuration

To configure a multi-release JAR, you need the following pieces of information:

  • The minimum (oldest) version of Java that will be supported by the project

  • The maximum (newest) version of Java for which your project has sources

Step 1: Base layer version

Choose your base layer version. This can be Java 8 or anything later. Configure the version by configuring the release property in the default-compile execution of maven-compiler-plugin:

<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <executions>
    <execution>
      <id>default-compile</id>
      <configuration>
        <release>8</release>
      </configuration>
    </execution>
  </executions>
</plugin>

If the build-release-8 property is present in the root of your project, then this step is automatically done for you.

Note that a single-layer Java 8 build does not support the release element because the corresponding javac option is only present in JDK 9 and later.

Step 2: Highest layer version

Configure the jdk.min.version property as described above to match either:

  • The maximum (newest) Java version for which sources exist in your project, or

  • Some Java version higher than that

This is the version of Java that will build all of your layers, so it necessarily must be able to compile every version of Java sources from oldest to newest.

Step 3: Source directories

The sources for your base layer continue to reside in src/main/java and src/test/java.

Additional layers are in directories whose names correspond to the version of Java that is targeted by that directory. For example, sources which are specific to Java 9 and later would be in src/main/java9, whereas sources which are specific to Java 11 and later would be in src/main/java11.

If you have a class that needs an alternative version for a given Java version, you only need to provide the replacement source file in the directory corresponding to the oldest version that supports the alternative source. It is not necessary to copy identical classes into more than one layer; doing so will increase the size of the resultant artifact needlessly.

There are restrictions on these directories. You may only provide sources that correspond to sources that exist in the base layer - that is, it is a violation of the MR JAR specification to provide sources that introduce new APIs only in later Java versions. The JDK does enforce this at run time. In addition, providing additional public members in later versions is generally not recommended.

Missing JDK APIs

If your project relies on APIs which are not in the Java SE specification (for example, classes such as sun.misc which are present in the jdk.unsupported module in Java 9 and later), and your base layer targets Java 8, you must take an additional step.

Since these APIs are not included in the class database that javac uses to compile (even though they are present at run time), stubs of the extra classes must be included but only during compilation.

To automatically perform this step, create a file in your project root named build-include-jdk-misc. The contents of this file do not matter; it can be empty or it can contain text referring to this document.

Build control files reference

File name Purpose Reference

build-release-8

Use the <release> option to set Java 8 for the base layer.

Step 1: Base layer version

build-include-jdk-misc

Include the jdk-misc dependency for Java 8 builds.

Missing JDK APIs

build-test-java8

Run tests for Java 8 when java8.home is set and JDK 9 or later is used.

Testing

build-test-java9

Run tests for Java 9 when java9.home is set and JDK 10 or later is used.

Testing

build-test-java10

Run tests for Java 10 when java10.home is set and JDK 11 or later is used.

Testing

build-test-java11

Run tests for Java 11 when java11.home is set and JDK 12 or later is used.

Testing

build-test-java12

Run tests for Java 12 when java12.home is set and JDK 13 or later is used.

Testing

Where to get more information?

The github wiki provides some additional examples. For questions/suggestions about the jboss-parent-pom, head to the JBoss Community Build space on the jboss.org site. Issues related to the jboss-parent-pom can be submitted to the JBoss build jira project

License

  • This software is in the public domain

Versions

Version
2.3.0.Final
2.2.0.Final
2.1.0.Final
2.0.0.Final
2.0.0.Beta2
2.0.0.Beta1
1.0.1
1.0.0