Debian Codegraph @

manual/Tasks/javah.html

raw
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>&mdash;the default compiler for the platform.</li>
45 <li><q>sun</q>&mdash;the standard compiler of the JDK.</li>
46 <li><q>kaffeh</q>&mdash;the native standard compiler of <a href="https://github.com/kaffe/kaffe"
47 target="_top">Kaffe</a>.</li>
48 <li><q>gcjh</q>&mdash;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>&mdash;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>&lt;arg&gt;</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>&lt;javah destdir=&quot;c&quot; class=&quot;org.foo.bar.Wibble&quot;/&gt;</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 &lt;javah outputFile=&quot;wibble.h&quot;&gt;
198 &lt;class name=&quot;org.foo.bar.Wibble,org.foo.bar.Bobble&quot;/&gt;
199 &lt;/javah&gt;</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 &lt;javah destdir=&quot;c&quot; force=&quot;yes&quot;&gt;
206 &lt;class name=&quot;org.foo.bar.Wibble&quot;/&gt;
207 &lt;class name=&quot;org.foo.bar.Bobble&quot;/&gt;
208 &lt;class name=&quot;org.foo.bar.Tribble&quot;/&gt;
209 &lt;/javah&gt;</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 &lt;javah destdir=&quot;c&quot; verbose=&quot;yes&quot; old=&quot;yes&quot; force=&quot;yes&quot;&gt;
216 &lt;class name=&quot;org.foo.bar.Wibble&quot;/&gt;
217 &lt;class name=&quot;org.foo.bar.Bobble&quot;/&gt;
218 &lt;class name=&quot;org.foo.bar.Tribble&quot;/&gt;
219 &lt;/javah&gt;
220 &lt;javah destdir=&quot;c&quot; verbose=&quot;yes&quot; stubs=&quot;yes&quot; old=&quot;yes&quot; force=&quot;yes&quot;&gt;
221 &lt;class name=&quot;org.foo.bar.Wibble&quot;/&gt;
222 &lt;class name=&quot;org.foo.bar.Bobble&quot;/&gt;
223 &lt;class name=&quot;org.foo.bar.Tribble&quot;/&gt;
224 &lt;/javah&gt;</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 &lt;javah destdir="c" class="org.foo.bar.Wibble"
231 implementation="org.example.MyAdapter"/&gt;</pre>
232 <p>or a define a type and nest this into the task like in:</p>
233 <pre>
234 &lt;componentdef classname="org.example.MyAdapter"
235 name="myadapter"/&gt;
236 &lt;javah destdir="c" class="org.foo.bar.Wibble"&gt;
237 &lt;myadapter/&gt;
238 &lt;/javah&gt;</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>