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

Устанавливает каталог, в котором будет сгенерирован JAR-файл. Если не указано, используется CMAKE_CURRENT_BINARY_DIR как выходной каталог.

GENERATE_NATIVE_HEADERS

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

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

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

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