mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-06 05:40:54 -06:00
Merge topic 'Help-UseJava-reorganization' into release-3.21
af9bd6c53f Help: UseJava reorganization
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6262This commit is contained in:
Brad King
@@ -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.
|
||||
.. _add_jar:
|
||||
|
||||
The default ``OUTPUT_DIR`` can also be changed by setting the variable
|
||||
``CMAKE_JAVA_TARGET_OUTPUT_DIR``.
|
||||
.. command:: add_jar
|
||||
|
||||
.. 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.
|
||||
Creates a jar file containing java objects and, optionally, resources::
|
||||
|
||||
``GENERATE_NATIVE_HEADERS`` option requires, at least, version 1.8 of the JDK.
|
||||
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.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.
|
||||
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 ``add_jar()`` function sets the following target properties on
|
||||
``<target_name>``:
|
||||
``SOURCES``
|
||||
Compiles the specified source files and adds the result in the jar file.
|
||||
|
||||
``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.4
|
||||
Support for response files, prefixed by ``@``.
|
||||
|
||||
.. 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.
|
||||
``RESOURCES``
|
||||
.. versionadded:: 3.21
|
||||
|
||||
.. code-block:: cmake
|
||||
Adds the named ``<resource>`` files to the jar by stripping the source file
|
||||
path and placing the file beneath ``<ns>`` within the jar.
|
||||
|
||||
install_jar(<target_name> <destination>)
|
||||
install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])
|
||||
For example::
|
||||
|
||||
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.
|
||||
RESOURCES NAMESPACE "/com/my/namespace" "a/path/to/resource.txt"
|
||||
|
||||
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.
|
||||
results in a resource accessible via ``/com/my/namespace/resource.txt``
|
||||
within the jar.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
The second signature with ``DESTINATION`` and ``COMPONENT`` options.
|
||||
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.
|
||||
|
||||
.. code-block:: cmake
|
||||
.. note::
|
||||
|
||||
install_jni_symlink(<target_name> <destination>)
|
||||
install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])
|
||||
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.
|
||||
|
||||
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.
|
||||
``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).
|
||||
|
||||
.. versionadded:: 3.4
|
||||
The second signature with ``DESTINATION`` and ``COMPONENT`` options.
|
||||
``ENTRY_POINT``
|
||||
Defines an entry point in the jar file.
|
||||
|
||||
Exporting JAR Targets
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
``VERSION``
|
||||
Adds a version to the target output name.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
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.
|
||||
|
||||
.. code-block:: cmake
|
||||
.. code-block:: cmake
|
||||
|
||||
install_jar_exports(TARGETS <jars>...
|
||||
[NAMESPACE <namespace>]
|
||||
FILE <filename>
|
||||
DESTINATION <destination> [COMPONENT <component>])
|
||||
add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
|
||||
|
||||
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)`.
|
||||
``MANIFEST``
|
||||
Defines a custom manifest for the jar.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
The ``NAMESPACE`` option.
|
||||
``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.
|
||||
|
||||
export_jars(TARGETS <jars>...
|
||||
[NAMESPACE <namespace>]
|
||||
FILE <filename>)
|
||||
``GENERATE_NATIVE_HEADERS``
|
||||
.. versionadded:: 3.11
|
||||
|
||||
This command writes a target export file ``<filename>`` for the named ``<jars>``
|
||||
targets. Its function is similar to that of :command:`export`.
|
||||
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.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
The ``NAMESPACE`` option.
|
||||
This option requires, at least, version 1.8 of the JDK.
|
||||
|
||||
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.
|
||||
|
||||
Examples
|
||||
""""""""
|
||||
.. code-block:: cmake
|
||||
|
||||
To add compile flags to the target you can set these flags with the following
|
||||
variable:
|
||||
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.
|
||||
|
||||
set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
|
||||
To export the interface target generated by ``GENERATE_NATIVE_HEADERS``
|
||||
option, sub-option ``INSTALL`` of ``DESTINATION`` is required:
|
||||
|
||||
.. 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.
|
||||
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)
|
||||
|
||||
.. code-block:: cmake
|
||||
Some variables can be set to customize the behavior of ``add_jar()`` as well
|
||||
as the java compiler:
|
||||
|
||||
set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
|
||||
``CMAKE_JAVA_COMPILE_FLAGS``
|
||||
Specify additional flags to java compiler.
|
||||
|
||||
To use a different output name for the target you can set it with:
|
||||
``CMAKE_JAVA_INCLUDE_PATH``
|
||||
Specify additional paths to the class path.
|
||||
|
||||
.. code-block:: cmake
|
||||
``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>`).
|
||||
|
||||
add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
|
||||
``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()``:
|
||||
|
||||
To use a different output directory than ``CMAKE_CURRENT_BINARY_DIR`` you can
|
||||
set it with:
|
||||
.. code-block:: cmake
|
||||
|
||||
.. code-block:: cmake
|
||||
set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
|
||||
add_jar(foo foo.java)
|
||||
|
||||
add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
|
||||
set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
|
||||
add_jar(bar bar.java)
|
||||
|
||||
To define an entry point in your jar you can set it with the ``ENTRY_POINT``
|
||||
named argument:
|
||||
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
|
||||
|
||||
add_jar(example ENTRY_POINT com/examples/MyProject/Main)
|
||||
The directory where native headers are generated. Defined when option
|
||||
``GENERATE_NATIVE_HEADERS`` is specified.
|
||||
|
||||
To define a custom manifest for the jar, you can set it with the ``MANIFEST``
|
||||
named argument:
|
||||
.. _install_jar:
|
||||
|
||||
.. code-block:: cmake
|
||||
.. command:: install_jar
|
||||
|
||||
add_jar(example MANIFEST /path/to/manifest)
|
||||
This command installs the jar file to the given destination::
|
||||
|
||||
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.
|
||||
install_jar(<target_name> <destination>)
|
||||
install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])
|
||||
|
||||
.. code-block:: cmake
|
||||
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.
|
||||
|
||||
add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
|
||||
.. versionadded:: 3.4
|
||||
The second signature with ``DESTINATION`` and ``COMPONENT`` options.
|
||||
|
||||
If the target is a JNI library, utilize the following commands to
|
||||
create a JNI symbolic link:
|
||||
``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".
|
||||
|
||||
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})
|
||||
The ``install_jar()`` command sets the following target properties
|
||||
on ``<target_name>``:
|
||||
|
||||
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:
|
||||
``INSTALL_DESTINATION``
|
||||
Holds the ``<destination>`` as described above, and is used by
|
||||
:ref:`install_jar_exports() <install_jar_exports>`.
|
||||
|
||||
.. code-block:: cmake
|
||||
.. _install_jni_symlink:
|
||||
|
||||
set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
|
||||
add_jar(foo foo.java)
|
||||
.. command:: install_jni_symlink
|
||||
|
||||
set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
|
||||
add_jar(bar bar.java)
|
||||
Installs JNI symlinks for target generated by :ref:`add_jar() <add_jar>`::
|
||||
|
||||
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.
|
||||
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
|
||||
:ref:`add_jar() <add_jar>` or it will fail.
|
||||
|
||||
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)
|
||||
.. versionadded:: 3.4
|
||||
The second signature with ``DESTINATION`` and ``COMPONENT`` options.
|
||||
|
||||
.. versionadded:: 3.20
|
||||
It is now possible to export the target generated by
|
||||
``GENERATE_NATIVE_HEADERS`` option.
|
||||
``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
|
||||
|
||||
add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native
|
||||
DESTINATION INSTALL include)
|
||||
install(TARGETS foo-native EXPORT native)
|
||||
install(DIRECTORY "$<TARGET_PROPERTY:foo-native,NATIVE_HEADERS_DIRECTORY>/"
|
||||
DESTINATION include)
|
||||
install(EXPORT native DESTINATION /to/export NAMESPACE foo)
|
||||
|
||||
Finding JARs
|
||||
^^^^^^^^^^^^
|
||||
|
||||
.. 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]
|
||||
)
|
||||
|
||||
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]
|
||||
)
|
||||
|
||||
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``.
|
||||
|
||||
If you don't set the ``INSTALLPATH``, then by default the documentation will
|
||||
be installed to :
|
||||
|
||||
::
|
||||
|
||||
${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
|
||||
|
||||
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:
|
||||
|
||||
create_javah(TARGET <target> | GENERATED_FILES <VAR>
|
||||
CLASSES <class>...
|
||||
[CLASSPATH <classpath>...]
|
||||
[DEPENDS <depend>...]
|
||||
[OUTPUT_NAME <path>|OUTPUT_DIR <path>]
|
||||
)
|
||||
.. command:: create_javah
|
||||
|
||||
.. versionadded:: 3.4
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. 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.
|
||||
Generates C header files for java classes::
|
||||
|
||||
Create C header files from java classes. These files provide the connective glue
|
||||
that allow your Java and C code to interact.
|
||||
create_javah(TARGET <target> | GENERATED_FILES <VAR>
|
||||
CLASSES <class>...
|
||||
[CLASSPATH <classpath>...]
|
||||
[DEPENDS <depend>...]
|
||||
[OUTPUT_NAME <path>|OUTPUT_DIR <path>]
|
||||
)
|
||||
|
||||
There are two main signatures for ``create_javah()``. The first signature
|
||||
returns generated files through variable specified by the ``GENERATED_FILES``
|
||||
option. For example:
|
||||
.. 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.
|
||||
|
||||
.. code-block:: cmake
|
||||
Create C header files from java classes. These files provide the connective
|
||||
glue that allow your Java and C code to interact.
|
||||
|
||||
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:
|
||||
|
||||
The second signature for ``create_javah()`` creates a target which encapsulates
|
||||
header files generation. E.g.
|
||||
.. code-block:: cmake
|
||||
|
||||
.. code-block:: cmake
|
||||
create_javah(GENERATED_FILES files_headers
|
||||
CLASSES org.cmake.HelloWorld
|
||||
CLASSPATH hello.jar
|
||||
)
|
||||
|
||||
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.
|
||||
|
||||
Both signatures share same options.
|
||||
.. code-block:: cmake
|
||||
|
||||
``CLASSES <class>...``
|
||||
Specifies Java classes used to generate headers.
|
||||
create_javah(TARGET target_headers
|
||||
CLASSES org.cmake.HelloWorld
|
||||
CLASSPATH hello.jar
|
||||
)
|
||||
|
||||
``CLASSPATH <classpath>...``
|
||||
Specifies various paths to look up classes. Here .class files, jar files or
|
||||
targets created by command add_jar can be used.
|
||||
Both signatures share same options.
|
||||
|
||||
``DEPENDS <depend>...``
|
||||
Targets on which the javah target depends.
|
||||
``CLASSES``
|
||||
Specifies Java classes used to generate headers.
|
||||
|
||||
``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.
|
||||
``CLASSPATH``
|
||||
Specifies various paths to look up classes. Here ``.class`` files, jar
|
||||
files or targets created by command add_jar can be used.
|
||||
|
||||
``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.
|
||||
``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::
|
||||
|
||||
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.
|
||||
|
||||
``FILE``
|
||||
Specify name of the export file.
|
||||
|
||||
|
||||
``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".
|
||||
|
||||
.. _export_jars:
|
||||
|
||||
.. command:: export_jars
|
||||
|
||||
.. 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
|
||||
^^^^^^^^^^^^
|
||||
|
||||
.. _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)
|
||||
|
||||
Reference in New Issue
Block a user