Author: hboutemy
Date: Sat Nov 8 23:34:05 2014
New Revision: 1637610
URL: http://svn.apache.org/r1637610
Log:
[MTOOLCHAIN-6] added documentation on custom toolchain
Added:
maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/CustomToolchainImpl.java
- copied, changed from r1637573,
maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/DefaultCustomToolchain.java
maven/plugins/trunk/maven-toolchains-plugin/src/site/apt/toolchains/custom.apt
(with props)
Removed:
maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/DefaultCustomToolchain.java
Modified:
maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/CustomToolchainFactory.java
maven/plugins/trunk/maven-toolchains-plugin/src/site/apt/toolchains/index.apt
Modified:
maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/CustomToolchainFactory.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/CustomToolchainFactory.java?rev=1637610&r1=1637609&r2=1637610&view=diff
==============================================================================
---
maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/CustomToolchainFactory.java
(original)
+++
maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/CustomToolchainFactory.java
Sat Nov 8 23:34:05 2014
@@ -63,7 +63,7 @@ public class CustomToolchainFactory
return null;
}
- DefaultCustomToolchain customToolchain = new DefaultCustomToolchain(
model, logger );
+ CustomToolchainImpl customToolchain = new CustomToolchainImpl( model,
logger );
// populate the provides section
Properties provides = getProvidesProperties( model );
@@ -95,11 +95,11 @@ public class CustomToolchainFactory
// populate the configuration section
Properties configuration = toProperties( (Xpp3Dom)
model.getConfiguration() );
- String toolHome = configuration.getProperty(
DefaultCustomToolchain.KEY_TOOLHOME );
+ String toolHome = configuration.getProperty(
CustomToolchainImpl.KEY_TOOLHOME );
if ( toolHome == null )
{
throw new MisconfiguredToolchainException( "Custom toolchain
without the "
- + DefaultCustomToolchain.KEY_TOOLHOME + " configuration
element." );
+ + CustomToolchainImpl.KEY_TOOLHOME + " configuration element."
);
}
toolHome = FileUtils.normalize( toolHome );
Copied:
maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/CustomToolchainImpl.java
(from r1637573,
maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/DefaultCustomToolchain.java)
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/CustomToolchainImpl.java?p2=maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/CustomToolchainImpl.java&p1=maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/DefaultCustomToolchain.java&r1=1637573&r2=1637610&rev=1637610&view=diff
==============================================================================
---
maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/DefaultCustomToolchain.java
(original)
+++
maven/plugins/trunk/maven-toolchains-plugin/src/it/custom-toolchain-plugin/src/main/java/org/apache/maven/plugins/toolchains/its/custom/CustomToolchainImpl.java
Sat Nov 8 23:34:05 2014
@@ -31,7 +31,7 @@ import org.codehaus.plexus.util.Os;
/**
* @author Hervé Boutemy
*/
-public class DefaultCustomToolchain
+public class CustomToolchainImpl
extends DefaultToolchain
implements CustomToolchain
{
@@ -39,7 +39,7 @@ public class DefaultCustomToolchain
public static final String KEY_TOOLHOME = "toolHome";
- public DefaultCustomToolchain( ToolchainModel model, Logger logger )
+ public CustomToolchainImpl( ToolchainModel model, Logger logger )
{
super( model, "custom", logger );
}
Added:
maven/plugins/trunk/maven-toolchains-plugin/src/site/apt/toolchains/custom.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-toolchains-plugin/src/site/apt/toolchains/custom.apt?rev=1637610&view=auto
==============================================================================
---
maven/plugins/trunk/maven-toolchains-plugin/src/site/apt/toolchains/custom.apt
(added)
+++
maven/plugins/trunk/maven-toolchains-plugin/src/site/apt/toolchains/custom.apt
Sat Nov 8 23:34:05 2014
@@ -0,0 +1,124 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you 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.
+
+ ------
+ Custom Toolchains
+ ------
+ Hervé Boutemy
+ ------
+ 2014-11-08
+ ------
+
+Custom Toolchains
+
+ You can create your own custom toolchains with plugins using them.
+
+ A full working sample is included in <<<maven-toolchains-plugin>>> ITs:
+
+ * see <<<src/it/custom-toolchain-plugin>>> for the custom toolchain and
plugin,
+
+ * see <<<src/it/use-custom-toolchain>>> for a sample project using the
toolchain through its plugin.
+
+ []
+
+ Following instructions are explanations of key points of the sample.
+
+* Creating Custom Toolchain
+
+ A toolchain consists in:
+
+ * an interface extending
{{{/ref/current/maven-core/apidocs/org/apache/maven/toolchain/Toolchain.html}<<<org.apache.maven.toolchain.Toolchain>>>}},
+
+ * an implementation of this interface, extending
+
{{{/ref/current/maven-core/apidocs/org/apache/maven/toolchain/DefaultToolchain.html}<<<org.apache.maven.toolchain.DefaultToolchain>>>}}
+ and implementing previous interface,
+
+ * a
{{{/ref/current/maven-core/apidocs/org/apache/maven/toolchain/ToolchainFactory.html}<<<org.apache.maven.toolchain.ToolchainFactory>>>}},
+ provided as Plexus component: Plexus
{{{http://plexus.codehaus.org/plexus-containers/plexus-component-annotations/}<<<@Component>>>}}
+ annotation in the class is extracted by
{{{http://plexus.codehaus.org/plexus-containers/plexus-component-metadata/}<<<plexus-component-metadata>>>}}
+ plugin.
+
+ []
+
+* Creating a Plugin Using a Toolchain
+
+ To get a configured toolchain, a plugin uses
+
{{{/ref/current/maven-core/apidocs/org/apache/maven/toolchain/ToolchainManager.html}<<<ToolchainManager>>>}}
API
+ to get epxected toolchain, then tool in the toolchain:
+
++--------+
+ @Component
+ private ToolchainManager toolchainManager;
+
+ @Parameter( defaultValue = "${session}", required = true, readonly = true )
+ private MavenSession session;
+
+ public void execute()
+ throws MojoExecutionException
+ {
+ // get the custom toolchain
+ CustomToolchain toolchain = (CustomToolchain)
toolchainManager.getToolchainFromBuildContext( "custom", session );
+
+ if ( toolchain == null )
+ {
+ throw new MojoExecutionException( "Could not find 'custom'
toolchain: please check maven-toolchains-plugin configuration." );
+ }
+
+ getLog().info( "Found 'custom' toolchain in build context." );
+
+ // get a tool from the toolchain
+ String path = toolchain.findTool( "tool" );
+
+ getLog().info( "Found expected tool named 'tool' at following
location: " + path );
+ }
++--------+
+
+ This code uses
{{{/plugin-tools/maven-plugin-plugin/examples/using-annotations.html}Maven
Plugin Tool Java 5 Annotations}}.
+
+* Using the Custom Toolchain and its Plugin
+
+ The custom toolchain implementation needs to be shared between the
toolchain-aware plugin and <<<maven-toolchains-plugin>>>:
+ this is done using Maven extension:
+
+ * if the toolchain is packaged with the plugin, this is done by declaring
the plugin as extension:
+
++--------+
+ <plugin>
+ <groupId>...</groupId>
+ <artifactId>...</artifactId>
+ <version>...</version>
+ <extensions>true</extensions><!-- to share the custom toolchain with
maven-toolchains-plugin -->
+ </plugin>
++--------+
+
+ * if the toolchain is packaged separately, to be shared by multiple plugins,
it has to be declared as a build extension:
+
++--------+
+<project>
+ <build>
+ <extensions>
+ <extension>
+ <groupId>...</groupId>
+ <artifactId>...</artifactId>
+ <version>...</version>
+ </extension>
+ </extensions>
+ </build>
+</project>
++--------+
+
+ []
Propchange:
maven/plugins/trunk/maven-toolchains-plugin/src/site/apt/toolchains/custom.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
maven/plugins/trunk/maven-toolchains-plugin/src/site/apt/toolchains/custom.apt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Modified:
maven/plugins/trunk/maven-toolchains-plugin/src/site/apt/toolchains/index.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-toolchains-plugin/src/site/apt/toolchains/index.apt?rev=1637610&r1=1637609&r2=1637610&view=diff
==============================================================================
---
maven/plugins/trunk/maven-toolchains-plugin/src/site/apt/toolchains/index.apt
(original)
+++
maven/plugins/trunk/maven-toolchains-plugin/src/site/apt/toolchains/index.apt
Sat Nov 8 23:34:05 2014
@@ -33,4 +33,4 @@ Standard Toolchains
[]
You can also create and use your own custom toolchains by following the
- {{{http://maven.apache.org/}TBD}} instructions.
+ {{{./custom.html}Custom Toolchains}} instructions.
