You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

copy.html 14 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367
  1. <!--
  2. Licensed to the Apache Software Foundation (ASF) under one or more
  3. contributor license agreements. See the NOTICE file distributed with
  4. this work for additional information regarding copyright ownership.
  5. The ASF licenses this file to You under the Apache License, Version 2.0
  6. (the "License"); you may not use this file except in compliance with
  7. the License. You may obtain a copy of the License at
  8. http://www.apache.org/licenses/LICENSE-2.0
  9. Unless required by applicable law or agreed to in writing, software
  10. distributed under the License is distributed on an "AS IS" BASIS,
  11. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. See the License for the specific language governing permissions and
  13. limitations under the License.
  14. -->
  15. <html>
  16. <head>
  17. <meta http-equiv="Content-Language" content="en-us">
  18. <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
  19. <title>Copy Task</title>
  20. </head>
  21. <body>
  22. <h2><a name="copy">Copy</a></h2>
  23. <h3>Description</h3>
  24. <p>Copies a file or resource collection to a new file or directory. By default, files are
  25. only copied if the source file is newer than the destination file,
  26. or when the destination file does not exist. However, you can explicitly
  27. overwrite files with the <code>overwrite</code> attribute.</p>
  28. <p><a href="../Types/resources.html#collection">Resource
  29. Collection</a>s are used to select a group of files to copy. To use a
  30. resource collection, the <code>todir</code> attribute must be set.
  31. <strong>Note</strong> that some resources (for example
  32. the <a href="../Types/resources.html#file">file</a> resource)
  33. return absolute paths as names and the result of using them without
  34. using a nested mapper (or the flatten attribute) may not be what you
  35. expect.</p>
  36. <p>
  37. <strong>Note: </strong>If you employ filters in your copy operation,
  38. you should limit the copy to text files. Binary files will be corrupted
  39. by the copy operation.
  40. This applies whether the filters are implicitly defined by the
  41. <a href="filter.html">filter</a> task or explicitly provided to the copy
  42. operation as <a href="../Types/filterset.html">filtersets</a>.
  43. <em>See <a href="#encoding">encoding note</a></em>.
  44. </p>
  45. <h3>Parameters</h3>
  46. <table border="1" cellpadding="2" cellspacing="0">
  47. <tr>
  48. <td valign="top"><b>Attribute</b></td>
  49. <td valign="top"><b>Description</b></td>
  50. <td align="center" valign="top"><b>Required</b></td>
  51. </tr>
  52. <tr>
  53. <td valign="top">file</td>
  54. <td valign="top">The file to copy.</td>
  55. <td valign="top" align="center">Yes, unless a nested
  56. resource collection element is used.</td>
  57. </tr>
  58. <tr>
  59. <td valign="top">preservelastmodified</td>
  60. <td valign="top">Give the copied files the same last modified
  61. time as the original source files.</td>
  62. <td valign="top" align="center">No; defaults to false.</td>
  63. </tr>
  64. <tr>
  65. <td valign="top">tofile</td>
  66. <td valign="top">The file to copy to.</td>
  67. <td valign="top" align="center" rowspan="2">With the <code>file</code>
  68. attribute, either <code>tofile</code> or <code>todir</code> can be used.<br/>
  69. With nested resource collection elements, if the number of
  70. included resources
  71. is greater than 1, or if only the <code>dir</code> attribute is
  72. specified in the <code>&lt;fileset&gt;</code>, or if the
  73. <code>file</code> attribute is also specified, then only
  74. <code>todir</code> is allowed.<br/>
  75. <em>Prior to Ant 1.8.2</em> the <code>tofile</code> attribute
  76. only supported filesystem resources top copy from.</td>
  77. </tr>
  78. <tr>
  79. <td valign="top">todir</td>
  80. <td valign="top">The directory to copy to.</td>
  81. </tr>
  82. <tr>
  83. <td valign="top">overwrite</td>
  84. <td valign="top">Overwrite existing files even if the destination
  85. files are newer.</td>
  86. <td valign="top" align="center">No; defaults to false.</td>
  87. </tr>
  88. <tr>
  89. <td valign="top">force</td>
  90. <td valign="top">Overwrite read-only destination
  91. files. <em>since Ant 1.8.2</em></td>
  92. <td valign="top" align="center">No; defaults to false.</td>
  93. </tr>
  94. <tr>
  95. <td valign="top">filtering</td>
  96. <td valign="top">Indicates whether token filtering using the <a href="../using.html#filters">global
  97. build-file filters</a> should take place during the copy.
  98. <em>Note</em>: Nested <code>&lt;filterset&gt;</code> elements will
  99. always be used, even if this attribute is not specified, or its value is
  100. <code>false</code> (<code>no</code>, or <code>off</code>).</td>
  101. <td valign="top" align="center">No; defaults to false.</td>
  102. </tr>
  103. <tr>
  104. <td valign="top">flatten</td>
  105. <td valign="top">Ignore the directory structure of the source files,
  106. and copy all files into the directory specified by the <code>todir</code>
  107. attribute. Note that you can achieve the same effect by using a
  108. <a href="../Types/mapper.html#flatten-mapper">flatten mapper</a>.</td>
  109. <td valign="top" align="center">No; defaults to false.</td>
  110. </tr>
  111. <tr>
  112. <td valign="top">includeEmptyDirs</td>
  113. <td valign="top">Copy any empty directories included in the FileSet(s).
  114. </td>
  115. <td valign="top" align="center">No; defaults to true.</td>
  116. </tr>
  117. <tr>
  118. <td valign="top">failonerror</td>
  119. <td valign="top">If false, log a warning message, but do not stop the
  120. build, when the file to copy does not exist or one of the nested
  121. filesets points to a directory that doesn't exist or an error occurs
  122. while copying.
  123. </td>
  124. <td valign="top" align="center">No; defaults to true.</td>
  125. </tr>
  126. <tr>
  127. <td valign="top">verbose</td>
  128. <td valign="top">Log the files that are being copied.</td>
  129. <td valign="top" align="center">No; defaults to false.</td>
  130. </tr>
  131. <tr>
  132. <td valign="top">encoding</td>
  133. <td valign="top">The encoding to assume when filter-copying the
  134. files. <em>since Ant 1.5</em>.</td>
  135. <td align="center">No - defaults to default JVM encoding</td>
  136. </tr>
  137. <tr>
  138. <td valign="top">outputencoding</td>
  139. <td valign="top">The encoding to use when writing the files.
  140. <em>since Ant 1.6</em>.</td>
  141. <td align="center">No - defaults to the value of the encoding
  142. attribute if given or the default JVM encoding otherwise.</td>
  143. </tr>
  144. <tr>
  145. <td valign="top">enablemultiplemappings</td>
  146. <td valign="top">
  147. If true the task will process to all the mappings for a
  148. given source path. If false the task will only process
  149. the first file or directory. This attribute is only relevant
  150. if there is a mapper subelement.
  151. <em>since Ant 1.6</em>.</td>
  152. <td align="center">No - defaults to false.</td>
  153. </tr>
  154. <tr>
  155. <td valign="top">granularity</td>
  156. <td valign="top">The number of milliseconds leeway to give before
  157. deciding a file is out of date. This is needed because not every
  158. file system supports tracking the last modified time to the
  159. millisecond level. Default is 1 second, or 2 seconds on DOS
  160. systems. This can also be useful if source and target files live
  161. on separate machines with clocks being out of sync. <em>since Ant
  162. 1.6.2</em>.</td>
  163. <td align="center">No</td>
  164. </tr>
  165. </table>
  166. <h3>Parameters specified as nested elements</h3>
  167. <h4>fileset or any other resource collection</h4>
  168. <p><a href="../Types/resources.html#collection">Resource
  169. Collection</a>s are used to select groups of files to copy. To use a
  170. resource collection, the <code>todir</code> attribute must be set.</p>
  171. <p>Prior to Ant 1.7 only <code>&lt;fileset&gt;</code> has been
  172. supported as a nested element.</p>
  173. <h4>mapper</h4>
  174. <p>You can define filename transformations by using a nested <a
  175. href="../Types/mapper.html">mapper</a> element. The default mapper used by
  176. <code>&lt;copy&gt;</code> is the <a
  177. href="../Types/mapper.html#identity-mapper">identity mapper</a>.</p>
  178. <p>
  179. <em>Since Ant 1.6.3</em>,
  180. one can use a filenamemapper type in place of the mapper element.
  181. </p>
  182. <p>Note that the source name handed to the mapper depends on the
  183. resource collection you use. If you use <code>&lt;fileset&gt;</code>
  184. or any other collection that provides a base directory, the name
  185. passed to the mapper will be a relative filename, relative to the base
  186. directory. In any other case the absolute filename of the source will
  187. be used.</p>
  188. <h4>filterset</h4>
  189. <p><a href="../Types/filterset.html">FilterSet</a>s are used to replace
  190. tokens in files that are copied.
  191. To use a FilterSet, use the nested <code>&lt;filterset&gt;</code> element.</p>
  192. <p>It is possible to use more than one filterset.</p>
  193. <h4>filterchain</h4>
  194. <p>The Copy task supports nested <a href="../Types/filterchain.html">
  195. FilterChain</a>s.</p>
  196. <p>
  197. If <code>&lt;filterset&gt;</code> and <code>&lt;filterchain&gt;</code> elements are used inside the
  198. same <code>&lt;copy&gt;</code> task, all <code>&lt;filterchain&gt;</code> elements are processed first
  199. followed by <code>&lt;filterset&gt;</code> elements.
  200. </p>
  201. <h3>Examples</h3>
  202. <p><b>Copy a single file</b></p>
  203. <pre>
  204. &lt;copy file=&quot;myfile.txt&quot; tofile=&quot;mycopy.txt&quot;/&gt;
  205. </pre>
  206. <p><b>Copy a single file to a directory</b></p>
  207. <pre>
  208. &lt;copy file=&quot;myfile.txt&quot; todir=&quot;../some/other/dir&quot;/&gt;
  209. </pre>
  210. <p><b>Copy a directory to another directory</b></p>
  211. <pre>
  212. &lt;copy todir=&quot;../new/dir&quot;&gt;
  213. &lt;fileset dir=&quot;src_dir&quot;/&gt;
  214. &lt;/copy&gt;
  215. </pre>
  216. <p><b>Copy a set of files to a directory</b></p>
  217. <pre>
  218. &lt;copy todir=&quot;../dest/dir&quot;&gt;
  219. &lt;fileset dir=&quot;src_dir&quot;&gt;
  220. &lt;exclude name=&quot;**/*.java&quot;/&gt;
  221. &lt;/fileset&gt;
  222. &lt;/copy&gt;
  223. &lt;copy todir=&quot;../dest/dir&quot;&gt;
  224. &lt;fileset dir=&quot;src_dir&quot; excludes=&quot;**/*.java&quot;/&gt;
  225. &lt;/copy&gt;
  226. </pre>
  227. <p><b>Copy a set of files to a directory, appending
  228. <code>.bak</code> to the file name on the fly</b></p>
  229. <pre>
  230. &lt;copy todir=&quot;../backup/dir&quot;&gt;
  231. &lt;fileset dir=&quot;src_dir&quot;/&gt;
  232. &lt;globmapper from=&quot;*&quot; to=&quot;*.bak&quot;/&gt;
  233. &lt;/copy&gt;
  234. </pre>
  235. <p><b>Copy a set of files to a directory, replacing @TITLE@ with Foo Bar
  236. in all files.</b></p>
  237. <pre>
  238. &lt;copy todir=&quot;../backup/dir&quot;&gt;
  239. &lt;fileset dir=&quot;src_dir&quot;/&gt;
  240. &lt;filterset&gt;
  241. &lt;filter token=&quot;TITLE&quot; value=&quot;Foo Bar&quot;/&gt;
  242. &lt;/filterset&gt;
  243. &lt;/copy&gt;
  244. </pre>
  245. <p><b>Collect all items from the current CLASSPATH setting into a
  246. destination directory, flattening the directory structure.</b></p>
  247. <pre>
  248. &lt;copy todir=&quot;dest&quot; flatten=&quot;true&quot;&gt;
  249. &lt;path&gt;
  250. &lt;pathelement path=&quot;${java.class.path}&quot;/&gt;
  251. &lt;/path&gt;
  252. &lt;/copy&gt;
  253. </pre>
  254. <p><b>Copies some resources to a given directory.</b></p>
  255. <pre>
  256. &lt;copy todir=&quot;dest&quot; flatten=&quot;true&quot;&gt;
  257. &lt;resources&gt;
  258. &lt;file file=&quot;src_dir/file1.txt&quot;/&gt;
  259. &lt;url url=&quot;http://ant.apache.org/index.html&quot;/&gt;
  260. &lt;/resources&gt;
  261. &lt;/copy&gt;
  262. </pre>
  263. <p>If the example above didn't use the flatten attribute,
  264. the <code>&lt;file&gt;</code> resource would have returned its full
  265. path as source and target name and would not have been copied at
  266. all. In general it is a good practice to use an explicit mapper
  267. together with resources that use an absolute path as their
  268. names.</p>
  269. <p><b>Copies the two newest resources into a destination directory.</b></p>
  270. <pre>
  271. &lt;copy todir=&quot;dest&quot; flatten=&quot;true&quot;&gt;
  272. &lt;first count=&quot;2&quot;&gt;
  273. &lt;sort&gt;
  274. &lt;date xmlns=&quot;antlib:org.apache.tools.ant.types.resources.comparators&quot;/&gt;
  275. &lt;resources&gt;
  276. &lt;file file=&quot;src_dir/file1.txt&quot;/&gt;
  277. &lt;file file=&quot;src_dir/file2.txt&quot;/&gt;
  278. &lt;file file=&quot;src_dir/file3.txt&quot;/&gt;
  279. &lt;url url=&quot;http://ant.apache.org/index.html&quot;/&gt;
  280. &lt;/resources&gt;
  281. &lt;/sort&gt;
  282. &lt;/first&gt;
  283. &lt;/copy&gt;
  284. </pre>
  285. <p>The paragraph following the previous example applies to this
  286. example as well.</p>
  287. <p><strong>Unix Note:</strong> File permissions are not retained when files
  288. are copied; they end up with the default <code>UMASK</code> permissions
  289. instead. This
  290. is caused by the lack of any means to query or set file permissions in the
  291. current Java runtimes. If you need a permission-preserving copy function,
  292. use <code>&lt;exec executable="cp" ... &gt;</code> instead.
  293. </p>
  294. <p><strong>Windows Note:</strong> If you copy a file to a directory
  295. where that file already exists, but with different casing,
  296. the copied file takes on the case of the original. The workaround is to
  297. <a href="delete.html">delete</a>
  298. the file in the destination directory before you copy it.
  299. </p>
  300. <p>
  301. <strong><a name="encoding">Important Encoding Note:</a></strong>
  302. The reason that binary files when filtered get corrupted is that
  303. filtering involves reading in the file using a Reader class. This
  304. has an encoding specifing how files are encoded. There are a number
  305. of different types of encoding - UTF-8, UTF-16, Cp1252, ISO-8859-1,
  306. US-ASCII and (lots) others. On Windows the default character encoding
  307. is Cp1252, on Unix it is usually UTF-8. For both of these encoding
  308. there are illegal byte sequences (more in UTF-8 than for Cp1252).
  309. </p>
  310. <p>
  311. How the Reader class deals with these illegal sequences is up to the
  312. implementation
  313. of the character decoder. The current Sun Java implemenation is to
  314. map them to legal characters. Previous Sun Java (1.3 and lower) threw
  315. a MalformedInputException. IBM Java 1.4 also thows this exception.
  316. It is the mapping of the characters that cause the corruption.
  317. </p>
  318. <p>
  319. On Unix, where the default is normally UTF-8, this is a <em>big</em>
  320. problem, as it is easy to edit a file to contain non US Ascii characters
  321. from ISO-8859-1, for example the Danish oe character. When this is
  322. copied (with filtering) by Ant, the character get converted to a
  323. question mark (or some such thing).
  324. </p>
  325. <p>
  326. There is not much that Ant can do. It cannot figure out which
  327. files are binary - a UTF-8 version of Korean will have lots of
  328. bytes with the top bit set. It is not informed about illegal
  329. character sequences by current Sun Java implementions.
  330. </p>
  331. <p>
  332. One trick for filtering containing only US-ASCII is to
  333. use the ISO-8859-1 encoding. This does not seem to contain
  334. illegal character sequences, and the lower 7 bits are US-ASCII.
  335. Another trick is to change the LANG environment variable from
  336. something like "us.utf8" to "us".
  337. </p>
  338. </body></html>