Debian Codegraph @

manual/Tasks/tstamp.html

raw
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>TStamp Task</title>
23 </head>
24
25 <body>
26
27 <h2 id="tstamp">Tstamp</h2>
28
29 <h3>Description</h3>
30 <p>Sets the <code>DSTAMP</code>, <code>TSTAMP</code>, and <code>TODAY</code> properties in the
31 current project. By default, the <code>DSTAMP</code> property is in the
32 format <q>yyyyMMdd</q>, <code>TSTAMP</code> is in the format <q>HHmm</q>, and <code>TODAY</code> is
33 in the format <q>MMMM d yyyy</q>. Use the nested <code>&lt;format&gt;</code> element to specify a
34 different format.</p>
35
36 <p>These properties can be used in the build file, for instance, to create timestamped filenames, or
37 used to replace placeholder tags inside documents to indicate, for example, the release date. The
38 best place for this task is probably in an initialization target.</p>
39
40 <p><em>Since Ant 1.10.2</em> the magic property <code>ant.tstamp.now</code> can be used to specify a
41 fixed date value in order to create reproducible builds. Its value must be a number and is
42 interpreted as seconds since the epoch (midnight 1970-01-01). With <code>ant.tstamp.now.iso</code>
43 you could also specify that value in ISO-8601 format (<code>1972-04-17T08:07:00Z</code>). If you
44 specify a value in an invalid format an INFO message will be logged and the value will be
45 ignored.</p>
46
47 <p>
48 <em>Since Ant 1.10.8</em> the <code>SOURCE_DATE_EPOCH</code> environment variable value (if set)
49 will be honoured for <a href="https://reproducible-builds.org/specs/source-date-epoch/#idm55">reproducible builds</a>.
50 Ant will log a DEBUG message if an invalid value (value that cannot be parsed to an integer), is specified
51 for that environment variable and will instead use the "current" date.
52 </p>
53
54 <h3>Parameters</h3>
55 <table class="attr">
56 <tr>
57 <th scope="col">Attribute</th>
58 <th scope="col">Description</th>
59 <th scope="col">Required</th>
60 </tr>
61 <tr>
62 <td>prefix</td>
63 <td>Prefix used for all properties set.</td>
64 <td>No; default is no prefix</td>
65 </tr>
66 </table>
67
68 <h3>Parameters specified as nested elements</h3>
69 <p>The task supports a <code>&lt;format&gt;</code> nested element that allows a property to be set
70 to the current date and time in a given format. The date/time patterns are as defined in the
71 Java <a href="https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html"
72 target="_top">SimpleDateFormat</a> class. The format element also allows offsets to be applied to
73 the time to generate different time values.</p>
74 <table class="attr">
75 <tr>
76 <th scope="col">Attribute</th>
77 <th scope="col">Description</th>
78 <th scope="col">Required</th>
79 </tr>
80 <tr>
81 <td>property</td>
82 <td>The property to receive the date/time string in the given pattern.</td>
83 <td>Yes</td>
84 </tr>
85 <tr>
86 <td>pattern</td>
87 <td>The date/time pattern to be used. The values are as defined by the Java SimpleDateFormat
88 class.</td>
89 <td>Yes</td>
90 </tr>
91 <tr>
92 <td>timezone</td>
93 <td>The timezone to use for displaying time. The values are as defined by the
94 Java <a href="https://docs.oracle.com/javase/8/docs/api/java/util/TimeZone.html"
95 target="_top">TimeZone</a> class.</td>
96 <td>No</td>
97 </tr>
98 <tr>
99 <td>offset</td>
100 <td>The numeric offset to the current time</td>
101 <td>No</td>
102 </tr>
103 <tr>
104 <td>unit</td>
105 <td>The unit of the offset to be applied to the current time. Valid values are
106 <ul>
107 <li><q>millisecond</q></li>
108 <li><q>second</q></li>
109 <li><q>minute</q></li>
110 <li><q>hour</q></li>
111 <li><q>day</q></li>
112 <li><q>week</q></li>
113 <li><q>month</q></li>
114 <li><q>year</q></li>
115 </ul>
116 </td>
117 <td>No</td>
118 </tr>
119 <tr>
120 <td>locale</td>
121 <td>The locale used to create date/time string. The general form is <q>language[, country[,
122 variant]]</q> (either <q>variant</q> or both <q>variant</q> and <q>country</q> may be
123 omitted). For more information please refer to documentation for
124 the <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html"
125 target="_top">Locale</a> class.</td>
126 <td>No</td>
127 </tr>
128 </table>
129
130 <h3>Examples</h3>
131
132 <p>Set the standard <code>DSTAMP</code>, <code>TSTAMP</code>, and <code>TODAY</code> properties
133 according to the default formats.</p>
134 <pre>&lt;tstamp/&gt;</pre>
135
136 <p>Set the standard properties as well as the property <code>TODAY_UK</code> with the date/time
137 pattern <q>d-MMMM-yyyy</q> using English locale (eg. 21-May-2001).</p>
138 <pre>
139 &lt;tstamp&gt;
140 &lt;format property=&quot;TODAY_GB&quot; pattern=&quot;d-MMMM-yyyy&quot; locale=&quot;en,GB&quot;/&gt;
141 &lt;/tstamp&gt;</pre>
142
143 <p>Create a timestamp, in the property <code>touch.time</code>, 5 hours before the current time. The
144 format in this example is suitable for use with the <code>&lt;touch&gt;</code> task. The standard
145 properties are set also.</p>
146 <pre>
147 &lt;tstamp&gt;
148 &lt;format property=&quot;touch.time&quot; pattern=&quot;MM/dd/yyyy hh:mm aa&quot;
149 offset=&quot;-5&quot; unit=&quot;hour&quot;/&gt;
150 &lt;/tstamp&gt;</pre>
151
152 <p>Set three properties with the standard formats, prefixed
153 with <q>start.</q>: <code>start.DSTAMP</code>, <code>start.TSTAMP</code>,
154 and <code>start.TODAY</code>.</p>
155 <pre>&lt;tstamp prefix="start"/&gt;</pre>
156
157 </body>
158 </html>