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

Создаёт JAR-файл, содержащий java-объекты и, необязательно, ресурсы:

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-файл, удаляя путь к исходному файлу и размещая файл под <ns> внутри JAR-файла.

Например:

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

в результате чего ресурс доступен через /com/my/namespace/resource.txt внутри JAR-файла.

Ресурсы можно добавить без изменения пространства имён, добавив их в список SOURCES (оригинальное поведение). В этом случае пути к ресурсам должны быть относительными к CMAKE_CURRENT_SOURCE_DIR. Добавление ресурсов без использования параметра RESOURCES в проектах вне исходного каталога почти наверняка приведёт к путанице.

Примечание

Добавление ресурсов через параметр SOURCES полагается на жёстко заданный список расширений файлов, которые проверяются для определения, компилируются ли они (например, File.java). Файлы с расширениями, соответствующими этим расширениям, компилируются. Файлы, не соответствующие этим расширениям, обрабатываются как ресурсы. Чтобы включить нескомпилированные ресурсы, соответствующие этим расширениям файлов, используйте параметр RESOURCES.

INCLUDE_JARS

Список JAR-файлов добавляется в путь класса при компиляции java-исходников, а также в зависимости от целевого объекта. INCLUDE_JARS также принимает и другие имена целевых объектов, созданные add_jar(). Для обратной совместимости JAR-файлы, указанные как исходные файлы, игнорируются (так было с момента первой версии этого модуля).

ENTRY_POINT

Определяет точку входа в JAR-файл.

VERSION

Добавляет версию в имя выходного целевого объекта.

Следующий пример создаст JAR-файл с именем shibboleet-1.2.0.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.

Генерирует файлы заголовков для методов, объявленных как native. Эти файлы обеспечивают соединительную связку, которая позволяет вашим кодам Java и C взаимодействовать. Для удобного использования сгенерированных файлов будет создан целевой объект INTERFACE. Подвариант DESTINATION может быть использован для указания каталога вывода для сгенерированных файлов заголовков.

Этот параметр требует, как минимум, версии 1.8 JDK.

Для оптимального использования этого параметра рекомендуется включить модуль JNI до любого вызова add_jar(). Созданный целевой объект для нативных заголовков затем можно использовать для компиляции исходных кодов C/C++ с помощью команды target_link_libraries().

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, требуется подвариант INSTALL опции DESTINATION:

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

Если необходимо создать несколько JAR-файлов из одного и того же дерева исходных файлов Java, для предотвращения накопления дублирующихся файлов классов в последующих JAR-файлах, установите/сбросьте CMAKE_JAR_CLASSES_PREFIX перед вызовом add_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: Указывает имя компонента установки, к которому относится правило установки, например, "runtime" или "development".

Команда install_jar() устанавливает следующие свойства целевого объекта на <target_name>:

INSTALL_DESTINATION: Содержит <destination>, как описано выше, и используется командой install_jar_exports().

install_jni_symlink

Устанавливает символические ссылки JNI для целевого объекта, сгенерированного командой add_jar():

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.

Генерирует заголовочные файлы C для Java-классов:

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

Устарело начиная с версии 3.11: Эта команда больше не будет поддерживаться начиная с версии 10 JDK из-за удаления инструмента javah. Вместо этого следует использовать команду add_jar(GENERATE_NATIVE_HEADERS).

Создаёт заголовочные файлы C из Java-классов. Эти файлы обеспечивают связующее звено, позволяющее вашим 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: Указывает различные пути для поиска классов. Здесь можно использовать файлы, JAR-файлы или целевые объекты, созданные командой add_jar.
DEPENDS: Целевые объекты, от которых зависит целевой объект javah.
OUTPUT_NAME: Объединяет получившиеся заголовочные файлы для всех классов, перечисленных в опции CLASSES, в <path>. Поведение аналогично опции -o инструмента javah.
OUTPUT_DIR: Устанавливает каталог, в котором будут сгенерированы заголовочные файлы. Поведение аналогично опции -d инструмента javah. Если не указано, используется CMAKE_CURRENT_BINARY_DIR в качестве каталога вывода.

Экспорт целевых JAR-файлов

install_jar_exports

Новое в версии 3.7.

Устанавливает файл экспорта целевого объекта:

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

Эта команда устанавливает файл экспорта целевого объекта <filename> для указанных целевых JAR-файлов в указанный <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>)

Эта команда записывает файл экспорта целевого объекта <filename> для указанных <jars> целевых объектов. Его функциональность аналогична функциональности 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: Укажите местоположение файлов классов пользователя. Поведение аналогично опции -classpath инструмента javadoc.
INSTALLPATH: Укажите место для установки документации Java. Если указано, документация будет установлена в ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>.
DOCTITLE: Укажите заголовок для верхней части файла сводного обзора. Поведение аналогично опции -doctitle инструмента javadoc.
WINDOWTITLE: Укажите заголовок для тега HTML <title>. Поведение аналогично опции -windowtitle инструмента javadoc.
AUTHOR: При указании значения TRUE включает текст @author в сгенерированную документацию. Поведение аналогично опции -author инструмента javadoc.
USE: При указании значения TRUE создаёт страницы использования класса и пакета. Включает одну страницу использования для каждого документированного класса и пакета. Поведение аналогично опции -use инструмента javadoc.
VERSION: При указании значения TRUE включает текст версии в сгенерированную документацию. Поведение аналогично опции -version инструмента javadoc.

© 2000–2021 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.22/module/UseJava.html