UseJava¶
Use Module for Java
This file provides functions for Java. It is assumed that FindJava.cmake has already been loaded. See FindJava.cmake for information on how to load Java into your CMake project.
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]]
)
This command creates a <target_name>.jar. It compiles the given source files (source) and adds the given resource files (resource) to the jar file. Source files can be java files or listing files (prefixed by ‘@’). If only resource files are given then just a jar file is created. The list of include jars are added to the classpath when compiling the java sources and also to the dependencies of the target. INCLUDE_JARS also accepts other target names created by add_jar. For backwards compatibility, jar files listed as sources are ignored (as they have been since the first version of this module).
The default OUTPUT_DIR can also be changed by setting the variable CMAKE_JAVA_TARGET_OUTPUT_DIR.
Optionally, using option GENERATE_NATIVE_HEADERS, native header files can be generated for methods declared as native. These files provide the connective glue that allow your Java and C code to interact. An INTERFACE target will be created for an easy usage of generated files. Sub-option DESTINATION can be used to specify output directory for generated header files.
GENERATE_NATIVE_HEADERS option requires, at least, version 1.8 of the JDK.
Additional instructions:
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)
Target Properties:
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"]
)
This command is used to find a full path to the named jar. A cache entry named by <VAR> is created to stor the result of this command. If the full path to a jar is found the result is stored in the variable and the search will not repeated unless the variable is cleared. If nothing is found, the result will be <VAR>-NOTFOUND, and the search will be attempted again next time find_jar is invoked with the same variable. The name of the full path to a file that is searched for is specified by the names listed after NAMES argument. Additional search locations can be specified after the PATHS argument. If you require special a version of a jar file you can specify it with the VERSIONS argument. The argument after DOC will be used for the documentation string in the cache.
install_jar(target_name destination)
install_jar(target_name DESTINATION destination [COMPONENT component])
This command installs the TARGET_NAME files to the given DESTINATION. It should be called in the same scope as add_jar() or it will fail.
Target Properties:
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])
This command installs the TARGET_NAME JNI symlinks to the given DESTINATION. It should be called in the same scope as add_jar() or it will fail.
install_jar_exports(TARGETS jars...
[NAMESPACE <namespace>]
FILE <filename>
DESTINATION <dir> [COMPONENT <component>])
This command installs a target export file <filename> for the named jar
targets to the given DESTINATION. Its function is similar to that of
install(EXPORTS ...).
export_jars(TARGETS jars...
[NAMESPACE <namespace>]
FILE <filename>)
This command writes a target export file <filename> for the named jar
targets. Its function is similar to that of 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]
)
Create java documentation based on files or packages. For more details please read the javadoc manpage.
There are two main signatures for create_javadoc. The first signature works with package names on a path with source files:
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
)
The second signature for create_javadoc works on a given list of files.
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]
)
Example:
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
)
Both signatures share most of the options. These options are the same as what you can find in the javadoc manpage. Please look at the manpage for CLASSPATH, DOCTITLE, WINDOWTITLE, AUTHOR, USE and VERSION.
The documentation will be by default installed to
${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
if you don’t set the INSTALLPATH.
create_javah(TARGET <target>
GENERATED_FILES <VAR>
CLASSES <class>...
[CLASSPATH <classpath>...]
[DEPENDS <depend>...]
[OUTPUT_NAME <path>|OUTPUT_DIR <path>]
)
Create C header files from java classes. These files provide the connective glue that allow your Java and C code to interact.
This command will no longer be supported starting with version 10 of the JDK due
to the suppression of javah tool.
Command add_jar(GENERATE_NATIVE_HEADERS) must be used instead.
There are two main signatures for create_javah. The first signature returns generated files through variable specified by GENERATED_FILES option:
Example:
Create_javah(GENERATED_FILES files_headers
CLASSES org.cmake.HelloWorld
CLASSPATH hello.jar
)
The second signature for create_javah creates a target which encapsulates header files generation.
Example:
Create_javah(TARGET target_headers
CLASSES org.cmake.HelloWorld
CLASSPATH hello.jar
)
Both signatures share same options.
CLASSES <class>...Specifies Java classes used to generate headers.
CLASSPATH <classpath>...Specifies various paths to look up classes. Here .class files, jar files or targets created by command add_jar can be used.
DEPENDS <depend>...Targets on which the javah target depends
OUTPUT_NAME <path>Concatenates the resulting header files for all the classes listed by option CLASSES into <path>. Same behavior as option ‘-o’ of javah tool.
OUTPUT_DIR <path>Sets the directory where the header files will be generated. Same behavior as option ‘-d’ of javah tool. If not specified, ${CMAKE_CURRENT_BINARY_DIR} is used as output directory.