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