| 1 |
<!DOCTYPE html> |
| 2 |
<!-- |
| 3 |
Licensed to the Apache Software Foundation (ASF) under one or more |
| 4 |
contributor license agreements. See the NOTICE file distributed with |
| 5 |
this work for additional information regarding copyright ownership. |
| 6 |
The ASF licenses this file to You under the Apache License, Version 2.0 |
| 7 |
(the "License"); you may not use this file except in compliance with |
| 8 |
the License. You may obtain a copy of the License at |
| 9 |
|
| 10 |
https://www.apache.org/licenses/LICENSE-2.0 |
| 11 |
|
| 12 |
Unless required by applicable law or agreed to in writing, software |
| 13 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 14 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 15 |
See the License for the specific language governing permissions and |
| 16 |
limitations under the License. |
| 17 |
--> |
| 18 |
<html lang="en"> |
| 19 |
|
| 20 |
<head> |
| 21 |
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| 22 |
<title>Javah Task</title> |
| 23 |
</head> |
| 24 |
|
| 25 |
<body> |
| 26 |
|
| 27 |
<h2 id="javah">Javah</h2> |
| 28 |
<h3>Description</h3> |
| 29 |
<p>Generates JNI headers from a Java class.</p> |
| 30 |
<p>When this task executes, it will generate the C header and source files that are needed to |
| 31 |
implement native methods. |
| 32 |
|
| 33 |
<p>If you are building with Java 8 or above consider |
| 34 |
using <a href="javac.html"><code>javac</code></a>'s <var>nativeheaderdir</var> attribute instead |
| 35 |
which allows you to compile the classes and generate the native header files in a single step.</p> |
| 36 |
|
| 37 |
<p><strong>Note</strong>: <code>javah</code> has been deprecated in Java 9 and removed in Java |
| 38 |
10. Attempts to use it with Java 10 will fail.</p> |
| 39 |
|
| 40 |
<p id="implementationvalues">It is possible to use different compilers. This can be selected with |
| 41 |
the <var>implementation</var> attribute or a nested element. Here are the choices of the |
| 42 |
attribute:</p> |
| 43 |
<ul> |
| 44 |
<li><q>default</q>—the default compiler for the platform.</li> |
| 45 |
<li><q>sun</q>—the standard compiler of the JDK.</li> |
| 46 |
<li><q>kaffeh</q>—the native standard compiler of <a href="https://github.com/kaffe/kaffe" |
| 47 |
target="_top">Kaffe</a>.</li> |
| 48 |
<li><q>gcjh</q>—the native standard compiler |
| 49 |
of <a href="https://gcc.gnu.org/gcc-7/changes.html#java" target="_top">gcj and |
| 50 |
gij</a>. <em>Since Apache Ant 1.8.2</em></li> |
| 51 |
<li><q>forking</q>—runs the <kbd>javah</kbd> executable via its command line interface in |
| 52 |
a separate process. Default when not running on Kaffe or gcj/gij <em>since Ant 1.9.8</em></li> |
| 53 |
</ul> |
| 54 |
|
| 55 |
<p><strong>Note</strong>: if you are using this task to work on multiple files the command line may |
| 56 |
become too long on some operating systems. Unfortunately the <kbd>javah</kbd> command doesn't |
| 57 |
support command argument files the way <kbd>javac</kbd> (for example) does, so all that can be |
| 58 |
done is breaking the amount of classes to compile into smaller chunks.</p> |
| 59 |
|
| 60 |
<h3>Parameters</h3> |
| 61 |
<table class="attr"> |
| 62 |
<tr> |
| 63 |
<th scope="col">Attribute</th> |
| 64 |
<th scope="col">Description</th> |
| 65 |
<th scope="col">Required</th> |
| 66 |
</tr> |
| 67 |
<tr> |
| 68 |
<td>class</td> |
| 69 |
<td>the fully-qualified name of the class (or classes, separated by commas)</td> |
| 70 |
<td>Yes</td> |
| 71 |
</tr> |
| 72 |
<tr> |
| 73 |
<td>outputFile</td> |
| 74 |
<td>concatenates the resulting header or source files for all the classes listed into this |
| 75 |
file</td> |
| 76 |
<td rowspan="2">Exactly one of the two</td> |
| 77 |
</tr> |
| 78 |
<tr> |
| 79 |
<td>destdir</td> |
| 80 |
<td class="left">sets the directory where <kbd>javah</kbd> saves the header files or the stub |
| 81 |
files.</td> |
| 82 |
</tr> |
| 83 |
<tr> |
| 84 |
<td>force</td> |
| 85 |
<td>specifies that output files should always be written |
| 86 |
(only when using an external javah of JDK 1.2)</td> |
| 87 |
<td>No</td> |
| 88 |
</tr> |
| 89 |
<tr> |
| 90 |
<td>old</td> |
| 91 |
<td>specifies that old JDK 1.0-style header files should be generated (otherwise output file |
| 92 |
contain JNI-style native method function prototypes) |
| 93 |
(only when using an external javah of JDK 1.2)</td> |
| 94 |
<td>No</td> |
| 95 |
</tr> |
| 96 |
<tr> |
| 97 |
<td>stubs</td> |
| 98 |
<td>generate C declarations from the Java object file (used with <var>old</var>)</td> |
| 99 |
<td>No</td> |
| 100 |
</tr> |
| 101 |
<tr> |
| 102 |
<td>verbose</td> |
| 103 |
<td>causes <kbd>javah</kbd> to print a message concerning the status of the generated files</td> |
| 104 |
<td>No</td> |
| 105 |
</tr> |
| 106 |
<tr> |
| 107 |
<td>classpath</td> |
| 108 |
<td>the classpath to use</td> |
| 109 |
<td>No</td> |
| 110 |
</tr> |
| 111 |
<tr> |
| 112 |
<td>bootclasspath</td> |
| 113 |
<td>location of bootstrap class files</td> |
| 114 |
<td>No</td> |
| 115 |
</tr> |
| 116 |
<tr> |
| 117 |
<td>extdirs</td> |
| 118 |
<td>location of installed extensions</td> |
| 119 |
<td>No</td> |
| 120 |
</tr> |
| 121 |
<tr> |
| 122 |
<td>implementation</td> |
| 123 |
<td>The compiler implementation to use. (See the above <a href="#implementationvalues">list</a> |
| 124 |
of valid compilers.)</td> |
| 125 |
<td>No; defaults to default compiler for the current JDK</td> |
| 126 |
</tr> |
| 127 |
</table> |
| 128 |
|
| 129 |
<h3>Parameters specified as nested elements</h3> |
| 130 |
|
| 131 |
<h4>arg</h4> |
| 132 |
|
| 133 |
<p>You can specify additional command line arguments for the compiler with |
| 134 |
nested <code><arg></code> elements. These elements are specified |
| 135 |
like <a href="../using.html#arg">Command-line Arguments</a> but have an additional attribute that |
| 136 |
can be used to enable arguments only if a given compiler implementation will be used.</p> |
| 137 |
|
| 138 |
<table class="attr"> |
| 139 |
<tr> |
| 140 |
<th scope="col">Attribute</th> |
| 141 |
<th scope="col">Description</th> |
| 142 |
<th scope="col">Required</th> |
| 143 |
</tr> |
| 144 |
<tr> |
| 145 |
<td>value</td> |
| 146 |
<td rowspan="4">See <a href="../using.html#arg">Command-line Arguments</a>.</td> |
| 147 |
<td rowspan="4">Exactly one of these</td> |
| 148 |
</tr> |
| 149 |
<tr> |
| 150 |
<td class="var">line</td> |
| 151 |
</tr> |
| 152 |
<tr> |
| 153 |
<td class="var">file</td> |
| 154 |
</tr> |
| 155 |
<tr> |
| 156 |
<td class="var">path</td> |
| 157 |
</tr> |
| 158 |
<tr> |
| 159 |
<td>prefix</td> |
| 160 |
<td rowspan="2">See <a href="../using.html#arg">Command-line Arguments</a>. <em>Since Ant |
| 161 |
1.8</em>.</td> |
| 162 |
<td>No</td> |
| 163 |
</tr> |
| 164 |
<tr> |
| 165 |
<td>suffix</td> |
| 166 |
<td>No</td> |
| 167 |
</tr> |
| 168 |
<tr> |
| 169 |
<td>implementation</td> |
| 170 |
<td>Only pass the specified argument if the chosen compiler implementation matches the value of |
| 171 |
this attribute. Legal values are the same as those in the |
| 172 |
above <a href="#implementationvalues">list</a> of valid compilers.)</td> |
| 173 |
<td>No</td> |
| 174 |
</tr> |
| 175 |
</table> |
| 176 |
|
| 177 |
<h4>implementationclasspath</h4> |
| 178 |
<p><em>Since Ant 1.8.0</em></p> |
| 179 |
<p>A <a href="../using.html#path">path-like structure</a> holding the classpath to use when loading |
| 180 |
the compiler implementation if a custom class has been specified. Doesn't have any effect when |
| 181 |
using one of the built-in compilers.</p> |
| 182 |
|
| 183 |
<h4>Any nested element of a type that implements JavahAdapter</h4> |
| 184 |
<p><em>Since Ant 1.8.0</em></p> |
| 185 |
<p>If a defined type implements the <code class="code">JavahAdapter</code> interface a nested |
| 186 |
element of that type can be used as an alternative to the <var>implementation</var> attribute.</p> |
| 187 |
|
| 188 |
<h3>Examples</h3> |
| 189 |
<p>Make a JNI header of the named class, using the JDK 1.2 JNI model. Assuming the |
| 190 |
directory <samp>c</samp> already exists, the file <samp>org_foo_bar_Wibble.h</samp> is created |
| 191 |
there. If this file already exists, it is left unchanged.</p> |
| 192 |
<pre><javah destdir="c" class="org.foo.bar.Wibble"/></pre> |
| 193 |
|
| 194 |
<p>This is similar to the previous example, except the output is written to a file |
| 195 |
called <samp>wibble.h</samp> in the current directory.</p> |
| 196 |
<pre> |
| 197 |
<javah outputFile="wibble.h"> |
| 198 |
<class name="org.foo.bar.Wibble,org.foo.bar.Bobble"/> |
| 199 |
</javah></pre> |
| 200 |
|
| 201 |
<p>Write three header files, one for each of the classes named. Because the <var>force</var> option |
| 202 |
is set, these header files are always written when the <code>Javah</code> task is invoked, even if |
| 203 |
they already exist.</p> |
| 204 |
<pre> |
| 205 |
<javah destdir="c" force="yes"> |
| 206 |
<class name="org.foo.bar.Wibble"/> |
| 207 |
<class name="org.foo.bar.Bobble"/> |
| 208 |
<class name="org.foo.bar.Tribble"/> |
| 209 |
</javah></pre> |
| 210 |
|
| 211 |
<p>Write the headers for the three classes using the 'old' JNI format, then write the |
| 212 |
corresponding <samp>.c</samp> stubs. The <var>verbose</var> option will cause <code>Javah</code> to |
| 213 |
describe its progress.</p> |
| 214 |
<pre> |
| 215 |
<javah destdir="c" verbose="yes" old="yes" force="yes"> |
| 216 |
<class name="org.foo.bar.Wibble"/> |
| 217 |
<class name="org.foo.bar.Bobble"/> |
| 218 |
<class name="org.foo.bar.Tribble"/> |
| 219 |
</javah> |
| 220 |
<javah destdir="c" verbose="yes" stubs="yes" old="yes" force="yes"> |
| 221 |
<class name="org.foo.bar.Wibble"/> |
| 222 |
<class name="org.foo.bar.Bobble"/> |
| 223 |
<class name="org.foo.bar.Tribble"/> |
| 224 |
</javah></pre> |
| 225 |
|
| 226 |
<p>If you want to use a |
| 227 |
custom <code class="code">JavahAdapter</code> <code>org.example.MyAdapter</code> you can either use |
| 228 |
the <var>implementation</var> attribute:</p> |
| 229 |
<pre> |
| 230 |
<javah destdir="c" class="org.foo.bar.Wibble" |
| 231 |
implementation="org.example.MyAdapter"/></pre> |
| 232 |
<p>or a define a type and nest this into the task like in:</p> |
| 233 |
<pre> |
| 234 |
<componentdef classname="org.example.MyAdapter" |
| 235 |
name="myadapter"/> |
| 236 |
<javah destdir="c" class="org.foo.bar.Wibble"> |
| 237 |
<myadapter/> |
| 238 |
</javah></pre> |
| 239 |
<p>in which case your <code>javah</code> adapter can support attributes and nested elements of its |
| 240 |
own.</p> |
| 241 |
|
| 242 |
</body> |
| 243 |
</html> |