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