mirror of https://github.com/apache/maven.git
o removing marmalade references
git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@291208 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Jason van Zyl
parent
00f18c515d
commit
bb95d2c1cc
|
|
@ -1,417 +0,0 @@
|
|||
--------
|
||||
Antlib for Maven 2.0
|
||||
--------
|
||||
Brett Porter
|
||||
--------
|
||||
24 June 2005
|
||||
--------
|
||||
|
||||
Antlib for Maven 2.0
|
||||
|
||||
Maven 2.0 now comes with a set of Ant tasks that can be used to utilise Maven's artifact handling features
|
||||
from within Ant. This includes:
|
||||
|
||||
* <Dependency management> - including transitive dependencies, scope recognition and SNAPSHOT handling
|
||||
|
||||
* <Artifact deployment> - file and SSH based deployment to a Maven repository
|
||||
|
||||
* <POM processing> - for reading a Maven 2.0 <<<pom.xml>>> file
|
||||
|
||||
The Ant tasks can be downloaded from {{{download.html#ant} Maven 2.0 download page}}.
|
||||
|
||||
Installing the Ant Tasks
|
||||
|
||||
For convenience, the Ant task and all its dependencies are packaged together as a single JAR file.
|
||||
|
||||
There are two ways to use the tasks from your scripts.
|
||||
|
||||
* Intalling in Ant's <<<lib>>> directory
|
||||
|
||||
This is the simplest installation method but requires changes on every machine using the build file.
|
||||
You can place the JAR in your Ant <<<lib>>> directory, include it in the <<<CLASSPATH>>> environment variable,
|
||||
or pass it in to Ant using the <<<-lib>>> command line parameter.
|
||||
|
||||
Using this method, to make the tasks available in your build file, add the following namespace to the start of
|
||||
the file:
|
||||
|
||||
-----
|
||||
<project ... xmlns:artifact="antlib:org.apache.maven.artifact.ant">
|
||||
...
|
||||
-----
|
||||
|
||||
* Declaring a <<<typedef>>>
|
||||
|
||||
Using a <<<typedef>>> declaration allows you to store the library anywhere you like (such as source control)
|
||||
and put it's location in the build file. This can be used to bootstrap the tasks by using <<<get>>> to obtain
|
||||
the library, and then reference it from the build script.
|
||||
|
||||
The following example shows how to set it up, assuming the library is in the <<<lib>>> subdirectory of your current
|
||||
project.
|
||||
|
||||
-----
|
||||
<project ... xmlns:artifact="urn:maven-artifact-ant">
|
||||
...
|
||||
<typedef resource="org/apache/maven/artifact/ant/antlib.xml" uri="urn:maven-artifact-ant">
|
||||
<classpath>
|
||||
<pathelement location="lib/maven-artifact-ant-2.0-beta-1.jar" />
|
||||
</classpath>
|
||||
</typedef>
|
||||
...
|
||||
-----
|
||||
|
||||
Using the Antlib
|
||||
|
||||
* Declaring Dependencies
|
||||
|
||||
The main purpose of the antlib is to utilise Maven's {{{dependencies.html} dependency management features}}.
|
||||
|
||||
This is achieved with the <<<dependencies>>> task. The simplest usage involves specifying your dependencies inline,
|
||||
such as in the following example:
|
||||
|
||||
-----
|
||||
<artifact:dependencies pathId="dependency.classpath">
|
||||
<dependency groupId="org.apache.maven.wagon" artifactId="wagon-provider-test"
|
||||
version="1.0-alpha-2"/>
|
||||
<dependency groupId="org.codehaus.modello" artifactId="modello-core"
|
||||
version="1.0-alpha-2-SNAPSHOT"/>
|
||||
<dependency groupId="javax.servlet" artifactId="servlet-api"
|
||||
version="2.4" scope="provided" />
|
||||
</artifact:dependencies>
|
||||
-----
|
||||
|
||||
The above example will download those 3 dependencies, and their dependencies, and so on. They will be stored in
|
||||
the default local repository location, <<<$\{user.home\}/.m2/repository>>>.
|
||||
|
||||
You can also use a Maven 2.0 POM to declare your dependencies, which is {{{#POM} explained below}}. This is a
|
||||
recommended practice so that you can reuse the file to deploy your own artifacts.
|
||||
|
||||
You may have noticed the <<<pathId>>> reference. This is optional, but if given will create a classpath reference
|
||||
that includes the local files downloaded as dependencies. This is usually used to pass to <<<javac>>> or other tasks:
|
||||
|
||||
-----
|
||||
<javac ...>
|
||||
<classpath refid="dependency.classpath" />
|
||||
...
|
||||
</javac>
|
||||
-----
|
||||
|
||||
Another option you can use is <<<filesetId>>>, which will give you a fileset reference that can be used to copy
|
||||
files into a particular location. For example, to populate <<<WEB-INF/lib>>> with your dependencies, and assuming
|
||||
you passed <<<filesetId="dependeny.fileset">>> to the <<<dependencies>>> task, you could use the following:
|
||||
|
||||
-----
|
||||
<copy todir="${webapp.output}/WEB-INF/lib">
|
||||
<fileset refid="depdendency.fileset" />
|
||||
</copy>
|
||||
-----
|
||||
|
||||
You can also specify a <<<scope>>> parameter on each dependency. This changes the behaviour of
|
||||
transitive dependencies and is useful for building different types of classpaths. To see how it affects
|
||||
the behaviour of the dependencies, see the {{{dependencies.html#Dependency_Scope} Dependency Mechanism}}
|
||||
documentation in the Maven 2.0 site.
|
||||
|
||||
* Declaring Repositories
|
||||
|
||||
All of the tasks can optionally take one or more remote repositories to download from and upload to, and a
|
||||
local repository to store downloaded and installed archives to.
|
||||
|
||||
These can be specified inline, or if you choose to reuse them, they can be declared with an <<<id>>>/<<<refid>>>
|
||||
combination.
|
||||
|
||||
For example, you can specify the remote repository you want to use:
|
||||
|
||||
-----
|
||||
<artifact:remoteRepository id="remote.repository" url="http://repository.mycompany.com/" />
|
||||
...
|
||||
<artifact:dependencies>
|
||||
...
|
||||
<remoteRepository refid="remote.repository" />
|
||||
</artifact:dependencies>
|
||||
-----
|
||||
|
||||
If no remote repositories are specified, the default {{{http://repo1.maven.org/maven2} http://repo1.maven.org/maven2}}
|
||||
is used.
|
||||
|
||||
<<Note:>> to work with transitive dependencies, you <must> use a Maven 2.0 repository.
|
||||
|
||||
If your repository requires authentication, you can provide this as a nested element. It accepts the
|
||||
attributes <<<username>>>, <<<password>>>, and for SSH based repositories <<<privateKey>>>
|
||||
and <<<passphrase>>>. For example:
|
||||
|
||||
-----
|
||||
<authentication username="brett" privateKey="${user.home}/.ssh/id_dsa" />
|
||||
-----
|
||||
|
||||
* Installing and Deploying Your Own Artifacts
|
||||
|
||||
If you want to share your built artifacts between projects, you can use two other tasks: <<<install>>> for
|
||||
placing them in your local repository for access as dependencies in other scripts, and <<<deploy>>> for
|
||||
deploying them to an remote location you have set up to serve as a repository in your organisation.
|
||||
|
||||
-----
|
||||
...
|
||||
<artifact:pom id="maven.project" file="pom.xml" />
|
||||
|
||||
<artifact:install file="target/maven-artifact-ant-2.0-alpha-3.jar">
|
||||
<pom refid="maven.project"/>
|
||||
</artifact:install>
|
||||
|
||||
<artifact:deploy file="target/maven-artifact-ant-2.0-alpha-3.jar">
|
||||
<remoteRepository url="scp://localhost/www/repository">
|
||||
<authentication username="${repository.username}" privateKey="${user.home}/.ssh/id_dsa"/>
|
||||
</remoteRepository>
|
||||
<pom refid="maven.project"/>
|
||||
</artifact:deploy>
|
||||
...
|
||||
-----
|
||||
|
||||
Note that the installation and deployment require that you have a Maven 2.0 POM file to deploy along with it.
|
||||
These are required for the transitive dependency mechanism to work effectively, and can be quite simple to
|
||||
create.
|
||||
|
||||
* Using a Maven {POM} File
|
||||
|
||||
In Maven, the Project Object Model (POM) represents a unit of work - one exists for each artifact that is built.
|
||||
|
||||
Maven 2.0 POM files are required for deploying your own artifacts to a repository for use in the dependencies
|
||||
elements of other projects.
|
||||
|
||||
They can also be reused for declaring your own dependencies, instead of specifying the inline version given earlier.
|
||||
|
||||
Here is the earlier example, expressed as a POM:
|
||||
|
||||
-----
|
||||
<project>
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
<groupId>com.mycompany.project</groupId>
|
||||
<artifactId>project-model</artifactId>
|
||||
<version>1.0-SNAPSHOT</version>
|
||||
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.apache.maven.wagon</groupId>
|
||||
<artifactId>wagon-provider-api</artifactId>
|
||||
<version>1.0-alpha-2</version>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.codehaus.modello</groupId>
|
||||
<artifactId>modello-core</artifactId>
|
||||
<version>1.0-alpha-2-SNAPSHOT</version>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>javax.servlet</groupId>
|
||||
<artifactId>servlet-api</artifactId>
|
||||
<version>2.4</version>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</project>
|
||||
-----
|
||||
|
||||
These elements represent:
|
||||
|
||||
* <modelVersion> - this is the version of the POM layout in use, currently <<<4.0.0>>>
|
||||
|
||||
* <groupId> - the group ID represents your organisation and project name, much like a Java package name.
|
||||
This must be universally unique. This becomes the base directory in the repository as well.
|
||||
|
||||
* <artifactId> - the artifact ID represents the current build unit. It usually equals the filename of the
|
||||
resulting file, and must be unique within the group.
|
||||
|
||||
* <version> - the version of the artifact you are building.
|
||||
|
||||
* <dependencies> - the artifacts the project is dependant on.
|
||||
|
||||
This is all that is required for most projects. However, it is also possible to use other fields available in
|
||||
Maven to describe your project, and reference them from your build script.
|
||||
|
||||
To access a POM as Ant properties, you must define it as a reference. For example, to access the version from a POM,
|
||||
you could use the following:
|
||||
|
||||
-----
|
||||
<artifact:pom id="maven.project" file="pom.xml" />
|
||||
|
||||
<echo>The version is ${maven.project.version}</echo>
|
||||
-----
|
||||
|
||||
You can also access nested parts of the POM. For example, you can read the default value of the <<<directory>>>
|
||||
element within the <<<build>>> element using a <<<.>>> separator.
|
||||
|
||||
-----
|
||||
<artifact:pom id="project" file="pom.xml" />
|
||||
|
||||
<echo>The version is ${project.build.directory}</echo>
|
||||
-----
|
||||
|
||||
For more information on the elements available in the POM, see the {{{maven-model/maven.html} descriptor reference}}.
|
||||
|
||||
The Settings File
|
||||
|
||||
The POM can be used to represent most of the information that the tasks have access to, including remote
|
||||
repositories. For information that is user or environment specific, such as the <<<authentication>>> tag, are
|
||||
specified in the <<<settings.xml>>> file in Maven, and can be accessed from the Ant tasks also.
|
||||
|
||||
The file is first looked for in <<<$\{user.home\}/.ant/settings.xml>>>, then in <<<$\{user.home\}/.m2/settings.xml>>>
|
||||
so that the settings can be shared with Maven 2.0 itself.
|
||||
|
||||
For example, to specify your proxy settings, you would specify the following <<<settings.xml>>> file:
|
||||
|
||||
-----
|
||||
<settings>
|
||||
<proxies>
|
||||
<proxy>
|
||||
<protocol>http</protocol>
|
||||
<host>proxy.host.net</host>
|
||||
<port>8080</port>
|
||||
<nonProxyHosts>localhost</nonProxyHosts>
|
||||
</proxy>
|
||||
</proxies>
|
||||
</settings>
|
||||
-----
|
||||
|
||||
For more information in configuring <<<settings.xml>>>, see:
|
||||
|
||||
* {{{configuration.html} Configuring Maven}}.
|
||||
|
||||
* {{{maven-settings/settings.html} Settings Descriptor Reference}}.
|
||||
|
||||
* There is a
|
||||
{{{http://svn.apache.org/repos/asf/maven/components/trunk/maven-core/src/conf/settings.xml} sample settings file}}
|
||||
in the Maven installation.
|
||||
|
||||
Sample Ant Script
|
||||
|
||||
The file
|
||||
{{{http://svn.apache.org/repos/asf/maven/components/trunk/maven-artifact-ant/sample.build.xml} sample.build.xml}}
|
||||
is a sample Ant script showing some of the functionality in action.
|
||||
|
||||
Getting Help
|
||||
|
||||
If you have any questions specific to the Ant tasks, please contact the
|
||||
{{{mail-lists.html} Maven Users Mailing List}}.
|
||||
|
||||
For more on the Maven functionality behind them, try the following links:
|
||||
|
||||
* {{{dependencies.html} Dependency Mechanism}}
|
||||
|
||||
* {{{maven-settings/settings.html} Settings Reference}}
|
||||
|
||||
* {{{maven-model/maven.html} POM Reference}}
|
||||
|
||||
Task Reference
|
||||
|
||||
* <<<dependencies>>>
|
||||
|
||||
This task will check if any of the specified dependencies, and their dependencies are missing or updated, and
|
||||
download them if necessary. The dependencies will be made available as a fileset or path reference.
|
||||
|
||||
The dependencies task accepts the following attributes:
|
||||
|
||||
*-----------------+--------------------------------------------------------+
|
||||
| <<<verbose>>> | If <<<true>>> this displays the results of each dependency resolution and their relationships. Default is <false>.
|
||||
*-----------------+--------------------------------------------------------+
|
||||
| <<<filesetId>>> | The reference ID to store a fileset under of the resolved dependencies.
|
||||
*-----------------+--------------------------------------------------------+
|
||||
| <<<pathId>>> | The reference ID to store a path under of the resolved dependencies.
|
||||
*-----------------+--------------------------------------------------------+
|
||||
|
||||
The task can include the <<<dependency>>> nested type, in addition to the other shared types explained later.
|
||||
You must include at least one <<<dependency>>> element, or a single <<<pom>>> element, but not both.
|
||||
|
||||
** <<<dependency>>>
|
||||
|
||||
*------------------+--------------------------------------------------------+
|
||||
| <<<groupId>>> | The group ID for of the dependency. <Required>
|
||||
*------------------+--------------------------------------------------------+
|
||||
| <<<artifactId>>> | The artifact ID for of the dependency. <Required>
|
||||
*------------------+--------------------------------------------------------+
|
||||
| <<<version>>> | The version of the dependency. <Required>
|
||||
*------------------+--------------------------------------------------------+
|
||||
| <<<type>>> | The type of the dependency. The default is <<<jar>>>.
|
||||
*------------------+--------------------------------------------------------+
|
||||
| <<<scope>>> | The scope of the usage of the dependency, which affects which of its dependencies are also retrieved. This can be <<<compile>>>, <<<runtime>>>, <<<test>>>, <<<provided>>>.
|
||||
*------------------+--------------------------------------------------------+
|
||||
|
||||
The dependency can also nest multiple <<<exclusion>>> elements.
|
||||
|
||||
*** <<<exclusion>>>
|
||||
|
||||
An exclusion can be used to prevent the resolution of a particular artifact in the tree of the dependency.
|
||||
|
||||
*------------------+--------------------------------------------------------+
|
||||
| <<<groupId>>> | The group ID for of the dependency to exclude. <Required>
|
||||
*------------------+--------------------------------------------------------+
|
||||
| <<<artifactId>>> | The artifact ID for of the dependency to exclude. <Required>
|
||||
*------------------+--------------------------------------------------------+
|
||||
|
||||
* <<<install>>>
|
||||
|
||||
This task will install the given file into the local repository. It is stored using the information in the supplied
|
||||
POM.
|
||||
|
||||
*------------------+--------------------------------------------------------+
|
||||
| <<<file>>> | The file to install in the local repository. <Required>
|
||||
*------------------+--------------------------------------------------------+
|
||||
|
||||
The task must also take a nested <<<pom>>>, and can have an optional <<<localRepository>>> element.
|
||||
|
||||
* <<<deploy>>>
|
||||
|
||||
This task will deploy the given file into the remote repository. It is stored using the information in the supplied
|
||||
POM.
|
||||
|
||||
*------------------+--------------------------------------------------------+
|
||||
| <<<file>>> | The file to deploy in the remote repository. <Required>
|
||||
*------------------+--------------------------------------------------------+
|
||||
|
||||
The task must also take a nested <<<pom>>>, and can have an optional <<<remoteRepository>>> element. If no
|
||||
<<<remoteRepository>>> element is given, the <<<distributionManagement>>> section of the POM is used.
|
||||
|
||||
Type Reference
|
||||
|
||||
* <<<localRepository>>>
|
||||
|
||||
Specifies the location of the local repository of artifacts.
|
||||
|
||||
*------------------+--------------------------------------------------------+
|
||||
| <<<location>>> | The directory of the local repository. <Required>
|
||||
*------------------+--------------------------------------------------------+
|
||||
| <<<layout>>> | The layout of the local repository. The valid options are <<<legacy>>> (Maven 1), or <<<default>>> (Maven 2).
|
||||
*------------------+--------------------------------------------------------+
|
||||
|
||||
* <<<remoteRepository>>>
|
||||
|
||||
Specifies the location of the remote repository.
|
||||
|
||||
*----------------------+--------------------------------------------------------+
|
||||
| <<<url>>> | The URL of the repository. <Required>
|
||||
*----------------------+--------------------------------------------------------+
|
||||
| <<<layout>>> | The layout of the remote repository. The valid options are <<<legacy>>> (Maven 1), or <<<default>>> (Maven 2).
|
||||
*----------------------+--------------------------------------------------------+
|
||||
| <<<snapshotPolicy>>> | How often to check for updates on dependencies with a version that includes <<<SNAPSHOT>>>. Valid values are <<<never>>>, <<<interval:MINUTES>>>, <<<daily>>> (<default)>, <<<always>>>.
|
||||
*----------------------+--------------------------------------------------------+
|
||||
| <<<checksumPolicy>>> | How to treat missing or incorrect checksums for the dependencies that are downloaded. Valid values are <<<warn>>> (<default>) and <<<fail>>>.
|
||||
*----------------------+--------------------------------------------------------+
|
||||
|
||||
The remote repository can also nest the following elements: <<<authentication>>> and <<<proxy>>>.
|
||||
|
||||
** <<<proxy>>>
|
||||
|
||||
The proxy element is typically used for HTTP repositories. The layout is the same as in the
|
||||
{{{maven-settings/settings.html#Proxy} settings reference}}.
|
||||
|
||||
** <<<authentication>>>
|
||||
|
||||
The authentication element is used for passing a username, password and other credentials to the repository either
|
||||
on upload or download. The layout is the same as in the {{{maven-settings/settings.html#Server} settings reference}}.
|
||||
|
||||
* <<<pom>>>
|
||||
|
||||
The POM element will load a POM file and make it available as a reference for the other tasks or as properties.
|
||||
|
||||
*------------------+--------------------------------------------------------+
|
||||
| <<<file>>> | The file of the POM to load. <Required>
|
||||
*------------------+--------------------------------------------------------+
|
||||
|
||||
|
|
@ -53,8 +53,5 @@ Developing Maven 2.0 Plugins
|
|||
|
||||
* Resources
|
||||
|
||||
[[1]] {{{developers/developing-plugins-with-marmalade.html}Developing plugins
|
||||
with Marmalade}}
|
||||
|
||||
[[2]] {{{developers/mojo-api-specification.html}Mojo API specification}}
|
||||
[[1]] {{{developers/mojo-api-specification.html}Mojo API specification}}
|
||||
|
||||
|
|
|
|||
|
|
@ -223,7 +223,7 @@ m2 clean:clean install
|
|||
@phase generate-sources
|
||||
----
|
||||
|
||||
<<Note:>> <Some plugin languages such as Marmalade have different ways of specifying mojo level declarations.
|
||||
<<Note:>> <Some plugin languages have different ways of specifying mojo level declarations.
|
||||
Please refer to the specific plugin development documentation for more information.>
|
||||
|
||||
Once this is specified, it will automatically be registered when the goal is listed in the project POM, as described
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ Plugin Overview
|
|||
|
||||
A Mojo is really just a goal in Maven 2, and plug-ins consist of
|
||||
any number of goals (Mojos). Mojos can be defined as annotated Java classes or
|
||||
as a XML plugin script if a plugin is defined in Marmalade. A Mojo specifies
|
||||
Beanshell script. A Mojo specifies
|
||||
metadata about a goal: a goal name, which phase of the lifecycle it fits into,
|
||||
and the parameters it is expecting.
|
||||
|
||||
|
|
@ -175,8 +175,8 @@ Plugin Overview
|
|||
isn't going to be the best choice for performance, and the development team
|
||||
thought it wise to adopt an approach which would allow plugin developers to
|
||||
choose from an array of plugin implementation choices. The first choice in
|
||||
Maven 2 should be Java plugins, but if you are used to defining plugins in Jelly
|
||||
you may also define a plugin using a scripting language known as Marmalade.
|
||||
Maven 2 should be Java plugins, but you may also use one of the supported
|
||||
scripting languages like Beanshell.
|
||||
|
||||
To summarize, the development team saw some critical gaps in the API and
|
||||
architecture of Maven 1.0 plug-ins, and the team decided that addressing
|
||||
|
|
|
|||
|
|
@ -38,7 +38,6 @@
|
|||
</menu>
|
||||
<menu name="Plugin Developers">
|
||||
<item name="Plugin Development Guide" href="/developers/plugin-development-guide.html"/>
|
||||
<item name="Developing Plugins with Marmalade" href="/developers/developing-plugins-with-marmalade.html"/>
|
||||
</menu>
|
||||
<menu name="Developers">
|
||||
<item name="Developers Guide" href="/developers/development-guide.html"/>
|
||||
|
|
|
|||
|
|
@ -1,342 +0,0 @@
|
|||
<?xml version="1.0"?>
|
||||
<!--
|
||||
/*
|
||||
* Copyright 2001-2004 The Apache Software Foundation.
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
*/
|
||||
-->
|
||||
|
||||
<document>
|
||||
|
||||
<properties>
|
||||
<title>Developing Plugins with Marmalade</title>
|
||||
<author email="jdcasey@apache.org">John Casey</author>
|
||||
</properties>
|
||||
|
||||
<body>
|
||||
<section name="Developing Plugins with Marmalade">
|
||||
<p>
|
||||
NOTE: Compare this tutorial to
|
||||
<a href="http://maven.apache.org/using/developing-plugins.html">Developing
|
||||
Plugins</a>
|
||||
from the Maven 1.0 website. Marmalade is meant to be quite similar to Jelly in its
|
||||
syntax, so this process should be very familiar to Maven 1.0 plugin developers.
|
||||
</p>
|
||||
<!-- TODO
|
||||
<p>
|
||||
If you need some background on how plugins fit into the execution model of Maven 2.0, try reading the
|
||||
<a href="architecture.html">Maven 2.0 Architecture</a>.
|
||||
</p>
|
||||
-->
|
||||
|
||||
<subsection name="Graduating from Jelly: Plugins in Marmalade">
|
||||
<p>
|
||||
Beginning in Maven 2.0, plugins can be implemented in various languages, including Marmalade, Java and
|
||||
Beanshell.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Marmalade is a next-generation Jelly-like XML language, and was chosen for early inclusion in Maven 2.0 to
|
||||
ease migration from Maven 1.0, and to provide a way to incorporate Ant scripts into a build project.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Marmalade currently has basic syntax compatibility with Jelly, and some measure of Jelly taglib
|
||||
compatibility... and this support will continue to improve as Marmalade matures. As such, Marmalade can allow
|
||||
the plugin developer the freedom to concentrate on porting between project models and core facilities, rather
|
||||
than worrying about changing implementation languages.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Marmalade is still only a fledgling project, and while it's core engine is sophisticated and mature, it's
|
||||
support for Jelly and other taglibs is still growing at a brisk pace. In order to provide as much Jelly
|
||||
functionality out-of-the-box to Maven 2.0 users, Marmalade has an available compatibility layer for Jelly,
|
||||
which will allow the user to embed Jelly within Marmalade for the taglibs that have not yet been ported to
|
||||
native Marmalade.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For those Maven 1.x users who have implemented their own plugins using Jelly, Marmalade can be
|
||||
an extremely powerful language for porting to Maven 2.0.
|
||||
</p>
|
||||
|
||||
<p>For more information on Marmalade, see the
|
||||
<a href="http://marmalade.codehaus.org">Marmalade website.</a>
|
||||
</p>
|
||||
</subsection>
|
||||
|
||||
<subsection name="Marmalade Plugin Basics">
|
||||
<p>
|
||||
A plugin implemented in Marmalade can contain the following:
|
||||
<ul>
|
||||
<li>[Required] One or more Marmalade scripts, each in a file with the extension
|
||||
<code>.mmld</code>
|
||||
</li>
|
||||
<li>
|
||||
[Optional] One or more Marmalade tag libraries, each consisting of:
|
||||
<ul>
|
||||
<li>One or more implementations of MarmaladeTag</li>
|
||||
<li>An implementation of
|
||||
<code>MarmaladeTagLibrary</code>
|
||||
, the constructor of which registers
|
||||
each MarmaladeTag implementation to a tag name (for use in scripts)
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
[Required] A
|
||||
<code>pom.xml</code>
|
||||
for building the plugin, which contains a script source directory
|
||||
resembling
|
||||
<code><![CDATA[<scriptSourceDirectory>src/main/scripts</scriptSourceDirectory>]]></code>
|
||||
</li>
|
||||
<li>[Optional] Plugin resources to be used from within the plugin's scripts (available on the
|
||||
classpath)</li>
|
||||
<li>[Optional] Other Java sources, which can be accessed from the plugin's scripts</li>
|
||||
</ul>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Each
|
||||
<code>.mmld</code>
|
||||
script file must provide the same basic structural elements, which define it
|
||||
as a Maven 2.0 plugin, and provide essential metadata. This metadata is used to:
|
||||
<ul>
|
||||
<li>Inject project and environmental information into the plugin (parameters)</li>
|
||||
<li>Make common infrastructural components available for use in the plugin</li>
|
||||
<li>Bind the plugin to a particular point in the build process lifecycle, if appropriate</li>
|
||||
<li>Provide a goal name to reference the plugin from inside the Maven 2.0 system</li>
|
||||
<li>Provide descriptive information about what the plugin script does</li>
|
||||
</ul>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The general structure of a Marmalade plugin script is:
|
||||
</p>
|
||||
<source><![CDATA[
|
||||
<!-- The term mojo is a play on POJO, meant to mean "Maven POJO".
|
||||
| Mojos correspond to goals in Maven 2.0.
|
||||
-->
|
||||
<mojo xmlns="marmalade:mojo">
|
||||
<metadata>
|
||||
<goal>pluginGoalName</goal>
|
||||
<lifecyclePhase>compile</lifecyclePhase> <!-- Bind to the 'compile' phase of the standard build lifecycle. -->
|
||||
<description>A description of what the plugin accomplishes for the build process.</description>
|
||||
<parameters>
|
||||
<parameter>
|
||||
<name>parameterName</name> <!-- A name for accessing the parameter from the Marmalade context. -->
|
||||
<expression>#project.build.directory</expression> <!-- The expression used to bind the parameter. -->
|
||||
<description>Description of what this parameter is used for.</description>
|
||||
</parameter>
|
||||
</parameters>
|
||||
</metadata>
|
||||
<execute>
|
||||
<!-- This is where the guts of the plugin go. Below is a sample body, wherein a file called
|
||||
| "touch.txt" will be created in the output directory (by default, in ${basedir}/target), containing
|
||||
| the content "File Content".
|
||||
-->
|
||||
<io:file xmlns:io="marmalade:io" path="${outputDirectory}/touch.txt" mkdirs="true">File Content</io:file>
|
||||
</execute>
|
||||
</mojo>]]></source>
|
||||
</subsection>
|
||||
|
||||
<subsection name="Creating Your First Plugin">
|
||||
<p>
|
||||
To start creating a plugin, you must first create a Maven 2.0 project. This is
|
||||
the same as creating any other project, for example one that builds a JAR, with
|
||||
the exception that in the case of a Marmalade plugin, you have to specify a special
|
||||
source directory in which to find script sources.
|
||||
</p>
|
||||
<p>
|
||||
In a new directory, create a
|
||||
<code>pom.xml</code>
|
||||
file like so:
|
||||
</p>
|
||||
<source><![CDATA[<project>
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<!-- for now, this is the only groupId acceptable for maven plugins -->
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
|
||||
<!-- uses a standard naming convention -->
|
||||
<artifactId>maven-hello-plugin</artifactId>
|
||||
|
||||
<!-- uses this version, to make it usable without configuring this plugin from
|
||||
| the project POM.
|
||||
-->
|
||||
<version>1.0-SNAPSHOT</version>
|
||||
|
||||
<!-- Designate this project as building a maven plugin -->
|
||||
<packaging>maven-plugin</packaging>
|
||||
|
||||
<name>Maven Hello World Plugin</name>
|
||||
|
||||
<!--
|
||||
You might want to include additional information here
|
||||
eg the developers, organisation, and dependencies
|
||||
-->
|
||||
|
||||
<build>
|
||||
<scriptSourceDirectory>src/main/scripts</scriptSourceDirectory>
|
||||
|
||||
<!-- Since the script source directory is only a marker for a resource, you
|
||||
| still have to declare that directory for resource inclusion when you
|
||||
| build.
|
||||
-->
|
||||
<resources>
|
||||
<resource>
|
||||
<directory>src/main/scripts</directory>
|
||||
<includes><include>**/*.mmld</include></includes>
|
||||
</resource>
|
||||
</resources>
|
||||
</build>
|
||||
</project>]]></source>
|
||||
|
||||
<p>
|
||||
Next, create your first plugin script. As mentioned above, each script corresponds to a single
|
||||
goal within the build system, so you may need several scripts.
|
||||
</p>
|
||||
<p>
|
||||
Since this is in fact a Hello World plugin, your script will simply output
|
||||
<code>Hello, World</code>
|
||||
to the screen. Create a script in
|
||||
<code>src/main/scripts/hello.mmld</code>
|
||||
with the following contents:
|
||||
</p>
|
||||
<source><![CDATA[
|
||||
<mojo xmlns="marmalade:mojo">
|
||||
<metadata>
|
||||
<goal>hello</goal>
|
||||
<description>Say Hello to the World.</description>
|
||||
</metadata>
|
||||
<execute>
|
||||
<c:out xmlns:c="marmalade:core">Hello, World</c:out>
|
||||
</execute>
|
||||
</mojo>]]></source>
|
||||
|
||||
<p>
|
||||
Now that you can run the following command to install this into Maven's local artifact repository:
|
||||
</p>
|
||||
<source>m2 install</source>
|
||||
|
||||
<p>
|
||||
You can prove the goal exists by running it.
|
||||
</p>
|
||||
<source>m2 hello:hello</source>
|
||||
|
||||
<p>
|
||||
This execution should result in the following content being printed to the screen:
|
||||
</p>
|
||||
<source>Hello, World</source>
|
||||
</subsection>
|
||||
|
||||
<subsection name="Using Plugin Parameters">
|
||||
<p>
|
||||
While you can always reference the POM information in a script using mojo parameters with expressions
|
||||
that reference project elements, a plugin will often need to create new parameters so that it can be
|
||||
customised.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The creation of these parameters simply involves defining them in the metadata section of the script,
|
||||
and optionally providing a default value for use in the event the user doesn't need to customize the plugin.
|
||||
</p>
|
||||
<p>
|
||||
As an example, create a parameter for the salutation to be used in your script:
|
||||
</p>
|
||||
<source><![CDATA[
|
||||
<mojo xmlns="marmalade:mojo">
|
||||
<metadata>
|
||||
.
|
||||
.
|
||||
.
|
||||
<parameters>
|
||||
<parameter>
|
||||
<name>salutation</name>
|
||||
<expression>#salutation</expression>
|
||||
<default>Hello</default>
|
||||
<description>The salutation to use in greeting the world.</description>
|
||||
</parameter>
|
||||
</parameters>
|
||||
</metadata>
|
||||
.
|
||||
.
|
||||
.
|
||||
</mojo>
|
||||
]]></source>
|
||||
<p>
|
||||
Note the additional element in this parameter declaration:
|
||||
<code>default</code>
|
||||
specified a default
|
||||
salutation in case the user doesn't need or want to customize the plugin.
|
||||
</p>
|
||||
<p>
|
||||
Now, to make use of the new parameter. Inside the
|
||||
<code><![CDATA[<c:out/>]]></code>
|
||||
action, simply
|
||||
write out the customizable salutation instead of the stock phrase
|
||||
<code>Hello</code>
|
||||
:
|
||||
</p>
|
||||
<source><![CDATA[
|
||||
<c:out xmlns:c="marmalade:core">${salutation}, World.</c:out>
|
||||
]]></source>
|
||||
<p>
|
||||
Install the new plugin and run it, to verify your changes:
|
||||
</p>
|
||||
<source>m2 install
|
||||
m2 hello:hello</source>
|
||||
<p>
|
||||
Notice that the output still has the same old salutation (which is the default value of the parameter).
|
||||
Now, to customize it:
|
||||
</p>
|
||||
<source>m2 -Dsalutation=Hiya hello:hello</source>
|
||||
<p>
|
||||
The output should now read:
|
||||
</p>
|
||||
<source>Hiya, World</source>
|
||||
|
||||
<p>
|
||||
Users of this plugin can also customize the salutation for their project and avoid having to specify it on
|
||||
the command line each time. All they have to do is create a plugin entry in their
|
||||
<code>pom.xml</code>
|
||||
similar to:
|
||||
</p>
|
||||
<source><![CDATA[
|
||||
<project>
|
||||
.
|
||||
.
|
||||
.
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-hello-plugin</artifactId>
|
||||
<version>1.0-SNAPSHOT</version>
|
||||
<configuration>
|
||||
<salutation>Hiya</salutation>
|
||||
</configuration>
|
||||
</plugin>
|
||||
</plugins>
|
||||
.
|
||||
.
|
||||
.
|
||||
</build>
|
||||
</project>
|
||||
]]></source>
|
||||
</subsection>
|
||||
</section>
|
||||
</body>
|
||||
</document>
|
||||
|
||||
|
|
@ -147,11 +147,6 @@
|
|||
</i>
|
||||
</li>
|
||||
-->
|
||||
<li>
|
||||
<i>
|
||||
<a href="developers/developing-plugins-with-marmalade.html">Developing Plugins with Marmalade</a>
|
||||
</i>
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
<b>More coming soon -</b>
|
||||
|
|
|
|||
Loading…
Reference in New Issue