## Link

Since Apache Ant 1.10.6

### Description

Assembles jmod files into an executable image. Equivalent to the JDK's jlink tool.

Requires Java 9 or later.

### Parameters

Attribute | Description | Required
--- | --- | ---
destDir | Root directory of created image. | Yes
modulepath | Path-like sequence of jmod files to link in order to create image. | One of these is required, unless a nested `<modulepath>` is present.
modulepathref | Path-like sequence of jmod files to link in order to create image, given as a reference to a path defined elsewhere.
modules | Comma-separated list of modules to place in the linked image. | Yes, unless one or more nested `<module>` elements are present.
observableModules | Comma-separated list of explicit modules that comprise "universe" visible to link tool while linking. | No
launchers | Comma-separated list of commands, each of the form name`=`module or name`=`module`/`mainclass | No
locales | Comma-separated list of extra locales, or wildcard patterns matching multiple locale names, to include. Requires `jdk.localedata` module. | No
excludeResources | Comma-separated list of patterns specifying resources to exclude from source jmods. Each is either a standard PathMatcher pattern or `@`filename, indicating a text file with one resource name per line. | No
excludeFiles | Comma-separated list of patterns specifying files to exclude from linked image. Each is either a standard PathMatcher pattern or `@`filename, indicating a text file with one file name per line. | No
resourceOrder | Comma-separated list of patterns specifying resource search order. Each is either a standard PathMatcher pattern or `@`filename, indicating a text file with one resource name per line. | No
bindServices | Boolean, whether to include in linked image any service providers found in module path corresponding to service provider interfaces used by explicitly linked modules. | No, default is false
ignoreSigning | Boolean, whether to allow signed jar files. (Note: As of Java 11, this is ignored and is always treated as true.) | No, default is false
includeHeaders | Boolean, whether to include header files in linked image. | No, default is true
includeManPages | Boolean, whether to include man pages in linked image. | No, default is true
includeNativeCommands | Boolean, whether to include native executables in linked image. | No, default is true
debug | Boolean, whether to include debug information. | No, default is true
verboseLevel | If set, the linker will produce verbose output, which will be logged at the specified Ant log level (`DEBUG`, `VERBOSE`, `INFO`, `WARN`, or `ERR`). | No, default is no verbose output

compress

Compression level of linked image. One of:

`0` or `none`
  no compression (default)
`1` or `strings`
  constant string sharing
`2` or `zip`
  zip compression

No, default is no compression

endianness | Byte order of linked image, must be `little` or `big` | No, default is native byte order
checkDuplicateLegal | Boolean. When merging legal notices from different modules because they have the same name, verify that their contents are identical. | No, default is false, which means any license files with the same name are assumed to have the same content, and no checking is done.

vmType

Hotspot VM in image. One of:

- `client`
- `server`
- `minimal`
- `all`

No, default is `all`

### Parameters specified as nested elements

`<link>` can have the following nested elements:

- modulepath
- module
- observableModule
- launcher
- locale
- resourceOrder
- excludeResources
- excludeFiles
- compress
- releaseInfo

#### modulepath

Path-like structure pointing to jmod files to link into image.

#### module

Names a single module to be placed in the linked image. This may be specified multiple times.

Attributes:

Attribute | Description | Required
--- | --- | ---
name | Name of module to add. | Yes

#### observableModule

Names a module visible to the linking process, instead of every module in the module path being considered. This may be specified multiple times.

Attributes:

Attribute | Description | Required
--- | --- | ---
name | Name of module to add to list of observable modules. | Yes

#### launcher

Specifies an executable file which will be added to the linked image, which executes a particular module's main class. Attributes:

Attribute | Description | Required
--- | --- | ---
name | Name of launcher. This typically is used for the name of the executable file. | Yes
module | Name of module to execute. | Yes
mainClass | Name of entry point class in module to execute. | Required unless module has its own main class defined.

#### locale

Specifies locales to include in linked image. May be specified multiple times. Requires `jdk.localedata` module. Attributes:

Attribute | Description | Required
--- | --- | ---
name | Name of locale, or wildcard pattern with `*` that matches multiple locale names. | Yes

#### resourceOrder

Explicit resource search order in linked image. May be specified multiple times. Attributes:

Attribute | Description | Required
--- | --- | ---
pattern | A standard PathMatcher pattern for matching resources | Exactly one of these
listFile | Text file containing list of resource names (not patterns), one per line

If the `resourceOrder` attribute is also present on the task, its patterns are treated as if they occur before patterns in nested `<resourceOrder>` elements.

#### excludeResources

Excludes files from linked image tree. May be specified multiple times. Attributes:

Attribute | Description | Required
--- | --- | ---
pattern | A standard PathMatcher pattern for matching resources | Exactly one of these
listFile | Text file containing list of resource names (not patterns), one per line

#### excludeFiles

Excludes files from linked image. May be specified multiple times. Attributes:

Attribute | Description | Required
--- | --- | ---
pattern | A standard PathMatcher pattern for matching files | Exactly one of these
listFile | Text file containing list of file names (not patterns), one per line

#### compress

Describes how image should be compressed. Attributes:

Attribute | Description | Required
--- | --- | ---

level

Compression level of linked image. One of:

`0` or `none`
  no compression (default)
`1` or `strings`
  constant string sharing
`2` or `zip`
  zip compression

Yes

files | Comma-separated list of patterns matching files to compress. Each pattern either a standard PathMatcher pattern or `@`filename, indicating a text file with one file name per line. | No

`<compress>` can also have any number of nested `<files>` elements, with these attributes:

Attribute | Description | Required
--- | --- | ---
pattern | A standard PathMatcher pattern for matching files | Exactly one of these
listFile | Text file containing list of file names (not patterns), one per line

#### releaseInfo

Replaces, augments, or trims the image's release info properties. Can be specified multiple times. Attributes:

Attribute | Description | Required
--- | --- | ---
file | Java properties file containing new release info properties that will entirely replace the current ones. | No
delete | Comma-separated property keys to remove from application's release info | No

`<releaseInfo>` can also have any number of these nested elements:

##### add

Specifies additional release info properties. Attributes:

Attribute | Description | Required
--- | --- | ---
key | Key of single property to add. | Yes, unless `file` is specified
value | Value of single property to add.
file | Java property file containing any number of properties to add. | Yes, unless `key` and `value` are specified
charset | Character set of property file. | No, default is `ISO_8859_1`, in accordance with java.util.Properties class.

##### delete

Property keys to remove from applicaiton's release info. Attributes:

Attribute | Description | Required
--- | --- | ---
key | Key of property to remove. | Yes

### Examples

#### Basic linking

    <jmod destfile="MyApp.jmod" classpath="build/myapp.jar"/>
    <link destDir="build/image" modulepath="MyApp.jmod"
          modules="com.example.myapp"/>

#### Custom binaries

This will cause a `bin/MyEditor` script to appear in the image:

    <jmod destfile="MyApp.jmod" classpath="build/myapp.jar"/>
    <link destDir="build/image" modulepath="MyApp.jmod"
          modules="com.example.myapp"
          launchers="MyEditor=com.example.myapp/com.example.myapp.editors.EditorMain"/>

Same thing, using a nested launcher element:

    <jmod destfile="MyApp.jmod" classpath="build/myapp.jar"/>
    <link destDir="build/image" modulepath="MyApp.jmod"
          modules="com.example.myapp">

        <launcher name="MyEditor" module="com.example.myapp"
                  mainClass="com.example.myapp.editors.EditorMain"/>

    </link>

#### Limiting locales

Include just the locales needed by the application from the jdk.localedata module:

    <jmod destfile="MyApp.jmod" classpath="build/myapp.jar"/>
    <link destDir="build/image" modulepath="MyApp.jmod"
          modules="com.example.myapp,jdk.localedata"
          locales="zh,jp-*"/>

#### Compressed image

Compress entire image:

    <jmod destfile="MyApp.jmod" classpath="build/myapp.jar"/>
    <link destDir="build/image" modulepath="MyApp.jmod"
          modules="com.example.myapp,jdk.localedata"
          compress="zip"/>

Compress only some files in the image:

    <jmod destfile="MyApp.jmod" classpath="build/myapp.jar"/>
    <link destDir="build/image" modulepath="MyApp.jmod"
          modules="com.example.myapp,jdk.localedata">

        <compress level="zip" files=".*\.xml"/>

    </link>

#### Cross-compiling

To create an image for a different platform:

- Download the JDK for that platform, and expand the archive manually into a directory of your choice. (Downloading a zip or tar.gz version of a JDK instead of an installer will make this easier.)
- Determine the foreign JDK's platform string. This can be done with a command that examines the JDK's `jmods/java.base.jmod` file:

      jmod describe "$FOREIGN_JDK_HOME"/jmods/java.base.jmod | grep '^platform'

- Create your jmod using the foreign JDK's platform string:

      <jmod destfile="MyApp.jmod" classpath="build/myapp.jar" platform="windows-amd64"/>

- Link with the foreign JDK's `jmods` directory in the module path:

      <link destDir="build/image"
            modulepath="MyApp.jmod;${foreign-jdk-home}/jmods"
            modules="com.example.myapp"/>