UseJava

Использование модуля для Java

Этот файл предоставляет функции для Java. Предполагается, что FindJava уже загружен. См. FindJava для информации о загрузке Java в ваш проект CMake.

Создание и установка JAR-файлов

add_jar(<target_name>
        [SOURCES] <source1> [<source2>...] [<resource1>...]
        [INCLUDE_JARS <jar1> [<jar2>...]]
        [ENTRY_POINT <entry>]
        [VERSION <version>]
        [OUTPUT_NAME <name>]
        [OUTPUT_DIR <dir>]
        [GENERATE_NATIVE_HEADERS <target>
                           [DESTINATION (<dir>|INSTALL <dir> [BUILD <dir>])]]
        )

Эта команда создаёт <target_name>.jar. Она компилирует заданные <source> файлы и добавляет заданные <resource> файлы в JAR-файл. Исходные файлы могут быть файлами Java или списками файлов (с префиксом @). Если указаны только файлы ресурсов, то создаётся только JAR-файл. Список INCLUDE_JARS добавляется в путь к классам при компиляции исходных файлов Java, а также в зависимости целевого объекта. INCLUDE_JARS также принимает другие имена целевых объектов, созданные add_jar(). Для обратной совместимости, JAR-файлы, указанные в качестве исходных, игнорируются (как это было сделано с первого выпуска модуля).

Значение по умолчанию OUTPUT_DIR также может быть изменено, задав переменную CMAKE_JAVA_TARGET_OUTPUT_DIR.

Функция add_jar() устанавливает следующие свойства целевого объекта для <target_name>:

INSTALL_FILES

Файлы, которые должны быть установлены. Это используется install_jar().

JNI_SYMLINK

Символическая ссылка JNI, которая должна быть установлена. Это используется install_jni_symlink().

JAR_FILE

Расположение JAR-файла для включения его в проект.

CLASSDIR

Каталог, в котором находятся файлы классов. Например, для использования с javah.

install_jar(<target_name> <destination>)
install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])

Эта команда устанавливает <target_name> файлы в указанный <destination>. Она должна быть вызвана в том же контексте, что и add_jar() или она завершится с ошибкой.

Функция install_jar() устанавливает свойство целевого объекта INSTALL_DESTINATION для установленных JAR-файлов. Это свойство содержит <destination>, как описано выше, и используется install_jar_exports(). Вы можете получить эту информацию с помощью get_property() и ключа свойства INSTALL_DESTINATION.

install_jni_symlink(<target_name> <destination>)
install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])

Эта команда устанавливает <target_name> JNI символические ссылки в указанный <destination>. Она должна быть вызвана в том же контексте, что и add_jar() или она завершится с ошибкой.

Экспорт JAR-целевых объектов

install_jar_exports(TARGETS <jars>...
                    [NAMESPACE <namespace>]
                    FILE <filename>
                    DESTINATION <destination> [COMPONENT <component>])

Эта команда устанавливает файл экспорта целевого объекта <filename> для указанных JAR-целевых объектов в указанный <destination> каталог. Его функция аналогична функции install(EXPORTS).

export_jars(TARGETS <jars>...
            [NAMESPACE <namespace>]
            FILE <filename>)

Эта команда записывает файл экспорта целевого объекта <filename> для указанных <jars> целевых объектов. Его функция аналогична функции export().

Примеры

Для добавления флагов компиляции в целевой объект, вы можете задать эти флаги с помощью следующей переменной:

set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)

Для добавления пути или JAR-файла в путь к классам, вы можете сделать это с помощью переменной CMAKE_JAVA_INCLUDE_PATH.

set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)

Для использования другого имени целевого объекта, вы можете задать его с помощью:

add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)

Для использования каталога вывода отличного от CMAKE_CURRENT_BINARY_DIR, вы можете задать его с помощью:

add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)

Для определения точки входа в JAR-файл, вы можете задать её с помощью именованного аргумента ENTRY_POINT:

add_jar(example ENTRY_POINT com/examples/MyProject/Main)

Для определения пользовательского манифеста для JAR-файла, вы можете задать его с помощью именованного аргумента MANIFEST:

add_jar(example MANIFEST /path/to/manifest)

Для добавления версии в имя выходного целевого объекта, вы можете задать её с помощью именованного аргумента VERSION к add_jar(). Следующий пример создаст JAR-файл с именем shibboleet-1.0.0.jar и создаст символическую ссылку shibboleet.jar на JAR-файл с информацией о версии.

add_jar(shibboleet shibbotleet.java VERSION 1.2.0)

Если целевой объект является библиотекой JNI, используйте следующие команды для создания 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})

Если одному целевому объекту требуется сгенерировать более одного 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)

Для оптимального использования опции GENERATE_NATIVE_HEADERS, рекомендуется включить модуль 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)

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)

Поиск 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 Дополнительные места поиска могут быть указаны после аргумента PATHS Если вам требуется специальная версия JAR-файла, вы можете указать её с помощью аргумента VERSIONS Аргумент после DOC будет использован для строки документации в кеше.

Javadoc

Команда create_javadoc() может быть использована для создания документации Java на основе файлов или пакетов. Для получения более подробной информации, пожалуйста, прочтите страницу справки javadoc.

Существует две основные сигнатуры для create_javadoc() Первая сигнатура работает с именами пакетов в пути с исходными файлами.

create_javadoc(<VAR>
               PACKAGES <pkg1> [<pkg2>...]
               [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(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(<VAR>
               FILES <file1> [<file2>...]
               [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(my_example_doc
  FILES ${example_SRCS}
  CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
  WINDOWTITLE "My example"
  DOCTITLE "<h1>My example</h1>"
  AUTHOR TRUE
  USE TRUE
  VERSION TRUE
)

Обе сигнатуры используют большинство опций. Эти опции такие же, как те, которые вы можете найти на странице справки javadoc. Пожалуйста, обратитесь к странице справки для CLASSPATH, DOCTITLE, WINDOWTITLE, AUTHOR, USE и VERSION.

Если вы не задаёте INSTALLPATH, то по умолчанию документация будет установлена в:

${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>

Генерация заголовков

create_javah(TARGET <target> | GENERATED_FILES <VAR>
             CLASSES <class>...
             [CLASSPATH <classpath>...]
             [DEPENDS <depend>...]
             [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
             )

Генерирует файлы заголовков 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 <class>...

Указывает классы Java, используемые для генерации заголовков.

CLASSPATH <classpath>...

Указывает различные пути для поиска классов. Здесь можно использовать файлы .class, jar-файлы или целевые файлы, созданные командой add_jar.

DEPENDS <depend>...

Цели, от которых зависит целевая задача javah.

OUTPUT_NAME <path>

Объединяет результирующие файлы заголовков для всех классов, перечисленных опцией CLASSES, в <path>. То же поведение, что и опция -o инструмента javah.

OUTPUT_DIR <path>

Устанавливает каталог, в котором будут сгенерированы файлы заголовков. То же поведение, что и опция -d инструмента javah. Если не указано, в качестве выходного каталога используется CMAKE_CURRENT_BINARY_DIR.