| <!-- |
| 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. |
| --> |
| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"></meta> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>PreSetDef Task</title> |
| <style type="text/css"> |
| <!-- |
| .code { background: #EFEFEF; margin-top: } |
| --> |
| </style> |
| </head> |
| |
| <body> |
| |
| <h2><a name="presetdef">PreSetDef</a></h2> |
| <h3>Description</h3> |
| <p> |
| The preset definition generates a new definition |
| based on a current definition with some attributes |
| or elements preset. |
| </p> |
| <p> |
| <em>since Ant 1.6</em> |
| </p> |
| <p> |
| The resolution of properties in any of the attributes or |
| nested text takes place with the definition is used and <em>not</em> |
| when the preset definition is defined. |
| </p> |
| <h3>Parameters</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">name</td> |
| <td valign="top">the name of the new definition</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">uri</td> |
| <td valign="top"> |
| The uri that this definition should live in. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>another type with attributes or elements set</h4> |
| <p>The <code><presetdef></code> task takes one nested element as a parameter. |
| This nested element can be any other type or task. The attributes |
| and elements that need to be preset are placed here. |
| </p> |
| |
| <h3>Examples</h3> |
| The following fragment defines a javac task with the debug, deprecation |
| srcdir and destdir |
| attributes set. It also has a src element to source files from a generated |
| directory. |
| <blockquote> |
| <pre class="code"> |
| <presetdef name="my.javac"> |
| <javac debug="${debug}" deprecation="${deprecation}" |
| srcdir="${src.dir}" destdir="${classes.dir}"> |
| <src path="${gen.dir}"/> |
| </javac> |
| </presetdef> |
| </pre> |
| </blockquote> |
| This can be used as a normal javac task - example: |
| <blockquote> |
| <pre class="code"> |
| <my.javac/> |
| </pre> |
| </blockquote> |
| The attributes specified in the preset task may be overridden - i.e. |
| they may be seen as optional attributes - example: |
| <blockquote> |
| <pre class="code"> |
| <my.javac srcdir="${test.src}" deprecation="no"/> |
| </pre> |
| </blockquote> |
| One may put a presetdef definition in an antlib. |
| For example suppose the jar file antgoodies.jar has |
| the antlib.xml as follows: |
| <blockquote> |
| <pre class="code"> |
| <antlib> |
| <taskdef resource="com/acme/antgoodies/tasks.properties"/> |
| <!-- Implement the common use of the javac command --> |
| <presetdef name="javac"> |
| <javac deprecation="${deprecation}" debug="${debug}" |
| srcdir="src" destdir="classes"/> |
| </presetdef> |
| </antlib> |
| </pre> |
| </blockquote> |
| One may then use this in a build file as follows: |
| <blockquote> |
| <pre class="code"> |
| <project default="example" xmlns:antgoodies="antlib:com.acme.antgoodies"> |
| <target name="example"> |
| <!-- Compile source --> |
| <antgoodies:javac srcdir="src/main"/> |
| <!-- Compile test code --> |
| <antgoodies:javac srcdir="src/test"/> |
| </target> |
| </project> |
| </pre> |
| </blockquote> |
| <p> |
| The following is an example of evaluation of properties when the |
| definition is used: |
| </p> |
| <blockquote> |
| <pre class="code"> |
| <target name="defineandcall"> |
| <presetdef name="showmessage"> |
| <echo>message is '${message}'</echo> |
| </presetdef> |
| <showmessage/> |
| <property name="message" value="Message 1"/> |
| <showmessage/> |
| <antcall target="called"> |
| <param name="message" value="Message 2"/> |
| </antcall> |
| </target> |
| <target name="called"> |
| <showmessage/> |
| </target> |
| </pre> |
| </blockquote> |
| <p> |
| The command ant defineandcall results in the output: |
| </p> |
| <blockquote> |
| <pre class="code"> |
| defineandcall: |
| [showmessage] message is '${message}' |
| [showmessage] message is 'Message 1' |
| |
| called: |
| [showmessage] message is 'Message 2' |
| </pre> |
| </blockquote> |
| <p> |
| It is possible to use a trick to evaluate properties when the definition is |
| <em>made</em> rather than used. This can be useful if you do not expect some |
| properties to be available in child builds run with |
| <code><ant ... inheritall="false"></code>: |
| </p> |
| <blockquote><pre class="code"> |
| <macrodef name="showmessage-presetdef"> |
| <attribute name="messageval"/> |
| <presetdef name="showmessage"> |
| <echo>message is '@{messageval}'</echo> |
| </presetdef> |
| </macrodef> |
| <showmessage-presetdef messageval="${message}"/> |
| </pre></blockquote> |
| <hr></hr> |
| |
| </body> |
| </html> |
| |
