UseJava¶

此檔案提供 Java 的支援。假設 FindJava 已被載入。請參閱 FindJava 以取得如何將 Java 載入到 CMake 專案的資訊。

概要¶

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 版本中新增。

將命名的 <resource> 檔案新增至 jar 檔中，方法是剝離來源檔案路徑，並將該檔案放置在 jar 檔中的 <ns> 下方。

例如

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 檔案會被忽略 (因為自此模組的第一個版本以來就是如此)。

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 子選項現在支援為 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 檔，為了防止後續 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 版本中新增: 具有 DESTINATION 和 COMPONENT 選項的第二個簽名。

DESTINATION: 指定要將檔案安裝到的磁碟目錄。
COMPONENT: 指定安裝規則關聯的安裝元件名稱，例如 "runtime" 或 "development"。

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: 指定安裝規則關聯的安裝元件名稱，例如 "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 版本起已棄用: 由於抑制 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
)

兩個簽名都共用相同的選項。

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 子選項從系統環境變數讀取路徑。
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 選項相同。

UseJava¶

概要¶

建立與安裝 JAR 檔¶

標頭產生¶

匯出 JAR 目標¶

尋找 JAR 檔案¶

建立 Java 文件¶

目錄

上一個主題

下一個主題

此頁面