diff options
Diffstat (limited to 'Modules/UseJava.cmake')
| -rw-r--r-- | Modules/UseJava.cmake | 856 |
1 files changed, 526 insertions, 330 deletions
diff --git a/Modules/UseJava.cmake b/Modules/UseJava.cmake index 120a54c84..ef63ac34b 100644 --- a/Modules/UseJava.cmake +++ b/Modules/UseJava.cmake @@ -5,413 +5,545 @@ UseJava ------- -Use Module for Java - -This file provides functions for Java. It is assumed that +This file provides support for ``Java``. It is assumed that :module:`FindJava` has already been loaded. See :module:`FindJava` for -information on how to load Java into your CMake project. +information on how to load Java into your ``CMake`` project. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Creating and Installing JARS`_ + `add_jar`_ (<target_name> [SOURCES] <source1> [<source2>...] ...) + `install_jar`_ (<target_name> DESTINATION <destination> [COMPONENT <component>]) + `install_jni_symlink`_ (<target_name> DESTINATION <destination> [COMPONENT <component>]) + + `Header Generation`_ + `create_javah`_ ((TARGET <target> | GENERATED_FILES <VAR>) CLASSES <class>... ...) + + `Exporting JAR Targets`_ + `install_jar_exports`_ (TARGETS <jars>... FILE <filename> DESTINATION <destination> ...) + `export_jars`_ (TARGETS <jars>... [NAMESPACE <namespace>] FILE <filename>) + + `Finding JARs`_ + `find_jar`_ (<VAR> NAMES <name1> [<name2>...] [PATHS <path1> [<path2>... ENV <var>]] ...) + + `Creating Java Documentation`_ + `create_javadoc`_ (<VAR> (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...]) ...) 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>|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). - -.. versionadded:: 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``. - -.. versionadded:: 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. - -.. versionadded:: 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``. - -.. versionadded:: 3.20 - The target generated by option ``GENERATE_NATIVE_HEADERS`` has the property - ``NATIVE_HEADERS_DIRECTORY`` which specify the directory holding the native - headers. - -.. code-block:: cmake - - 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 :command:`get_property` and the ``INSTALL_DESTINATION`` -property key. - -.. versionadded:: 3.4 - The second signature with ``DESTINATION`` and ``COMPONENT`` options. - -.. code-block:: cmake - - 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. - -.. versionadded:: 3.4 - The second signature with ``DESTINATION`` and ``COMPONENT`` options. +.. _add_jar: -Exporting JAR Targets -^^^^^^^^^^^^^^^^^^^^^ +.. command:: add_jar -.. versionadded:: 3.7 + Creates a jar file containing java objects and, optionally, resources:: -.. code-block:: cmake + add_jar(<target_name> + [SOURCES] <source1> [<source2>...] [<resource1>...] + [RESOURCES NAMESPACE <ns1> <resource1>... [NAMESPACE <nsX> <resourceX>...]... ] + [INCLUDE_JARS <jar1> [<jar2>...]] + [ENTRY_POINT <entry>] + [VERSION <version>] + [MANIFEST <manifest>] + [OUTPUT_NAME <name>] + [OUTPUT_DIR <dir>] + [GENERATE_NATIVE_HEADERS <target> + [DESTINATION (<dir>|INSTALL <dir> [BUILD <dir>])]] + ) - install_jar_exports(TARGETS <jars>... - [NAMESPACE <namespace>] - FILE <filename> - DESTINATION <destination> [COMPONENT <component>]) + 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. -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)`. + ``SOURCES`` + Compiles the specified source files and adds the result in the jar file. -.. versionadded:: 3.9 - The ``NAMESPACE`` option. + .. versionadded:: 3.4 + Support for response files, prefixed by ``@``. -.. code-block:: cmake + ``RESOURCES`` + .. versionadded:: 3.21 - export_jars(TARGETS <jars>... - [NAMESPACE <namespace>] - FILE <filename>) + Adds the named ``<resource>`` files to the jar by stripping the source file + path and placing the file beneath ``<ns>`` within the jar. -This command writes a target export file ``<filename>`` for the named ``<jars>`` -targets. Its function is similar to that of :command:`export`. + For example:: -.. versionadded:: 3.9 - The ``NAMESPACE`` option. + RESOURCES NAMESPACE "/com/my/namespace" "a/path/to/resource.txt" + results in a resource accessible via ``/com/my/namespace/resource.txt`` + within the jar. -Examples -"""""""" + Resources may be added without adjusting the namespace by adding them to + the list of ``SOURCES`` (original behavior), in this case, resource + paths must be relative to ``CMAKE_CURRENT_SOURCE_DIR``. Adding resources + without using the ``RESOURCES`` parameter in out of source builds will + almost certainly result in confusion. -To add compile flags to the target you can set these flags with the following -variable: + .. note:: -.. code-block:: cmake + Adding resources via the ``SOURCES`` parameter relies upon a hard-coded + list of file extensions which are tested to determine whether they + compile (e.g. File.java). ``SOURCES`` files which match the extensions + are compiled. Files which do not match are treated as resources. To + include uncompiled resources matching those file extensions use + the ``RESOURCES`` parameter. - set(CMAKE_JAVA_COMPILE_FLAGS -nowarn) + ``INCLUDE_JARS`` + The list of 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). + ``ENTRY_POINT`` + Defines an entry point in the jar file. -To add a path or a jar file to the class path you can do this with the -``CMAKE_JAVA_INCLUDE_PATH`` variable. + ``VERSION`` + Adds a version to the target output name. -.. code-block:: cmake + The following example will create a jar file with the name + ``shibboleet-1.2.0.jar`` and will create a symlink ``shibboleet.jar`` + pointing to the jar with the version information. - set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar) + .. code-block:: cmake -To use a different output name for the target you can set it with: + add_jar(shibboleet shibbotleet.java VERSION 1.2.0) -.. code-block:: cmake + ``MANIFEST`` + Defines a custom manifest for the jar. - add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar) + ``OUTPUT_NAME`` + Specify a different output name for the target. -To use a different output directory than ``CMAKE_CURRENT_BINARY_DIR`` you can -set it with: + ``OUTPUT_DIR`` + Sets the directory where the jar file will be generated. If not specified, + :variable:`CMAKE_CURRENT_BINARY_DIR` is used as the output directory. -.. code-block:: cmake + ``GENERATE_NATIVE_HEADERS`` + .. versionadded:: 3.11 - add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin) + Generates native header files 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. -To define an entry point in your jar you can set it with the ``ENTRY_POINT`` -named argument: + This option requires, at least, version 1.8 of the JDK. -.. code-block:: cmake + For an optimum usage of this option, 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. - add_jar(example ENTRY_POINT com/examples/MyProject/Main) + .. code-block:: cmake -To define a custom manifest for the jar, you can set it with the ``MANIFEST`` -named argument: + 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) -.. code-block:: cmake + .. versionadded:: 3.20 + ``DESTINATION`` sub-option now supports the possibility to specify + different output directories for ``BUILD`` and ``INSTALL`` steps. If + ``BUILD`` directory is not specified, a default directory will be used. - add_jar(example MANIFEST /path/to/manifest) + To export the interface target generated by ``GENERATE_NATIVE_HEADERS`` + option, sub-option ``INSTALL`` of ``DESTINATION`` is required: -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 -.. code-block:: cmake + 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) - add_jar(shibboleet shibbotleet.java VERSION 1.2.0) + Some variables can be set to customize the behavior of ``add_jar()`` as well + as the java compiler: -If the target is a JNI library, utilize the following commands to -create a JNI symbolic link: + ``CMAKE_JAVA_COMPILE_FLAGS`` + Specify additional flags to java compiler. -.. code-block:: cmake + ``CMAKE_JAVA_INCLUDE_PATH`` + Specify additional paths to the class path. - 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}) + ``CMAKE_JNI_TARGET`` + If the target is a JNI library, sets this boolean variable to ``TRUE`` to + enable creation of a JNI symbolic link (see also + :ref:`install_jni_symlink() <install_jni_symlink>`). -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: + ``CMAKE_JAR_CLASSES_PREFIX`` + If multiple jars should be produced from the same java source filetree, + to prevent the accumulation of duplicate class files in subsequent jars, + set/reset ``CMAKE_JAR_CLASSES_PREFIX`` prior to calling the ``add_jar()``: -.. code-block:: cmake + .. code-block:: cmake - set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo) - add_jar(foo foo.java) + 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) + 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. + The ``add_jar()`` function sets the following target properties on + ``<target_name>``: -.. code-block:: cmake + ``INSTALL_FILES`` + The files which should be installed. This is used by + :ref:`install_jar() <install_jar>`. + ``JNI_SYMLINK`` + The JNI symlink which should be installed. This is used by + :ref:`install_jni_symlink() <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``. + ``NATIVE_HEADERS_DIRECTORY`` + .. versionadded:: 3.20 - 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 directory where native headers are generated. Defined when option + ``GENERATE_NATIVE_HEADERS`` is specified. -.. versionadded:: 3.20 - It is now possible to export the target generated by - ``GENERATE_NATIVE_HEADERS`` option. +.. _install_jar: - .. code-block:: cmake +.. command:: install_jar - 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) + This command installs the jar file to the given destination:: -Finding JARs -^^^^^^^^^^^^ + install_jar(<target_name> <destination>) + install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>]) -.. code-block:: cmake - - 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. - -.. code-block:: cmake - - 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] - ) + This command installs the ``<target_name>`` file to the given + ``<destination>``. It should be called in the same scope as + :ref:`add_jar() <add_jar>` or it will fail. -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 -files. - -.. 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] - ) + .. versionadded:: 3.4 + The second signature with ``DESTINATION`` and ``COMPONENT`` options. + + ``DESTINATION`` + Specify the directory on disk to which a file will be installed. + + ``COMPONENT`` + Specify an installation component name with which the install rule is + associated, such as "runtime" or "development". + + The ``install_jar()`` command sets the following target properties + on ``<target_name>``: + + ``INSTALL_DESTINATION`` + Holds the ``<destination>`` as described above, and is used by + :ref:`install_jar_exports() <install_jar_exports>`. + +.. _install_jni_symlink: -For example: +.. command:: install_jni_symlink -.. code-block:: cmake + Installs JNI symlinks for target generated by :ref:`add_jar() <add_jar>`:: - 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 - ) + install_jni_symlink(<target_name> <destination>) + install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>]) -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``. + This command installs the ``<target_name>`` JNI symlinks to the given + ``<destination>``. It should be called in the same scope as + :ref:`add_jar() <add_jar>` or it will fail. -If you don't set the ``INSTALLPATH``, then by default the documentation will -be installed to : + .. versionadded:: 3.4 + The second signature with ``DESTINATION`` and ``COMPONENT`` options. -:: + ``DESTINATION`` + Specify the directory on disk to which a file will be installed. - ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR> + ``COMPONENT`` + Specify an installation component name with which the install rule is + associated, such as "runtime" or "development". + 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}) Header Generation ^^^^^^^^^^^^^^^^^ -.. code-block:: cmake +.. _create_javah: + +.. command:: create_javah + + .. versionadded:: 3.4 + + Generates C header files for java classes:: + + create_javah(TARGET <target> | GENERATED_FILES <VAR> + CLASSES <class>... + [CLASSPATH <classpath>...] + [DEPENDS <depend>...] + [OUTPUT_NAME <path>|OUTPUT_DIR <path>] + ) + + .. deprecated:: 3.11 + 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 :ref:`add_jar(GENERATE_NATIVE_HEADERS) <add_jar>` 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: + + .. 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. 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. + + ``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. + + ``OUTPUT_NAME`` + 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`` + 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. + +Exporting JAR Targets +^^^^^^^^^^^^^^^^^^^^^ + +.. _install_jar_exports: + +.. command:: install_jar_exports + + .. versionadded:: 3.7 + + Installs a target export file:: - create_javah(TARGET <target> | GENERATED_FILES <VAR> - CLASSES <class>... - [CLASSPATH <classpath>...] - [DEPENDS <depend>...] - [OUTPUT_NAME <path>|OUTPUT_DIR <path>] - ) + install_jar_exports(TARGETS <jars>... + [NAMESPACE <namespace>] + FILE <filename> + DESTINATION <destination> [COMPONENT <component>]) -.. versionadded:: 3.4 + 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(EXPORT)`. -.. deprecated:: 3.11 - 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. + ``TARGETS`` + List of targets created by :ref:`add_jar() <add_jar>` command. -Create C header files from java classes. These files provide the connective glue -that allow your Java and C code to interact. + ``NAMESPACE`` + .. versionadded:: 3.9 -There are two main signatures for ``create_javah()``. The first signature -returns generated files through variable specified by the ``GENERATED_FILES`` -option. For example: + The ``<namespace>`` value will be prepend to the target names as they are + written to the import file. -.. code-block:: cmake + ``FILE`` + Specify name of the export file. - 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. + ``DESTINATION`` + Specify the directory on disk to which a file will be installed. -.. code-block:: cmake + ``COMPONENT`` + Specify an installation component name with which the install rule is + associated, such as "runtime" or "development". - create_javah(TARGET target_headers - CLASSES org.cmake.HelloWorld - CLASSPATH hello.jar - ) +.. _export_jars: -Both signatures share same options. +.. command:: export_jars -``CLASSES <class>...`` - Specifies Java classes used to generate headers. + .. versionadded:: 3.7 -``CLASSPATH <classpath>...`` - Specifies various paths to look up classes. Here .class files, jar files or - targets created by command add_jar can be used. + Writes a target export file:: -``DEPENDS <depend>...`` - Targets on which the javah target depends. + export_jars(TARGETS <jars>... + [NAMESPACE <namespace>] + FILE <filename>) -``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. + This command writes a target export file ``<filename>`` for the named ``<jars>`` + targets. Its function is similar to that of :command:`export`. -``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. + ``TARGETS`` + List of targets created by :ref:`add_jar() <add_jar>` command. + + ``NAMESPACE`` + .. versionadded:: 3.9 + + The ``<namespace>`` value will be prepend to the target names as they are + written to the import file. + + ``FILE`` + Specify name of the export file. + +Finding JARs +^^^^^^^^^^^^ + +.. _find_jar: + +.. command:: find_jar + + Finds the specified jar file:: + + 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. + + ``NAMES`` + Specify one or more possible names for the jar file. + + ``PATHS`` + Specify directories to search in addition to the default locations. + The ``ENV`` var sub-option reads paths from a system environment variable. + + ``VERSIONS`` + Specify jar versions. + + ``DOC`` + Specify the documentation string for the ``<VAR>`` cache entry. + +Creating Java Documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _create_javadoc: + +.. command:: create_javadoc + + Creates java documentation based on files and packages:: + + create_javadoc(<VAR> + (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...]) + [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)] + ) + + The ``create_javadoc()`` command can be used to create java documentation. + 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 "<h1>My example</h1>" + AUTHOR TRUE + USE TRUE + VERSION TRUE + ) + + The second signature for ``create_javadoc()`` works on a given list of files: + + .. code-block:: cmake + + create_javadoc(my_example_doc + FILES java/A.java java/B.java + 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. For more details please read the + javadoc manpage. + + ``PACKAGES`` + Specify java packages. + + ``FILES`` + Specify java source files. If relative paths are specified, they are + relative to :variable:`CMAKE_CURRENT_SOURCE_DIR`. + + ``SOURCEPATH`` + Specify the directory where to look for packages. By default, + :variable:`CMAKE_CURRENT_SOURCE_DIR` directory is used. + + ``CLASSPATH`` + Specify where to find user class files. Same behavior as option + ``-classpath`` of ``javadoc`` tool. + + ``INSTALLPATH`` + Specify where to install the java documentation. If you specified, the + documentation will be installed to + ``${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>``. + + ``DOCTITLE`` + Specify the title to place near the top of the overview summary file. + Same behavior as option ``-doctitle`` of ``javadoc`` tool. + + ``WINDOWTITLE`` + Specify the title to be placed in the HTML ``<title>`` tag. Same behavior + as option ``-windowtitle`` of ``javadoc`` tool. + + ``AUTHOR`` + When value ``TRUE`` is specified, includes the ``@author`` text in the + generated docs. Same behavior as option ``-author`` of ``javadoc`` tool. + + ``USE`` + When value ``TRUE`` is specified, creates class and package usage pages. + Includes one Use page for each documented class and package. Same behavior + as option ``-use`` of ``javadoc`` tool. + + ``VERSION`` + When value ``TRUE`` is specified, includes the version text in the + generated docs. Same behavior as option ``-version`` of ``javadoc`` tool. #]=======================================================================] function (__java_copy_file src dest comment) @@ -449,6 +581,58 @@ function(__java_export_jar VAR TARGET PATH) set(${VAR} "${${VAR}}" PARENT_SCOPE) endfunction() +function(__java_copy_resource_namespaces VAR DEST JAVA_RESOURCE_FILES JAVA_RESOURCE_FILES_RELATIVE) + + set(_ns_ID "") + set(_ns_VAL "") + + foreach(_item IN LISTS VAR) + if(NOT _ns_ID) + if(NOT _item STREQUAL "NAMESPACE") + message(FATAL_ERROR "UseJava: Expecting \"NAMESPACE\", got\t\"${_item}\"") + return() + endif() + endif() + + if(_item STREQUAL "NAMESPACE") + set(_ns_VAL "") # Prepare for next namespace + set(_ns_ID "${_item}") + continue() + endif() + + if( NOT _ns_VAL) + # we're expecting the next token to be a namespace value + # whatever it is, we're treating it like a namespace + set(_ns_VAL "${_item}") + continue() + endif() + + if(_ns_ID AND _ns_VAL) + # We're expecting a file name, check to see if we got one + cmake_path(ABSOLUTE_PATH _item OUTPUT_VARIABLE _test_file_name) + if (NOT EXISTS "${_test_file_name}") + message(FATAL_ERROR "UseJava: File does not exist:\t${_item}") + return() + endif() + endif() + + cmake_path(ABSOLUTE_PATH _item OUTPUT_VARIABLE _abs_file_name) + cmake_path(GET _item FILENAME _resource_file_name) + set(_dest_resource_file_name "${_ns_VAL}/${_resource_file_name}" ) + + __java_copy_file( ${_abs_file_name} + ${DEST}/${_dest_resource_file_name} + "Copying ${_item} to the build directory") + + list(APPEND RESOURCE_FILES_LIST ${DEST}/${_dest_resource_file_name}) + list(APPEND RELATIVE_RESOURCE_FILES_LIST ${_dest_resource_file_name}) + + endforeach() + + set(${JAVA_RESOURCE_FILES} "${RESOURCE_FILES_LIST}" PARENT_SCOPE) + set(${JAVA_RESOURCE_FILES_RELATIVE} "${RELATIVE_RESOURCE_FILES_LIST}" PARENT_SCOPE) +endfunction() + # define helper scripts set(_JAVA_EXPORT_TARGETS_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/UseJava/javaTargets.cmake.in) set(_JAVA_SYMLINK_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/UseJava/Symlinks.cmake) @@ -461,12 +645,14 @@ endif() function(add_jar _TARGET_NAME) - cmake_parse_arguments(_add_jar - "" - "VERSION;OUTPUT_DIR;OUTPUT_NAME;ENTRY_POINT;MANIFEST" - "SOURCES;INCLUDE_JARS;GENERATE_NATIVE_HEADERS" - ${ARGN} - ) + set(options) # currently there are no zero value args (aka: options) + set(oneValueArgs "ENTRY_POINT;MANIFEST;OUTPUT_DIR;;OUTPUT_NAME;VERSION" ) + set(multiValueArgs "GENERATE_NATIVE_HEADERS;INCLUDE_JARS;RESOURCES;SOURCES" ) + + cmake_parse_arguments(PARSE_ARGV 1 _add_jar + "${options}" + "${oneValueArgs}" + "${multiValueArgs}" ) # In CMake < 2.8.12, add_jar used variables which were set prior to calling # add_jar for customizing the behavior of add_jar. In order to be backwards @@ -490,6 +676,9 @@ function(add_jar _TARGET_NAME) set(_add_jar_ENTRY_POINT "${CMAKE_JAVA_JAR_ENTRY_POINT}") endif() + # This *should* still work if <resources1>... are included without a + # named RESOURCES argument. In that case, the old behavior of potentially + # misplacing the within the Jar will behave as previously (incorrectly) set(_JAVA_SOURCE_FILES ${_add_jar_SOURCES} ${_add_jar_UNPARSED_ARGUMENTS}) if (NOT DEFINED _add_jar_OUTPUT_DIR) @@ -639,6 +828,13 @@ function(add_jar _TARGET_NAME) endif () endforeach() + if(_add_jar_RESOURCES) # Process RESOURCES if it exists + __java_copy_resource_namespaces("${_add_jar_RESOURCES}" + ${CMAKE_JAVA_CLASS_OUTPUT_PATH} + _JAVA_RESOURCE_FILES + _JAVA_RESOURCE_FILES_RELATIVE) + endif() + foreach(_JAVA_INCLUDE_JAR IN LISTS _add_jar_INCLUDE_JARS) if (TARGET ${_JAVA_INCLUDE_JAR}) get_target_property(_JAVA_JAR_PATH ${_JAVA_INCLUDE_JAR} JAR_FILE) |