Help: UseJava reorganization

Fixes: #22155

Modules/UseJava.cmake

@@ -5,442 +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>...]
-          [RESOURCES NAMESPACE <ns1> <resource1>... [NAMESPACE <nsX> <resourceX>...]... ]
-          [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.
-
-.. versionadded:: 3.21
-  The ``RESOURCES`` parameter adds the named ``<resource>`` files to the jar
-  by stripping the source file path and placing the file beneath ``<ns>``
-  within the jar.
-
-For example::
-
-  RESOURCES NAMESPACE "/com/my/namespace" "a/path/to/resource.txt"
-
-results in a resource accessible via ``/com/my/namespace/resource.txt``
-within the jar.
-
-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.
-
-.. note::
-
-  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.
-
-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
+.. _add_jar:
 
- 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.
+.. command:: add_jar
 
-.. versionadded:: 3.4
-  The second signature with ``DESTINATION`` and ``COMPONENT`` options.
+  Creates a jar file containing java objects and, optionally, resources::
 
-Exporting JAR Targets
-^^^^^^^^^^^^^^^^^^^^^
+    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>])]]
+            )
 
-.. versionadded:: 3.7
+  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.
 
-.. code-block:: cmake
+  ``SOURCES``
+    Compiles the specified source files and adds the result in the jar file.
 
- install_jar_exports(TARGETS <jars>...
-                     [NAMESPACE <namespace>]
-                     FILE <filename>
-                     DESTINATION <destination> [COMPONENT <component>])
+    .. versionadded:: 3.4
+      Support for response files, prefixed by ``@``.
 
-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)`.
+  ``RESOURCES``
+    .. versionadded:: 3.21
 
-.. versionadded:: 3.9
-  The ``NAMESPACE`` option.
+    Adds the named ``<resource>`` files to the jar by stripping the source file
+    path and placing the file beneath ``<ns>`` within the jar.
 
-.. code-block:: cmake
+    For example::
 
- export_jars(TARGETS <jars>...
-             [NAMESPACE <namespace>]
-             FILE <filename>)
+      RESOURCES NAMESPACE "/com/my/namespace" "a/path/to/resource.txt"
 
-This command writes a target export file ``<filename>`` for the named ``<jars>``
-targets.  Its function is similar to that of :command:`export`.
+    results in a resource accessible via ``/com/my/namespace/resource.txt``
+    within the jar.
 
-.. versionadded:: 3.9
-  The ``NAMESPACE`` option.
+    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.
 
+    .. note::
 
-Examples
-""""""""
+      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.
 
-To add compile flags to the target you can set these flags with the following
-variable:
+  ``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).
 
-.. code-block:: cmake
+  ``ENTRY_POINT``
+    Defines an entry point in the jar file.
 
-  set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
+  ``VERSION``
+    Adds a version to the target output name.
 
+    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.
 
-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
 
-.. code-block:: cmake
+      add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
 
-  set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
+  ``MANIFEST``
+    Defines a custom manifest for the jar.
 
-To use a different output name for the target you can set it with:
+  ``OUTPUT_NAME``
+    Specify a different output name for the target.
 
-.. code-block:: cmake
+  ``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.
 
-  add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
+  ``GENERATE_NATIVE_HEADERS``
+    .. versionadded:: 3.11
 
-To use a different output directory than ``CMAKE_CURRENT_BINARY_DIR`` you can
-set it with:
+    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.
 
-.. code-block:: cmake
+    This option requires, at least, version 1.8 of the JDK.
 
-  add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
+    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.
 
-To define an entry point in your jar you can set it with the ``ENTRY_POINT``
-named argument:
+    .. code-block:: cmake
 
-.. 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)
 
-  add_jar(example ENTRY_POINT com/examples/MyProject/Main)
+    .. 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.
 
-To define a custom manifest for the jar, you can set it with the ``MANIFEST``
-named argument:
+      To export the interface target generated by ``GENERATE_NATIVE_HEADERS``
+      option, sub-option ``INSTALL`` of ``DESTINATION`` is required:
 
-.. code-block:: cmake
+      .. code-block:: cmake
 
-  add_jar(example MANIFEST /path/to/manifest)
+        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)
 
-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.
+  Some variables can be set to customize the behavior of ``add_jar()`` as well
+  as the java compiler:
 
-.. code-block:: cmake
+  ``CMAKE_JAVA_COMPILE_FLAGS``
+    Specify additional flags to java compiler.
 
-  add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
+  ``CMAKE_JAVA_INCLUDE_PATH``
+    Specify additional paths to the class path.
 
-If the target is a JNI library, utilize the following commands to
-create a JNI symbolic link:
+  ``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>`).
 
-.. code-block:: cmake
+  ``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()``:
 
-  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})
+    .. code-block:: cmake
 
-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)
 
-.. code-block:: cmake
+      set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
+      add_jar(bar bar.java)
 
-  set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
-  add_jar(foo foo.java)
+  The ``add_jar()`` function sets the following target properties on
+  ``<target_name>``:
 
-  set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
-  add_jar(bar bar.java)
+  ``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
 
-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 directory where native headers are generated. Defined when option
+    ``GENERATE_NATIVE_HEADERS`` is specified.
 
-.. code-block:: cmake
+.. _install_jar:
 
-  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)
+.. command:: install_jar
 
-.. versionadded:: 3.20
-  It is now possible to export the target generated by
-  ``GENERATE_NATIVE_HEADERS`` option.
+  This command installs the jar file to the given destination::
 
-  .. code-block:: cmake
+   install_jar(<target_name> <destination>)
+   install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])
 
-    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 ``<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.
 
-Finding JARs
-^^^^^^^^^^^^
+  .. versionadded:: 3.4
+    The second signature with ``DESTINATION`` and ``COMPONENT`` options.
 
-.. 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]
-                )
+  ``DESTINATION``
+    Specify the directory on disk to which a file will be installed.
 
-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]
-                )
+  ``COMPONENT``
+    Specify an installation component name with which the install rule is
+    associated, such as "runtime" or "development".
 
-For example:
+  The ``install_jar()`` command sets the following target properties
+  on ``<target_name>``:
 
-.. code-block:: cmake
+  ``INSTALL_DESTINATION``
+    Holds the ``<destination>`` as described above, and is used by
+    :ref:`install_jar_exports() <install_jar_exports>`.
 
-  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:
 
-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``.
+.. command:: install_jni_symlink
 
-If you don't set the ``INSTALLPATH``, then by default the documentation will
-be installed to :
+  Installs JNI symlinks for target generated by :ref:`add_jar() <add_jar>`::
 
-::
+   install_jni_symlink(<target_name> <destination>)
+   install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])
 
-   ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
+  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.
 
+  .. 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".
+
+  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.
 
- create_javah(TARGET <target> | GENERATED_FILES <VAR>
-              CLASSES <class>...
-              [CLASSPATH <classpath>...]
-              [DEPENDS <depend>...]
-              [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
-              )
+  ``CLASSPATH``
+    Specifies various paths to look up classes. Here ``.class`` files, jar
+    files or targets created by command add_jar can be used.
 
-.. versionadded:: 3.4
+  ``DEPENDS``
+    Targets on which the javah target depends.
 
-.. 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.
+  ``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.
 
-Create C header files from java classes. These files provide the connective glue
-that allow your Java and C code to interact.
+  ``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.
 
-There are two main signatures for ``create_javah()``.  The first signature
-returns generated files through variable specified by the ``GENERATED_FILES``
-option.  For example:
+Exporting JAR Targets
+^^^^^^^^^^^^^^^^^^^^^
+
+.. _install_jar_exports:
+
+.. command:: install_jar_exports
+
+  .. versionadded:: 3.7
+
+  Installs a target export file::
+
+   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 :command:`install(EXPORT)`.
+
+  ``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.
 
-.. 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
+
+  Writes a target export file::
+
+   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`.
+
+  ``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
+^^^^^^^^^^^^
 
-``CLASSPATH <classpath>...``
-  Specifies various paths to look up classes. Here .class files, jar files or
-  targets created by command add_jar can be used.
+.. _find_jar:
 
-``DEPENDS <depend>...``
-  Targets on which the javah target depends.
+.. command:: find_jar
 
-``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.
+  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
 
-``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.
+    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)