The jmod Command

名称

jmod - 创建JMOD文件并列出现有JMOD文件的内容

概要

jmod（create|extract|list|describe|hash）[选项] jmod-文件

包括以下内容：

主要操作模式

create: 创建新的JMOD存档文件。
extract: 从JMOD存档文件中提取所有文件。
list: 打印所有条目的名称。
describe: 打印模块详细信息。
hash: 确定叶模块并记录直接和间接需要它们的依赖项的哈希值。

选项

选项: 参见jmod选项。

必需

jmod-文件: 指定要创建的JMOD文件的名称或要检索信息的文件。

描述

注意：对于大多数开发任务，包括在模块路径上部署模块或将其发布到Maven存储库中，继续在模块化JAR文件中打包模块。 jmod工具适用于具有本地库或其他配置文件的模块，或者您打算使用jlink工具将其链接到运行时映像中的模块。

JMOD文件格式允许您聚合除.class文件、元数据和资源之外的文件。该格式可传输但不可执行，这意味着您可以在编译时或链接时使用它，但不能在运行时使用。

许多jmod选项涉及指定一个路径，该路径的内容将被复制到生成的JMOD文件中。这些选项会复制指定路径的所有内容，包括子目录及其内容，但不包括文件名与--exclude选项指定的模式匹配的文件。

使用--hash-modules选项或jmod hash命令，您可以在每个模块的描述符中记录允许依赖于它的模块的内容的哈希值，从而通过限定导出将这些模块“绑定”在一起。这使得一个包可以导出到一个或多个具有特定名称的模块，而不导出到其他模块。运行时会验证模块的记录哈希值是否与运行时解析的哈希值匹配；如果不匹配，则运行时会返回错误。

jmod选项

--class-path 路径

指定要复制到生成的JMOD文件中的应用程序JAR文件或包含类的目录的位置。

--cmds 路径

指定要复制到生成的JMOD文件中的本机命令的位置。

--compress 压缩

指定在创建JMOD文件时要使用的压缩方式。接受的值为zip-[0-9]，其中zip-0表示无压缩，zip-9表示最佳压缩。默认为zip-6。

--config 路径

指定要复制到生成的JMOD文件中的可编辑用户配置文件的位置。

--date时间戳

使用ISO-8601扩展偏移日期时间格式指定条目的时间戳，例如"2022-02-12T12:30:00-05:00"。

--dir 路径

指定jmod将从指定的JMOD存档中提取的文件放置的位置。

--dry-run

执行哈希模式的干运行。它标识叶模块及其所需模块，但不记录任何哈希值。

--exclude 模式列表

排除与提供的逗号分隔模式列表匹配的文件，每个元素使用以下形式之一：

glob模式
glob:glob模式
regex:regex模式

有关glob模式语法，请参阅FileSystem.getPathMatcher方法。有关regex模式语法，请参阅Pattern类，表示正则表达式。

--hash-modules regex模式

根据与给定regex模式匹配的模块图，确定叶模块并记录直接和间接需要它们的依赖项的哈希值。这些哈希值记录在正在创建的JMOD存档文件中，或者由jmod hash命令指定的模块路径上的JMOD存档或模块化JAR中。

--header-files 路径

指定要复制到生成的JMOD文件中的头文件的位置。

--help 或 -h

打印使用消息。

--help-extra

打印额外选项的帮助信息。

--legal-notices 路径

指定要复制到生成的JMOD文件中的法律声明的位置。

--libs 路径

指定要复制到生成的JMOD文件中的本机库的位置。

--main-class 类名

指定要在module-info.class文件中记录的主类。

--man-pages 路径

指定要复制到生成的JMOD文件中的man页面的位置。

--module-version 模块版本

指定要在module-info.class文件中记录的模块版本。

--module-path 路径或 -p 路径

指定模块路径。如果还指定了--hash-modules，则此选项是必需的。

--target-platform 平台

指定目标平台。

--version

打印jmod工具的版本信息。

@文件名

从指定文件中读取选项。

选项文件是一个包含通常在命令提示符中输入的选项和值的文本文件。选项可以出现在一行或多行上。您不能为路径名指定环境变量。您可以通过在行首加上井号符号（#）来注释掉行。

以下是jmod命令的选项文件示例：

#Wed Dec 07 00:40:19 EST 2016
create --class-path mods/com.greetings --module-path mlib
  --cmds commands --config configfiles --header-files src/h
  --libs lib --main-class com.greetings.Main
  --man-pages man --module-version 1.0
  --os-arch "x86_x64" --os-name "macOS"
  --os-version "10.10.5" greetingsmod

jmod的额外选项

除了jmod选项中描述的选项外，以下是可与该命令一起使用的额外选项。

--do-not-resolve-by-default: 从默认根模块集中排除
--warn-if-resolved: 提示工具在模块已解析时发出警告。其中之一是deprecated、deprecated-for-removal或incubating。

jmod创建示例

以下是创建JMOD文件的示例：

jmod create --class-path mods/com.greetings --cmds commands
  --config configfiles --header-files src/h --libs lib
  --main-class com.greetings.Main --man-pages man --module-version 1.0
  --os-arch "x86_x64" --os-name "macOS"
  --os-version "10.10.5" greetingsmod

创建一个JMOD文件，指定条目的日期为2022年3月15日00:00:00：

jmod create --class-path build/foo/classes --date 2022-03-15T00:00:00Z
   jmods/foo1.jmod

jmod哈希示例

以下示例演示了当您尝试将叶模块（在此示例中为ma）与所需模块（mb）链接在一起时会发生什么，以及所需模块中记录的哈希值与叶模块的哈希值不匹配时会发生什么。

创建并编译以下.java文件：
- jmodhashex/src/ma/module-info.java
```
module ma {
  requires mb;
}
```
- jmodhashex/src/mb/module-info.java
```
module mb {
}
```
- jmodhashex2/src/ma/module-info.java
```
module ma {
  requires mb;
}
```
- jmodhashex2/src/mb/module-info.java
```
module mb {
}
```
为每个模块创建一个JMOD存档。创建目录jmodhashex/jmods和jmodhashex2/jmods，然后从jmodhashex目录运行以下命令，然后从jmodhashex2目录运行：
- jmod create --class-path mods/ma jmods/ma.jmod
- jmod create --class-path mods/mb jmods/mb.jmod
可选地预览jmod hash命令。从jmodhashex目录运行以下命令：

jmod hash --dry-run -module-path jmods --hash-modules .*

该命令打印如下内容：
```
演示运行：
mb
  使用 SHA-256 哈希 ma 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
```
这表明jmod hash命令（不带--dry-run选项）将记录模块mb中叶模块ma的哈希值。
记录包含在jmodhashex目录中的JMOD存档文件中的哈希值。从jmodhashex目录运行以下命令：

jmod hash --module-path jmods --hash-modules .*

该命令打印如下内容：

哈希值已记录在模块 mb 中

打印包含在jmodhashex目录中的每个JMOD存档的信息。从jmodhashex目录运行以下突出显示的命令：

jmod describe jmods/ma.jmod

ma
  需要强制的 java.base
  需要 mb

jmod describe jmods/mb.jmod

mb
  需要强制的 java.base
  使用 SHA-256 哈希 ma 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a

尝试创建一个包含来自jmodhashex2目录的模块ma但来自jmodhashex目录的模块mb的运行时映像。从jmodhashex2目录运行以下命令：
- Linux 和 macOS：
  
  jlink --module-path $JAVA_HOME/jmods:jmods/ma.jmod:../jmodhashex/jmods/mb.jmod --add-modules ma --output ma-app
- Windows：
  
  jlink --module-path %JAVA_HOME%/jmods;jmods/ma.jmod;../jmodhashex/jmods/mb.jmod --add-modules ma --output ma-app
该命令打印类似以下的错误消息：
```
错误：ma 的哈希值 (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2) 与在 mb 中记录的预期哈希值 (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a) 不同
```