## Symlink

### Description

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.

### Parameters

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.

### Parameters specified as nested elements

#### fileset

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.

### Examples

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`