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.

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

Для оптимального использования данного параметра рекомендуется включить модуль 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–2024 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/latest/module/UseJava.html