UseJava

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

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

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-jar добавляется в classpath при компиляции 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.

Дополнительные инструкции:

To add compile flags to the target you can set these flags with
the following variable:

set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)

To add a path or a jar file to the class path you can do this
with the CMAKE_JAVA_INCLUDE_PATH variable.

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

To use a different output name for the target you can set it with:

add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)

To use a different output directory than CMAKE_CURRENT_BINARY_DIR
you can set it with:

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

To define an entry point in your jar you can set it with the ENTRY_POINT
named argument:

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

To define a custom manifest for the jar, you can set it with the manifest
named argument:

add_jar(example MANIFEST /path/to/manifest)

To add a VERSION to the target output name you can set it using
the VERSION named argument to add_jar. This will create a jar file with the
name shibboleet-1.0.0.jar and will create a symlink shibboleet.jar
pointing to the jar with the version information.

add_jar(shibboleet shibbotleet.java VERSION 1.2.0)

If the target is a JNI library, utilize the following commands to
create a JNI symbolic link:

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

If a single target needs to produce more than one jar from its
java source code, to prevent the accumulation of duplicate class
files in subsequent jars, set/reset CMAKE_JAR_CLASSES_PREFIX prior
to calling the add_jar() function:

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)

For an optimum usage of option GENERATE_NATIVE_HEADERS, it is recommended to
include module JNI before any call to add_jar. The produced target for native
headers can then be used to compile C/C++ sources with command
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)

Свойства целевого объекта:

The add_jar() function sets some target properties. You can get these
properties with the
   get_property(TARGET <target_name> PROPERTY <propery_name>)
command.

INSTALL_FILES      The files which should be installed. This is used by
                   install_jar().
JNI_SYMLINK        The JNI symlink which should be installed.
                   This is used by install_jni_symlink().
JAR_FILE           The location of the jar file so that you can include
                   it.
CLASSDIR           The directory where the class files can be found. For
                   example to use them with javah.

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 будет использован для строки документации в кэше.

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

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

Свойства целевого объекта:

The install_jar() function sets the INSTALL_DESTINATION target property
on jars so installed. This property holds the DESTINATION as described
above, and is used by install_jar_exports(). You can get this property
with the
   get_property(TARGET <target_name> PROPERTY INSTALL_DESTINATION)
command.

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

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

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

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

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

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

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

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

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

Example:
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.

Документация будет по умолчанию установлена в

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

если вы не зададите INSTALLPATH.

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

Создать файлы заголовков C из классов Java. Эти файлы обеспечивают соединение, которое позволяет взаимодействовать коду Java и C.

Эта команда больше не будет поддерживаться, начиная с версии 10 JDK, из-за прекращения поддержки инструмента javah. Вместо этого необходимо использовать команду add_jar(GENERATE_NATIVE_HEADERS).

Существует два основных варианта подписи для create_javah. Первый вариант возвращает сгенерированные файлы через переменную, указанную параметром GENERATED_FILES:

Example:
Create_javah(GENERATED_FILES files_headers
  CLASSES org.cmake.HelloWorld
  CLASSPATH hello.jar
)

Второй вариант подписи для create_javah создаёт целевой объект, который обобщает генерацию заголовочных файлов.

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