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