Source code file content

Revision: 2

import
» Project Revision History

» Checkout URL

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

Size: 23517 bytes, 1 line
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
    <head>
        <title>Beginning JNI with NetBeans C/C++ Pack 5.5, Linux</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 C/C++ Pack 5.5, Linux</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 take 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 second part of the tutorial that covers the creation of a sample 
            JNI application in the Linux
            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" target="_blank">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><tt>gcc</tt>, <tt>make</tt></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;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 performing 
            required configuration changes that should be applied to your 
            system, prior to starting the tutorial.
        </p>
        
        <div class="indent"> 
            <h3>Configuring System</h3>
            
            <ol>
                <p>
                Append the paths to the directories that contain the <tt>gcc</tt> 
                and <tt>make</tt> utilities to the PATH environment variable.
            </ol>
            
            <h3>Running 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-linux/figure-01.png" 
                            alt="Creating a General Java Application project, Linux">
                            <br>Figure 1
                    </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-linux/figure-02.png" 
                            alt="Creating a General Java Application project">
                            <br>Figure 2
                    </p>
                </li>
                
                <p>
                <li>Leave the Set as Main Project checkbox selected. Then click 
                    Finish.<br>
                    <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 Main class source in the editor, right-click the Main 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>Press Alt - Enter 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-linux/figure-03.png"
                            alt="Code hine pop-up">
                  <br>Figure 3                    </p>
                </li>
                
                <p>
                <li>Modify the body of the <tt>nativePrint()</tt> method by deleting its 
                contents and inserting the </tt>native</tt> keyword into the method signature as follows:
                    <pre class="examplecode">
                        
        private native void nativePrint();
                    </pre>
                    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.
              </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 -o HelloWorldNative.h -jni 
                -classpath &lt;PROJECTS_ROOT&gt;/HelloWorld/build/classes helloworld.Main
                    </pre><br>
                  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 though the process of creating the 
            native part of the sample application. You will create the C++ 
            Dynamic Library project and configure it to be able to build 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-linux/figure-04.png" 
                            alt="Creating a new C/C++ Library, Linux">
                            <br>Figure 4
                    </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-linux/figure-05.png" 
                            alt="Creating a new C/C++ Library, Part 2">
                            <br>Figure 5
                    </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 value of the Additional Include Libraries 
                    property. Set it to be <tt>&lt;JAVA_HOME&gt;/include, 
                    &lt;JAVA_HOME&gt;/include/linux</tt>
                    <br>
                    These settings are required to enable references to the 
                        Java <tt>jni.h</tt> library from your C code.
                        <p><br><br>
                        <img src="beginning-jni-linux/figure-06.png" 
                            alt="C/C++ Library Properties, Linux">
                            <br>Figure 6                    </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>-shared -m32</tt>.
                    <br>
                        The <tt>-shared</tt> option tells the compiler to 
                        generate a dynamic library.<br>
                        <tt>-m32</tt> tells the compiler to create a 32-bit 
                        binary. By default on 64-bit systems the compiled 
                        binaries are 64-bit, which causes a lot of problems 
                        with 32-bit JDKs.
                        <p><br><br>
                        <img src="beginning-jni-linux/figure-07.png" 
                            alt="C/C++ Library Properties, Part 2">
                            <br>Figure 7                    </p>
              </li>
                
                <p> 
                <li>Navigate to Configuration Properties &gt; Linker &gt; 
                    General. Edit the Output property  value. Set it to                    <tt>dist/HelloWorldNative.so</tt>

                    <br>
                    The goal of this step is to simplify the 
                        path of the resulting <tt>so</tt> file, in order to make 
                        referencing it from Java easier for 
                        you.
                        <p><br><br>
                        <img src="beginning-jni-linux/figure-08.png" 
                            alt="C/C++ Library Properties, Part 3">
                            <br>Figure 8                    </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-linux/figure-09.png" 
                            alt="Creating a new C file">
                            <br>Figure 9                    </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-linux/figure-10.png" 
                            alt="Implementing the native method">
                            <br>Figure 10                    </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>
                    <p><br><br>
                        <img src="beginning-jni-linux/figure-11.png" 
                            alt="Building the library">
                            <br>Figure 11                    </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>
        
        <br>
        
        <!-- =============================================================== -->
        <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.so");
        }
                    </pre>
                    <p><br><br>
                        <img src="beginning-jni-linux/figure-12.png" 
                            alt="Referencing the native library from Java">
                            <br>Figure 12
                    </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: 
                  <pre class="examplecode">
                            
        Hello World from C
        BUILD SUCCESSFUL (total time: 0 seconds)
                        </pre></p>
                    <p><br><br>
                        <img src="beginning-jni-linux/figure-13.png" 
                            alt="Running the application">
                            <br>Figure 13                    </p>
                </li>
            </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-linux/beginning-jni-linux-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