source: release-kits/lirk3/bin/ant-installer/web/manual1.7.0/manual/OptionalTasks/symlink.html@ 14982

Last change on this file since 14982 was 14982, checked in by oranfry, 16 years ago

initial import of LiRK3
File size: 5.5 KB
Line 
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
9 http://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS,
13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 See the License for the specific language governing permissions and
15 limitations under the License.
16-->
17<html>
18
19<head>
20<meta http-equiv="Content-Language" content="en-us">
21<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
22<title>Symlink Task</title>
23</head>
24
25<body>
26
27<h2><a name="symlink">Symlink</a></h2>
28<h3>Description</h3>
29<p> Manages symbolic links on Unix based platforms. Can be used to
30make an individual link, delete a link, create multiple links from properties files,
31or create properties files describing links in the specified directories.
32Existing links are not overwritten by default.
33
34<p><a href="../CoreTypes/fileset.html">FileSet</a>s are used to select a
35set of links to record, or a set of property files to create links from. </p>
36<h3>Parameters</h3>
37<table border="1" cellpadding="2" cellspacing="0">
38 <tr>
39 <td valign="top"><b>Attribute</b></td>
40 <td valign="top"><b>Description</b></td>
41 <td align="center" valign="top"><b>Required</b></td>
42 </tr>
43 <tr>
44 <td valign="top">action</td>
45 <td valign="top">The type of action to perform, may be "single",
46 "record", "recreate" or "delete".</td>
47 <td valign="top" align="center">No, defaults to single.</td>
48 </tr>
49 <tr>
50 <td valign="top">link</td>
51 <td valign="top">The name of the link to be created or deleted.</td>
52 <td valign="center" align="center" >required for
53 action="single" or "delete". Ignored in other actions.</td>
54 </tr>
55 <tr>
56 <td valign="top">resource</td>
57 <td valign="top">The resource the link should point to.</td>
58 <td valign="top" align="center">required for action="single". Ignored in other actions.</td>
59 </tr>
60 <tr>
61 <td valign="top">linkfilename</td>
62 <td valign="top">The name of the properties file to create in
63 each included directory.</td>
64 <td valign="top" align="center">required for action="record".
65 Ignored in other actions.</td>
66 </tr>
67 <tr>
68 <td valign="top">overwrite</td>
69 <td valign="top">Overwrite existing links or not.</td>
70 <td valign="top" align="center">No; defaults to false.</td>
71 </tr>
72 <tr>
73 <td valign="top">failonerror</td>
74 <td valign="top">Stop build if true, log a warning message, but do not stop the build,
75 when the an error occurs if false.
76 </td>
77 <td valign="top" align="center">No; defaults to true.</td>
78 </tr>
79</table>
80<h3>Parameters specified as nested elements</h3>
81
82<h4>fileset</h4>
83 <p><a href="../CoreTypes/fileset.html">FileSet</a>s
84 are used when action = "record" to select directories and linknames to be recorded.
85 They are also used when action = "recreate" to specify both the name of the property
86 files to be processed, and the directories in which they can be found. At least one
87 fileset is required for each case.</p>
88
89<h3>Examples</h3>
90
91 <p> Make a link named "foo" to a resource named "bar.foo" in subdir:</p>
92 <pre>
93 &lt;symlink link="${dir.top}/foo" resource="${dir.top}/subdir/bar.foo"/&gt;
94 </pre>
95
96 <p> Record all links in subdir and it's descendants in files named
97 "dir.links"</p>
98 <pre>
99 &lt;symlink action="record" linkfilename="dir.links"&gt;
100 &lt;fileset dir="${dir.top}" includes="subdir&#47;**"/&gt;
101 &lt;/symlink&gt;
102 </pre>
103
104 <p> Recreate the links recorded in the previous example:</p>
105 <pre>
106 &lt;symlink action="recreate"&gt;
107 &lt;fileset dir="${dir.top}" includes="subdir&#47;**&#47;dir.links"/&gt;
108 &lt;/symlink&gt;
109 </pre>
110
111 <p> Delete a link named "foo":
112 <pre>
113 &lt;symlink action="delete" link="${dir.top}/foo"/&gt;
114 </pre>
115
116 <p><strong>Java 1.2 and earlier:</strong> Due to limitations on executing system
117 level commands in Java versions earlier than 1.3 this task may have difficulty
118 operating with a relative path in ANT_HOME. The typical symptom is an
119 IOException where ant can't find /some/working/directory${ANT_HOME}/bin/antRun
120 or something similar. The workaround is to change your ANT_HOME environment
121 variable to an absolute path, which will remove the /some/working/directory portion
122 of the above path and allow ant to find the correct commandline execution script.
123
124 <p><strong>LIMITATIONS:</strong> Because Java has no direct support for
125 handling symlinks this task divines them by comparing canonical and
126 absolute paths. On non-unix systems this may cause false positives.
127 Furthermore, any operating system on which the command
128 <code>ln -s &lt;linkname&gt; &lt;resourcename&gt;</code> is not a valid
129 command on the command line will not be able to use action="single" or
130 action="recreate". Action="record" and action=delete should still work. Finally,
131 the lack of support for symlinks in Java means that all links are recorded as
132 links to the <strong>canonical</strong> resource name. Therefore the link:
133 <code>link --> subdir/dir/../foo.bar</code> will be recorded as
134 <code>link=subdir/foo.bar</code> and restored as
135 <code>link --> subdir/foo.bar</code></p>
136
137
138
139</body>
140</html>
Note: See TracBrowser for help on using the repository browser.