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.

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