jnigen.php - gerrit/www.eclipse.org/swt - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
     <title>Generating the SWT JNI Code</title>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
     <meta http-equiv="Content-Style-Type" content="text/css">
     <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
     <link rel="stylesheet" href="swt.css" type="text/css">
     <link rel="shortcut icon" href="http://www.eclipse.org/images/eclipse.ico" type="image/x-icon">
 </head>
 <body bgcolor="#ffffff" text="#000000">
 <table width="875px" class="swtpage">
 <colgroup><col width="125px"><col width="750px"></colgroup>
 <tr><?php include "sidebar.php"; ?>
 <td valign="top" style="padding: 10px"><h1 style="padding: 0; margin: 0; border-bottom: 1px solid #000000;">Generating the SWT JNI Code</h1>

 <p>All of the C code used by SWT is generated by the <b>JNIGeneratorApp</b>
 application included in the SWT Tools bundle and available on the
 <a href="updatesite.php">SWT Tools Update Sites</a>.

 This page describes how to use this tool when fixing bugs or adding
 features to SWT.</p>

 <b>Note</b> that this process has changed for SWT 3.5. For older versions see <a href="http://www.eclipse.org/swt/jnigen_34.php">Generating the SWT JNI Code for SWT 3.4</a>.
     <p></p>

 <h3>Adding native methods</h3>

 <ol>
 <li>Add the function prototype in <tt>OS.java</tt>, copying the style and structure
     of the other functions in that file. Note that for Mac/Cocoa, portions of <tt>OS.java</tt>
     are also <a href="http://www.eclipse.org/swt/macgen.php">generated</a>.
     <p></p>
 <li>Install the latest SWT Tools from the <a href="updatesite.php">SWT Tools Update Site</a>.
     <p></p>
 <li>Restart Eclipse.
     <p></p>
 <li>Use code assist templates like <b>jni*</b> (i.e. <i>jnifield</i> and <i>jnimethod</i>) to add javadoc tags that describe flags and casts for any primitive types. See <a href="http://www.eclipse.org/swt/jnigen_metadata.php">metadata</a> for more documentation.
     <p></p>
     <center><img src="images/jnitemplates.png" alt="build.xml"></center>
     <p></p>
 <li>Save the file. This should build the appropriate C files.
     <p></p>

 <li>Compile the new C code and copy the new libraries to the appropriate fragment.  Steps:
     <ul>
       <li>right-click on the <tt>build.xml</tt> file of the appropriate fragment (i. e. org.eclipse.swt.&lt;ws&gt;.&lt;os&gt;.&lt;arch&gt;) depending on the os, platform and architecture being built</li>
       <li>select "Run As -> Ant Build..."</li>
       <li>on the Targets tab check the <tt>build_libraries</tt> target</li>
 	  <li>on the JRE tab select "Run in the same JRE as the workspace"</li>
       <li>on the Refresh tab check "Refresh resources upon completion" to refresh your workspace
     	after running the build; this ensures that Eclipse will pick up the fresh binaries</li>
    	  <li>press the "Run" button to begin</li>
     <p></p>
 </ol>

 <h3>Adding structs</h3>

 <p>Often, methods return values or require parameters as a C struct.  To
 add a new structure, simply add a new class in the same package as
 the OS.java file which matches the definition of the C structure.
 This will be picked up and correctly handled by <i>JNIGeneratorApp</i>.</p>

 <p>If a struct is input-only or output-only, this information can be used
 by <i>JNIGeneratorApp</i> to generate more efficient C code.  Use the
 <b>flags</b> attribute of the native function to indicate this in the
 metadata.</p>

 <h3>More Hints</h3>

 <ul>
 <li>For GTK+ and Motif, all native functions must be wrapped in locking
     code.  When adding functions, simply copy the style and structure of the
     other native functions.
 <li>Many functions on Mac OS X return structs which use <b>unions</b>.  For
     an example of how to add the markup for a union, see the
     <b>ControlFontStyleRec</b> structure and its metadata.
 </ul>

 <p>And there you go!  If you're having trouble, please post to the SWT
 mailing list or file a new bug in bugzilla.</p>

 </table>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<head>
	<title>Generating the SWT JNI Code</title>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<meta http-equiv="Content-Style-Type" content="text/css">
	<link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
	<link rel="stylesheet" href="swt.css" type="text/css">
	<link rel="shortcut icon" href="http://www.eclipse.org/images/eclipse.ico" type="image/x-icon">
	</head>
	<body bgcolor="#ffffff" text="#000000">
	<table width="875px" class="swtpage">
	<colgroup><col width="125px"><col width="750px"></colgroup>
	<tr><?php include "sidebar.php"; ?>
	<td valign="top" style="padding: 10px"><h1 style="padding: 0; margin: 0; border-bottom: 1px solid #000000;">Generating the SWT JNI Code</h1>

	<p>All of the C code used by SWT is generated by the <b>JNIGeneratorApp</b>
	application included in the SWT Tools bundle and available on the
	<a href="updatesite.php">SWT Tools Update Sites</a>.

	This page describes how to use this tool when fixing bugs or adding
	features to SWT.</p>

	<b>Note</b> that this process has changed for SWT 3.5. For older versions see <a href="http://www.eclipse.org/swt/jnigen_34.php">Generating the SWT JNI Code for SWT 3.4</a>.
	<p></p>

	<h3>Adding native methods</h3>

	<ol>
	<li>Add the function prototype in <tt>OS.java</tt>, copying the style and structure
	of the other functions in that file. Note that for Mac/Cocoa, portions of <tt>OS.java</tt>
	are also <a href="http://www.eclipse.org/swt/macgen.php">generated</a>.
	<p></p>
	<li>Install the latest SWT Tools from the <a href="updatesite.php">SWT Tools Update Site</a>.
	<p></p>
	<li>Restart Eclipse.
	<p></p>
	<li>Use code assist templates like <b>jni*</b> (i.e. <i>jnifield</i> and <i>jnimethod</i>) to add javadoc tags that describe flags and casts for any primitive types. See <a href="http://www.eclipse.org/swt/jnigen_metadata.php">metadata</a> for more documentation.
	<p></p>
	<center><img src="images/jnitemplates.png" alt="build.xml"></center>
	<p></p>
	<li>Save the file. This should build the appropriate C files.
	<p></p>

	<li>Compile the new C code and copy the new libraries to the appropriate fragment. Steps:
	<ul>
	<li>right-click on the <tt>build.xml</tt> file of the appropriate fragment (i. e. org.eclipse.swt.<ws>.<os>.<arch>) depending on the os, platform and architecture being built</li>
	<li>select "Run As -> Ant Build..."</li>
	<li>on the Targets tab check the <tt>build_libraries</tt> target</li>
	<li>on the JRE tab select "Run in the same JRE as the workspace"</li>
	<li>on the Refresh tab check "Refresh resources upon completion" to refresh your workspace
	after running the build; this ensures that Eclipse will pick up the fresh binaries</li>
	<li>press the "Run" button to begin</li>
	<p></p>
	</ol>

	<h3>Adding structs</h3>

	<p>Often, methods return values or require parameters as a C struct. To
	add a new structure, simply add a new class in the same package as
	the OS.java file which matches the definition of the C structure.
	This will be picked up and correctly handled by <i>JNIGeneratorApp</i>.</p>

	<p>If a struct is input-only or output-only, this information can be used
	by <i>JNIGeneratorApp</i> to generate more efficient C code. Use the
	<b>flags</b> attribute of the native function to indicate this in the
	metadata.</p>

	<h3>More Hints</h3>

	<ul>
	<li>For GTK+ and Motif, all native functions must be wrapped in locking
	code. When adding functions, simply copy the style and structure of the
	other native functions.
	<li>Many functions on Mac OS X return structs which use <b>unions</b>. For
	an example of how to add the markup for a union, see the
	<b>ControlFontStyleRec</b> structure and its metadata.
	</ul>

	<p>And there you go! If you're having trouble, please post to the SWT
	mailing list or file a new bug in bugzilla.</p>

	</table>
	</body>
	</html>