| <!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>Uptodate Task</title> |
| </head> |
| |
| <body> |
| |
| <h2 id="uptodate">Uptodate</h2> |
| <h3>Description</h3> |
| <p>Sets a property if a target file or set of target files is more up-to-date than a source file or |
| set of source files. A single source file is specified using the <var>srcfile</var> attribute. A set |
| of source files is specified using the nested <code><srcfiles></code> elements. These |
| are <a href="../Types/fileset.html">FileSet</a>s, whereas multiple target files are specified using |
| a nested <a href="../Types/mapper.html"><code><mapper></code></a> element.</p> |
| <p>By default, the value of the property is set to <q>true</q> if the timestamp of the source |
| file(s) is not more recent than the timestamp of the corresponding target file(s). You can set the |
| value to something other than the default by specifying the <var>value</var> attribute.</p> |
| <p>If a <code><srcfiles></code> element is used, without also specifying |
| a <code><mapper></code> element, the default behavior is to use |
| a <a href="../Types/mapper.html#merge-mapper">merge mapper</a>, with the <var>to</var> attribute set |
| to the value of the <var>targetfile</var> attribute.</p> |
| <p>Normally, this task is used to set properties that are useful to avoid target execution depending |
| on the relative age of the specified files.</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>property</td> |
| <td>The name of the property to set.</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>value</td> |
| <td>The value to set the property to.</td> |
| <td>No; defaults to <q>true</q>.</td> |
| </tr> |
| <tr> |
| <td>srcfile</td> |
| <td>The file to check against the target file(s).</td> |
| <td>Yes, unless a nested |
| <code><srcfiles></code> or <code><srcresources></code> |
| element is present.</td> |
| </tr> |
| <tr> |
| <td>targetfile</td> |
| <td>The file for which we want to determine the status.</td> |
| <td>Yes, unless a nested <code><mapper></code> element is present.</td> |
| </tr> |
| </table> |
| |
| <h3>Parameters specified as nested elements</h3> |
| <h4 id="srcfiles">srcfiles</h4> |
| <p>The nested <code><srcfiles></code> element is a <a href="../Types/fileset.html">fileset</a> |
| and allows you to specify a set of files to check against the target file(s).</p> |
| |
| <p><strong>Note</strong>: You can specify either the <var>srcfile</var> attribute or |
| nested <code><srcfiles></code> elements, but not both. |
| |
| <p>Note that the task will completely ignore any directories that seem to be matched by |
| the <var>srcfiles</var> fileset, it will only consider normal files. If you need logic that applies |
| to directories as well, use a nested <code>srcresources</code> element and a <code>dirset</code> |
| (for example).</p> |
| |
| <h4 id="srcresources">srcresources</h4> |
| <p><em>Since Apache Ant 1.7</em></p> |
| <p>The nested <code><srcresources></code> element is |
| a <a href="../Types/resources.html#union">union</a> and allows you to specify a collection of |
| resources to check against the target file(s).</p> |
| |
| <h4 id="mapper">mapper</h4> |
| <p>The nested <code><mapper></code> element allows you to specify a set of target files to |
| check for being up-to-date with respect to a set of source files.</p> |
| <p>The mapper <var>to</var> attribute is relative to the target file, or to the <var>dir</var> |
| attribute of the nested <code>srcfiles</code> element.</p> |
| <p><em>Since Ant 1.6.3</em>, one can use a <code>filenamemapper</code> type in place of the mapper |
| element.</p> |
| <h3>Examples</h3> |
| <p>Set the property <code>xmlBuild.notRequired</code> to <q>true</q> if |
| the <samp>${deploy}/xmlClasses.jar</samp> file is more up-to-date than any of the DTD files in |
| the <samp>${src}/xml</samp> directory.</p> |
| <pre> |
| <uptodate property="xmlBuild.notRequired" targetfile="${deploy}\xmlClasses.jar"> |
| <srcfiles dir="${src}/xml" includes="**/*.dtd"/> |
| </uptodate></pre> |
| <p>This can be written as:</p> |
| <pre> |
| <uptodate property="xmlBuild.notRequired"> |
| <srcfiles dir= "${src}/xml" includes="**/*.dtd"/> |
| <mapper type="merge" to="${deploy}\xmlClasses.jar"/> |
| </uptodate></pre> |
| <p>as well.</p> |
| |
| <p>The <code>xmlBuild.notRequired</code> property can then be used in a <code><target></code> |
| tag's <var>unless</var> attribute to conditionally run that target. For example, running the |
| following target:</p> |
| <pre> |
| <target name="xmlBuild" depends="chkXmlBuild" unless="xmlBuild.notRequired"> |
| ... |
| </target></pre> |
| <p>will first run the <q>chkXmlBuild</q> target, which contains the <code><uptodate></code> |
| task that determines whether <code>xmlBuild.notRequired</code> gets set. The property named in |
| the <var>unless</var> attribute is then checked for being set/not set. If it did get set (ie., the |
| jar file is up-to-date), then the <q>xmlBuild</q> target won't be run.</p> |
| |
| <p>The following example shows a single source file being checked against a single target file:</p> |
| <pre> |
| <uptodate property="isUpToDate" |
| srcfile="/usr/local/bin/testit" |
| targetfile="${build}/.flagfile"/> |
| </pre> |
| <p>sets the property <code>isUpToDate</code> to <q>true</q> if <samp>/usr/local/bin/testit</samp> is |
| not newer than <samp>${build}/.flagfile</samp>.</p> |
| <p>The following shows usage of a relative mapper.</p> |
| <pre> |
| <uptodate property="checkUptodate.uptodate"> |
| <srcfiles dir="src" includes="*"/> |
| <mapper type="merge" to="../dest/output.done"/> |
| </uptodate> |
| <echo message="checkUptodate result: ${checkUptodate.uptodate}"/></pre> |
| <p>The previous example can be a bit confusing, so it may be better to use absolute paths:</p> |
| <pre> |
| <property name="dest.dir" location="dest"/> |
| <uptodate property="checkUptodate.uptodate"> |
| <srcfiles dir="src" includes="*"/> |
| <mapper type="merge" to="${dest.dir}/output.done"/> |
| </uptodate></pre> |
| |
| </body> |
| </html> |