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 будет создан для простого использования сгенерированных файлов. Подопция DESTINATION может быть использована для указания каталога вывода сгенерированных файлов заголовков.

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

Для оптимального использования данного параметра рекомендуется включить модуль JNI перед любым вызовом add_jar(). Созданный целевой объект для native заголовков может затем использоваться для компиляции 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.

Каталог, где сгенерированы 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

Устанавливает 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–2023 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.26/module/UseJava.html