runeduniverse/r4m-maven-extension

Runes4Maven (r4m) Maven Extension provides an alternative way for defining maven executions

Runes4Maven (r4m) Maven Extension

Runes4Maven (r4m) Maven Extension provides an alternative way for defining maven executions

Concept

Maven hides a bunch of very useful options under the hood. Additionally the Executions feature is very powerful but can be quite a hussle to configure correctly. Furthermore maven does not provide an option to just launch one phase which might include only goals that don't require any prerequisites.

Runes4Maven (r4m) reworks two core features and adds ease of life features.

1. Which executions get activated?
2. Which Goals are included in which execution?
3. Selecting Goals through 'modes'
4. Activating Executions for entire lifecycle-tasks (phases)
5. Specific declaration of which phases are to run.
6. Help Lifecycle

Project Execution Model (PEM) [1-3]

The Project Execution Model pem.xml can be used to override all inherited default executions and specify specific triggers, restrictions and modes for your specific usecase. We strongly recommend not to write the PEM from scratch but to generate the currently active configuration. This can be done by running r4m:gen-full-pem to generate to full PEM usually around 700-1000 lines (yes maven does inject a ton of configuration), we recommend to generate only the relevant PEM for your usecase by running r4m:gen-rel-pem. Please keep in mind that the relevant PEM of the root project of a multi-module-maven project only includes the config of the root project.

The pem.xml has the schema header shown below, allowing you to speed up writing it with an adequate IDE (Eclipse/Intellij).

<project-execution-model
    xmlns="https://api.runeduniverse.net/runes4tools/r4m-pem"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://api.runeduniverse.net/runes4tools/r4m-pem 
    https://api.runeduniverse.net/runes4tools/r4m-pem-v1_0_0.xsd">

    <modelVersion>1.0.0</modelVersion>
    <executions>
        ...
    </executions>
</project-execution-model>

Every Execution defined in the PEM can have multiple triggers. Currently following triggers are available - other core-extensions may define additional triggers:

always, never, default, on-call (this is always active), active-profile, inactive-profile, provided-profile, missing-profile

Every Execution defined in the PEM can have multiple restrictions, once a restriction type is defined at least one of those definitions has to be fulfilled. Currently following restriction is available - other core-extensions may define additional restrictions:

packaging-procedure

Every Goal in the PEM has to have at least one mode. By default the modes default and dev are preconfigured. This can be changed inside the pem.xml.

What might I use modes for? With modes you can have two seperate 'modes' of one execution, for example you can make it so that a formtting goal only runs in 'dev' mode and not during normal operation.

Lifecycle Tasks Rework [3-5]

When running maven you append goal/lifecycle tasks to the maven command 'mvn'.

Maven already provides the goal tasks in following style - as such they are unchanged:

<plugin-prefix>:<goal>[@<execution>] or <plugin-group-id>:<plugin-artifact-id>[:<plugin-version>]:<goal>[@<execution>]

Runes4Maven (r4m) further reworked the Lifecycle Tasks which allow following style:

[<modes>/]<lifecycle-tasks>[@<executions>]

<modes>

Modes are a comma separated list of active modes. By default the modes default and dev are available but you may define others within the pem.xml config.

<lifecycle-tasks>

Lifecycle Tasks are a comma separated list of active lifecycle-phases. Every Lifecycle Phase may have one additional modifier before and/or after it:

] or [ <phase> ] or [

Modifiers

   ']' before the phase:
       select all phases before the phase excluding the phase itself
   '[' before the phase:
       select all phases after the phase including the phase itself
   ']' after the phase:
       select all phases before the phase including the phase itself
   '[' after the phase:
       select all phases after the phase excluding the phase itself

<executions>

Executions are a comma separated list of active executions.

Examples

Install everything without running tests in 'dev' mode:

dev/]test[,install]

Run all the tests without recompiling, with the 'pipeline' execution:

[test]@pipeline

Package the project with the custom defined modes 'my-mode' & 'my-test-mode' and executions 'pipeline' & 'test':

my-mode,my-test-mode/package]@pipeline,test

Help Lifecycle [6]

Runes4Maven (r4m) provides the help lifecycle. With this the cmd mvn help is finally viable. Runes4Maven does not crawl build-plugins to attach their help goals to the help lifecycle.

But we recommend every build-plugin developer to attach their help goals to this lifecycle. In case the default maven way does not work for you, we recommend you to include a plugin-pem.xml file with the same syntax as the PEM in your jar under the path META-INF/r4m/plugin-pem.xml and set the execution 'source' field to plugin. You may of course also attach all your other goals to lifecycles in the same way.

Goals

Goal	Description
r4m:help	Prints the help-page
r4m:help-tasks	Prints goal/lifecycle tasks help-page. It describes how the new build argument 'lifecycle-tasks' works.
r4m:gen-full-pem	Discovers all loaded Executions which influence the current project build lifecycles. Discovered Executions will be condensed as much as possible and written to the 'full-pem.xml' file in the defined build directory.
r4m:gen-rel-pem	Discovers all loaded Executions which are relevant to and influence the current project build lifecycles. Discovered Executions will be condensed as much as possible and written to the 'rel-pem.xml' file in the defined build directory.
r4m:status	Shows the status of all r4m features.

Installation

Runes4Maven (r4m) reworks can be installed in two major ways:

Maven Core Extension

Runes4Maven (r4m) installed as maven core extension exposes r4m full potential. A Core Extension can be installed system wide via the ${maven.home}/lib/ext folder of you maven installation.

Or per execution by adding the CLI argument -Dmaven.ext.class.path=extension.jar

Or per project by adding it in the extensions.xml. This has to be located in the .mvn folder which has to be in the root folder of your maven project per maven definition.

We recommend the per project installation:

just place following file in the .mvn folder your projects root directory!

.mvn/extensions.xml

<extensions xmlns="http://maven.apache.org/EXTENSIONS/1.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/EXTENSIONS/1.0.0 http://maven.apache.org/xsd/core-extensions-1.0.0.xsd">
	<extension>
		<groupId>net.runeduniverse.tools.maven.r4m</groupId>
		<artifactId>r4m-maven-extension</artifactId>
		<version>1.0.1</version>
	</extension>
</extensions>

Maven Build Extension

Runes4Maven (r4m) installed as maven build extension limits its potential. Some features may not be available in this mode it will print a sizable warning!

Maven Guide Example for Build Extensions

Properties

Property	Default	Options	Description
r4m.active-profiles-inheritance	upstream	upstream, top-level, false	This property defines whether active profiles are inherited when running single modules (defined via -pl <module>) inside a multi-module-maven project. Since by default profiles activated via cli (-P<profile>) only apply to the top-level project.
r4m.fancy-output	true	true, false	Some help goals output "fancy" styled text which gets removed when logging. These goals will log in an alternate way when set to false.
r4m.generate-plugin-executions	true	true, false	This property defines whether missing active executions can be auto-generated. For further information see Issue #5.
r4m.generate-plugin-executions-on-fork	true	true, false	This property defines whether missing active executions can be auto-generated when forking. For further information see Issue #5.
r4m.lifecycle-task-request-calculator	declared	declared, sequential	This property defines how lifecycle-tasks without modifiers get interpreted. Option declared -> <phase> => [<phase>] vs option sequential -> <phase> => <phase>].
r4m.lifecycle-task-request-calculator-on-fork	sequential	declared, sequential	This property defines how maven default based goal forks, defining an execute-phase, get interpreted. Option declared -> <phase> => [<phase>] vs option sequential -> <phase> => <phase>].
r4m.missing-build-plugin-handler	warn	skip, warn, scan, download	This property defines how active goals without an active plugin definition should get handled. In case you have a plugin which requires a secondary "missing/undefined" plugin you may set this property to scan or download but be warned this slows down operation significantly. Furthermore in case you have a maven-plugin which has a secondary plugin bundled you can forceload the secondary plugin by setting this property to scan but again this slows down operation significantly and is not recommended. Please just define all required plugins!
r4m.patch-mojo-on-fork	true	true, false	This defines whether the mojos during fork can be rewritten. This 'fixes' the gui but may break other plugins which might rely on that variable downstream.

r4m-maven-extension's Issues

Feature: create atrifacts for model and model-builder

Goals

• split r4m-model from r4m-api
• split r4m-model-builder from r4m-maven-extension

So they are available as artifacts for other extensions / tools

Patch Info: Eclipse Compatibility Error on "Update Project"

Eclipse Compatibility Error

Problem:

Eclipse on startup and every time you execute "Maven" > "Update Project" the execution will crash and report an internal error. However the error is not always the same!

Reason:

We traced the error back to eclipse. It seems that eclipse tries to extract information from the project and in doing so starts a clone of the official maven-core which does not provide all the dependencies that r4m requires!

Solution:

To resolve this issue we explicitly declared the dependency and scoped it as compile.

The fix will be deployed via the patch-version r4m-maven-extension: 1.0.1!

Should updating to >1.0.1 not fix the issue for you...

1. ... you will have to wipe out the older versions of this extension in your maven repository: Delete <user-home>/.m2/repository/net/runeduniverse/tools/maven/r4m/r4m-maven-extension.
2. ... you should restart your IDE (Eclipse)

Feature: Mode & Execution Launch Parameters for Lifecycle Phases from CLI

Goals

make it easier to use and provide more cli options

Before

• A phase can be executed via a mode by running a phase which forks the phase.
  Basically only within a forked state
• Same behavior as for Modes applies for Execution evocation of phases
• Basic Maven sequential phase execution behavior can be called by prefix but spams available lifecycle phase output

sequential phase execution behavior:

mvn dev-<phase>

After

• Define a Mode by phase prefix
• Define an Execution by phase postfix
• Switch phase execution behavior with + flag before phase

mvn [<mode>/][+]<phase>[@<execution>]

Dependencies: implement java-utils-maven

Goals

• move general tools to net.runeduniverse.lib.utils:utils-maven

Bug: External PEM Extensions not loading

PEM Extensions included in other (build-)extensions don't get loaded!

This bug is probably caused by r4m not searching additional extension realms for plexus artifacts

Bug: Improper identification of other maven-extensions without goals

Problem:
When r4m finds an extension which is missing its PluginDescripter file the crash is only logged but not counted in it's R4MLifecycleParticipant.unidentifiablePlugins collection.

Operation is not influenced by this but causes considerable console spam!

Solution:
Extensions discovered via R4MLifecycleParticipant.scanCoreExtensions() should not get logged when missing their PluginDescripter file.

Bug: Plugin <configuration> missing on active Profile

Plugin configuration doesn't get implemented when injecting with active profiles.

Feature: Rework Phase Tasks

Rework Phase Tasks / Phase Ranges

Currently one is expected to define phases like +install.
This will be changed to install] to express "all phases in the lifecycle of before the in question".

Furthermore [install will be supported to express "all phases in the lifecycle of after the in question".

Another feature will be to define call on phases after a certain point.

For example:

The package] phase has been called previously and you want to finish the lifecycle but not deploy the artifact.
Now the phase-task package[,]deploy can be used.

Added Properties

r4m.lifecycle-task-request-calculator and r4m.lifecycle-task-request-calculator-on-fork

the two properties following values & effects:

declared: treats <phase> like [<phase>]

sequential: treats <phase> like <phase>]

Error with task range when Property is set

java.lang.StringIndexOutOfBoundsException when property r4m.lifecycle-task-request-calculator is set to sequential

executed task range is mvn clean install] -e

[ERROR] begin 0, end -1, length 5
java.lang.StringIndexOutOfBoundsException: begin 0, end -1, length 5
    at java.lang.String.checkBoundsBeginEnd (String.java:4606)
    at java.lang.String.substring (String.java:2709)
    at net.runeduniverse.tools.maven.r4m.lifecycle.SequentialLifecycleTaskReqCalcDelegate.splitEntries (SequentialLifecycleTaskReqCalcDelegate.java:76)
    at net.runeduniverse.tools.maven.r4m.lifecycle.DefaultLifecycleTaskReqCalcDelegate.calculateTaskRequest (DefaultLifecycleTaskReqCalcDelegate.java:51)
    at net.runeduniverse.tools.maven.r4m.lifecycle.AdvancedLifecycleExecutionPlanCalculator.calculateMojoExecutions (AdvancedLifecycleExecutionPlanCalculator.java:290)
    at net.runeduniverse.tools.maven.r4m.lifecycle.AdvancedLifecycleExecutionPlanCalculator.calculateExecutionPlan (AdvancedLifecycleExecutionPlanCalculator.java:166)
    at net.runeduniverse.tools.maven.r4m.lifecycle.AdvancedLifecycleExecutionPlanCalculator.calculateExecutionPlan (AdvancedLifecycleExecutionPlanCalculator.java:182)
    at org.apache.maven.lifecycle.internal.builder.BuilderCommon.resolveBuildPlan (BuilderCommon.java:98)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:111)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:81)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build (SingleThreadedBuilder.java:56)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute (LifecycleStarter.java:128)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:294)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:192)
    at org.apache.maven.DefaultMaven.execute (DefaultMaven.java:105)
    at org.apache.maven.cli.MavenCli.execute (MavenCli.java:960)
    at org.apache.maven.cli.MavenCli.doMain (MavenCli.java:293)
    at org.apache.maven.cli.MavenCli.main (MavenCli.java:196)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke0 (Native Method)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke (NativeMethodAccessorImpl.java:77)
    at jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke (DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke (Method.java:568)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced (Launcher.java:282)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch (Launcher.java:225)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode (Launcher.java:406)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main (Launcher.java:347)
[ERROR] 
[ERROR] Re-run Maven using the -X switch to enable full debug logging.