# UseJava

Use Module for Java

This file provides functions for Java. It is assumed that `FindJava` has already been loaded. See `FindJava` for information on how to load Java into your CMake project.

## Creating And Installing JARs

    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>|INSTALL <dir> [BUILD <dir>])]]
            )

This command creates a `<target_name>.jar`. It compiles the given `<source>` files and adds the given `<resource>` files 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).

New in version 3.4: Support for response files (prefixed by `@`) in the `SOURCES` list.

The default `OUTPUT_DIR` can also be changed by setting the variable `CMAKE_JAVA_TARGET_OUTPUT_DIR`.

New in version 3.11: 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 the output directory for generated header files.

`GENERATE_NATIVE_HEADERS` option requires, at least, version 1.8 of the JDK.

New in version 3.20: `DESTINATION` sub-option now supports the possibility to specify different output directories for `BUILD` and `INSTALL` steps. This is required to export the interface target generated by `GENERATE_NATIVE_HEADERS` option. If `BUILD` directory is not specified, a default directory will be used.

The `add_jar()` function sets the following target properties on `<target_name>`:

`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`.

New in version 3.20: The target generated by option `GENERATE_NATIVE_HEADERS` has the property `NATIVE_HEADERS_DIRECTORY` which specify the directory holding the native headers.

    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.

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 information with `get_property()` and the `INSTALL_DESTINATION` property key.

New in version 3.4: The second signature with `DESTINATION` and `COMPONENT` options.

    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.

New in version 3.4: The second signature with `DESTINATION` and `COMPONENT` options.

## Exporting JAR Targets

New in version 3.7.

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

This command installs a target export file `<filename>` for the named jar targets to the given `<destination>` directory. Its function is similar to that of `install(EXPORTS)`.

New in version 3.9: The `NAMESPACE` option.

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

This command writes a target export file `<filename>` for the named `<jars>` targets. Its function is similar to that of `export()`.

New in version 3.9: The `NAMESPACE` option.

### Examples

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()`. The following example 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 the `target_link_libraries()` command.

    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)

New in version 3.20: It is now possible to export the target generated by `GENERATE_NATIVE_HEADERS` option.

    add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native
                                                 DESTINATION INSTALL include)
    install(TARGETS foo-native EXPORT native)
    install(DIRECTORY "$<TARGET_PROPERTY:foo-native,NATIVE_HEADERS_DIRECTORY>/"
            DESTINATION include)
    install(EXPORT native DESTINATION /to/export NAMESPACE foo)

## Finding JARs

    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 store 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.

## Javadoc

The `create_javadoc()` command can be used to 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.

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

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

For 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`.

If you don't set the `INSTALLPATH`, then by default the documentation will be installed to :

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

## Header Generation

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

New in version 3.4.

Deprecated since version 3.11: This command will no longer be supported starting with version 10 of the JDK due to the suppression of javah tool. The `add_jar(GENERATE_NATIVE_HEADERS)` command should be used instead.

Create C header files from java classes. These files provide the connective glue that allow your Java and C code to interact.

There are two main signatures for `create_javah()`. The first signature returns generated files through variable specified by the `GENERATED_FILES` option. For 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. E.g.

    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 the output directory.