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>]]
        )

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

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

Необязательно, используя опцию GENERATE_NATIVE_HEADERS, можно сгенерировать заголовки нативных файлов для методов, объявленных как native. Эти файлы предоставляют связующее звено, позволяющее взаимодействовать коду Java и C. Для простого использования сгенерированных файлов будет создан целевой объект INTERFACE. Подвариант DESTINATION может быть использован для указания каталога вывода сгенерированных заголовков.

GENERATE_NATIVE_HEADERS опция требует, как минимум, версии 1.8 JDK.

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

INSTALL_FILES

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

JNI_SYMLINK

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

JAR_FILE

Расположение JAR-файла, чтобы вы могли его включить.

CLASSDIR

Каталог, где можно найти файлы .class. Например, чтобы использовать их с 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() , иначе произойдёт ошибка.

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

Поиск 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 в качестве каталога вывода.