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

Этот параметр требует, как минимум, версии 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–2024 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.30/module/UseJava.html