2006-09-11 04:19:00 +00:00
|
|
|
<!--
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
http://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.
|
|
|
|
|
-->
|
2001-02-13 12:32:01 +00:00
|
|
|
<html>
|
|
|
|
|
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
2005-04-29 18:58:16 +00:00
|
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
2001-12-04 03:06:04 +00:00
|
|
|
<title>Copy Task</title>
|
2001-02-13 12:32:01 +00:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
2018-01-22 23:52:21 +01:00
|
|
|
<h2 id="copy">Copy</h2>
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Description</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Copies a file or resource collection to a new file or directory. By default, files are only
|
|
|
|
|
copied if the source file is newer than the destination file, or when the destination file does not
|
|
|
|
|
exist. However, you can explicitly overwrite files with the <var>overwrite</var> attribute.</p>
|
2003-02-05 13:14:33 +00:00
|
|
|
|
2018-03-05 17:35:30 +01:00
|
|
|
<p><a href="../Types/resources.html#collection">Resource collections</a> are used to select a group
|
2018-02-28 07:58:59 +01:00
|
|
|
of files to copy. To use a resource collection, the <var>todir</var> attribute must be
|
|
|
|
|
set. <strong>Note</strong> that some resources (for example
|
|
|
|
|
the <a href="../Types/resources.html#file">file</a> resource) return absolute paths as names and the
|
|
|
|
|
result of using them without using a nested mapper (or the flatten attribute) may not be what you
|
2008-10-09 11:29:17 +00:00
|
|
|
expect.</p>
|
2003-02-05 13:14:33 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><strong>Note</strong>: If you employ filters in your copy operation, you should limit the copy to
|
|
|
|
|
text files. Binary files will be corrupted by the copy operation. This applies whether the filters
|
|
|
|
|
are implicitly defined by the <a href="filter.html">filter</a> task or explicitly provided to the
|
|
|
|
|
copy operation
|
|
|
|
|
as <a href="../Types/filterset.html">filtersets</a>. <em>See <a href="#encoding">encoding
|
|
|
|
|
note</a></em>.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Parameters</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>file</td>
|
|
|
|
|
<td>The file to copy.</td>
|
|
|
|
|
<td>Yes, unless a nested resource collection element is used</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>preservelastmodified</td>
|
|
|
|
|
<td>Give the copied files the same last modified time as the original source files.</td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>tofile</td>
|
|
|
|
|
<td>The file to copy to. Prior to Apache Ant 1.8.2, the <var>tofile</var> attribute only
|
|
|
|
|
supported <a href="../Types/resources.html#file">file resources</a> to copy from.</td>
|
|
|
|
|
<td rowspan="2">With the <var>file</var> attribute, either <var>tofile</var> or <var>todir</var>
|
|
|
|
|
can be used.<br/> With nested resource collection elements, if the number of included
|
|
|
|
|
resources is greater than 1, or if only the <var>dir</var> attribute is specified in
|
|
|
|
|
the <code><fileset></code>, or if the <var>file</var> attribute is also specified, then
|
|
|
|
|
only <var>todir</var> is allowed.<br/></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>todir</td>
|
2018-03-03 21:26:50 +01:00
|
|
|
<td class="left">The directory to copy to.</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>overwrite</td>
|
|
|
|
|
<td>Overwrite existing files even if the destination files are newer.</td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2010-05-10 14:35:56 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>force</td>
|
|
|
|
|
<td>Overwrite read-only destination files. <em>since Ant 1.8.2</em></td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2010-05-10 14:35:56 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>filtering</td>
|
|
|
|
|
<td>Indicates whether token filtering using the <a href="../using.html#filters">global
|
|
|
|
|
build-file filters</a> should take place during the copy. <strong>Note</strong>:
|
|
|
|
|
Nested <code><filterset></code> elements will always be used, even if this attribute is
|
|
|
|
|
not specified, or its value is <q>false</q>, <q>no</q>, or <q>off</q>.</td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>flatten</td>
|
|
|
|
|
<td>Ignore the directory structure of the source files, and copy all files into the directory
|
|
|
|
|
specified by the <var>todir</var> attribute. Note that you can achieve the same effect by
|
|
|
|
|
using a <a href="../Types/mapper.html#flatten-mapper">flatten mapper</a>.</td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>includeEmptyDirs</td>
|
|
|
|
|
<td>Copy any empty directories included in the FileSet(s).</td>
|
|
|
|
|
<td>No; defaults to <q>true</q></td>
|
2002-04-01 03:49:51 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>failonerror</td>
|
|
|
|
|
<td>If <q>false</q>, log a warning message, but do not stop the build, when the file to copy
|
|
|
|
|
does not exist or one of the nested filesets points to a directory that doesn't exist or an
|
|
|
|
|
error occurs while copying.</td>
|
|
|
|
|
<td>No; defaults to <q>true</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2011-07-24 10:35:58 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>quiet</td>
|
|
|
|
|
<td>If <q>true</q> and <var>failonerror</var> is <q>false</q>, then do not log a warning message
|
|
|
|
|
when the file to copy does not exist or one of the nested filesets points to a directory that
|
|
|
|
|
doesn't exist or an error occurs while copying. <em>since Ant 1.8.3</em>.</td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2011-07-24 10:35:58 +00:00
|
|
|
</tr>
|
2002-06-01 12:26:43 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>verbose</td>
|
|
|
|
|
<td>Log the files that are being copied.</td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2002-06-01 12:26:43 +00:00
|
|
|
</tr>
|
2003-03-27 16:32:19 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>encoding</td>
|
|
|
|
|
<td>The encoding to assume when filter-copying the files. <em>since Ant 1.5</em>.</td>
|
|
|
|
|
<td>No; defaults to default JVM character encoding</td>
|
2003-03-27 16:32:19 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>outputencoding</td>
|
|
|
|
|
<td>The encoding to use when writing the files.
|
2003-03-27 16:32:19 +00:00
|
|
|
<em>since Ant 1.6</em>.</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No; defaults to <var>encoding</var> if set or default JVM character encoding otherwise</td>
|
2003-03-27 16:32:19 +00:00
|
|
|
</tr>
|
2003-07-24 13:14:21 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>enablemultiplemappings</td>
|
|
|
|
|
<td>If <q>true</q> the task will process to all the mappings for a given source
|
|
|
|
|
path. If <q>false</q> the task will only process the first file or directory. This attribute
|
|
|
|
|
is only relevant if there is a <code>mapper</code> subelement. <em>since Ant 1.6</em>.</td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2003-07-24 13:14:21 +00:00
|
|
|
</tr>
|
2003-09-23 13:16:04 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>granularity</td>
|
|
|
|
|
<td>The number of milliseconds leeway to give before deciding a file is out of date. This is
|
|
|
|
|
needed because not every file system supports tracking the last modified time to the
|
|
|
|
|
millisecond level. This can also be useful if source and target files live on separate
|
|
|
|
|
machines with clocks being out of sync. <em>since Ant 1.6.2</em>.</td>
|
|
|
|
|
<td>No; default is 1 second, or 2 seconds on DOS systems</td>
|
2003-09-23 13:16:04 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
</table>
|
|
|
|
|
<h3>Parameters specified as nested elements</h3>
|
2002-06-01 12:26:43 +00:00
|
|
|
|
2018-03-05 17:35:30 +01:00
|
|
|
<h4>any filesystem based resource collection</h4>
|
|
|
|
|
<p><a href="../Types/resources.html#collection">Resource collections</a> are used to select groups
|
2018-02-28 07:58:59 +01:00
|
|
|
of files to copy. To use a resource collection, the <var>todir</var> attribute must be set.</p>
|
|
|
|
|
<p>Prior to Ant 1.7, only <code><fileset></code> has been supported as a nested element.</p>
|
2002-06-01 12:26:43 +00:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
<h4>mapper</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>You can define filename transformations by using a
|
|
|
|
|
nested <a href="../Types/mapper.html">mapper</a> element. The default mapper used
|
|
|
|
|
by <code><copy></code> is the <a href="../Types/mapper.html#identity-mapper">identity
|
|
|
|
|
mapper</a>.</p>
|
|
|
|
|
<p><em>Since Ant 1.6.3</em>, one can use a filenamemapper type in place of the mapper element.</p>
|
2002-06-01 12:26:43 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Note that the source name handed to the mapper depends on the resource collection you use. If
|
|
|
|
|
you use <code><fileset></code> or any other collection that provides a base directory, the
|
|
|
|
|
name passed to the mapper will be a relative filename, relative to the base directory. In any other
|
|
|
|
|
case the absolute filename of the source will be used.</p>
|
2005-09-28 18:42:46 +00:00
|
|
|
|
2001-08-30 13:23:14 +00:00
|
|
|
<h4>filterset</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><a href="../Types/filterset.html">FilterSet</a>s are used to replace tokens in files that are
|
|
|
|
|
copied. To use a FilterSet, use the nested <code><filterset></code> element.</p>
|
2002-06-01 12:26:43 +00:00
|
|
|
|
2009-08-18 11:23:09 +00:00
|
|
|
<p>It is possible to use more than one filterset.</p>
|
|
|
|
|
|
2002-06-01 12:26:43 +00:00
|
|
|
<h4>filterchain</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>The Copy task supports nested <a href="../Types/filterchain.html">FilterChain</a>s.</p>
|
2002-06-01 12:26:43 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>If <code><filterset></code> and <code><filterchain></code> elements are used inside
|
|
|
|
|
the same <code><copy></code> task, all <code><filterchain></code> elements are processed
|
|
|
|
|
first followed by <code><filterset></code> elements.</p>
|
2002-07-22 11:12:16 +00:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Examples</h3>
|
2018-05-15 09:51:58 +02:00
|
|
|
|
|
|
|
|
<p>Copy a single file</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre><copy file="myfile.txt" tofile="mycopy.txt"/></pre>
|
2018-05-15 09:51:58 +02:00
|
|
|
|
|
|
|
|
<p>Copy a single file to a directory</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre><copy file="myfile.txt" todir="../some/other/dir"/></pre>
|
2018-05-15 09:51:58 +02:00
|
|
|
|
|
|
|
|
<p>Copy a directory to another directory</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<copy todir="../new/dir">
|
|
|
|
|
<fileset dir="src_dir"/>
|
|
|
|
|
</copy>
|
2001-02-13 12:32:01 +00:00
|
|
|
</pre>
|
2018-05-15 09:51:58 +02:00
|
|
|
|
|
|
|
|
<p>Copy a set of files to a directory</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<copy todir="../dest/dir">
|
|
|
|
|
<fileset dir="src_dir">
|
|
|
|
|
<exclude name="**/*.java"/>
|
|
|
|
|
</fileset>
|
|
|
|
|
</copy>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<copy todir="../dest/dir">
|
|
|
|
|
<fileset dir="src_dir" excludes="**/*.java"/>
|
|
|
|
|
</copy></pre>
|
2018-05-15 09:51:58 +02:00
|
|
|
|
|
|
|
|
<p>Copy a set of files to a directory, appending <samp>.bak</samp> to the file name on the
|
|
|
|
|
fly</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<copy todir="../backup/dir">
|
|
|
|
|
<fileset dir="src_dir"/>
|
|
|
|
|
<globmapper from="*" to="*.bak"/>
|
|
|
|
|
</copy></pre>
|
2001-08-30 13:23:14 +00:00
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Copy a set of files to a directory, replacing <code>@TITLE@</code> with <samp>Foo
|
|
|
|
|
Bar</samp> in all files.</p>
|
2001-08-30 13:23:14 +00:00
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<copy todir="../backup/dir">
|
|
|
|
|
<fileset dir="src_dir"/>
|
|
|
|
|
<filterset>
|
|
|
|
|
<filter token="TITLE" value="Foo Bar"/>
|
|
|
|
|
</filterset>
|
|
|
|
|
</copy></pre>
|
2001-08-30 13:23:14 +00:00
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Collect all items from the current <code>CLASSPATH</code> setting into a destination
|
|
|
|
|
directory, flattening the directory structure.</p>
|
2005-09-28 18:42:46 +00:00
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<copy todir="dest" flatten="true">
|
|
|
|
|
<path>
|
|
|
|
|
<pathelement path="${java.class.path}"/>
|
|
|
|
|
</path>
|
|
|
|
|
</copy></pre>
|
2005-09-28 18:42:46 +00:00
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Copies some resources to a given directory.</p>
|
2005-10-30 12:23:15 +00:00
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<copy todir="dest" flatten="true">
|
|
|
|
|
<resources>
|
|
|
|
|
<file file="src_dir/file1.txt"/>
|
|
|
|
|
<url url="http://ant.apache.org/index.html"/>
|
|
|
|
|
</resources>
|
|
|
|
|
</copy></pre>
|
2005-10-30 12:23:15 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>If the example above didn't use the <var>flatten</var> attribute, the <code><file></code>
|
|
|
|
|
resource would have returned its full path as source and target name and would not have been copied
|
|
|
|
|
at all. In general it is a good practice to use an explicit mapper together with resources that use
|
|
|
|
|
an absolute path as their names.</p>
|
2008-10-09 11:29:17 +00:00
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Copies the two newest resources into a destination directory.</p>
|
2005-10-30 12:23:15 +00:00
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<copy todir="dest" flatten="true">
|
|
|
|
|
<first count="2">
|
|
|
|
|
<sort>
|
|
|
|
|
<date xmlns="antlib:org.apache.tools.ant.types.resources.comparators"/>
|
|
|
|
|
<resources>
|
|
|
|
|
<file file="src_dir/file1.txt"/>
|
|
|
|
|
<file file="src_dir/file2.txt"/>
|
|
|
|
|
<file file="src_dir/file3.txt"/>
|
|
|
|
|
<url url="http://ant.apache.org/index.html"/>
|
|
|
|
|
</resources>
|
|
|
|
|
</sort>
|
|
|
|
|
</first>
|
|
|
|
|
</copy></pre>
|
2005-10-30 12:23:15 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>The paragraph following the previous example applies to this example as well.</p>
|
2005-10-30 12:23:15 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><strong>Unix Note</strong>: File permissions are not retained when files are copied; they end up
|
|
|
|
|
with the default <code>UMASK</code> permissions instead. This is caused by the lack of any means to
|
|
|
|
|
query or set file permissions in the current Java runtimes. If you need a permission-preserving copy
|
|
|
|
|
function, use <code><exec executable="cp" ... ></code> instead.</p>
|
2001-08-30 13:23:14 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><strong>Windows Note</strong>: If you copy a file to a directory where that file already exists,
|
|
|
|
|
but with different case, the copied file takes on the case of the original. The workaround is
|
|
|
|
|
to <a href="delete.html">delete</a> the file in the destination directory before you copy it.</p>
|
|
|
|
|
<p id="encoding"><strong>Important Encoding Note</strong>: The reason that binary files when
|
|
|
|
|
filtered get corrupted is that filtering involves reading in the file using a Reader class. This has
|
|
|
|
|
an encoding specifying how files are encoded. There are a number of different types of
|
|
|
|
|
encoding—UTF-8, UTF-16, Cp1252, ISO-8859-1, US-ASCII and (lots of) others. On Windows the
|
|
|
|
|
default character encoding is Cp1252, on Unix it is usually UTF-8. For both of these encoding there
|
|
|
|
|
are illegal byte sequences (more in UTF-8 than for Cp1252).</p>
|
|
|
|
|
<p>How the Reader class deals with these illegal sequences is up to the implementation of the
|
|
|
|
|
character decoder. The current Sun Java implementation is to map them to legal characters. Previous
|
2018-03-10 20:17:33 +01:00
|
|
|
Sun Java (1.3 and lower) threw a <code>MalformedInputException</code>. IBM Java 1.4 also throws this
|
|
|
|
|
exception. It is the mapping of the characters that cause the corruption.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>On Unix, where the default is normally UTF-8, this is a <em>big</em> problem, as it is easy to
|
|
|
|
|
edit a file to contain non US-ASCII characters from ISO-8859-1, for example the Danish œ
|
|
|
|
|
character. When this is copied (with filtering) by Ant, the character get converted to a question
|
|
|
|
|
mark (or some such thing).</p>
|
|
|
|
|
<p>There is not much that Ant can do. It cannot figure out which files are binary—a UTF-8
|
|
|
|
|
version of Korean will have lots of bytes with the top bit set. It is not informed about illegal
|
|
|
|
|
character sequences by current Sun Java implementations.</p>
|
|
|
|
|
<p>One trick for filtering containing only US-ASCII is to use the ISO-8859-1 encoding. This does not
|
|
|
|
|
seem to contain illegal character sequences, and the lower 7 bits are US-ASCII. Another trick is to
|
|
|
|
|
change the <code>LANG</code> environment variable from something like <q>us.utf8</q>
|
|
|
|
|
to <q>us</q>.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
2018-01-22 23:52:21 +01:00
|
|
|
</body>
|
|
|
|
|
</html>
|
