Source code file content

Revision: 2

import
» Project Revision History

» Checkout URL

web-content / trunk / docs / jni / beginning-jni-win.html

Size: 27499 bytes, 1 line
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
    <head>
        <title>Beginning JNI with NetBeans&#8482; C/C++ Pack 5.5, Windows</title>
        <link rel="stylesheet" href="http://netbeans.org/netbeans.css">
        <meta name="description" value="A tutorial describing how to compile and run JNI powered java applications using NetBeans IDE">

        <meta name="author" content="Dmitry Lipin, Kirill Sorokin">
    </head>
    <body>
        <h1>Beginning JNI with NetBeans&#8482; C/C++ Pack 5.5, Windows</h1>

        

        <div class="articledate" style="margin-left: 0px;">
            Contributed and maintained by 

            <a href="mailto:dlipin@netbeans.org"><i>Dmitry Lipin</i></a> and 
            <a href="mailto:ksorokin@netbeans.org"><i>Kirill Sorokin</i></a>.
        </div>
        
        <p>
            The tutorial will guide you through the creation of a sample 
            application which uses JNI to execute some native code written in 
            the C programming language. For the Java&#8482; part of the application you
            will use NetBeans&#8482; IDE 5.5; for the C part - NetBeans&#8482; C/C++ Pack 
            5.5.<br>

            You will start off by creating a simple Java project, adding a native 
            method to it and then implementing this method in C using
            NetBeans C/C++ Pack 5.5.
    </p>
        
        <p>
            This is the first part of the tutorial that covers the creation of a sample 
            JNI application in the Microsoft<SUP>&reg;</SUP> Windows<SUP>&reg;</SUP>
            operating system.        </p>
        
        <p align="center">
            <b>Expected duration: <i>30</i> minutes</b>
        </p>
        
        <div class="indent"> 
            <h3 class="tutorial">Prerequisites</h3>
            
            <p>
                This tutorial assumes you have some basic knowledge of, or 
                programming experience with, the following technologies:
            </p>
            
            <ul>
                <li><a href="http://en.wikipedia.org/wiki/Java_programming_language" target="_blank">Java programming language</a></li>
                <li><a href="http://en.wikipedia.org/wiki/C_programming_language" target="_blank">C programming language</a></li>
                <li><a href="http://www.netbeans.org" target="_blank">NetBeans IDE</a></li>
            </ul>
            
            <h3 class="tutorial">Software Required for  Tutorial</h3>
            
            <p>
                Before you begin, you need to install the following software on 
                your computer:
            </p>
            
            <ul>
                <li>J2SE Development Kit (JDK&trade;) 5.0 (<a href="http://java.sun.com/javase/downloads/index.jsp">download</a>)</li>
                <li>NetBeans IDE 5.5 (<a href="http://www.netbeans.org/downloads/index.html" target="_blank">download</a>)</li>
                <li>NetBeans C/C++ Pack 5.5 (<a href="http://www.netbeans.org/downloads/index.html" target="_blank">download</a>)</li>
                <li>Cygwin (<a href="http://www.cygwin.com/" target="_blank">download</a>)</li>
            </ul>
            
            <h3 class="tutorial">Notations Used in Tutorial</h3>
            
            <ul>
                <li><tt>&lt;JAVA_HOME&gt;</tt> - the JDK installation directory</li>
                <li><tt>&lt;CYGWIN_HOME&gt;</tt> - the Cygwin installation directory.</li>
                <li><tt>&lt;PROJECTS_ROOT&gt;</tt> - directory that contains the Java project you create</li>
            </ul>
            
            <h3 class="tutorial">Tutorial Exercises</h3>
            <ul>

                <li><a href="#Exercise_0">Exercise 0: Installing and Configuring Tutorial Environment</a></li>
                <li><a href="#Exercise_1">Exercise 1: Setting Up General Java Application Project</a></li>
                <li><a href="#Exercise_2">Exercise 2: Setting Up C/C++ Dynamic Library Project</a></li>
                <li><a href="#Exercise_3">Exercise 3: Building and Running Application</a></li>
            </ul>
        </div>

        <br />
        
        <!-- =============================================================== -->
        
        <h2><a name="Exercise_0"></a>
            Exercise 0: Installing and Configuring  Tutorial Environment</h2>
        
        <p>
            This exercise will guide you through the process of installing and 
            configuring the required software. While the installation of JDK, 
            NetBeans IDE and NetBeans C/C++ Pack is pretty trivial, Cygwin 
            requires special attention.
            </p>
            <p>
            After you install the software, some minor changes to the system
            configuration should be applied.
        </p>
        
        <div class="indent"> 
            <h3>Downloading and Installing Cygwin</h3>
            
            <ol>
                <p>
                <li>Download and run the Cygwin installer from 
                    <a href="http://www.cygwin.com/setup.exe">
                    http://www.cygwin.com/setup.exe</a>.                </li>
                <p>
                <li>At the Choose Installation Type page, select Install From 
                    Internet, and click Next.                </li>
                    
                <p>
                <li>At the Choose Installation Directory page, define the 
                    settings appropriate for your system, then click Next.                </li>

                    
                <p>
                <li>At the Select Local Package Directory page, define the directory 
                    which Cygwin installer will use as its cache directory, and 
                    click Next.                </li>
                    
                <p>
                <li>At the Select Connection Type page, choose the type of 
                    Internet connection  you have, and click Next.                </li>
                    
                <p>
                <li>At the Choose Download Site(s) page, select a mirror which is 
                    closest to your location, and click Next.                </li>
                
                <p>
                <li>
                    At the Select Packages page, select at least these 
                    packages: <b>gcc-core</b>, <b>gcc-g++</b>, <b>gdb,</b> and 
                    <b>make</b>. You can select other packages as well but 
                    these are required for the tutorial.
                    <br><br>
                    <p>
                        <img src="beginning-jni-win/figure-01.png" 
                            alt="Select Packages page, part 1">
                            <br>Figure 1<br><br><br>

                        <img src="beginning-jni-win/figure-02.png" 
                            alt="Select Packages page, part 2">
                            <br>Figure 2<br><br><br>

                        <img src="beginning-jni-win/figure-03.png" 
                            alt="Select Packages page, part 3">
                            <br>Figure 3                    </p>
                </li>
                
                <p>
                <li>Click Next. The Cygwin installer  proceeds with 
                    the download and configuration of the selected packages.                </li>

            </ol>
            
            <h3>Configuring  System</h3>
            
            <ol>
                <p>
                Add the <tt>&lt;CYGWIN_HOME&gt;\bin</tt> directory path 
                    to the <tt>PATH</tt> environment variable value.
            </ol>
            
            <h3>Running the Software</h3>
            
            <ol>
                <p>
                Start the NetBeans IDE.
            </ol>
        </div>
        
        <br />
        
        <!-- =============================================================== -->
        <h2><a name="Exercise_1"></a>
            Setting Up General Java Application Project</h2>
        
        <p>
            The goal of this exercise is to create and configure the Java part 
            of the JNI application you will be developing. You will create a 
            new Java application project, initialize its main class and add a 
            native method to this class.
        </p>
        
        <div class="indent"> 
            <h3 class="tutorial">
                Creating General Java Application Project</h3>
            
            <ol>
                <p> 
                <li>Choose File &gt; New Project. Under Categories, select 
                    General. Under Projects, select Java Application, and 
                    click Next.
                    <p><br><br>
                        <img src="beginning-jni-win/figure-04.png" 
                            alt="Creating a General Java Application project, Windows">
                            <br>Figure 4
                    </p>
                </li>
                
                <p> 
                <li>Under Project Name, enter <tt>HelloWorld</tt>.</li>
                
                <p> 
                <li>Change the Project Location to any directory on your 
                    computer (hereinafter, this directory is referred to as 
                    <tt>&lt;PROJECTS_ROOT&gt;</tt>).</li>
                
                <p>
                <li>Leave the Create Main Class checkbox selected and accept 
                    the default value for the corresponding text field.
                    <p><br><br>
                        <img src="beginning-jni-win/figure-05.png" 
                            alt="Creating a General Java Application project">
                            <br>Figure 5
                    </p>
                </li>
                
                <p>
                <li>Leave the Set as Main Project checkbox selected, and click 
                    Finish.<br>
                    The IDE creates the 
                        <tt>&lt;PROJECTS_ROOT&gt;/HelloWorld</tt> project 
                        folder.
                </li>
            </ol>
            
            <h3 class="tutorial">Editing Main Class Source</h3>
            
            <ol>
                <p> 
                <li>To open the <tt>Main</tt> class source in the editor, right-click the <tt>Main</tt> class node, and choose Open from the context menu.</li>
                
                <p> 
                <li>Replace the  body 
                  of the <tt>main</tt> method with 
                  the following:
                  <pre class="examplecode">
                        
        new Main().nativePrint();
                    </pre>
                </li>
                
                <p> 
                <li>Wait till the newly entered line gets underlined with a red 
                    wave. Press <tt>Alt - Enter</tt> and choose the Create method 
                    nativePrint() in helloworld.Main line from the drop-down list.<br>
                    A compilation error was caused by referencing a non-existing method in Step 2 above and the IDE automatically proposes a 
                        fix for this problem.
                    <p><br><br>
                        <img src="beginning-jni-win/figure-06.png"
                            alt="Code hine pop-up">
                            <br>Figure 6                    </p>
                </li>
                
                <p>
                <li>Edit the <tt>nativePrint()</tt> method. Delete the contents 
                    of the method and add the  <tt>native</tt> keyword to the 
                    method signature. So the method now should look like this:
                    <pre class="examplecode">
                        
        private native void nativePrint();
                    </pre>
                    <p>The <tt>native</tt> keyword indicates that the method 
                        has an implementation located in an external native 
                        library, thus the code is going to compile correctly. However at runtime the library location is not clear. Refer to the <a
                        href="#javaprojconfig">Configuring the Java Project</a> section below for details.</p>

              </li>

                

                <p>

                <li>Press <tt>Shift - F11</tt> to clean and build the project.<br>

                    The project should build successfully.
                </li>
            </ol>
            
            <h3 class="tutorial">Creating Native Library Header File</h3>
            
            <ol>
                <p> 
                <li>Switch to the  console and navigate to the 
                    <tt>&lt;PROJECTS_ROOT&gt;</tt> directory.</li>
                
                <p>
                <li>Type the following:
                    <pre class="examplecode">
                        
        &lt;JAVA_HOME&gt;\bin\javah.exe -o HelloWorldNative.h -jni 
                -classpath &lt;PROJECTS_ROOT&gt;\HelloWorld\build\classes helloworld.Main

                    </pre>
                    A <tt>HelloWorldNative.h</tt> C header file is 
                        generated. It is required to provide correct function 
                        declaration for the native implementation of the 
                        <tt>nativePrint()</tt> method.
                </li>
                
                <p> 
                <li>Switch back to the NetBeans IDE window.</li>
                
            </ol>
            
            <h3 class="tutorial">Summary</h3>
            
            <p>
                In this exercise you created a new General Java Application 
                Project, specified its location and defined the package and 
                name of the main class of the project. You also added a new 
                method to the main class and marked it as a method having a 
                native implementation. As a final step we created a C header 
                file which is required later for the native library compilation.            </p>

        </div>
        
        <br />
        
        <!-- =============================================================== -->
        <h2><a name="Exercise_2"></a>
            Setting Up New C/C++ Dynamic Library Project</h2>
        
        <p>
            This exercise will lead you through the creation of the 
            native part of the sample application. You will create the C++ 
            Dynamic Library project and configure it to be able to build the JNI 
            code.        </p>
        <p>
            After the project has been set up, you will create the 
            implementation for the native method, you have declared earlier in 
            the Java part of the application.
        </p>
        
        <div class="indent"> 
            <h3 class="tutorial">Creating New C/C++ Dynamic Library Project</h3>
            
            <ol>
                <p> 
                <li>Choose File &gt; New Project. Under Categories, select 
                    C/C++ Development. Under Projects, select C/C++ Dynamic 
                    Library, and click Next.
                    <p><br><br>
                        <img src="beginning-jni-win/figure-07.png" 
                            alt="Creating a new C/C++ Library, Windows">
                            <br>Figure 7
                    </p>
                </li>
                
                <p> 
                <li>Under Project Name, type <tt>HelloWorldNative</tt>.</li>
                
                <p> 
                <li>Under Project Location, type the same location as you 
                    entered for the General Java Application project, 
                    <tt>&lt;PROJECTS_ROOT&gt;</tt>. The required value should 
                    be already there as the default value.
                </li>
                
                <p>
                <li>Accept the defaults for all other fields.
                    <p><br><br>
                        <img src="beginning-jni-win/figure-08.png" 
                            alt="Creating a new C/C++ Library, Part 2">
                            <br>Figure 8
                    </p>
                </li>
                

                <li>Leave the Set as Main Project checkbox selected. 
                    Then click Finish.<br>
                    The IDE creates the 
                        <tt>&lt;PROJECTS_ROOT&gt;/HelloWorldNative</tt> 
                        project folder.
                </li>
            </ol>
            
            <h3 class="tutorial">Setting  Project Properties</h3>
            
            <ol>
                <p> 
                <li>Right-click the project node and choose Properties 
                    from the context menu.</li>
                
                <p> 
                <li>In the opened dialog box navigate to Configuration 
                    Properties &gt; C/C++ &gt; GNU C Compiler &gt; General. 
                    Edit the values of the Additional Include Libraries 
                    properties. Set them to <tt>&lt;JAVA_HOME&gt;/include, 
                    &lt;JAVA_HOME&gt;/include/win32</tt>.<br>
                    These settings are required to enable references to the 
                        Java <tt>jni.h</tt> library from your C code.<br>
                        <b>Note:</b> If <tt>&lt;JAVA_HOME&gt;</tt> contains 
                        spaces, please ensure you embedded the path into quotation 
                        marks, otherwise you may experience build 
                        problems.
                        <p><br><br>
                        <img src="beginning-jni-win/figure-09.png" 
                            alt="C/C++ Library Properties, Windows">
                            <br>Figure 9                    </p>
              </li>
                
                <p> 
                <li>Navigate to Configuration Properties &gt; C/C++ &gt; GNU C 
                    Compiler &gt; Command Line. Edit the value of the 
                    Additional Options property. Set it to  <tt>-mno-cygwin 
                    -Wl,--add-stdcall-alias -shared -m32</tt>. <br>
                    The <tt>-mno-cygwin</tt> option, enables building 
                        DLLs that have no dependencies on Cygwin own libraries 
                        and thus can be executed on machines which do not have 
                        Cygwin installed.<br>
                        The <tt>-Wl,--add-stdcall-alias</tt> passes the 
                        <tt>--add-stdcall-alias</tt> option to the linker;
                        without it, the resulting application would fail with 
                        the <tt>UnsatisfiedLinkError</tt>.<br>
                        The <tt>-shared</tt> option tells the compiler to 
                        generate a DLL ( not an executable file).<br>
                        <tt>-m32</tt> tells the compiler to create a 32-bit 
                        binary. On 64-bit systems the compiled 
                        binaries are 64-bit by default , which causes a lot of problems 
                        with 32-bit JDKs.
                        <p><br><br>
                        <img src="beginning-jni-win/figure-10.png" 
                            alt="C/C++ Library Properties, Part 2">
                            <br>Figure 10                    </p>
                </li>

                

                <p> 

                <li>Navigate to Configuration Properties &gt; Linker &gt; 
                    General. Edit the value of the Output property. Set it to 
                    <tt>dist/HelloWorldNative.dll</tt>.<br>
                    The goal of this step is to simplify the 
                        path of the resulting DLL file, in order to make referencing it from Java easier for 
                        you.
                    <p><br><br>
                        <img src="beginning-jni-win/figure-11.png" 
                            alt="C/C++ Library Properties, Part 3">
                            <br>Figure 11                    </p>
                </li>
                
                <p> 
                <li>Click OK.<br>
                    The defined settings are saved.
                </li>
            </ol>
            
            <h3 class="tutorial">Adding  Header File</h3>
            

            <ol>
                <p> 
                <li>Copy the generated <tt>&lt;PROJECTS_ROOT&gt;\HelloWorldNative.h</tt> header file to the 

                    C/C++ Library project directory, 
                    <tt>&lt;PROJECTS_ROOT&gt;\HelloWorldNative</tt>.               </li>

                    
                <p>
              <li>In the Projects view, navigate to HelloWorldNative &gt; 
                    Source Files. Right-click the Source Files node and 
                    choose Add Existing Item from the context menu. Point the 
                    IDE to the <tt>HelloWorldNative.h</tt> file.</b>
                    <br>
                  The <tt>HelloWorldNative.h</tt> file  appears 
                        under Source Files.                </li>
            </ol>
            
            <h3 class="tutorial">Implementing Method</h3>
            
            <ol>
                <p> 
                <li>Right-click the Source Files node and choose New &gt; Add 
                    Empty C File from the context menu. Under File Name type 
                    <tt>HelloWorldNative</tt>, and click Finish.<br>
                    The editor opens the <tt>HelloWorldNative.c</tt> file.
                    <p><br><br>
                        <img src="beginning-jni-win/figure-12.png" 
                            alt="Creating a new C file">
                            <br>Figure 12                    </p>
                </li>
                
                <p>
                <li>Edit the <tt>HelloWorldNative.c</tt> file by typing the 
                    following code:
                    <pre class="examplecode">
                        
        #include &lt;jni.h&gt;
        #include &lt;stdio.h&gt;
        #include "HelloWorldNative.h"
        
        JNIEXPORT void JNICALL Java_helloworld_Main_nativePrint
            (JNIEnv *env, jobject obj) 
        {
            printf("\nHello World from C\n");
        }
                    </pre>
                    <p><br><br>
                        <img src="beginning-jni-win/figure-13.png" 
                            alt="Implementing the native method">
                            <br>Figure 13                    </p>
              </li>
                
                <p>
                <li>Right-click the <tt>HelloWorldNative</tt> project node 
                    and choose Build Project.
                    <br>
                    The Output dialog box displays <tt>Build successful. 
                    Exit value 0.</tt><br>
                    <p><br><br>
                        <img src="beginning-jni-win/figure-14.png" 
                            alt="Building the library">
                            <br>Figure 14                    </p>
              </li>
            </ol>
            
            <h3 class="tutorial">Summary</h3>
            
            <p>
                In this exercise you created a new C/C++ Dynamic Library, 
                specified its location and configured it to be able to build 
                JNI implementation of your Java method. You added the generated 
                header file for the native method you have declared in the Java 
                application and implemented it.
            </p>
        </div>
       
        
        
        <!-- =============================================================== -->
        <h2><a name="Exercise_3"></a>Building and Running Application</h2>
        
        <p>
            In this exercise you will perform some final alterations to the Java
            part of the application. This is required to ensure the Java part properly loads the native 
            library you had compiled in the previous exercise. After that you 
            will compile and run the resulting application.
        </p>
        
        <div class="indent"> 
            <h3 class="tutorial"><a name="javaprojconfig"></a>Configuring Java Project</h3>
            
            <ol>
                <p> 
                <li>Open the <tt>Main.java</tt> file in the editor.</li>
                
                <p>
                <li>Add the following initialization code:
                    <pre class="examplecode">
                        
        static {
            System.load("&lt;PROJECTS_ROOT&gt;\\HelloWorldNative\\dist\\HelloWorldNative.dll");

        }
                    </pre>
                    <p><br><br>
                        <img src="beginning-jni-win/figure-15.png" 
                            alt="Referencing the native library from Java">
                            <br>Figure 15
                    </p>
                    
                </li>
            </ol>
            
            <h3 class="tutorial">Running Application</h3>
            
            <ol>
                <p> 
                <li>To set the <tt>HelloWorld</tt> Java project as the main 
                    project, right-click  the project node and 
                    choose Set As Main Project from the context menu.</li>
                    
                <p>
                <li>Press F6 to run the application.
                    <br>
                    The program should execute correctly and the  
                        Output dialog box should say: <br>
                  <pre class="examplecode">
                            
        Hello World from C
        BUILD SUCCESSFUL (total time: 0 seconds)
                        </pre></p>
                    <p><br><br>
                        <img src="beginning-jni-win/figure-16.png" 
                            alt="Running the application">
                            <br>Figure 16
                    </p>
                
            </ol>
            
            <h3 class="tutorial">Summary</h3>
            
            <p>
                In this exercise you made some final configuration steps and 
                ran the application to verify that the implementation of the 
                native method comes from the native C library.            </p>
        </div>
      
        <br>
        

        <h2><a name="nextsteps"></a>Next Steps</h2>

        

        <p>

            You can download the sources for this tutorial from 

            <a href="beginning-jni-win/beginning-jni-win-src.zip" target="_blank">here</a>.

        </p>

        

        <p>You can use the following documents to get more information:

        <ul>
                <li><a href="http://cnd.netbeans.org/cnd-tutorial.html" target="_blank">Getting Started With the NetBeans C/C++ Development Pack</a>, the NetBeans C/C++ Pack 5.5 tutorial</li>

                <li><a href="http://java.sun.com/j2se/1.5.0/docs/guide/jni/index.html" target="_blank">Java Native Interface</a>, the Java Native Interface 5.0 specification</li>
    </ul>
        </p>
    </body>
</html>

Project Features

About this Project

CND was started in November 2009, is owned by DimaZh, and has 197 members.
By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20160708.bf2ac18). © 2014, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo
 
 
Close
loading
Please Confirm
Close