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 檔案中。

Added in version 3.4: 版本 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 列表會新增至類別路徑，也會新增至目標的依賴項。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 定義自訂的 manifest。

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)

Added in version 3.20: 版本 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() 相同的範圍內呼叫，否則將會失敗。

Added in version 3.4: 版本 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() 相同的範圍內呼叫，否則將會失敗。

Added in version 3.4: 版本 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>]
             )

Deprecated since version 3.11: 自版本 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 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 manpage。

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 文件¶

目錄

上一主題

下一主題

本頁