Manages symbolic links on Unix based platforms. Can be used to make an individual link, delete a link, create multiple links from properties files, or create properties files describing links in the specified directories. Existing links are not overwritten by default.
FileSets are used to select a set of links to record, or a set of property files to create links from.
| Attribute | Description | Required |
| action | The type of action to perform, may be "single", "record", "recreate" or "delete". | No, defaults to single. |
| link | The name of the link to be created or deleted. | required for action="single" or "delete". Ignored in other actions. |
| resource | The resource the link should point to. | required for action="single". Ignored in other actions. |
| linkfilename | The name of the properties file to create in each included directory. | required for action="record". Ignored in other actions. |
| overwrite | Overwrite existing links or not. | No; defaults to false. |
| failonerror | Stop build if true, log a warning message, but do not stop the build, when the an error occurs if false. | No; defaults to true. |
FileSets are used when action = "record" to select directories and linknames to be recorded. They are also used when action = "recreate" to specify both the name of the property files to be processed, and the directories in which they can be found. At least one fileset is required for each case.
Make a link named "foo" to a resource named "bar.foo" in subdir:
<symlink link="${dir.top}/foo" resource="${dir.top}/subdir/bar.foo"/>
Record all links in subdir and it's descendants in files named "dir.links"
<symlink action="record" linkfilename="dir.links">
<fileset dir="${dir.top}" includes="subdir/**"/>
</symlink>
Recreate the links recorded in the previous example:
<symlink action="recreate">
<fileset dir="${dir.top}" includes="subdir/**/dir.links"/>
</symlink>
Delete a link named "foo":
<symlink action="delete" link="${dir.top}/foo"/>
Java 1.2 and earlier: Due to limitations on executing system level commands in Java versions earlier than 1.3 this task may have difficulty operating with a relative path in ANT_HOME. The typical symptom is an IOException where ant can't find /some/working/directory${ANT_HOME}/bin/antRun or something similar. The workaround is to change your ANT_HOME environment variable to an absolute path, which will remove the /some/working/directory portion of the above path and allow ant to find the correct commandline execution script.
LIMITATIONS: Because Java has no direct support for
handling symlinks this task divines them by comparing canonical and
absolute paths. On non-unix systems this may cause false positives.
Furthermore, any operating system on which the command
ln -s <linkname> <resourcename> is not a valid
command on the command line will not be able to use action="single" or
action="recreate". Action="record" and action=delete should still work. Finally,
the lack of support for symlinks in Java means that all links are recorded as
links to the canonical resource name. Therefore the link:
link --> subdir/dir/../foo.bar will be recorded as
link=subdir/foo.bar and restored as
link --> subdir/foo.bar