Debian Codegraph @

manual/Tasks/symlink.html

raw
1 <!DOCTYPE html>
2 <!--
3 Licensed to the Apache Software Foundation (ASF) under one or more
4 contributor license agreements. See the NOTICE file distributed with
5 this work for additional information regarding copyright ownership.
6 The ASF licenses this file to You under the Apache License, Version 2.0
7 (the "License"); you may not use this file except in compliance with
8 the License. You may obtain a copy of the License at
9
10 https://www.apache.org/licenses/LICENSE-2.0
11
12 Unless required by applicable law or agreed to in writing, software
13 distributed under the License is distributed on an "AS IS" BASIS,
14 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 See the License for the specific language governing permissions and
16 limitations under the License.
17 -->
18 <html lang="en">
19
20 <head>
21 <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
22 <title>Symlink Task</title>
23 </head>
24
25 <body>
26
27 <h2 id="symlink">Symlink</h2>
28 <h3>Description</h3>
29 <p>Manages symbolic links on platforms where Java supports symbolic links. Can be used to make an
30 individual link, delete a link, create multiple links from properties files, or create properties
31 files describing links in the specified directories. Existing files are not overwritten by
32 default.</p>
33 <p><a href="../Types/fileset.html">FileSet</a>s are used to select a set of links to record, or a
34 set of property files to create links from.</p>
35 <h3>Parameters</h3>
36 <table class="attr">
37 <tr>
38 <th scope="col">Attribute</th>
39 <th scope="col">Description</th>
40 <th scope="col">Required</th>
41 </tr>
42 <tr>
43 <td>action</td>
44 <td>The type of action to perform, may be <q>single</q>, "<q>record</q>, <q>recreate</q>
45 or <q>delete</q>.</td>
46 <td>No; defaults to <q>single</q></td>
47 </tr>
48 <tr>
49 <td>link</td>
50 <td>The name of the link to be created or deleted.<br/><strong>Note</strong>: this attribute is
51 resolved against the current working directory rather than the project's <var>basedir</var>
52 for historical reasons. It is recommended you always use an absolute path or a path
53 like <samp>${basedir}/some-path</samp> as its value.
54 </td>
55 <td>Yes, for <var>action</var>=<q>single</q> or <q>delete</q>; ignored in other actions</td>
56 </tr>
57 <tr>
58 <td>resource</td>
59 <td>The resource the link should point to.</td>
60 <td>Yes, for <var>action</var>=<q>single</q>; ignored in other actions</td>
61 </tr>
62 <tr>
63 <td>linkfilename</td>
64 <td>The name of the properties file to create in each included directory.</td>
65 <td>Yes, for <var>action</var>=<q>record</q>; ignored in other actions</td>
66 </tr>
67 <tr>
68 <td>overwrite</td>
69 <td>Overwrite existing files or not. If overwrite is set to <q>true</q>, then any existing file,
70 specified by the link attribute, will be overwritten irrespective of whether or not the
71 existing file is a symbolic link.</td>
72 <td>No; defaults to <q>false</q></td>
73 </tr>
74 <tr>
75 <td>failonerror</td>
76 <td>Stop build if true, log a warning message, but do not stop the build, when the an error
77 occurs if <q>false</q>.</td>
78 <td>No; defaults to <q>true</q></td>
79 </tr>
80 </table>
81 <h3>Parameters specified as nested elements</h3>
82
83 <h4>fileset</h4>
84 <p><a href="../Types/fileset.html">FileSet</a>s are used when <var>action</var>=<q>record</q> to
85 select directories and link names to be recorded. They are also used
86 when <var>action</var>=<q>recreate</q> to specify both the name of the property files to be
87 processed, and the directories in which they can be found. At least one fileset is required for each
88 case.</p>
89
90 <h3>Examples</h3>
91
92 <p>Make a link named <samp>foo</samp> to a resource named <samp>bar.foo</samp>
93 in <samp>subdir</samp>:</p>
94 <pre>&lt;symlink link="${dir.top}/foo" resource="${dir.top}/subdir/bar.foo"/&gt;</pre>
95
96 <p>Record all links in <samp>subdir</samp> and its descendants in files
97 named <samp>dir.links</samp></p>
98 <pre>
99 &lt;symlink action="record" linkfilename="dir.links"&gt;
100 &lt;fileset dir="${dir.top}" includes="subdir/**"/&gt;
101 &lt;/symlink&gt;</pre>
102
103 <p>Recreate the links recorded in the previous example:</p>
104 <pre>
105 &lt;symlink action="recreate"&gt;
106 &lt;fileset dir="${dir.top}" includes="subdir/**/dir.links"/&gt;
107 &lt;/symlink&gt;</pre>
108
109 <p>Delete a link named <samp>foo</samp>:</p>
110 <pre>&lt;symlink action="delete" link="${dir.top}/foo"/&gt;</pre>
111
112 <p><strong>Java 1.2 and earlier</strong>: Due to limitations on executing system level commands in
113 Java versions earlier than 1.3 this task may have difficulty operating with a relative path
114 in <code>ANT_HOME</code>. The typical symptom is an <code>IOException</code> where Apache Ant can't
115 find <samp>/some/working/directory${ANT_HOME}/bin/antRun</samp> or something similar. The workaround
116 is to change your <code>ANT_HOME</code> environment variable to an absolute path, which will remove
117 the <samp>/some/working/directory</samp> portion of the above path and allow Ant to find the correct
118 command line execution script.</p>
119
120 <p><strong>Note</strong>: <em>Since Ant 1.10.2</em>, this task relies on the symbolic link support
121 introduced in Java 7 through the <code class="code">java.nio.file.Files</code> APIs</p>
122
123 </body>
124 </html>