| <!-- |
| 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 |
| |
| http://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> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>Javah Task</title> |
| </head> |
| |
| <body> |
| |
| <h2><a name="javah">Javah</a></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. JNI operates differently depending on |
| whether <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javah.html">JDK1.2+</a> |
| or <a href="http://java.sun.com/products/jdk/1.1/docs/tooldocs/win32/javah.html">pre-JDK1.2</a> |
| systems are used.</p> |
| |
| <p>It is possible to use different compilers. This can be selected |
| with the <code>implementation</code> attribute or a nested element. <a |
| name="implementationvalues">Here are the choices of the attribute</a>:</p> |
| <ul> |
| <li>default - the default compiler for the platform.</li> |
| <li>sun (the standard compiler of the JDK) - default when not |
| running on Kaffee or gcj/gij or Java9.</li> |
| <li>kaffeh (the native standard compiler of <a href="http://www.kaffe.org" target="_top">Kaffe</a>)</li> |
| <li>gcjh (the native standard compiler |
| of <a href="http://gcc.gnu.org/java/" |
| target="_top">gcj and gij</a>) <em>since Apache Ant 1.8.2</em></li> |
| <li>forking - runs the javah executable via its command line |
| interface in a separate process. Default wehn running on |
| Java9. <em>since Ant 1.9.8</em></li> |
| </ul> |
| |
| <p><b>Note:</b> if you are using this task to work on multiple files |
| the command line may become too long on some operating systems. |
| Unfortunately the javah command doesn't support command argument |
| files the way javac (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 border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td valign="top" align="center"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">class</td> |
| <td valign="top">the fully-qualified name of the class (or classes, |
| separated by commas)</td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">outputFile</td> |
| <td valign="top">concatenates the resulting header or source files for all the classes listed into this file</td> |
| <td align="center" valign="middle" rowspan="2">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">destdir</td> |
| <td valign="top">sets the directory where javah saves the header files or the |
| stub files.</td> |
| </tr> |
| <tr> |
| <td valign="top">force</td> |
| <td valign="top">specifies that output files should always be written (JDK1.2 only)</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">old</td> |
| <td valign="top">specifies that old JDK1.0-style header files should be generated |
| (otherwise output file contain JNI-style native method function prototypes) (JDK1.2 only)</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">stubs</td> |
| <td valign="top">generate C declarations from the Java object file (used with old)</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">verbose</td> |
| <td valign="top">causes Javah to print a message concerning the status of the generated files</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">classpath</td> |
| <td valign="top">the classpath to use.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">bootclasspath</td> |
| <td valign="top">location of bootstrap class files.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">extdirs</td> |
| <td valign="top"> location of installed extensions.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">implementation</td> |
| <td valign="top">The compiler implementation to use. If this |
| attribute is not set, the default compiler for the current VM |
| will be used. (See the above <a |
| href="#implementationvalues">list</a> of valid compilers.)</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <p>Either outputFile or destdir must be supplied, but not both. </p> |
| |
| <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 border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td width="12%" valign="top"><b>Attribute</b></td> |
| <td width="78%" valign="top"><b>Description</b></td> |
| <td width="10%" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">value</td> |
| <td align="center" rowspan="4">See |
| <a href="../using.html#arg">Command-line Arguments</a>.</td> |
| <td align="center" rowspan="4">Exactly one of these.</td> |
| </tr> |
| <tr> |
| <td valign="top">line</td> |
| </tr> |
| <tr> |
| <td valign="top">file</td> |
| </tr> |
| <tr> |
| <td valign="top">path</td> |
| </tr> |
| <tr> |
| <td valign="top">prefix</td> |
| <td align="center" rowspan="2">See |
| <a href="../using.html#arg">Command-line Arguments</a>. |
| <em>Since Ant 1.8.</em></td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">suffix</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">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 align="center">No</td> |
| </tr> |
| </table> |
| |
| <h4>implementationclasspath <em>since Ant 1.8.0</em></h4> |
| |
| <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 |
| <em>since Ant 1.8.0</em></h4> |
| |
| <p>If a defined type implements the <code>JavahAdapter</code> |
| interface a nested element of that type can be used as an |
| alternative to the <code>implementation</code> attribute.</p> |
| |
| <h3>Examples</h3> |
| <pre> <javah destdir="c" class="org.foo.bar.Wibble"/></pre> |
| <p>makes a JNI header of the named class, using the JDK1.2 JNI model. Assuming |
| the directory 'c' already exists, the file <tt>org_foo_bar_Wibble.h</tt> |
| is created there. If this file already exists, it is left unchanged.</p> |
| <pre> <javah outputFile="wibble.h"> |
| <class name="org.foo.bar.Wibble,org.foo.bar.Bobble"/> |
| </javah></pre> |
| <p>is similar to the previous example, except the output is written to a file |
| called <tt>wibble.h</tt> |
| in the current directory.</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>writes three header files, one for each of the classes named. Because the |
| force option is set, these header files are always written when the Javah task |
| is invoked, even if they already exist.</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>writes the headers for the three classes using the 'old' JNI format, then |
| writes the corresponding .c stubs. The verbose option will cause Javah to |
| describe its progress.</p> |
| |
| <p>If you want to use a custom |
| JavahAdapter <code>org.example.MyAdapter</code> you can either |
| use the implementation 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 javah adapter can support attributes and |
| nested elements of its own.</p> |
| |
| </body> |
| |
| </html> |
