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 для каждого документированного класса и пакета. То же поведение, что и параметр -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.27/module/UseJava.html