UseJava

此文件提供了对 Java 的支持。假定 FindJava 模块已加载。有关如何将 Java 加载到 CMake 项目的信息,请参阅 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 文件。

SOURCES

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

版本 3.4 中已添加: 支持以 @ 为前缀的响应文件。

RESOURCES

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。在 out-of-source 构建中使用 RESOURCES 参数以外的方式添加资源几乎肯定会导致混乱。

注意

通过 SOURCES 参数添加资源依赖于硬编码的文件扩展名列表,这些扩展名用于确定它们是否被编译(例如 File.java)。匹配扩展名的 SOURCES 文件将被编译。不匹配的文件将被视为资源。要包含匹配这些文件扩展名的未编译资源,请使用 RESOURCES 参数。

INCLUDE_JARS

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

ENTRY_POINT

定义 jar 文件中的入口点。

VERSION

向目标输出名称添加版本号。

以下示例将创建一个名为 shibboleet-1.2.0.jar 的 jar 文件,并创建一个指向包含版本信息的 jar 的符号链接 shibboleet.jar

add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
MANIFEST

为 jar 定义自定义清单文件。

OUTPUT_NAME

指定目标的其他输出名称。

OUTPUT_DIR

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

GENERATE_NATIVE_HEADERS

3.11 版本新增。

为声明为 native 的方法生成 native 头文件。这些文件提供了允许 Java 和 C 代码交互的连接。将为易于使用的生成文件创建一个 INTERFACE 目标。可以使用子选项 DESTINATION 来指定生成头文件的输出目录。

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

为了最佳使用此选项,建议在任何调用 add_jar() 之前包含 JNI 模块。然后,可以使用生成的 native 头文件目标通过 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 子选项现在支持为 BUILDINSTALL 步骤指定不同的输出目录。如果未指定 BUILD 目录,将使用默认目录。

要导出 GENERATE_NATIVE_HEADERS 选项生成的接口目标,需要 DESTINATIONINSTALL 子选项。

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 符号链接的创建(另请参见 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_FILES

应安装的文件。这由 install_jar() 使用。

JNI_SYMLINK

应安装的 JNI 符号链接。这由 install_jni_symlink() 使用。

JAR_FILE

jar 文件的位置,以便您可以包含它。

CLASSDIR

可以找到类文件的目录。例如,用于与 javah 一起使用。

NATIVE_HEADERS_DIRECTORY

在 3.20 版本中添加。

生成 native 头文件的目录。当指定 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 中已添加: 带有 DESTINATIONCOMPONENT 选项的第二个签名。

DESTINATION

指定文件将被安装到的磁盘目录。

COMPONENT

指定与安装规则关联的安装组件名称,例如“runtime”或“development”。

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

INSTALL_DESTINATION

包含上面描述的 <destination>,并由 install_jar_exports() 使用。

头文件生成

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(javah 工具的抑制),此命令将不再被支持。应改用 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
)

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

CLASSES

指定用于生成头文件的 Java 类。

CLASSPATH

指定查找类的各种路径。此处可以使用 .class 文件、jar 文件或由 add_jar 命令创建的目标。

DEPENDS

javah 目标依赖的目标。

OUTPUT_NAME

CLASSES 选项列出的所有类的结果头文件连接到 <path>。与 javah 工具的 -o 选项具有相同行为。

OUTPUT_DIR

设置生成头文件的目录。与 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)

TARGETS

add_jar() 命令创建的目标列表。

NAMESPACE

版本 3.9 中添加。

<namespace> 值将被添加到导入文件中写入的目标名称之前。

FILE

指定导出文件的名称。

DESTINATION

指定文件将被安装到的磁盘目录。

COMPONENT

指定与安装规则关联的安装组件名称,例如“runtime”或“development”。

export_jars

3.7 版本中新增。

写入目标导出文件。

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

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

TARGETS

add_jar() 命令创建的目标列表。

NAMESPACE

版本 3.9 中添加。

<namespace> 值将被添加到导入文件中写入的目标名称之前。

FILE

指定导出文件的名称。

查找 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() 时会再次尝试搜索。

NAMES

指定 jar 文件的一个或多个可能名称。

PATHS

指定除默认位置之外要搜索的目录。 ENV var 子选项从系统环境变量读取路径。

VERSIONS

指定 jar 版本。

DOC

<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 手册。

PACKAGES

指定 Java 包。

FILES

指定 Java 源文件。如果指定了相对路径,则它们相对于 CMAKE_CURRENT_SOURCE_DIR

SOURCEPATH

指定查找包的目录。默认情况下,使用 CMAKE_CURRENT_SOURCE_DIR 目录。

CLASSPATH

指定查找用户类文件的位置。与 javadoc 工具的 -classpath 选项具有相同行为。

INSTALLPATH

指定安装 Java 文档的位置。如果指定,文档将被安装到 ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>

DOCTITLE

指定放置在概述摘要文件顶部的标题。与 javadoc 工具的 -doctitle 选项具有相同行为。

WINDOWTITLE

指定放置在 HTML <title> 标签中的标题。与 javadoc 工具的 -windowtitle 选项具有相同行为。

AUTHOR

指定 TRUE 时,将在生成的文档中包含 @author 文本。与 javadoc 工具的 -author 选项具有相同行为。

USE

指定 TRUE 时,将创建类和包使用情况页面。为每个文档化的类和包包含一个使用页面。与 javadoc 工具的 -use 选项具有相同行为。

VERSION

指定 TRUE 时,将在生成的文档中包含版本文本。与 javadoc 工具的 -version 选项具有相同行为。