| <!DOCTYPE html> |
| <!-- |
| 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 |
| |
| https://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 lang="en"> |
| |
| <head> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>PreSetDef Task</title> |
| </head> |
| |
| <body> |
| |
| <h2 id="presetdef">PreSetDef</h2> |
| <p><em>Since Apache Ant 1.6</em></p> |
| <h3>Description</h3> |
| <p>The preset definition generates a new definition based on a current definition with some |
| attributes or elements preset.</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 class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>name</td> |
| <td>the name of the new definition</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>uri</td> |
| <td>The URI that this definition should live in.</td> |
| <td>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> |
| <p>The following fragment defines a <code>javac</code> task with |
| the <var>debug</var>, <var>deprecation</var>, <var>srcdir</var> and <var>destdir</var> |
| attributes set. It also has a <code>src</code> element to source files from a generated |
| directory.</p> |
| <pre> |
| <presetdef name="my.javac"> |
| <javac debug="${debug}" deprecation="${deprecation}" |
| srcdir="${src.dir}" destdir="${classes.dir}"> |
| <src path="${gen.dir}"/> |
| </javac> |
| </presetdef></pre> |
| <p>This can be used as a normal <code>javac</code> task—for example:</p> |
| <pre><my.javac/></pre> |
| <p>The attributes specified in the preset task may be overridden—i.e. they may be seen as |
| optional attributes—for example:</p> |
| <pre><my.javac srcdir="${test.src}" deprecation="no"/></pre> |
| <p>One may put a <code>presetdef</code> definition in an antlib. For example suppose the jar |
| file <samp>antgoodies.jar</samp> has the <samp>antlib.xml</samp> as follows:</p> |
| <pre> |
| <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> |
| <p>One may then use this in a build file as follows:</p> |
| <pre> |
| <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> |
| <p>The following is an example of evaluation of properties when the definition is used:</p> |
| <pre> |
| <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> |
| <p>The command <kbd>ant defineandcall</kbd> results in the output:</p> |
| <pre class="output"> |
| defineandcall: |
| [showmessage] message is '${message}' |
| [showmessage] message is 'Message 1' |
| |
| called: |
| [showmessage] message is 'Message 2'</pre> |
| <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> |
| <pre> |
| <macrodef name="showmessage-presetdef"> |
| <attribute name="messageval"/> |
| <presetdef name="showmessage"> |
| <echo>message is '@{messageval}'</echo> |
| </presetdef> |
| </macrodef> |
| <showmessage-presetdef messageval="${message}"/></pre> |
| |
| </body> |
| </html> |
