|
|
|
@@ -0,0 +1,205 @@ |
|
|
|
<document> |
|
|
|
|
|
|
|
<properties> |
|
|
|
<author email="adammurdoch@apache.org">Adam Murdoch</author> |
|
|
|
<title>VFS User Guide</title> |
|
|
|
</properties> |
|
|
|
|
|
|
|
<body> |
|
|
|
|
|
|
|
<section name="Handling Files"> |
|
|
|
|
|
|
|
<p>Myrmidon includes a Virtual File System (VFS), which allows files from |
|
|
|
different sources to be treated identically. The VFS currently supports |
|
|
|
the following file types:</p> |
|
|
|
|
|
|
|
<table> |
|
|
|
<tr><th>File System</th><th>Description</th><th>URL Format</th></tr> |
|
|
|
<tr> |
|
|
|
<td>Local Files</td> |
|
|
|
<td>Files on the local file system.</td> |
|
|
|
<td>Three different formats are currently supported for local file names: |
|
|
|
<ul> |
|
|
|
<li><code>file://</code> <i>absolute-file-name</i></li> |
|
|
|
<li>Absolute file names</li> |
|
|
|
<li>Relative file names. These are resolved relative to the |
|
|
|
project's base directory. |
|
|
|
</li> |
|
|
|
</ul> |
|
|
|
</td> |
|
|
|
</tr> |
|
|
|
<tr> |
|
|
|
<td>Zip Files</td> |
|
|
|
<td>The contents of Zip files (and Jar, War, and Ear files). |
|
|
|
Currently, the VFS supports read-only access to Zip file contents, |
|
|
|
and only for local Zip files.</td> |
|
|
|
<td><code>zip://</code> <i>zip-file-path</i> [<code>!</code><i>absolute-path</i>]</td> |
|
|
|
</tr> |
|
|
|
<tr> |
|
|
|
<td>FTP</td> |
|
|
|
<td>Files on an FTP server.</td> |
|
|
|
<td><code>ftp://</code> [[<i>password</i><code>:</code>] <i>username</i><code>@</code>] <i>hostname</i> [<code>:</code><i>port</i>] [<i>absolute-path</i>]</td> |
|
|
|
</tr> |
|
|
|
<tr> |
|
|
|
<td>SMB</td> |
|
|
|
<td>Files on a CFIS server, such as Samba or Windows shares.</td> |
|
|
|
<td><code>smb://</code> [[<i>password</i><code>:</code>] <i>username</i><code>@</code>] <i>hostname</i> [<code>:</code><i>port</i>] [<i>absolute-path</i>]</td> |
|
|
|
</tr> |
|
|
|
</table> |
|
|
|
|
|
|
|
<p>Here are some example URLs:</p> |
|
|
|
|
|
|
|
<ul> |
|
|
|
<li><code>build/classes</code></li> |
|
|
|
<li><code>c:\program files\ant\bin</code></li> |
|
|
|
<li><code>file://C:/program files/ant</code></li> |
|
|
|
<li><code>zip://build/lib/ant.jar!/org/apache/tools</code></li> |
|
|
|
<li><code>ftp://adam@somehost/pub/downloads</code></li> |
|
|
|
<li><code>smb://password:adam@somehost/home/adam</code></li> |
|
|
|
</ul> |
|
|
|
|
|
|
|
<p>Currently, there are only a handful of VFS aware tasks. This will grow |
|
|
|
as more tasks are ported to the new API, and data types.</p> |
|
|
|
|
|
|
|
<subsection name="File Sets"> |
|
|
|
|
|
|
|
<p>A file set in Myrmidon is more general than Ant 1's concept of a file set. |
|
|
|
Firstly, there is more than one type of file set. Secondly, they are VFS enabled. |
|
|
|
File sets are automatically converted to a <a href="#Paths">path</a>, and so |
|
|
|
can be used anywhere that a path can.</p> |
|
|
|
|
|
|
|
<h3><code><v-fileset></code></h3> |
|
|
|
|
|
|
|
<p>This is the equivalent of Ant 1's <code><fileset></code> (The name |
|
|
|
is temporary, it will be changed to <code><fileset></code> once more |
|
|
|
porting work as been completed).</p> |
|
|
|
|
|
|
|
<p>Rather than use a set of include and exclude patterns to choose the files |
|
|
|
that make up the file set, <code><v-fileset></code> takes zero or more |
|
|
|
<a href="#File Selectors">file selectors</a>. File selectors can be used to |
|
|
|
select files based on any attribute of the file, rather than just the name. |
|
|
|
You can use <code><name></code> selectors to achieve the same result |
|
|
|
as using includes or excludes.</p> |
|
|
|
|
|
|
|
<p>A <code><v-fileset></code> element takes the following attributes:</p> |
|
|
|
|
|
|
|
<table> |
|
|
|
<tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr> |
|
|
|
<tr> |
|
|
|
<td>dir</td> |
|
|
|
<td>The base directory for the file set. This can be any URL that the |
|
|
|
VFS supports.</td> |
|
|
|
<td>Required</td> |
|
|
|
</tr> |
|
|
|
</table> |
|
|
|
|
|
|
|
<p>A <code><v-fileset></code> element takes any number of nested |
|
|
|
<a href="#File Selectors">file selector</a> elements. To be included in the |
|
|
|
file set, a file must be selected by all the file selectors. That is, the |
|
|
|
file selectors are implicitly AND-ed together. If no file selector is provided, |
|
|
|
all the files and directories are included in the set.</p> |
|
|
|
|
|
|
|
<p>An example:</p> |
|
|
|
|
|
|
|
<source><![CDATA[ |
|
|
|
|
|
|
|
<v-fileset dir="src"> |
|
|
|
<name pattern="org/apache/tools/ant/**"/> |
|
|
|
<is-file/> |
|
|
|
</v-fileset> |
|
|
|
]]></source> |
|
|
|
|
|
|
|
<h3><code><flat-fileset></code></h3> |
|
|
|
|
|
|
|
<p>This file set takes a set of nested file sets and paths, and flattens them |
|
|
|
into a single directory. It can be used as a way of converting a path into a |
|
|
|
file set. It can also be used as a replacement for the <code>flatten</code> |
|
|
|
attribute for the copy and move tasks.</p> |
|
|
|
|
|
|
|
<p>A <code><flat-fileset></code> element takes no attributes, and a set |
|
|
|
of nested paths or file sets.</p> |
|
|
|
|
|
|
|
<p>An example:</p> |
|
|
|
|
|
|
|
<source><![CDATA[ |
|
|
|
|
|
|
|
<v-copy todir="dist/lib"> |
|
|
|
<flat-fileset> |
|
|
|
<v-fileset dir="build/lib"> |
|
|
|
<basename pattern="*.jar"/> |
|
|
|
<v-fileset> |
|
|
|
<v-path path="${classpath}"/> |
|
|
|
</flat-fileset> |
|
|
|
</v-copy> |
|
|
|
]]></source> |
|
|
|
|
|
|
|
</subsection> |
|
|
|
|
|
|
|
<subsection name="Paths"> |
|
|
|
|
|
|
|
<p>Paths are an ordered list of files.</p> |
|
|
|
|
|
|
|
<h3><code><v-path></code></h3> |
|
|
|
|
|
|
|
<p>This is the equivalent of Ant 1's <code><path></code>.</p> |
|
|
|
|
|
|
|
<h3><code><filtered-path></code></h3> |
|
|
|
|
|
|
|
<p>A path that applies file selectors to a set of nested file sets and paths.</p> |
|
|
|
|
|
|
|
</subsection> |
|
|
|
|
|
|
|
<subsection name="File Selectors"> |
|
|
|
|
|
|
|
<p>File selectors are used to select files from file sets and paths.</p> |
|
|
|
|
|
|
|
<h3><code><and></code></h3> |
|
|
|
|
|
|
|
<p>Combines zero or more file selectors, using AND. An empty <code><and></code> |
|
|
|
selector accepts all files.</p> |
|
|
|
|
|
|
|
<h3><code><basename></code></h3> |
|
|
|
|
|
|
|
<p>Selects files whose base name matches an Ant 1 style pattern, or a regular |
|
|
|
expression.</p> |
|
|
|
|
|
|
|
<h3><code><exists></code></h3> |
|
|
|
|
|
|
|
<p>Selects files that exist.</p> |
|
|
|
|
|
|
|
<h3><code><is-empty></code></h3> |
|
|
|
|
|
|
|
<p>Selects empty folders, that is, folders that have no children.</p> |
|
|
|
|
|
|
|
<h3><code><is-folder></code></h3> |
|
|
|
|
|
|
|
<p>Selects folders, does not select regular files.</p> |
|
|
|
|
|
|
|
<h3><code><is-file></code></h3> |
|
|
|
|
|
|
|
<p>Selects regular files, does not select folders.</p> |
|
|
|
|
|
|
|
<h3><code><name></code></h3> |
|
|
|
|
|
|
|
<p>Selects files whose path in a file set matches an Ant 1 style pattern, or |
|
|
|
a regular expression.</p> |
|
|
|
|
|
|
|
<h3><code><not></code></h3> |
|
|
|
|
|
|
|
<p>Selects files that are not selected by a nested file selector.</p> |
|
|
|
|
|
|
|
<h3><code><or></code></h3> |
|
|
|
|
|
|
|
<p>Combines zero or more file selectors, using OR. An empty <code><or></code> |
|
|
|
selector accepts all files.</p> |
|
|
|
|
|
|
|
<h3><code><url></code></h3> |
|
|
|
|
|
|
|
<p>Selects files whose URL matches an Ant 1 style pattern, or a regular expression.</p> |
|
|
|
|
|
|
|
</subsection> |
|
|
|
|
|
|
|
</section> |
|
|
|
</body> |
|
|
|
|
|
|
|
</document> |
Peter Donald