<!DOCTYPE html> <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <html lang="en"> <head> <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> <title>Link Task</title> </head> <body> <h2 id="link">Link</h2> <p><em>Since Apache Ant 1.10.6</em></p> <h3>Description</h3> <p>Assembles jmod files into an executable image. Equivalent to the JDK's <a href="https://docs.oracle.com/en/java/javase/11/tools/jlink.html">jlink</a> tool. </p> <p>Requires Java 9 or later.</p> <h3>Parameters</h3> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>destDir</td> <td>Root directory of created image.</td> <td>Yes</td> </tr> <tr> <td>modulepath</td> <td>Path-like sequence of jmod files to link in order to create image.</td> <td rowspan="2">One of these is required, unless a nested <code><modulepath></code> is present.</td> </tr> <tr> <td>modulepathref</td> <td class="left">Path-like sequence of jmod files to link in order to create image, given as a <a href="../using.html#references">reference</a> to a path defined elsewhere.</td> </tr> <tr> <td>modules</td> <td>Comma-separated list of modules to place in the linked image.</td> <td>Yes, unless one or more nested <code><module></code> elements are present.</td> </tr> <tr> <td>observableModules</td> <td>Comma-separated list of explicit modules that comprise "universe" visible to link tool while linking.</td> <td>No</td> </tr> <tr> <td>launchers</td> <td>Comma-separated list of commands, each of the form <var>name</var><code>=</code><var>module</var> or <var>name</var><code>=</code><var>module</var><code>/</code><var>mainclass</var></td> <td>No</td> </tr> <tr> <td>locales</td> <td>Comma-separated list of extra locales, or wildcard patterns matching multiple locale names, to include. Requires <code>jdk.localedata</code> module.</td> <td>No</td> </tr> <tr> <td>excludeResources</td> <td>Comma-separated list of patterns specifying resources to exclude from source jmods. Each is either a <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher%28java.lang.String%29">standard PathMatcher pattern</a> or <code>@</code><var>filename</var>, indicating a text file with one resource name per line.</td> <td>No</td> </tr> <tr> <td>excludeFiles</td> <td>Comma-separated list of patterns specifying files to exclude from linked image. Each is either a <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher%28java.lang.String%29">standard PathMatcher pattern</a> or <code>@</code><var>filename</var>, indicating a text file with one file name per line.</td> <td>No</td> </tr> <tr> <td>resourceOrder</td> <td>Comma-separated list of patterns specifying resource search order. Each is either a <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher%28java.lang.String%29">standard PathMatcher pattern</a> or <code>@</code><var>filename</var>, indicating a text file with one resource name per line.</td> <td>No</td> </tr> <tr> <td>bindServices</td> <td>Boolean, whether to include in linked image any service providers found in module path corresponding to service provider interfaces used by explicitly linked modules.</td> <td>No, default is false</td> </tr> <tr> <td>ignoreSigning</td> <td>Boolean, whether to allow signed jar files. (Note: As of Java 11, this is ignored and is always treated as true.)</td> <td>No, default is false</td> </tr> <tr> <td>includeHeaders</td> <td>Boolean, whether to include header files in linked image.</td> <td>No, default is true</td> </tr> <tr> <td>includeManPages</td> <td>Boolean, whether to include man pages in linked image.</td> <td>No, default is true</td> </tr> <tr> <td>includeNativeCommands</td> <td>Boolean, whether to include native executables in linked image.</td> <td>No, default is true</td> </tr> <tr> <td>debug</td> <td>Boolean, whether to include debug information.</td> <td>No, default is true</td> </tr> <tr> <td>verboseLevel</td> <td>If set, the linker will produce verbose output, which will be logged at the specified Ant log level (<code>DEBUG</code>, <code>VERBOSE</code>, <code>INFO</code>, <code>WARN</code>, or <code>ERR</code>).</td> <td>No, default is no verbose output</td> </tr> <tr> <td>compress</td> <td>Compression level of linked image. One of: <dl> <dt><code>0</code> or <code>none</code></dt> <dd>no compression (default)</dd> <dt><code>1</code> or <code>strings</code></dt> <dd>constant string sharing</dd> <dt><code>2</code> or <code>zip</code></dt> <dd>zip compression</dd> </dl> </td> <td>No, default is no compression</td> </tr> <tr> <td>endianness</td> <td>Byte order of linked image, must be <code>little</code> or <code>big</code> <td>No, default is native byte order</td> </tr> <tr> <td>checkDuplicateLegal</td> <td>Boolean. When merging legal notices from different modules because they have the same name, verify that their contents are identical.</td> <td>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.</td> </tr> <tr> <td>vmType</td> <td>Hotspot VM in image. One of: <ul> <li><code>client</code> <li><code>server</code> <li><code>minimal</code> <li><code>all</code> </ul> </td> <td>No, default is <code>all</code></td> </tr> </table> <h3>Parameters specified as nested elements</h3> <p><code><link></code> can have the following nested elements:</p> <ul> <li><a href="#nested-modulepath">modulepath</a></li> <li><a href="#nested-module">module</a></li> <li><a href="#nested-observableModule">observableModule</a></li> <li><a href="#nested-launcher">launcher</a></li> <li><a href="#nested-locale">locale</a></li> <li><a href="#nested-resourceOrder">resourceOrder</a></li> <li><a href="#nested-excludeResources">excludeResources</a></li> <li><a href="#nested-excludeFiles">excludeFiles</a></li> <li><a href="#nested-compress">compress</a></li> <li><a href="#nested-releaseInfo">releaseInfo</a></li> </ul> <h4 id="nested-modulepath">modulepath</h4> <p><a href="../using.html#path">Path-like structure</a> pointing to jmod files to link into image.</p> <h4 id="nested-module">module</h4> <p>Names a single module to be placed in the linked image. This may be specified multiple times.</p> <p>Attributes:</p> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>name</td> <td>Name of module to add.</td> <td>Yes</td> </tr> </table> <h4 id="nested-observableModule">observableModule</h4> <p>Names a module visible to the linking process, instead of every module in the module path being considered. This may be specified multiple times. <p>Attributes:</p> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>name</td> <td>Name of module to add to list of observable modules.</td> <td>Yes</td> </tr> </table> <h4 id="nested-launcher">launcher</h4> <p>Specifies an executable file which will be added to the linked image, which executes a particular module's main class. Attributes:</p> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>name</td> <td>Name of launcher. This typically is used for the name of the executable file.</td> <td>Yes</td> </tr> <tr> <td>module</td> <td>Name of module to execute.</td> <td>Yes</td> </tr> <tr> <td>mainClass</td> <td>Name of entry point class in module to execute.</td> <td>Required unless module has its own main class defined.</td> </tr> </table> <h4 id="nested-locale">locale</h4> <p>Specifies locales to include in linked image. May be specified multiple times. Requires <code>jdk.localedata</code> module. Attributes:</p> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>name</td> <td>Name of locale, or wildcard pattern with <q><code>*</code></q> that matches multiple locale names.</td> <td>Yes</td> </tr> </table> <h4 id="nested-resourceOrder">resourceOrder</h4> <p>Explicit resource search order in linked image. May be specified multiple times. Attributes:</p> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>pattern</td> <td>A <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher%28java.lang.String%29">standard PathMatcher pattern</a> for matching resources</td> <td rowspan="2">Exactly one of these</td> </tr> <tr> <td>listFile</td> <td class="left">Text file containing list of resource names (not patterns), one per line</td> </tr> </table> <p>If the <code>resourceOrder</code> attribute is also present on the task, its patterns are treated as if they occur before patterns in nested <code><resourceOrder></code> elements.</p> <h4 id="nested-excludeResources">excludeResources</h4> <p>Excludes files from linked image tree. May be specified multiple times. Attributes:</p> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>pattern</td> <td>A <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher%28java.lang.String%29">standard PathMatcher pattern</a> for matching resources</td> <td rowspan="2">Exactly one of these</td> </tr> <tr> <td>listFile</td> <td class="left">Text file containing list of resource names (not patterns), one per line</td> </tr> </table> <h4 id="nested-excludeFiles">excludeFiles</h4> <p>Excludes files from linked image. May be specified multiple times. Attributes:</p> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>pattern</td> <td>A <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher%28java.lang.String%29">standard PathMatcher pattern</a> for matching files</td> <td rowspan="2">Exactly one of these</td> </tr> <tr> <td>listFile</td> <td class="left">Text file containing list of file names (not patterns), one per line</td> </tr> </table> <h4 id="nested-compress">compress</h4> <p>Describes how image should be compressed. Attributes:</p> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>level</td> <td>Compression level of linked image. One of: <dl> <dt><code>0</code> or <code>none</code></dt> <dd>no compression (default)</dd> <dt><code>1</code> or <code>strings</code></dt> <dd>constant string sharing</dd> <dt><code>2</code> or <code>zip</code></dt> <dd>zip compression</dd> </dl> </td> <td>Yes</td> </tr> <tr> <td>files</td> <td>Comma-separated list of patterns matching files to compress. Each pattern either a <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher%28java.lang.String%29">standard PathMatcher pattern</a> or <code>@</code><var>filename</var>, indicating a text file with one file name per line.</td> <td>No</td> </tr> </table> <p><code><compress></code> can also have any number of nested <code><files></code> elements, with these attributes:</p> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>pattern</td> <td>A <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher%28java.lang.String%29">standard PathMatcher pattern</a> for matching files</td> <td rowspan="2">Exactly one of these</td> </tr> <tr> <td>listFile</td> <td class="left">Text file containing list of file names (not patterns), one per line</td> </tr> </table> <h4 id="nested-releaseInfo">releaseInfo</h4> <p>Replaces, augments, or trims the image's release info properties. Can be specified multiple times. Attributes:</p> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>file</td> <td>Java properties file containing new release info properties that will entirely replace the current ones.</td> <td>No</td> </tr> <tr> <td>delete</td> <td>Comma-separated property keys to remove from application's release info <td>No</td> </tr> </table> <p><code><releaseInfo></code> can also have any number of these nested elements:</p> <h5>add</h5> <p>Specifies additional release info properties. Attributes:</p> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>key</td> <td>Key of single property to add.</td> <td rowspan="2">Yes, unless <code>file</code> is specified</td> </tr> <tr> <td>value</td> <td class="left">Value of single property to add.</td> </tr> <tr> <td>file</td> <td>Java property file containing any number of properties to add.</td> <td>Yes, unless <code>key</code> and <code>value</code> are specified</td> </tr> <tr> <td>charset</td> <td>Character set of property file.</td> <td>No, default is <code>ISO_8859_1</code>, in accordance with java.util.Properties class.</td> </tr> </table> <h5>delete</h5> <p>Property keys to remove from applicaiton's release info. Attributes:</p> <table class="attr"> <tr> <th scope="col">Attribute</th> <th scope="col">Description</th> <th scope="col">Required</th> </tr> <tr> <td>key</td> <td>Key of property to remove.</td> <td>Yes</td> </tr> </table> <h3>Examples</h3> <h4>Basic linking</h4> <pre> <jmod destfile="MyApp.jmod" classpath="build/myapp.jar"/> <link destDir="build/image" modulepath="MyApp.jmod" modules="com.example.myapp"/> </pre> <h4>Custom binaries</h4> <p>This will cause a <samp>bin/MyEditor</samp> script to appear in the image: <pre> <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"/> </pre> <p>Same thing, using a nested launcher element:</p> <pre> <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> </pre> <h4>Limiting locales</h4> <p>Include just the locales needed by the application from the <a href="https://docs.oracle.com/en/java/javase/11/docs/api/jdk.localedata/module-summary.html">jdk.localedata</a> module:</p> <pre> <jmod destfile="MyApp.jmod" classpath="build/myapp.jar"/> <link destDir="build/image" modulepath="MyApp.jmod" modules="com.example.myapp,jdk.localedata" locales="zh,jp-*"/> </pre> <h4>Compressed image</h4> <p>Compress entire image:</p> <pre> <jmod destfile="MyApp.jmod" classpath="build/myapp.jar"/> <link destDir="build/image" modulepath="MyApp.jmod" modules="com.example.myapp,jdk.localedata" compress="zip"/> </pre> <p>Compress only some files in the image:</p> <pre> <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> </pre> <h4>Cross-compiling</h4> <p>To create an image for a different platform: <ul> <li>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.)</li> <li>Determine the foreign JDK's platform string. This can be done with a command that examines the JDK's <samp>jmods/java.base.jmod</samp> file: <pre> jmod describe "$FOREIGN_JDK_HOME"/jmods/java.base.jmod | grep '^platform' </pre> </li> <li>Create your jmod using the foreign JDK's platform string: <pre> <jmod destfile="MyApp.jmod" classpath="build/myapp.jar" platform="windows-amd64"/> </pre> </li> <li>Link with the foreign JDK's <samp>jmods</samp> directory in the module path: <pre> <link destDir="build/image" modulepath="MyApp.jmod;${foreign-jdk-home}/jmods" modules="com.example.myapp"/> </pre> </li> </ul> </body> </html>