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). Файлы с расширениями, соответствующими SOURCES, будут скомпилированы. Файлы, которые не соответствуют расширениям, обрабатываются как ресурсы. Чтобы включить нескомпилированные ресурсы, соответствующие этим расширениям, используйте параметр 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

Добавлен в версии 3.11.

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

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

Для оптимального использования данного параметра рекомендуется включить модуль 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: Указывает различные пути для поиска классов. Здесь можно использовать файлы .class, 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 для каждого документированного класса и пакета. Поведение аналогично опции -use инструмента javadoc.
VERSION: При указании значения TRUE включает текст версии в сгенерированную документацию. Поведение аналогично опции -version инструмента javadoc.

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