使用Java¶

此文件提供对 Java 的支持。假设 FindJava 已经被加载。有关如何将 Java 加载到您的 CMake 项目中的信息，请参见:module:FindJava。

概要¶

Creating and Installing JARS
  add_jar (<target_name> [SOURCES] <source1> [<source2>...] ...)
  install_jar (<target_name> DESTINATION <destination> [COMPONENT <component>])
  install_jni_symlink (<target_name> DESTINATION <destination> [COMPONENT <component>])

Header Generation
  create_javah ((TARGET <target> | GENERATED_FILES <VAR>) CLASSES <class>... ...)

Exporting JAR Targets
  install_jar_exports (TARGETS <jars>... FILE <filename> DESTINATION <destination> ...)
  export_jars (TARGETS <jars>... [NAMESPACE <namespace>] FILE <filename>)

Finding JARs
  find_jar (<VAR> NAMES <name1> [<name2>...] [PATHS <path1> [<path2>... ENV <var>]] ...)

Creating Java Documentation
  create_javadoc (<VAR> (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...]) ...)

创建和安装 JAR¶

add_jar¶

创建一个包含 java 对象和可选资源的 jar 文件：

add_jar(<target_name>
        [SOURCES] <source1> [<source2>...] [<resource1>...]
        [RESOURCES NAMESPACE <ns1> <resource1>... [NAMESPACE <nsX> <resourceX>...]... ]
        [INCLUDE_JARS <jar1> [<jar2>...]]
        [ENTRY_POINT <entry>]
        [VERSION <version>]
        [MANIFEST <manifest>]
        [OUTPUT_NAME <name>]
        [OUTPUT_DIR <dir>]
        [GENERATE_NATIVE_HEADERS <target>
                                 [DESTINATION (<dir>|INSTALL <dir> [BUILD <dir>])]]
        )

此命令创建一个 <target_name>.jar。它编译给定的 <source> 文件并将给定的 <resource> 文件添加到 jar 文件中。源文件可以是 java 文件或列表文件（以``@`` 为前缀）。如果只给出资源文件，则只创建一个 jar 文件。

来源

编译指定的源文件并将结果添加到 jar 文件中。

在 3.4 版本加入: 支持以“@”为前缀的响应文件。

资源

在 3.21 版本加入.

通过剥离源文件路径并将文件放在 jar 中的 <ns> 下，将命名的 <resource> 文件添加到 jar。

例如：：

RESOURCES NAMESPACE "/com/my/namespace" "a/path/to/resource.txt"

导致可通过 jar 中的“/com/my/namespace/resource.txt”访问资源。

通过将资源添加到 SOURCES``（原始行为）列表中，可以在不调整命名空间的情况下添加资源，在这种情况下，资源路径必须相对于 ``CMAKE_CURRENT_SOURCE_DIR。在非源构建中添加资源而不使用“RESOURCES”参数几乎肯定会导致混淆。

备注

通过 SOURCES 参数添加资源依赖于一个硬编码的文件扩展名列表，这些文件扩展名经过测试以确定它们是否编译（例如 File.java）。编译匹配扩展名的 SOURCES 文件。不匹配的文件被视为资源。要包含与这些文件扩展名匹配的未编译资源，请使用“RESOURCES”参数。

INCLUDE_JARS

jar 列表在编译 java 源代码时添加到类路径中，也添加到目标的依赖项中。 INCLUDE_JARS 还接受由 add_jar() 创建的其他目标名称。为了向后兼容，列为源的 jar 文件将被忽略（因为它们自本模块的第一个版本以来一直如此）。

入口点

在 jar 文件中定义入口点。

版本

将版本添加到目标输出名称。

以下示例将创建一个名为“shibboleet-1.2.0.jar”的 jar 文件，并将创建一个符号链接“shibboleet.jar”指向带有版本信息的 jar。

add_jar(shibboleet shibbotleet.java VERSION 1.2.0)

清单

为 jar 定义自定义清单。

OUTPUT_NAME

为目标指定不同的输出名称。

输出目录

设置将生成 jar 文件的目录。如果未指定，则使用 CMAKE_CURRENT_BINARY_DIR 作为输出目录。

GENERATE_NATIVE_HEADERS

在 3.11 版本加入.

为声明为本机的方法生成本机头文件。这些文件提供了允许 Java 和 C 代码进行交互的连接胶水。将创建一个 INTERFACE 目标，以便轻松使用生成的文件。子选项 DESTINATION 可用于指定生成的头文件的输出目录。

此选项至少需要 1.8 版的 JDK。

为了最佳使用此选项，建议在调用 add_jar() 之前包含模块 JNI。然后可以使用为本机头文件生成的目标来使用 target_link_libraries() 命令编译 C/C++ 源代码。

find_package(JNI)
add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
add_library(bar bar.cpp)
target_link_libraries(bar PRIVATE foo-native)

在 3.20 版本加入: DESTINATION 子选项现在支持为 BUILD 和 INSTALL 步骤指定不同输出目录的可能性。如果未指定 BUILD 目录，将使用默认目录。

要导出由``GENERATE_NATIVE_HEADERS`` 选项生成的接口目标，需要``DESTINATION`` 的子选项``INSTALL``：

add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native
                     DESTINATION INSTALL include)
install(TARGETS foo-native EXPORT native)
install(DIRECTORY "$<TARGET_PROPERTY:foo-native,NATIVE_HEADERS_DIRECTORY>/"
        DESTINATION include)
install(EXPORT native DESTINATION /to/export NAMESPACE foo)

可以设置一些变量来自定义 add_jar() 以及 java 编译器的行为：

CMAKE_JAVA_COMPILE_FLAGS

为 java 编译器指定附加标志。

CMAKE_JAVA_INCLUDE_PATH

指定类路径的附加路径。

CMAKE_JNI_TARGET

如果目标是 JNI 库，请将此布尔变量设置为“TRUE”以启用 JNI 符号链接的创建（另请参阅:ref:install_jni_symlink() <install_jni_symlink>）。

CMAKE_JAR_CLASSES_PREFIX

如果应该从同一个 java 源文件树中生成多个 jar，为了防止在后续 jar 中积累重复的类文件，请在调用 add_jar() 之前设置/重置 CMAKE_JAR_CLASSES_PREFIX：

set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
add_jar(foo foo.java)

set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
add_jar(bar bar.java)

add_jar() 函数在 <target_name> 上设置以下目标属性：

安装文件: 应该安装的文件。这由 install_jar() 使用。
JNI_SYMLINK: 应该安装的 JNI 符号链接。这由 install_jni_symlink() 使用。
JAR_FILE: jar 文件的位置，以便您可以包含它。
CLASSDIR: 可以找到类文件的目录。例如将它们与 javah 一起使用。
NATIVE_HEADERS_DIRECTORY: 在 3.20 版本加入.

生成本机标头的目录。在指定选项``GENERATE_NATIVE_HEADERS`` 时定义。

install_jar¶

此命令将 jar 文件安装到给定目标：

install_jar(<target_name> <destination>)
install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])

此命令将 <target_name> 文件安装到给定的 <destination>。它应该在与 add_jar() 相同的范围内调用，否则它将失败。

在 3.4 版本加入: 带有``DESTINATION`` 和``COMPONENT`` 选项的第二个签名。

目的地: 指定磁盘上将安装文件的目录。
组件: 指定与安装规则关联的安装组件名称，例如“runtime”或“development”。

install_jar() 命令在 <target_name> 上设置以下目标属性：

安装目标: 如上所述保存 <destination>，并由 install_jar_exports() 使用。

install_jni_symlink¶

为由 add_jar():: 生成的目标安装 JNI 符号链接：

install_jni_symlink(<target_name> <destination>)
install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])

此命令将``<target_name>`` JNI 符号链接安装到给定的``<destination>``。它应该在与 add_jar() 相同的范围内调用，否则它将失败。

在 3.4 版本加入: 带有``DESTINATION`` 和``COMPONENT`` 选项的第二个签名。

目的地: 指定磁盘上将安装文件的目录。
组件: 指定与安装规则关联的安装组件名称，例如“runtime”或“development”。

使用以下命令创建 JNI 符号链接：

set(CMAKE_JNI_TARGET TRUE)
add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})

标头生成¶

create_javah¶

在 3.4 版本加入.

为 java 类生成 C 头文件

create_javah(TARGET <target> | GENERATED_FILES <VAR>
             CLASSES <class>...
             [CLASSPATH <classpath>...]
             [DEPENDS <depend>...]
             [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
             )

自 3.11 版本弃用: 由于 suppression of javah tool，从 JDK 版本 10 开始将不再支持此命令。应该改用 add_jar(GENERATE_NATIVE_HEADERS) 命令。

从 java 类创建 C 头文件。这些文件提供了允许 Java 和 C 代码进行交互的连接胶水。

create_javah() 有两个主要的签名。第一个签名通过“GENERATED_FILES”选项指定的变量返回生成的文件。例如：

create_javah(GENERATED_FILES files_headers
  CLASSES org.cmake.HelloWorld
  CLASSPATH hello.jar
)

create_javah() 的第二个签名创建了一个封装头文件生成的目标。例如。

create_javah(TARGET target_headers
  CLASSES org.cmake.HelloWorld
  CLASSPATH hello.jar
)

两个签名共享相同的选项。

类: 指定用于生成标头的 Java 类。
类路径: 指定查找类的各种路径。这里可以使用 .class 文件、jar 文件或通过命令 add_jar 创建的目标。
取决于: javah 目标所依赖的目标。
OUTPUT_NAME: 将选项“CLASSES”列出的所有类的结果头文件连接到“<path>”。与 javah` 工具的选项 -o 行为相同。
输出目录: 设置将生成头文件的目录。与 javah` 工具的选项 -d 行为相同。如果未指定，则使用 CMAKE_CURRENT_BINARY_DIR 作为输出目录。

导出 JAR 目标¶

install_jar_exports¶

在 3.7 版本加入.

安装目标导出文件

install_jar_exports(TARGETS <jars>...
                    [NAMESPACE <namespace>]
                    FILE <filename>
                    DESTINATION <destination> [COMPONENT <component>])

此命令将命名 jar 目标的目标导出文件 <filename> 安装到给定的 <destination> 目录。它的功能类似于 install(EXPORT)。

目标: add_jar() 命令创建的目标列表。
命名空间: 在 3.9 版本加入.

<namespace> 值将在写入导入文件时添加到目标名称之前。
文件: 指定导出文件的名称。
目的地: 指定磁盘上将安装文件的目录。
组件: 指定与安装规则关联的安装组件名称，例如“runtime”或“development”。

export_jars¶

在 3.7 版本加入.

写入目标导出文件

export_jars(TARGETS <jars>...
            [NAMESPACE <namespace>]
            FILE <filename>)

此命令为命名的“<jars>”目标写入目标导出文件“<filename>”。它的功能类似于 export()。

目标: add_jar() 命令创建的目标列表。
命名空间: 在 3.9 版本加入.

<namespace> 值将在写入导入文件时添加到目标名称之前。
文件: 指定导出文件的名称。

查找 JAR¶

find_jar¶

查找指定的 jar 文件

find_jar(<VAR>
         <name> | NAMES <name1> [<name2>...]
         [PATHS <path1> [<path2>... ENV <var>]]
         [VERSIONS <version1> [<version2>]]
         [DOC "cache documentation string"]
        )

此命令用于查找指定 jar 的完整路径。创建一个名为 <VAR> 的缓存条目来存储此命令的结果。如果找到 jar 的完整路径，结果将存储在变量中，除非清除变量，否则不会重复搜索。如果没有找到，结果将是``<VAR>-NOTFOUND``，下次使用相同的变量调用``find_jar()`` 时将再次尝试搜索。

名字: 为 jar 文件指定一个或多个可能的名称。
路径: 除默认位置外，还指定要搜索的目录。 ENV var 子选项从系统环境变量中读取路径。
版本: 指定 jar 版本。
文档: 为 <VAR> 缓存条目指定文档字符串。

创建 Java 文档¶

create_javadoc¶

基于文件和包创建 java 文档

create_javadoc(<VAR>
               (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...])
               [SOURCEPATH <sourcepath>]
               [CLASSPATH <classpath>]
               [INSTALLPATH <install path>]
               [DOCTITLE <the documentation title>]
               [WINDOWTITLE <the title of the document>]
               [AUTHOR (TRUE|FALSE)]
               [USE (TRUE|FALSE)]
               [VERSION (TRUE|FALSE)]
               )

create_javadoc() 命令可用于创建 java 文档。 create_javadoc() 有两个主要的签名。

第一个签名与源文件路径上的包名称一起使用：

create_javadoc(my_example_doc
               PACKAGES com.example.foo com.example.bar
               SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
               CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
               WINDOWTITLE "My example"
               DOCTITLE "<h1>My example</h1>"
               AUTHOR TRUE
               USE TRUE
               VERSION TRUE
              )

create_javadoc() 的第二个签名适用于给定的文件列表：

create_javadoc(my_example_doc
               FILES java/A.java java/B.java
               CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
               WINDOWTITLE "My example"
               DOCTITLE "<h1>My example</h1>"
               AUTHOR TRUE
               USE TRUE
               VERSION TRUE
              )

两个签名共享大部分选项。有关详细信息，请阅读 javadoc 联机帮助页。

包裹: 指定 java 包。
文件: 指定 java 源文件。如果指定了相对路径，它们是相对于 CMAKE_CURRENT_SOURCE_DIR 的。
源路径: 指定查找包的目录。默认情况下，使用 CMAKE_CURRENT_SOURCE_DIR 目录。
类路径: 指定在何处查找用户类文件。与 javadoc 工具的选项 -classpath 行为相同。
安装路径: 指定安装 java 文档的位置。如果您指定，文档将安装到“${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>”。
DOCTITLE: 指定要放在概览摘要文件顶部附近的标题。与 javadoc 工具的选项 -doctitle 行为相同。
窗口标题: 指定要放置在 HTML <title> 标记中的标题。与 javadoc 工具的选项 -windowtitle 行为相同。
作者: 当指定值“TRUE”时，在生成的文档中包含“@author”文本。与 javadoc` 工具的选项 -author 行为相同。
使用: 当指定值 TRUE 时，创建类和包使用页面。为每个记录的类和包包括一个使用页面。与“javadoc”工具的选项“-use”的行为相同。
版本: 当指定值 TRUE 时，在生成的文档中包含版本文本。与 javadoc 工具的选项 -version 行为相同。

使用Java¶

概要¶

创建和安装 JAR¶

标头生成¶

导出 JAR 目标¶

查找 JAR¶

创建 Java 文档¶

目录

上一主题

下一主题

本页