Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "M2E/Extension Development"
Line 15: | Line 15: | ||
* provide metadata to metadata to register the project configurator with m2e and to map maven plugin execution to the project configurator | * provide metadata to metadata to register the project configurator with m2e and to map maven plugin execution to the project configurator | ||
− | + | == m2e/antlr3 code generation support explained == | |
− | As an example, here is explanation of how different parts of | + | As an example, here is explanation of how different parts of [https://github.com/sonatype/m2eclipse-extras/tree/0.13.0.20110622-1538/org.sonatype.m2e.antlr m2e/antlr] fit together |
− | On command line, | + | On command line, [http://www.antlr.org/antlr3-maven-plugin/usage.html antlr3-maven-plugin], reads ANTLR grammar files from directory specified by ${sourceDirectory} plugin configuration parameter (defaults to src/main/antlr3) and generates output files in directory specified by ${outputDirectory} plugin configuration parameter (defaults to target/generated-sources/antlr3). |
− | ==== AntlrProjectConfigurator and corresponding metadata ==== | + | ==== [https://github.com/sonatype/m2eclipse-extras/blob/0.13.0.20110622-1538/org.sonatype.m2e.antlr/src/org/sonatype/m2e/antlr/internal/AntlrProjectConfigurator.java AntlrProjectConfigurator] and corresponding metadata ==== |
− | + | [http://git.eclipse.org/c/m2e/m2e-core.git/tree/org.eclipse.m2e.jdt/src/org/eclipse/m2e/jdt/AbstractJavaProjectConfigurator.java?id=releases/1.0/1.0.0.20110607-2117 AbstractJavaProjectConfigurator] is a convenience abstract implementation of AbstractProjectConfigurator that provides default behaviour common to many java code generation m2e extensions. AbstractJavaProjectConfigurator assumes single additional java source folder needs to be configured for the project and the source folder location is defined by ${outputDirectory} maven plugin configuration parameter. This allows very simple ANTLR project configurator implementation (is explained below) | |
public class AntlrProjectConfigurator | public class AntlrProjectConfigurator | ||
Line 72: | Line 72: | ||
</extension> | </extension> | ||
− | === | + | === [https://github.com/sonatype/m2eclipse-extras/blob/0.13.0.20110622-1538/org.sonatype.m2e.antlr/src/org/sonatype/m2e/antlr/internal/AntlrBuildParticipant.java AntlrBuildParticipant] === |
AntlrBuildParticipant generates java source files (any resources generated by ANTLR, to be precise) during eclipse incremental and full builds. | AntlrBuildParticipant generates java source files (any resources generated by ANTLR, to be precise) during eclipse incremental and full builds. | ||
Line 100: | Line 100: | ||
=== Testing m3e/antlr code generation support === | === Testing m3e/antlr code generation support === | ||
− | == Project directory structure overview == | + | == Building the code and generating p2 repository == |
+ | |||
+ | === Project directory structure overview === | ||
org.somecatchyname/ <= project basedir, all project files are under this directory | org.somecatchyname/ <= project basedir, all project files are under this directory |
Revision as of 09:59, 22 June 2011
Contents
Prerequisites
Some OSGi bundle development and PDE knowledge is assumed. TODO link to some PDE documentation and tutorials
Java code generation overview
Although there are no strict rules, usually maven java code generation plugins like antlr3-maven-plugin or maven-jaxb-plugin take one or more input files from project source tree and generate a number java source files in a subdirectory of target/generated-sources/ directory. These generated sources are usually required to compile and/or run project tests.
To properly support code generation inside Eclipse IDE workspace, the IDE generally needs to perform some configuration (semi) statically during project import and then do actually code generation either on request or automatically as part of workspace build.
m2e extension that provides support for generation will typically need to
- implement a subclass of org.eclipse.m2e.jdt.AbstractJavaProjectConfigurator to perform necessary project configuration
- implement subclass of MojoExecutionBuildParticipant to delegate actual code generation to underlying maven plugin goal
- provide metadata to metadata to register the project configurator with m2e and to map maven plugin execution to the project configurator
m2e/antlr3 code generation support explained
As an example, here is explanation of how different parts of m2e/antlr fit together
On command line, antlr3-maven-plugin, reads ANTLR grammar files from directory specified by ${sourceDirectory} plugin configuration parameter (defaults to src/main/antlr3) and generates output files in directory specified by ${outputDirectory} plugin configuration parameter (defaults to target/generated-sources/antlr3).
AntlrProjectConfigurator and corresponding metadata
AbstractJavaProjectConfigurator is a convenience abstract implementation of AbstractProjectConfigurator that provides default behaviour common to many java code generation m2e extensions. AbstractJavaProjectConfigurator assumes single additional java source folder needs to be configured for the project and the source folder location is defined by ${outputDirectory} maven plugin configuration parameter. This allows very simple ANTLR project configurator implementation (is explained below)
public class AntlrProjectConfigurator extends AbstractJavaProjectConfigurator { @Override public AbstractBuildParticipant getBuildParticipant( IMavenProjectFacade projectFacade, MojoExecution execution, IPluginExecutionMetadata executionMetadata ) { return new AntlrBuildParticipant( execution ); } }
The follow extension in plugin.xml registers ANTLR project configurator with m2e
<extension point="org.eclipse.m2e.core.projectConfigurators"> <configurator class="org.sonatype.m2e.antlr.internal.AntlrProjectConfigurator" id="org.sonatype.m2e.antlr.antlrConfigurator" name="ANTLR Project Configurator"> </configurator> </extension>
lifecycle-mapping-metadata.xml located at the root of the project (and at the root of OSGi bundle jar at runtime) maps antlr3-maven-plugin antlr goal to ANTLR project configurator. Note that configurator id in the mapping matches configurator id defined in the extension point above.
<pluginExecution> <pluginExecutionFilter> <groupId>org.antlr</groupId> <artifactId>antlr3-maven-plugin</artifactId> <versionRange>[3.1.1,)</versionRange> <goals> <goal>antlr</goal> </goals> </pluginExecutionFilter> <action> <configurator> <id>org.sonatype.m2e.antlr.antlrConfigurator</id> </configurator> </action> </pluginExecution>
And finally, the following extension in plugin.xml registers m2e extension as lifecycle mapping metadata source with m2e. This is mostly needed as performance optimization, because without this extension m2e would have to search lifecycle-mapping-metadata.xml file in all installed eclipse plugins.
<extension point="org.eclipse.m2e.core.lifecycleMappingMetadataSource"> </extension>
AntlrBuildParticipant
AntlrBuildParticipant generates java source files (any resources generated by ANTLR, to be precise) during eclipse incremental and full builds.
First AntlrBuildParticipant checks if any of the grammar files have changed and short-cuts code generation if there were no changes.
File source = maven.getMojoParameterValue(getSession(), getMojoExecution(), "sourceDirectory", File.class); Scanner ds = buildContext.newScanner( source ); // delta or full scanner ds.scan(); String[] includedFiles = ds.getIncludedFiles(); if (includedFiles == null || includedFiles.length <= 0 ) { return null; }
Then, AntlrBuildParticipant delegates to MojoExecutionBuildParticipant.build to execute antlr3-maven-plugin antlr goal. This generates resources on filesystem, but does not update eclipse workspace
Set<IProject> result = super.build( kind, monitor );
Finally, AntlrBuildParticipant refreshes generation output folder in workspace
File generated = maven.getMojoParameterValue(getSession(), getMojoExecution(), "outputDirectory", File.class); if (generated != null) { buildContext.refresh( generated ); }
Testing m3e/antlr code generation support
Building the code and generating p2 repository
Project directory structure overview
org.somecatchyname/ <= project basedir, all project files are under this directory org.somecatchyname.m2e/ <= main bundle project src/ pom.xml org.somecatchyname.m2e.tests/ <= automated tests (optional, but highly recommended) src/ pom.xml org.somecatchyname.m2e.feature/ <= eclipse feature project feature.xml pom.xml pom.xml <= aggregator pom.xml
Submitting M2E marketplace entries