diff --git a/Modules/UseJava.cmake b/Modules/UseJava.cmake index 5600b4c1cd..b0315b2992 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. -:: - - 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 .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 PROPERTY ) - 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( - name | NAMES name1 [name2 ...] - [PATHS path1 [path2 ... ENV var]] - [VERSIONS version1 [version2]] - [DOC "cache documentation string"] +Creating And Installing JARs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + add_jar( + [SOURCES] [...] [...] + [INCLUDE_JARS [...]] + [ENTRY_POINT ] + [VERSION ] + [OUTPUT_NAME ] + [OUTPUT_DIR ] + [GENERATE_NATIVE_HEADERS [DESTINATION ]] ) -This command is used to find a full path to the named jar. A cache -entry named by 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 -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. +This command creates a ``.jar``. It compiles the given +```` files and adds the given ```` 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). -:: +The default ``OUTPUT_DIR`` can also be changed by setting the variable +``CMAKE_JAVA_TARGET_OUTPUT_DIR``. - install_jar(target_name destination) - install_jar(target_name DESTINATION destination [COMPONENT component]) +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. -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. +``GENERATE_NATIVE_HEADERS`` option requires, at least, version 1.8 of the JDK. -Target Properties: +The ``add_jar()`` function sets the following target properties on +````: -:: +``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``. - 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 PROPERTY INSTALL_DESTINATION) - command. +.. code-block:: cmake + install_jar( ) + install_jar( DESTINATION [COMPONENT ]) +This command installs the ```` files to the given +````. 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 ```` 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. - install_jni_symlink(target_name destination) - install_jni_symlink(target_name DESTINATION destination [COMPONENT component]) +.. code-block:: cmake -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_jni_symlink( ) + install_jni_symlink( DESTINATION [COMPONENT ]) -:: +This command installs the ```` JNI symlinks to the given +````. It should be called in the same scope as ``add_jar()`` or +it will fail. - install_jar_exports(TARGETS jars... +.. code-block:: cmake + + install_jar_exports(TARGETS ... [NAMESPACE ] FILE - DESTINATION [COMPONENT ]) + DESTINATION [COMPONENT ]) This command installs a target export file ```` for the named jar -targets to the given ``DESTINATION``. Its function is similar to that of -:command:`install(EXPORTS ...)`. +targets to the given ```` directory. Its function is similar to +that of :command:`install(EXPORTS)`. -:: +.. code-block:: cmake - export_jars(TARGETS jars... + export_jars(TARGETS ... [NAMESPACE ] FILE ) -This command writes a target export file ```` for the named jar -targets. Its function is similar to that of :command:`export(...)`. +This command writes a target export file ```` for the named ```` +targets. Its function is similar to that of :command:`export`. -:: + +Examples +"""""""" + +To add compile flags to the target you can set these flags with the following +variable: + +.. code-block:: cmake + + 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_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) + +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: + +.. 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 + + 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) + +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}) + +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 + + 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 +: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) + + +Finding JARs +^^^^^^^^^^^^ + +.. code-block:: cmake + + find_jar( + | NAMES [...] + [PATHS [... ENV ]] + [VERSIONS []] + [DOC "cache documentation string"] + ) + +This command is used to find a full path to the named jar. A cache +entry named by ```` 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 ``-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. + +.. code-block:: cmake create_javadoc( - PACKAGES pkg1 [pkg2 ...] + PACKAGES [...] [SOURCEPATH ] [CLASSPATH ] [INSTALLPATH ] @@ -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. +For example: -There are two main signatures for create_javadoc. The first signature -works with package names on a path with source files: +.. 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 "

My example

" + AUTHOR TRUE + USE TRUE + VERSION TRUE + ) - 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 "

My example

" - 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. -:: +.. code-block:: cmake - create_javadoc( - FILES file1 [file2 ...] - [CLASSPATH ] - [INSTALLPATH ] - [DOCTITLE "the documentation title"] - [WINDOWTITLE "the title of the document"] - [AUTHOR TRUE|FALSE] - [USE TRUE|FALSE] - [VERSION TRUE|FALSE] - ) + create_javadoc( + FILES [...] + [CLASSPATH ] + [INSTALLPATH ] + [DOCTITLE "the documentation title"] + [WINDOWTITLE "the title of the document"] + [AUTHOR TRUE|FALSE] + [USE TRUE|FALSE] + [VERSION TRUE|FALSE] + ) +For example: +.. code-block:: cmake -Example: - -:: - - create_javadoc(my_example_doc - FILES ${example_SRCS} - CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH} - WINDOWTITLE "My example" - DOCTITLE "

My example

" - AUTHOR TRUE - USE TRUE - VERSION TRUE - ) - - + create_javadoc(my_example_doc + FILES ${example_SRCS} + CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH} + WINDOWTITLE "My example" + DOCTITLE "

My example

" + 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/ +Header Generation +^^^^^^^^^^^^^^^^^ -if you don't set the INSTALLPATH. +.. code-block:: cmake -:: - - create_javah(TARGET - GENERATED_FILES + create_javah(TARGET | GENERATED_FILES CLASSES ... [CLASSPATH ...] [DEPENDS ...] @@ -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 `_. -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 `_. + 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 ...`` - Specifies Java classes used to generate headers. +``CLASSES ...`` + Specifies Java classes used to generate headers. - ``CLASSPATH ...`` - Specifies various paths to look up classes. Here .class files, jar files or targets - created by command add_jar can be used. +``CLASSPATH ...`` + Specifies various paths to look up classes. Here .class files, jar files or + targets created by command add_jar can be used. - ``DEPENDS ...`` - Targets on which the javah target depends +``DEPENDS ...`` + Targets on which the javah target depends. - ``OUTPUT_NAME `` - Concatenates the resulting header files for all the classes listed by option CLASSES - into . Same behavior as option '-o' of javah tool. +``OUTPUT_NAME `` + Concatenates the resulting header files for all the classes listed by option + ``CLASSES`` into ````. Same behavior as option ``-o`` of javah tool. - ``OUTPUT_DIR `` - 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 `` + 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)