mirror of
https://github.com/apache/ant.git
synced 2025-05-17 21:45:12 +00:00
362f5f0c59
* Ant 1.10 requires jdk 8 doc update * Updated the manual to reflect ant requires JDK 8 +
244 lines
9.0 KiB
HTML
244 lines
9.0 KiB
HTML
<!DOCTYPE html>
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
https://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
|
<title>Javah Task</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h2 id="javah">Javah</h2>
|
|
<h3>Description</h3>
|
|
<p>Generates JNI headers from a Java class.</p>
|
|
<p>When this task executes, it will generate the C header and source files that are needed to
|
|
implement native methods.
|
|
|
|
<p>If you are building with Java 8 or above consider
|
|
using <a href="javac.html"><code>javac</code></a>'s <var>nativeheaderdir</var> attribute instead
|
|
which allows you to compile the classes and generate the native header files in a single step.</p>
|
|
|
|
<p><strong>Note</strong>: <code>javah</code> has been deprecated in Java 9 and removed in Java
|
|
10. Attempts to use it with Java 10 will fail.</p>
|
|
|
|
<p id="implementationvalues">It is possible to use different compilers. This can be selected with
|
|
the <var>implementation</var> attribute or a nested element. Here are the choices of the
|
|
attribute:</p>
|
|
<ul>
|
|
<li><q>default</q>—the default compiler for the platform.</li>
|
|
<li><q>sun</q>—the standard compiler of the JDK.</li>
|
|
<li><q>kaffeh</q>—the native standard compiler of <a href="https://github.com/kaffe/kaffe"
|
|
target="_top">Kaffe</a>.</li>
|
|
<li><q>gcjh</q>—the native standard compiler
|
|
of <a href="https://gcc.gnu.org/gcc-7/changes.html#java" target="_top">gcj and
|
|
gij</a>. <em>Since Apache Ant 1.8.2</em></li>
|
|
<li><q>forking</q>—runs the <kbd>javah</kbd> executable via its command line interface in
|
|
a separate process. Default when not running on Kaffe or gcj/gij <em>since Ant 1.9.8</em></li>
|
|
</ul>
|
|
|
|
<p><strong>Note</strong>: if you are using this task to work on multiple files the command line may
|
|
become too long on some operating systems. Unfortunately the <kbd>javah</kbd> command doesn't
|
|
support command argument files the way <kbd>javac</kbd> (for example) does, so all that can be
|
|
done is breaking the amount of classes to compile into smaller chunks.</p>
|
|
|
|
<h3>Parameters</h3>
|
|
<table class="attr">
|
|
<tr>
|
|
<th scope="col">Attribute</th>
|
|
<th scope="col">Description</th>
|
|
<th scope="col">Required</th>
|
|
</tr>
|
|
<tr>
|
|
<td>class</td>
|
|
<td>the fully-qualified name of the class (or classes, separated by commas)</td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>outputFile</td>
|
|
<td>concatenates the resulting header or source files for all the classes listed into this
|
|
file</td>
|
|
<td rowspan="2">Exactly one of the two</td>
|
|
</tr>
|
|
<tr>
|
|
<td>destdir</td>
|
|
<td class="left">sets the directory where <kbd>javah</kbd> saves the header files or the stub
|
|
files.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>force</td>
|
|
<td>specifies that output files should always be written
|
|
(only when using an external javah of JDK 1.2)</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>old</td>
|
|
<td>specifies that old JDK 1.0-style header files should be generated (otherwise output file
|
|
contain JNI-style native method function prototypes)
|
|
(only when using an external javah of JDK 1.2)</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>stubs</td>
|
|
<td>generate C declarations from the Java object file (used with <var>old</var>)</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>verbose</td>
|
|
<td>causes <kbd>javah</kbd> to print a message concerning the status of the generated files</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>classpath</td>
|
|
<td>the classpath to use</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>bootclasspath</td>
|
|
<td>location of bootstrap class files</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>extdirs</td>
|
|
<td>location of installed extensions</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>implementation</td>
|
|
<td>The compiler implementation to use. (See the above <a href="#implementationvalues">list</a>
|
|
of valid compilers.)</td>
|
|
<td>No; defaults to default compiler for the current JDK</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>Parameters specified as nested elements</h3>
|
|
|
|
<h4>arg</h4>
|
|
|
|
<p>You can specify additional command line arguments for the compiler with
|
|
nested <code><arg></code> elements. These elements are specified
|
|
like <a href="../using.html#arg">Command-line Arguments</a> but have an additional attribute that
|
|
can be used to enable arguments only if a given compiler implementation will be used.</p>
|
|
|
|
<table class="attr">
|
|
<tr>
|
|
<th scope="col">Attribute</th>
|
|
<th scope="col">Description</th>
|
|
<th scope="col">Required</th>
|
|
</tr>
|
|
<tr>
|
|
<td>value</td>
|
|
<td rowspan="4">See <a href="../using.html#arg">Command-line Arguments</a>.</td>
|
|
<td rowspan="4">Exactly one of these</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="var">line</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="var">file</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="var">path</td>
|
|
</tr>
|
|
<tr>
|
|
<td>prefix</td>
|
|
<td rowspan="2">See <a href="../using.html#arg">Command-line Arguments</a>. <em>Since Ant
|
|
1.8</em>.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>suffix</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>implementation</td>
|
|
<td>Only pass the specified argument if the chosen compiler implementation matches the value of
|
|
this attribute. Legal values are the same as those in the
|
|
above <a href="#implementationvalues">list</a> of valid compilers.)</td>
|
|
<td>No</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>implementationclasspath</h4>
|
|
<p><em>Since Ant 1.8.0</em></p>
|
|
<p>A <a href="../using.html#path">path-like structure</a> holding the classpath to use when loading
|
|
the compiler implementation if a custom class has been specified. Doesn't have any effect when
|
|
using one of the built-in compilers.</p>
|
|
|
|
<h4>Any nested element of a type that implements JavahAdapter</h4>
|
|
<p><em>Since Ant 1.8.0</em></p>
|
|
<p>If a defined type implements the <code class="code">JavahAdapter</code> interface a nested
|
|
element of that type can be used as an alternative to the <var>implementation</var> attribute.</p>
|
|
|
|
<h3>Examples</h3>
|
|
<p>Make a JNI header of the named class, using the JDK 1.2 JNI model. Assuming the
|
|
directory <samp>c</samp> already exists, the file <samp>org_foo_bar_Wibble.h</samp> is created
|
|
there. If this file already exists, it is left unchanged.</p>
|
|
<pre><javah destdir="c" class="org.foo.bar.Wibble"/></pre>
|
|
|
|
<p>This is similar to the previous example, except the output is written to a file
|
|
called <samp>wibble.h</samp> in the current directory.</p>
|
|
<pre>
|
|
<javah outputFile="wibble.h">
|
|
<class name="org.foo.bar.Wibble,org.foo.bar.Bobble"/>
|
|
</javah></pre>
|
|
|
|
<p>Write three header files, one for each of the classes named. Because the <var>force</var> option
|
|
is set, these header files are always written when the <code>Javah</code> task is invoked, even if
|
|
they already exist.</p>
|
|
<pre>
|
|
<javah destdir="c" force="yes">
|
|
<class name="org.foo.bar.Wibble"/>
|
|
<class name="org.foo.bar.Bobble"/>
|
|
<class name="org.foo.bar.Tribble"/>
|
|
</javah></pre>
|
|
|
|
<p>Write the headers for the three classes using the 'old' JNI format, then write the
|
|
corresponding <samp>.c</samp> stubs. The <var>verbose</var> option will cause <code>Javah</code> to
|
|
describe its progress.</p>
|
|
<pre>
|
|
<javah destdir="c" verbose="yes" old="yes" force="yes">
|
|
<class name="org.foo.bar.Wibble"/>
|
|
<class name="org.foo.bar.Bobble"/>
|
|
<class name="org.foo.bar.Tribble"/>
|
|
</javah>
|
|
<javah destdir="c" verbose="yes" stubs="yes" old="yes" force="yes">
|
|
<class name="org.foo.bar.Wibble"/>
|
|
<class name="org.foo.bar.Bobble"/>
|
|
<class name="org.foo.bar.Tribble"/>
|
|
</javah></pre>
|
|
|
|
<p>If you want to use a
|
|
custom <code class="code">JavahAdapter</code> <code>org.example.MyAdapter</code> you can either use
|
|
the <var>implementation</var> attribute:</p>
|
|
<pre>
|
|
<javah destdir="c" class="org.foo.bar.Wibble"
|
|
implementation="org.example.MyAdapter"/></pre>
|
|
<p>or a define a type and nest this into the task like in:</p>
|
|
<pre>
|
|
<componentdef classname="org.example.MyAdapter"
|
|
name="myadapter"/>
|
|
<javah destdir="c" class="org.foo.bar.Wibble">
|
|
<myadapter/>
|
|
</javah></pre>
|
|
<p>in which case your <code>javah</code> adapter can support attributes and nested elements of its
|
|
own.</p>
|
|
|
|
</body>
|
|
</html>
|