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 文件或 listing 文件（前缀为 @）。如果只给出资源文件，则只会创建一个 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。在非源构建中添加资源而不使用 RESOURCES 参数几乎肯定会带来困扰。

注意

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

INCLUDE_JARS

编译 Java 源码时，jar 的列表会添加到 classpath，还会添加到目标的依赖项中。 INCLUDE_JARS 还会接受由 add_jar() 创建的其他目标名称。出于向后兼容性的考虑，以源文件形式列出的 jar 文件将被忽略（从该模块的第一个版本起即如此）。

ENTRY_POINT

在 jar 文件中定义一个入口点。

VERSION

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

以下示例将创建一个名为 shibboleet-1.2.0.jar 的 jar 文件，并将创建一个符号链接 shibboleet.jar 指向带有版本信息的 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 版中添加。

为声明为本地的方法生成本地头文件。这些文件提供了让您的 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 符号链接的创建（另请参阅 install_jni_symlink()）。

CMAKE_JAR_CLASSES_PREFIX

如果要从同一个 java 源文件目录生成多个 jar，则应在调用 add_jar() 之前设置/重置 CMAKE_JAR_CLASSES_PREFIX，以防止在后续的 jar 中累积重复的类文件

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 中添加。

生成本机标头时所在的目录。在指定 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 选项的第二个签名。

DESTINATION

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

COMPONENT

指定安装组件名称，安装规则与该组件相关联，例如“运行时”或“开发”。

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

INSTALL_DESTINATION

保存如上所述的 <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 选项的第二个签名。

DESTINATION

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

COMPONENT

指定安装组件名称，安装规则与该组件相关联，例如“运行时”或“开发”。

使用以下命令创建 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 版中标记为已弃用： 由于 废除 javah 工具，此命令在 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
)

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

create_javah(header_files

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

CLASSES

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

CLASSPATH

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

OUTPUT_NAME

DEPENDS

OUTPUT_DIR

javah 目标所依赖的目标。

OUTPUT

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

TARGET_DIRECTORY

设置头文件将生成的目录。此行为与 javah 工具的 -d 选项的行为相同。如果未指定，则 CMAKE_CURRENT_BINARY_DIR 将用作输出目录。

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

导出的 JAR 目标

install_jar_exports

3.7 版中新增。

安装目标导出文件

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

TARGETS

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

NAMESPACE

DESTINATION

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

COMPONENT

指定安装组件名称，安装规则与该组件相关联，例如“运行时”或“开发”。

3.9 版中新增。

TARGET_DIRECTORY

<namespace> 值将追加到目标名称，因为它们会被写入导入文件。

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

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

install_jar_exports

3.7 版中新增。

安装目标导出文件

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

TARGETS

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

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

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 目录。

CLASSES

CLASSPATH

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

指定在何处安装 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 的行为相同。