usage.apt.vm

 ------
 Usage
 ------
 Dan Tran
 Dennis Lundberg
 Robert Scholte
 Adrian Price
 Karl Heinz Marbaise
 ------
 2017-01-29
 ------

~~ The MIT License
~~
~~ Copyright (c) 2004, The Codehaus
~~
~~ Permission is hereby granted, free of charge, to any person obtaining a copy of
~~ this software and associated documentation files (the "Software"), to deal in
~~ the Software without restriction, including without limitation the rights to
~~ use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
~~ of the Software, and to permit persons to whom the Software is furnished to do
~~ so, subject to the following conditions:
~~
~~ The above copyright notice and this permission notice shall be included in all
~~ copies or substantial portions of the Software.
~~
~~ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
~~ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
~~ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
~~ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
~~ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
~~ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
~~ SOFTWARE.


Usage

  Brief examples on how to use the Build Helper Maven Plugin's goals.

* Add more source directories to your project

  Use this example to add more source directories to your project, since
  <<<pom.xml>>> only allows one source directory.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>add-source</id>
            <phase>generate-sources</phase>
            <goals>
              <goal>add-source</goal>
            </goals>
            <configuration>
              <sources>
                <source>some directory</source>
                ...
              </sources>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
-------------------

* Add more test source directories to your project

  The same as the previous example, but this time we add more test source
  directories to your project.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>add-test-source</id>
            <phase>generate-test-sources</phase>
            <goals>
              <goal>add-test-source</goal>
            </goals>
            <configuration>
              <sources>
                <source>some directory</source>
                ...
              </sources>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
-------------------

* Add more resource directories to your project

  This example shows how to add additional resource directories to your project.
  Another goal called <<<add-test-resource>>> can be used in a similar way to
  add test resources to the project.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>add-resource</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>add-test-resource</goal>
            </goals>
            <configuration>
              <resources>
                <resource>
                  <directory>src/my-resources</directory>
                  <targetPath>my-resources</targetPath>
                  <excludes>
                    <exclude>**/junk/**</exclude>
                  </excludes>
                </resource>
              </resources>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
-------------------

* Attach additional artifacts to your project

  Typically run after <<<antrun:run>>>, or another plugin, that produces files
  that you want to attach to the project for install and deploy.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <!-- add configuration for antrun or another plugin here -->
      </plugin>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>attach-artifacts</id>
            <phase>package</phase>
            <goals>
              <goal>attach-artifact</goal>
            </goals>
            <configuration>
              <artifacts>
                <artifact>
                  <file>some file</file>
                  <type>extension of your file </type>
                  <classifier>optional</classifier>
                </artifact>
                ...
              </artifacts>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
-------------------

* Access the parsed components of a project version

  The <<<parse-version>>> goal can be used to access the component parts of a version string. For example,
  the major version or the qualifier by themselves.  Executing the following plugin configuration
  will parse the version of the current project and set several properties.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>parse-version</id>
            <goals>
              <goal>parse-version</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
-------------------

  After the goal executes (by default during the <<<validate>>> phase) the following
  properties will contain the components of the current project version.

-------------------
parsedVersion.majorVersion
parsedVersion.minorVersion
parsedVersion.incrementalVersion
parsedVersion.qualifier
parsedVersion.buildNumber
-------------------

  Apart from the above properties the following properties will be set:

-------------------
parsedVersion.nextMajorVersion
parsedVersion.nextMinorVersion
parsedVersion.nextIncrementalVersion
parsedVersion.nextBuildNumber
-------------------

  And another set of properties is set by using the defined formatting.
  See {{{./parse-version-mojo.html}build-helper:parse-version}}

-------------------
formattedVersion.majorVersion
formattedVersion.minorVersion
formattedVersion.incrementalVersion
formattedVersion.buildNumber
formattedVersion.nextMajorVersion
formattedVersion.nextMinorVersion
formattedVersion.nextIncrementalVersion
formattedVersion.nextBuildNumber
-------------------


  The property prefix <<<parsedVersion>>> can be configured using the <<<propertyPrefix>>> parameter.

  An OSGi compatible version will also be created and made available through the property:

-------------------
parsedVersion.osgiVersion
-------------------

  This property contains the original version string with the first instance of '-' replaced by '.'
  For example, <<<1.0.2-beta-1>>> will be converted to <<<1.0.2.beta-1>>>. Each occurance
  of a another `.` will be replaced by `_` cause OSGi does not allow to have more than three `.`
  in a version.

* Resolve the latest released version of a project

  The <<<released-version>>> goal can be used to resolve the latest released version of a project.
  Executing the following plugin configuration makes the latest released version of the current project available.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>released-version</id>
            <goals>
              <goal>released-version</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
-------------------

  After the goal executes (by default during the <<<validate>>> phase) the following
  property will be available.

-------------------
releasedVersion.version
releasedVersion.majorVersion
releasedVersion.minorVersion
releasedVersion.incrementalVersion
releasedVersion.buildNumber
releasedVersion.qualifier
-------------------

  The property prefix "releasedVersion" can be configured using the <<<propertyPrefix>>> parameter.
  This property can become very handy if you want to provide links to download the latest version.
  If you have to do a <<<site-deploy>>> during snapshot-development, the $\{project.version\} is useless.


* Remove a project's artifacts from local repository

  Mainly used to remove previously installed large project artifacts in the local repository before the <<<install>>> phase starts.
  The example below removes all the project's artifacts including all versions from the local repository
  at the implicit <<<package>>> phase. To remove only the current version, set the \<<<<removeAll\>>>> configuration
  element to <<<false>>>.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>remove-old-installers</id>
            <goals>
              <goal>remove-project-artifact</goal>
            </goals>
            <configuration>
              <removeAll>true</removeAll>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
-------------------

* Reserve a list of random and unused network ports

  Use this plugin to reserve a set of available unused network ports to be placed in a given property
  set, so that they can be inserted into other plugin configurations.

  The example below shows how one can pass in random ports to Selenium server port and Tomcat http port.
  Useful for running multiple tests concurrently.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>reserve-network-port</id>
            <goals>
              <goal>reserve-network-port</goal>
            </goals>
            <phase>process-resources</phase>
            <configuration>
              <portNames>
                <portName>selenium.server.port</portName>
                <portName>tomcat.http.port</portName>
              </portNames>
            </configuration>
          </execution>
        </executions>
      </plugin>

      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>selenium-maven-plugin</artifactId>
        <executions>
          <execution>
            <id>start-selenium</id>
            <phase>test</phase>
            <goals>
              <goal>start-server</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <port>${selenium.server.port}</port>
          [...]
        </configuration>
      </plugin>

      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>tomcat-maven-plugin</artifactId>
        <executions>
          <execution>
            <id>run-tomcat</id>
            <phase>test</phase>
            <goals>
              <goal>run</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <port>${tomcat.http.port}</port>
          [...]
        </configuration>
      </plugin>

      [...]

    </plugins>
  </build>
</project>
-------------------
  It is also possible to define port names via resource file(s). Resources in classpath are also supported (artifact
  with resource has to be defined in plugin dependencies section).

  <<<portNames>>> and <<<urls>>> parameters can be combined.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <dependencies>
          <dependency>
            <artifactId>jar-with-port-names.txt</artifactId>
            [...]
        </dependencies>
        <executions>
          <execution>
            <id>reserve-network-port</id>
            <goals>
              <goal>reserve-network-port</goal>
            </goals>
            <phase>process-resources</phase>
            <configuration>
              <urls>
                <url>file:///${project.basedir}/names1.txt</url>
                <url>classpath:port-names.txt</url>
              </urls>
            </configuration>
          </execution>
        </executions>
      </plugin>

      [...]

    </plugins>
  </build>
</project>
-------------------
  port-names.txt:

-------------------
# Selenium port name
selenium.server.port
# Tomcat port name
tomcat.http.port
-------------------

* Set a property by applying a regex replacement to a value

  The <<<regex-property>>> goal can be used to set a property to a value after regex replacement has been applied.
  For example, executing the following plugin configuration to set the <<<human.version>>> property.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>regex-property</id>
            <goals>
              <goal>regex-property</goal>
            </goals>
            <configuration>
              <name>human.version</name>
              <value>\${project.version}</value>
              <regex>-SNAPSHOT</regex>
              <replacement> pre-release development version</replacement>
              <failIfNoMatch>false</failIfNoMatch>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
-------------------

  After the goal executes (by default during the <<<validate>>> phase) the <<<human.version>>> property would have
  the value <<<1.0>>> if the <<<project.version>>> was <<<1.0>>> but if the project version was <<<1.0-SNAPSHOT>>>
  then it would have the value <<<1.0 pre-release development version>>>.

  To load multiple properties in one execution, use <<<regex-properties>>> goal

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>regex-properties</id>
            <goals>
              <goal>regex-properties</goal>
            </goals>
            <configuration>
              <regexPropertySettings>
                <regexPropertySetting>
                  <name>human.version</name>
                  <value>\${project.version}</value>
                  <regex>-SNAPSHOT</regex>
                  <replacement> pre-release development version</replacement>
                  <failIfNoMatch>false</failIfNoMatch>
                </regexPropertySetting>
                [....]
              </regexPropertySettings>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
-------------------

* Set a property based on the current time and date

  The <<<timestamp-property>>> goal can be used to set a property to a value based on the current time and date (with
  an optional offset applied). For example, executing the following plugin configuration to set the
  <<<next.year>>> property to next year.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>timestamp-property</id>
            <goals>
              <goal>timestamp-property</goal>
            </goals>
            <configuration>
              <name>next.year</name>
              <pattern>yyyy</pattern>
              <unit>year</unit>
              <offset>+1</offset>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
-------------------

  After the goal executes (by default during the <<<validate>>> phase) the <<<next.year>>> property will have the
  value of next year.

  The <<<pattern>>> parameter accepts any valid <<<java.text.SimpleDateFormat>>> format string.

  The <<<unit>>> will accept any of: <<<millisecond>>>, <<<second>>>, <<<minute>>>, <<<hour>>>, <<<day>>>, <<<week>>>,
  <<<month>>> and <<<year>>>. The <<<offset>>> parameter takes integer values only and defaults to <<<0>>>.

  The <<<locale>>> and <<<timeZone>>> parameters can be further used to control the build-time behaviour.

* Set a property based on the <<<maven.build.timestamp>>>

  The <<<maven.build.timestamp>>> property does not allow for timezone overrides for obvious reasons.
  The <<<timestamp-property>>> goal can be used to create one with a local timezone timestamp.
  But the default implementation uses the <<<current>>> time, which is thus not the same for all modules in a multi module project.
  The new <<<timeSource>>> parameter with value <<<build>>> now allows the usage of <<<maven.build.timestamp>>> property instead of the <<<current>>> timestamp.

-------------------
<project>
  ...
  <properties>
    <maven.build.timestamp.format>yyyy-MM-dd HH:mm:ss z</maven.build.timestamp.format>
  </properties>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>module-timestamp-property</id>
            <phase>validate</phase>
            <goals>
              <goal>timestamp-property</goal>
            </goals>
            <configuration>
              <name>module.build.timestamp</name>
              <pattern>${maven.build.timestamp.format}</pattern>
              <timeZone>Europe/Amsterdam</timeZone>
              <!-- <timeSource>current</timeSource> -->
            </configuration>
          </execution>
          <execution>
            <id>local-timestamp-property</id>
            <phase>validate</phase>
            <goals>
              <goal>timestamp-property</goal>
            </goals>
            <configuration>
              <name>local.build.timestamp</name>
              <pattern>${maven.build.timestamp.format}</pattern>
              <timeZone>Europe/Amsterdam</timeZone>
              <timeSource>build</timeSource>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
-------------------

* Retrieve current host IP address

  The <<<local-ip>>> goal can be used to load current host address

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>get-local-ip</id>
            <goals>
              <goal>local-ip</goal>
            </goals>
            <configuration>
              <!-- if not given, 'local.ip' name is used -->
              <localIpProperty>my.local.ip</localIpProperty>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
-------------------

* Retrieve current hostname

  The <<<hostname>>> goal can be used to load current hostname

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>get-hostname</id>
            <goals>
              <goal>hostname</goal>
            </goals>
            <configuration>
              <!-- if not given, 'hostname' name is used -->
              <hostnameProperty>my.local.ip</hostnameProperty>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
-------------------

* Retrieve available number of CPUs

  The <<<cpu-count>>> goal can be used to load number of CPU

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>get-cpu-count</id>
            <goals>
              <goal>cpu-count</goal>
            </goals>
            <configuration>
              <!-- if not given, 'cpu.count' name is used -->
              <cpuCount>my.cpu.count</cpuCount>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
-------------------

* Set a property according to whether target files are up to date with respect to their sources

  'Up to date' means that the target file both exists and has a 'last modification timestamp' (<<<java.io.File.lastModified()>>>)
  equal to or later than that of the corresponding source file(s).

  Source files are computed relative to the <<<fileset>>>'s required <<<directory>>> property.
  If the <<<fileset>>> has an <<<outputDirectory>>> property, target files are computed relative to that;
  otherwise, target files are also computed relative to <<<directory>>>.

  The <<<fileset>>> element supports a <<<mapper>>>, whose <<<type>>> can be any of the built-in mappers
  <<<flatten glob identity merge package unpackage>>>. Alternatively, the <<<classname>>> property can specify the
  fully qualified name of a class that implements <<<org.apache.maven.shared.model.fileset.mappers.FileNameMapper>>>.

  The <<<uptodate-property>>> goal can be used to set a property to a value if specified target files are up to date.
  For example, executing the following plugin configuration to set the <<<obj.status>>> property.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>obj-uptodate</id>
            <goals>
              <goal>uptodate-property</goal>
            </goals>
            <configuration>
              <name>obj.status</name>
              <value>fresh</value>
              <else>stale</else>
              <fileSet>
                <directory>src/main/c</directory>
                <outputDirectory>target/obj</outputDirectory>
                <includes>
                  <include>mod-*/**</include>
                </includes>
                <excludes>
                  <exclude>**/*.old.*</exclude>
                </excludes>
                <mapper>
                  <type>glob</type>
                  <from>*.c</from>
                  <to>*.o</to>
                </mapper>
              </fileSet>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
-------------------

  After the goal executes (by default during the <<<validate>>> phase) the <<<obj.status>>> property would have
  the value <<<fresh>>> if all <<<target/obj/**/*.o>>> object files were up to date with respect to their
  corresponding <<<src/main/c/mod-*/**/*.c>>> source files (excluding any with <<<.old.>>> in the name);
  otherwise, the property would have the value <<<stale>>>.

  To set multiple properties for multiple file sets in one execution, use the <<<uptodate-properties>>> goal.
  The <<<upToDatePropertySetting>>> element supports all the configuration properties documented above for the
  <<<uptodate-property>>> goal.

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>lib-doc-uptodate</id>
            <goals>
              <goal>uptodate-properties</goal>
            </goals>
            <configuration>
              <upToDatePropertySettings>
                <upToDatePropertySetting>
                  <name>lib.uptodate</name>
                  <fileSet>
                    <directory>target/obj</directory>
                    <outputDirectory>target/lib</outputDirectory>
                    <mapper>
                      <type>merge</type>
                      <from>*.o</from>
                      <to>mylibrary.so</to>
                    </mapper>
                  </fileSet>
                </upToDatePropertySetting>
                <upToDatePropertySetting>
                  <name>doc.uptodate</name>
                  <fileSet>
                    <directory>src/main/c</directory>
                    <outputDirectory>target/site/doc</outputDirectory>
                    <mapper>
                      <type>merge</type>
                      <from>*.c</from>
                      <to>mylibrary.html</to>
                    </mapper>
                  </fileSet>
                </upToDatePropertySetting>
              </upToDatePropertySettings>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
-------------------

  After the goal executes, the <<<lib.uptodate>>> property would have the value <<<true>>> if <<<target/lib/mylibrary.so>>>
  is up to date with respect to all the <<<target/obj/**/*.o>>> object files. Also, the <<<doc.uptodate>>> property would
  have the value <<<true>>> if <<<target/site/doc/mylibrary.html>>> is up to date with respect to <<<src/main/c/**/*.c>>>.