| <!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> |