| 1 |
<!DOCTYPE html> |
| 2 |
<!-- |
| 3 |
Licensed to the Apache Software Foundation (ASF) under one or more |
| 4 |
contributor license agreements. See the NOTICE file distributed with |
| 5 |
this work for additional information regarding copyright ownership. |
| 6 |
The ASF licenses this file to You under the Apache License, Version 2.0 |
| 7 |
(the "License"); you may not use this file except in compliance with |
| 8 |
the License. You may obtain a copy of the License at |
| 9 |
|
| 10 |
https://www.apache.org/licenses/LICENSE-2.0 |
| 11 |
|
| 12 |
Unless required by applicable law or agreed to in writing, software |
| 13 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 14 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 15 |
See the License for the specific language governing permissions and |
| 16 |
limitations under the License. |
| 17 |
--> |
| 18 |
<html lang="en"> |
| 19 |
|
| 20 |
<head> |
| 21 |
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| 22 |
<title>PreSetDef Task</title> |
| 23 |
</head> |
| 24 |
|
| 25 |
<body> |
| 26 |
|
| 27 |
<h2 id="presetdef">PreSetDef</h2> |
| 28 |
<p><em>Since Apache Ant 1.6</em></p> |
| 29 |
<h3>Description</h3> |
| 30 |
<p>The preset definition generates a new definition based on a current definition with some |
| 31 |
attributes or elements preset.</p> |
| 32 |
<p>The resolution of properties in any of the attributes or nested text takes place with the |
| 33 |
definition is used and <em>not</em> when the preset definition is defined.</p> |
| 34 |
<h3>Parameters</h3> |
| 35 |
<table class="attr"> |
| 36 |
<tr> |
| 37 |
<th scope="col">Attribute</th> |
| 38 |
<th scope="col">Description</th> |
| 39 |
<th scope="col">Required</th> |
| 40 |
</tr> |
| 41 |
<tr> |
| 42 |
<td>name</td> |
| 43 |
<td>the name of the new definition</td> |
| 44 |
<td>Yes</td> |
| 45 |
</tr> |
| 46 |
<tr> |
| 47 |
<td>uri</td> |
| 48 |
<td>The URI that this definition should live in.</td> |
| 49 |
<td>No</td> |
| 50 |
</tr> |
| 51 |
</table> |
| 52 |
<h3>Parameters specified as nested elements</h3> |
| 53 |
<h4>another type with attributes or elements set</h4> |
| 54 |
<p>The <code><presetdef></code> task takes one nested element as a parameter. This nested |
| 55 |
element can be any other type or task. The attributes and elements that need to be preset are |
| 56 |
placed here.</p> |
| 57 |
|
| 58 |
<h3>Examples</h3> |
| 59 |
<p>The following fragment defines a <code>javac</code> task with |
| 60 |
the <var>debug</var>, <var>deprecation</var>, <var>srcdir</var> and <var>destdir</var> |
| 61 |
attributes set. It also has a <code>src</code> element to source files from a generated |
| 62 |
directory.</p> |
| 63 |
<pre> |
| 64 |
<presetdef name="my.javac"> |
| 65 |
<javac debug="${debug}" deprecation="${deprecation}" |
| 66 |
srcdir="${src.dir}" destdir="${classes.dir}"> |
| 67 |
<src path="${gen.dir}"/> |
| 68 |
</javac> |
| 69 |
</presetdef></pre> |
| 70 |
<p>This can be used as a normal <code>javac</code> task—for example:</p> |
| 71 |
<pre><my.javac/></pre> |
| 72 |
<p>The attributes specified in the preset task may be overridden—i.e. they may be seen as |
| 73 |
optional attributes—for example:</p> |
| 74 |
<pre><my.javac srcdir="${test.src}" deprecation="no"/></pre> |
| 75 |
<p>One may put a <code>presetdef</code> definition in an antlib. For example suppose the jar |
| 76 |
file <samp>antgoodies.jar</samp> has the <samp>antlib.xml</samp> as follows:</p> |
| 77 |
<pre> |
| 78 |
<antlib> |
| 79 |
<taskdef resource="com/acme/antgoodies/tasks.properties"/> |
| 80 |
<!-- Implement the common use of the javac command --> |
| 81 |
<presetdef name="javac"> |
| 82 |
<javac deprecation="${deprecation}" debug="${debug}" |
| 83 |
srcdir="src" destdir="classes"/> |
| 84 |
</presetdef> |
| 85 |
</antlib></pre> |
| 86 |
<p>One may then use this in a build file as follows:</p> |
| 87 |
<pre> |
| 88 |
<project default="example" xmlns:antgoodies="antlib:com.acme.antgoodies"> |
| 89 |
<target name="example"> |
| 90 |
<!-- Compile source --> |
| 91 |
<antgoodies:javac srcdir="src/main"/> |
| 92 |
<!-- Compile test code --> |
| 93 |
<antgoodies:javac srcdir="src/test"/> |
| 94 |
</target> |
| 95 |
</project></pre> |
| 96 |
<p>The following is an example of evaluation of properties when the definition is used:</p> |
| 97 |
<pre> |
| 98 |
<target name="defineandcall"> |
| 99 |
<presetdef name="showmessage"> |
| 100 |
<echo>message is '${message}'</echo> |
| 101 |
</presetdef> |
| 102 |
<showmessage/> |
| 103 |
<property name="message" value="Message 1"/> |
| 104 |
<showmessage/> |
| 105 |
<antcall target="called"> |
| 106 |
<param name="message" value="Message 2"/> |
| 107 |
</antcall> |
| 108 |
</target> |
| 109 |
<target name="called"> |
| 110 |
<showmessage/> |
| 111 |
</target></pre> |
| 112 |
<p>The command <kbd>ant defineandcall</kbd> results in the output:</p> |
| 113 |
<pre class="output"> |
| 114 |
defineandcall: |
| 115 |
[showmessage] message is '${message}' |
| 116 |
[showmessage] message is 'Message 1' |
| 117 |
|
| 118 |
called: |
| 119 |
[showmessage] message is 'Message 2'</pre> |
| 120 |
<p>It is possible to use a trick to evaluate properties when the definition is <em>made</em> |
| 121 |
rather than used. This can be useful if you do not expect some properties to be available in |
| 122 |
child builds run with <code><ant ... inheritall="false"></code>:</p> |
| 123 |
<pre> |
| 124 |
<macrodef name="showmessage-presetdef"> |
| 125 |
<attribute name="messageval"/> |
| 126 |
<presetdef name="showmessage"> |
| 127 |
<echo>message is '@{messageval}'</echo> |
| 128 |
</presetdef> |
| 129 |
</macrodef> |
| 130 |
<showmessage-presetdef messageval="${message}"/></pre> |
| 131 |
|
| 132 |
</body> |
| 133 |
</html> |