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.