Copy Task

From 753a6c60f47f3ac4f270005b65e9d6481de8eb68 Mon Sep 17 00:00:00 2001 From: Ashlee Young Date: Fri, 23 Oct 2015 10:00:02 -0700 Subject: Adding maven and ant source trees Change-Id: I0a39b9add833a31b9c3f98d193983ae2f3a5a445 Signed-off-by: Ashlee Young --- .../ant/apache-ant-1.9.6/manual/Tasks/copy.html | 376 +++++++++++++++++++++ 1 file changed, 376 insertions(+) create mode 100644 framework/src/ant/apache-ant-1.9.6/manual/Tasks/copy.html (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/copy.html') diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/copy.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/copy.html new file mode 100644 index 00000000..d1b8ff2a --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/copy.html @@ -0,0 +1,376 @@ + + + + + + +Copy Task + + + + +

Copy

Description

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 overwrite attribute.

+ +

Resource +Collections are used to select a group of files to copy. To use a +resource collection, the todir attribute must be set. +Note that some resources (for example +the file 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 +expect.

+ +

+Note: 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 +filter task or explicitly provided to the copy +operation as filtersets. + See encoding note. +

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Attribute	Description	Required
file	The file to copy.	Yes, unless a nested + resource collection element is used.
preservelastmodified	Give the copied files the same last modified + time as the original source files.	No; defaults to false.
tofile	The file to copy to.	With the `file` + attribute, either `tofile` or `todir` can be used. + + With nested resource collection elements, if the number of + included resources + is greater than 1, or if only the `dir` attribute is + specified in the `<fileset>`, or if the + `file` attribute is also specified, then only + `todir` is allowed. + Prior to Apache Ant 1.8.2 the `tofile` attribute + only supported filesystem resources top copy from.
todir	The directory to copy to.
overwrite	Overwrite existing files even if the destination + files are newer.	No; defaults to false.
force	Overwrite read-only destination + files. since Ant 1.8.2	No; defaults to false.
filtering	Indicates whether token filtering using the global + build-file filters should take place during the copy. + Note: Nested `<filterset>` elements will + always be used, even if this attribute is not specified, or its value is + `false` (`no`, or `off`).	No; defaults to false.
flatten	Ignore the directory structure of the source files, + and copy all files into the directory specified by the `todir` + attribute. Note that you can achieve the same effect by using a + flatten mapper.	No; defaults to false.
includeEmptyDirs	Copy any empty directories included in the FileSet(s). +	No; defaults to true.
failonerror	If false, 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. +	No; defaults to true.
quiet	If true and failonerror is false, 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. since Ant 1.8.3. +	No; defaults to false.
verbose	Log the files that are being copied.	No; defaults to false.
encoding	The encoding to assume when filter-copying the + files. since Ant 1.5.	No - defaults to default JVM encoding
outputencoding	The encoding to use when writing the files. + since Ant 1.6.	No - defaults to the value of the encoding + attribute if given or the default JVM encoding otherwise.
enablemultiplemappings	+ If true the task will process to all the mappings for a + given source path. If false the task will only process + the first file or directory. This attribute is only relevant + if there is a mapper subelement. + since Ant 1.6.	No - defaults to false.
granularity	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. Default is 1 second, or 2 seconds on DOS + systems. This can also be useful if source and target files live + on separate machines with clocks being out of sync. since Ant + 1.6.2.	No

Parameters specified as nested elements

+ +

fileset or any other resource collection

Resource +Collections are used to select groups of files to copy. To use a +resource collection, the todir attribute must be set.

Prior to Ant 1.7 only <fileset> has been +supported as a nested element.

+ +

mapper

You can define filename transformations by using a nested mapper element. The default mapper used by + <copy> is the identity mapper.

+ Since Ant 1.6.3, + one can use a filenamemapper type in place of the mapper element. +

+ +

Note that the source name handed to the mapper depends on the +resource collection you use. If you use <fileset> +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.

+ +

filterset

FilterSets are used to replace +tokens in files that are copied. + To use a FilterSet, use the nested <filterset> element.

+ +

It is possible to use more than one filterset.

+ +

filterchain

The Copy task supports nested +FilterChains.

+ +

+If <filterset> and <filterchain> elements are used inside the +same <copy> task, all <filterchain> elements are processed first +followed by <filterset> elements. +

+ +

Examples

Copy a single file

+  <copy file="myfile.txt" tofile="mycopy.txt"/>
+

Copy a single file to a directory

+  <copy file="myfile.txt" todir="../some/other/dir"/>
+

Copy a directory to another directory

+  <copy todir="../new/dir">
+    <fileset dir="src_dir"/>
+  </copy>
+

Copy a set of files to a directory

+  <copy todir="../dest/dir">
+    <fileset dir="src_dir">
+      <exclude name="**/*.java"/>
+    </fileset>
+  </copy>
+
+  <copy todir="../dest/dir">
+    <fileset dir="src_dir" excludes="**/*.java"/>
+  </copy>
+

Copy a set of files to a directory, appending +.bak to the file name on the fly

+  <copy todir="../backup/dir">
+    <fileset dir="src_dir"/>
+    <globmapper from="*" to="*.bak"/>
+  </copy>
+

+ +

Copy a set of files to a directory, replacing @TITLE@ with Foo Bar +in all files.

+  <copy todir="../backup/dir">
+    <fileset dir="src_dir"/>
+    <filterset>
+      <filter token="TITLE" value="Foo Bar"/>
+    </filterset>
+  </copy>
+

+ +

Collect all items from the current CLASSPATH setting into a +destination directory, flattening the directory structure.

+  <copy todir="dest" flatten="true">
+    <path>
+      <pathelement path="${java.class.path}"/>
+    </path>
+  </copy>
+

+ +

Copies some resources to a given directory.

+  <copy todir="dest" flatten="true">
+    <resources>
+      <file file="src_dir/file1.txt"/>
+      <url url="http://ant.apache.org/index.html"/>
+    </resources>
+  </copy>
+

+ +

If the example above didn't use the flatten attribute, + the <file> 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.

+ +

Copies the two newest resources into a destination directory.

+  <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>
+

+ +

The paragraph following the previous example applies to this + example as well.

+ +

Unix Note: File permissions are not retained when files +are copied; they end up with the default UMASK 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 <exec executable="cp" ... > instead. +

+ +

Windows Note: If you copy a file to a directory +where that file already exists, but with different casing, +the copied file takes on the case of the original. The workaround is to +delete +the file in the destination directory before you copy it. +

+ Important Encoding Note: + 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) 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). +

+ 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 Sun Java (1.3 and lower) threw + a MalformedInputException. IBM Java 1.4 also throws this exception. + It is the mapping of the characters that cause the corruption. +

+ On Unix, where the default is normally UTF-8, this is a big + problem, as it is easy to edit a file to contain non US Ascii characters + from ISO-8859-1, for example the Danish oe character. When this is + copied (with filtering) by Ant, the character get converted to a + question mark (or some such thing). +

+ 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 implementions. +

+ 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 LANG environment variable from + something like "us.utf8" to "us". +

+ + + + + -- cgit