diff options
Diffstat (limited to 'Modules/UseJava.cmake')
| -rw-r--r-- | Modules/UseJava.cmake | 526 |
1 files changed, 231 insertions, 295 deletions
diff --git a/Modules/UseJava.cmake b/Modules/UseJava.cmake index 5600b4c1c..07984885b 100644 --- a/Modules/UseJava.cmake +++ b/Modules/UseJava.cmake @@ -8,289 +8,234 @@ 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 +:module:`FindJava` has already been loaded. See :module:`FindJava` for information on how to load Java into your CMake project. -:: +Creating And Installing JARs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: 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>]] + ) - 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 +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 +(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 +``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. +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. +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. +``GENERATE_NATIVE_HEADERS`` option requires, at least, version 1.8 of the JDK. -Additional instructions: +The ``add_jar()`` function sets the following target properties on +``<target_name>``: -:: - - To add compile flags to the target you can set these flags with - the following variable: +``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``. +.. code-block:: cmake + install_jar(<target_name> <destination>) + install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>]) -:: - - set(CMAKE_JAVA_COMPILE_FLAGS -nowarn) +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 :command:`get_property` and the ``INSTALL_DESTINATION`` +property key. +.. code-block:: cmake -:: - - 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) - - - -:: + install_jni_symlink(<target_name> <destination>) + install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>]) - To use a different output directory than CMAKE_CURRENT_BINARY_DIR - you can set it with: +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. +.. code-block:: cmake + install_jar_exports(TARGETS <jars>... + [NAMESPACE <namespace>] + FILE <filename> + DESTINATION <destination> [COMPONENT <component>]) -:: - - 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. +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 :command:`install(EXPORTS)`. +.. code-block:: cmake + 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 :command:`export`. - add_jar(shibboleet shibbotleet.java VERSION 1.2.0) +Examples +"""""""" +To add compile flags to the target you can set these flags with the following +variable: -:: +.. code-block:: cmake - If the target is a JNI library, utilize the following commands to - create a JNI symbolic link: + 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. -:: +.. code-block:: cmake - 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}) + set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar) +To use a different output name for the target you can set it with: +.. code-block:: cmake -:: + add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar) - 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: +To use a different output directory than ``CMAKE_CURRENT_BINARY_DIR`` you can +set it with: +.. code-block:: cmake + 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: - set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo) - add_jar(foo foo.java) +.. code-block:: cmake + 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: -:: +.. code-block:: cmake - set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar) - add_jar(bar bar.java) + 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. +.. code-block:: cmake -:: + add_jar(shibboleet shibbotleet.java VERSION 1.2.0) - 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. +If the target is a JNI library, utilize the following commands to +create a JNI symbolic link: +.. code-block:: cmake -:: + 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}) - 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) +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: +.. code-block:: cmake -Target Properties: + 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) - The add_jar() function sets some target properties. You can get these - properties with the - get_property(TARGET <target_name> PROPERTY <propery_name>) - command. +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 +:command:`target_link_libraries` command. +.. code-block:: cmake + 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) -:: - 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. +Finding JARs +^^^^^^^^^^^^ -:: +.. code-block:: cmake - find_jar(<VAR> - name | NAMES name1 [name2 ...] - [PATHS path1 [path2 ... ENV var]] - [VERSIONS version1 [version2]] - [DOC "cache documentation string"] + 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. +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 +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. +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 +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. +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. -:: - - install_jni_symlink(target_name destination) - install_jni_symlink(target_name DESTINATION destination [COMPONENT component]) +There are two main signatures for ``create_javadoc()``. The first signature +works with package names on a path with source files. -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 -:command:`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 :command:`export(...)`. - -:: +.. code-block:: cmake create_javadoc(<VAR> - PACKAGES pkg1 [pkg2 ...] + PACKAGES <pkg1> [<pkg2>...] [SOURCEPATH <sourcepath>] [CLASSPATH <classpath>] [INSTALLPATH <install path>] @@ -301,80 +246,70 @@ targets. Its function is similar to that of :command:`export(...)`. [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 - ) +For example: +.. code-block:: cmake + 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 +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: - -:: +.. code-block:: cmake + + 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 - ) +For example: +.. code-block:: cmake + 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. +manpage for ``CLASSPATH``, ``DOCTITLE``, ``WINDOWTITLE``, ``AUTHOR``, ``USE`` +and ``VERSION``. -The documentation will be by default installed to +If you don't set the ``INSTALLPATH``, then by default the documentation will +be installed to : :: ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR> +Header Generation +^^^^^^^^^^^^^^^^^ -if you don't set the INSTALLPATH. - -:: +.. code-block:: cmake - create_javah(TARGET <target> - GENERATED_FILES <VAR> + create_javah(TARGET <target> | GENERATED_FILES <VAR> CLASSES <class>... [CLASSPATH <classpath>...] [DEPENDS <depend>...] @@ -384,55 +319,55 @@ if you don't set the INSTALLPATH. 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 <http://openjdk.java.net/jeps/313>`_. -Command ``add_jar(GENERATE_NATIVE_HEADERS)`` must be used instead. +.. deprecated:: 3.11 -There are two main signatures for create_javah. The first signature -returns generated files through variable specified by GENERATED_FILES option: +.. note:: -:: + This command will no longer be supported starting with version 10 of the JDK + due to the `suppression of javah tool <http://openjdk.java.net/jeps/313>`_. + The ``add_jar(GENERATE_NATIVE_HEADERS)`` command should be used instead. - Example: - Create_javah(GENERATED_FILES files_headers - CLASSES org.cmake.HelloWorld - CLASSPATH hello.jar - ) +There are two main signatures for ``create_javah()``. The first signature +returns generated files through variable specified by the ``GENERATED_FILES`` +option. For example: +.. code-block:: cmake + 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 - ) +The second signature for ``create_javah()`` creates a target which encapsulates +header files generation. E.g. +.. code-block:: cmake + 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. +``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. +``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 +``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_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. +``OUTPUT_DIR <path>`` + Sets the directory where the header files will be generated. Same behavior + as option ``-d`` of javah tool. If not specified, + :variable:`CMAKE_CURRENT_BINARY_DIR` is used as the output directory. #]=======================================================================] function (__java_copy_file src dest comment) @@ -800,7 +735,8 @@ function(add_jar _TARGET_NAME) # this INTERFACE library depends on jar generation add_dependencies (${_GENERATE_NATIVE_HEADERS_TARGET} ${_TARGET_NAME}) - set_property (DIRECTORY PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${_GENERATE_NATIVE_HEADERS_OUTPUT_DIR}") + set_property (DIRECTORY APPEND PROPERTY ADDITIONAL_CLEAN_FILES + "${_GENERATE_NATIVE_HEADERS_OUTPUT_DIR}") endif() endfunction() |