diff --git a/src/site/apt/examples/example-exec-using-toolchains.apt.vm b/src/site/markdown/examples/example-exec-using-toolchains.md.vm similarity index 65% rename from src/site/apt/examples/example-exec-using-toolchains.apt.vm rename to src/site/markdown/examples/example-exec-using-toolchains.md.vm index d379ea8b..689138d8 100644 --- a/src/site/apt/examples/example-exec-using-toolchains.apt.vm +++ b/src/site/markdown/examples/example-exec-using-toolchains.md.vm @@ -1,238 +1,257 @@ - ------ - Using toolchains with the exec:exec goal - ------ - Markus KARG - ------ - 2016-04-24 - ------ - - ~~ Copyright 2016 The Codehaus - ~~ - ~~ 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. - - ~~ NOTE: For help with the syntax of this file, see: - ~~ http://maven.apache.org/doxia/references/apt-format.html - - -Using Toolchains Instead of Explicit Paths - - To keep both, the POM and the <<>> free of explicit paths, the <<>> goal supports Maven Toolchains. - Toolchains are configured using the file <<>> and apply different algorithms how to find the wanted tool on disk. - More information on toolchains can be found on the {{{https://maven.apache.org/guides/mini/guide-using-toolchains.html}Maven web site}}. - - There are three ways of using toolchains: The "paths" toolchain provided by the Exec Maven Plugin, the "jdk" toolchain provided by the Maven Toolchains Plugin, and custom toolchains provided by third party plugins. - -* The "paths" Toolchain - - The "paths" toolchain is included in the Exec Maven Plugin and must be enabled explicitly in the POM. - It searches a configurable list of folders for the requested tool. - The first match will be invoked. - -** pom.xml - -+-------------------+ - - ... - - - - maven-toolchains-plugin - $context.get("maven-toolchains-plugin.version") - - - - toolchain - - - - - - - - foo-bar - - - - - - org.codehaus.mojo - exec-maven-plugin - ${project.version} - - true - ... - - paths - - ... - - - - ... - -+-------------------+ - -** toolchains.xml - -+-------------------+ - - - - paths - - - foo-bar - - - - C:\Program Files\FooBar\SDK\bin - C:\Program Files\FooBar\Runtime\bin - - - - ... - -+-------------------+ - -* The "jdk" Toolchain - - The "jdk" toolchain is included in the Maven Toolchains Plugin and enabled by default. - It searches the <<>> folder of the specified JDK for the requested tool. - -** pom.xml - -+-------------------+ - - ... - - - - maven-toolchains-plugin - $context.get("maven-toolchains-plugin.version") - - - - toolchain - - - - - - - - [1.5,) - - - - - - org.codehaus.mojo - exec-maven-plugin - ${project.version} - ... - - - - ... - -+-------------------+ - -** toolchains.xml - -+-------------------+ - - - - jdk - - - 1.5 - sun - sun-jdk-1.5 - - - C:\Program Files\Java\jdk1.5.0 - - - ... - -+-------------------+ - -* Custom Toolchains - - Custom toolchains are included in third party Maven plugins and must be enabled explicitly in the POM. - Their type id, configuration and search algorithms are plugin specific. - See particular plugin's documentation. - -** pom.xml - -+-------------------+ - - ... - - - - - - - ... - - - maven-toolchains-plugin - $context.get("maven-toolchains-plugin.version") - - - - toolchain - - - - - - - - - - - org.codehaus.mojo - exec-maven-plugin - ${project.version} - ... - - - - ... - - - - ... - -+-------------------+ - -** toolchains.xml - -+-------------------+ - - - - - - - - - - - - ... - -+-------------------+ +title: Using toolchains with the exec:exec goal +author: Markus KARG + +#* + ~~ Copyright 2016 The Codehaus + ~~ + ~~ 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. + + ~~ NOTE: For help with the syntax of this file, see: + ~~ http://maven.apache.org/doxia/references/apt-format.html +*# + +Using Toolchains Instead of Explicit Paths +========================================== + +To keep both, the POM and the `PATH` free of explicit paths, the `exec:exec` goal supports Maven Toolchains. + +Toolchains are configured using the file `toolchains.xml` and apply different algorithms how to find the wanted tool on disk. + +More information on toolchains can be found on the [Maven website](https://maven.apache.org/guides/mini/guide-using-toolchains.html). + +There are three ways of using toolchains: + - the "paths" toolchain provided by the Exec Maven Plugin + - the "jdk" toolchain provided by the Maven Toolchains Plugin, + - and custom toolchains provided by third party plugins. + +The "paths" Toolchain +--------------------- + +The "paths" toolchain is included in the Exec Maven Plugin and **must be enabled** explicitly +by `true` in the plugin configuration in POM. + +It searches a configurable list of folders for the requested tool. The first match will be invoked. + +**pom.xml:** + +```xml + + ... + + + + maven-toolchains-plugin + $context.get("maven-toolchains-plugin.version") + + + + toolchain + + + + + + + + foo-bar + + + + + + org.codehaus.mojo + exec-maven-plugin + ${project.version} + + true + ... + + + paths + meExecutable + + ... + + + + ... + +``` + +**toolchains.xml:** + +```xml + + + + paths + + + foo-bar + + + + C:\Program Files\FooBar\SDK\bin + C:\Program Files\FooBar\Runtime\bin + + + + ... + +``` + +In the above example executable `meExecutable` will be searched in directory: `C:\Program Files\FooBar\SDK\bin` or `C:\Program Files\FooBar\Runtime\bin` + +The "jdk" Toolchain +------------------- + +The "jdk" toolchain is included in the Maven Toolchains Plugin and enabled by default. +It searches the `bin` folder of the specified `JDK` for the requested tool. + +**pom.xml:** + +```xml + + ... + + + + maven-toolchains-plugin + $context.get("maven-toolchains-plugin.version") + + + + toolchain + + + + + + + + [x,) + + + + + + org.codehaus.mojo + exec-maven-plugin + ${project.version} + + java + + ... + + + + ... + +``` + +**toolchains.xml:** + +```xml + + + + jdk + + z.y.z + vendor + ... + + + C:\Program Files\Java\jdk-x.y.z + + + ... + +``` + +In the above example executable `java` will be searched in `JDK` provided by `toolchain`. + +Custom Toolchains +----------------- + +Custom toolchains are included in third party Maven plugins and must be enabled explicitly in the POM. +Their type id, configuration and search algorithms are plugin specific. + +See particular plugin's documentation. + +**pom.xml:** + +```xml + + ... + + + + + + + ... + + + maven-toolchains-plugin + $context.get("maven-toolchains-plugin.version") + + + + toolchain + + + + + + + + + + + org.codehaus.mojo + exec-maven-plugin + ${project.version} + ... + + + meExecutable + + ... + + + + ... + +``` + +**toolchains.xml:** + +```xml + + + + + + + + + + + + ... + +``` + +In the above example executable `meExecutable` will be searched by provided custom toolchain. +