Alan's Ramblings - dll tag

Building Win32 JNI code using NetBeans and MinGW

Tue, 27 Jun 2006 07:37:33 GMT

I use a GPS mapping application called OziExplorer, and just for laughs I started fiddling around with encapsulating the API for the application so that I could use it from Java. Access to the API is via a DLL, which meant delving into the scary world of both JNI and building DLLs on Win32. Whenever I've tried to do this in the past, it always seemed to require loading vast amounts of unwanted crap on my machine so that I got a compiler that worked, arcane spells involving mapfiles, sacrificial slaughter of various wildlife and so much pain in general that I'd always given up in disgust. However, I'm a glutton for punishment so I thought I'd have another crack at it. I couldn't find anything on the web that told you everything you needed to know all in one place, so I thought I'd document it since I'd got it all working.

Step 1

If you don't already have it, download and install the latest version of the Java Development Kit. I used version 1.5.0_07, the instructions below should work with other versions... Do this first to make you life easy - the NetBeans installer will pick up the latest version of the JDK that you have installed.

Step 2

If you don't already have it, download Netbeans and install it. I used version 5.0, that or anything later should be fine.

Step 3

Install the Ant cpptasks module. This adds support to Ant for building C code. The only bit of this you need is cpptasks.jar, and you should copy it to the lib subdirectory of the new version of Ant you installed in step 3.

Step 4

Install a copy of MinGW. This is a Win32 version of the well-know gcc compiler. Unfortunately the MinGW documentation is as clear as mud on exactly how to do this - if you go to the download page you get a huge shopping list of bits, with no clear directions as to which bits you actually need - the documentation is clearly written with the assumption that you already know. The easiest way to sort the mess out is to download the "MinGW" installer - look for the section entitled "MinGW" and you'll see a file called MinGW-<version>.exe, in my case <version> was 4.1.0. Download and run that and it will ask you for an installation location (I used C:\Program Files\MinGW, then deselect everything except The minimal set of packages required to build C/C++. Leave everything on the next screen selected and start the install. The installer will then pull the bits you need from the web. You can probably prune the list, but the whole thing is only 60Mb so it didn't seem worth the effort.

Step 5

Set up your environment. In order for Ant to be able to run the compiler, it will need to be able to find it, and the same goes for any DLLs that you will use or generate. Windows particularly sucks in this area, so to save spraying DLLs all over my C drive I created the directory C:\DLLs to dump everything in. With that done, right click on My Computer, click on Advanced then Environment Variables. Select Path from the list, then add ;C:\Program Files\MinGW\bin;c:\DLLs to the end, or wherever you installed the compiler, and wherever you intend to install your DLLs. If it isn't already there, add the path to the Java bin directory as well - in my case this is ;C:\Program Files\Java\jdk1.5.0_04\bin. I don't know if it is necessary, but at this point I logged out/into Windows to make sure my environment changes took effect.

Step 6

Add the appropriate JNI code to your project - I don't intend to cover the process for doing that here, instead see the JNI documentation. The tricky bits are getting everything to link together, the problem being caused by the awful Win32 name decoration mess. Basically, DLLs usually use the stdcall calling convention, and when you build them with gcc by default it 'decorates' the symbol names by appending '@' and a number (the number of bytes that will be popped off the stack by the function) - follow the links for details. There are two main issues:

In the case of the DLL I was wrapping, the functions used the stdcall convention but didn't have the name decorations expected by gcc. The solution was to use a def file in concert with dlltool to generate a gcc library file - then instead of linking directly with the DLL, you link against the library file. The def file itself is just a list of the decorated names that gcc is expecting to see in the DLL - you can get these by looking at the linker output, when gcc can't find the decorated names when it is linking it helpfully prints out the missing symbol names. Beware - if you do build without using stdcall your code will sort-of work, but because the stack isn't being cleaned up properly you'll get all sorts of odd crashes.
In the case of the DLL I was generating (containing the JNI code), by default gcc adds the name decoration to the symbols but the Java runtime doesn't look for the decorated symbols, so you get run-time linker errors from Java when you try to load the DLL. The solution here is quite simple - add the --kill-at flag to the gcc command line and gcc will generate your DLL without the name decorations, and Java will be happy.

Step 7

Javap can be used to output the method and field signatures that will be needed in the JNI C code. Unfortunately there isn't an Ant target to do this, so it's necessary to roll our own. The first thing is to put the following 2-line Windows batch script somewhere - I called mine javap-s.bat and put it under the nbproject subdirectory of my NetBeans project. See the following section for the explanation of how to hook it into Ant.

@echo off
javap -s -private -classpath %~dps1 %~n1 > %~s2

Step 8

The next tricky bit is adding the necessary goop to your project.xml file to get Ant to build your code bearing in mind the issues I described above. This isn't helped by the fact that the cpptasks add-on has a bug that means it doesn't work properly with MinGW. Here's what works for me. Firstly, add the following to the nbproject/project.properties file:

lib.dir=lib
jni.dir=jni
signatures.dir=signatures

Then add the following to the build.xml file:

    <!-- Load the cpptasks task -->
    <taskdef resource="cpptasks.tasks"/>
    <typedef resource="cpptasks.types"/>

    <!-- Compile the JNI code into a DLL -->
    <target name="-post-compile">
        <!-- Make sure the output directories exists -->
        <mkdir dir="${jni.dir}"/>
        <mkdir dir="${signatures.dir}"/>

        <!-- Run javah to produce a header file for the JNI functions -->
        <javah verbose="yes" classpath="${build.classes.dir}"
         destdir="${jni.dir}">
            <class name="com.oziexplorer.OziAPI"/>
        </javah>

        <!-- Run javap to produce files containing the JNI signatures -->
        <apply executable="nbproject/javap-s.bat" dest="${signatures.dir}"
          resolveexecutable="true" failonerror="true" ignoremissing="false">
            <fileset dir="${build.classes.dir}/com/oziexplorer"
              includes="*.class"/>
            <mapper type="glob" from="*.class" to="*.txt"/>
            <srcfile/>
            <targetfile/>
        </apply>

        <!-- Check the library definition file is up to date -->
        <apply executable="dlltool" dest="${jni.dir}" failonerror="true"
          ignoremissing="false">
            <filelist dir="${src.dir}/com/oziexplorer" files="OziAPI.def"/>
            <mapper type="glob" from="*.def" to="lib*.a"/>
            <arg value="-k"/>
            <arg value="--dllname"/>
            <arg value="OziAPI.dll"/>
            <arg value="--def"/>
            <srcfile/>
            <arg value="--output-lib"/>
            <targetfile/>
        </apply>

        <!-- Compile the C code -->
        <cc link="shared" outtype="shared" multithreaded="true" optimize="speed"
          objdir="${jni.dir}" outfile="${jni.dir}/OziAPI">
            <compilerarg value="-Wall"/>
            <compilerarg value="-D_JNI_IMPLEMENTATION_"/>
            <compilerarg value="-fno-strict-aliasing"/>
            <linker name="gcc">
                <linkerarg value="--kill-at"/>
                <linkerarg value="-oOziAPIJava.dll"/>
            </linker>
            <sysincludepath location="${java.home}/../include"/>
            <sysincludepath location="${java.home}/../include/win32"/>
            <fileset dir="${src.dir}/com/oziexplorer" includes="OziAPI.c"/>
            <libset dir="${jni.dir}" libs="OziAPI"/>
        </cc>
    </target>

    <!-- Copy the stripped DLL and OziAPI.DLL to the dist directory -->
    <target name="-post-jar">
        <apply executable="strip" dest="${dist.dir}" failonerror="true"
          ignoremissing="false">
            <filelist dir="${jni.dir}" files="OziAPIJava.dll"/>
            <mapper type="glob" from="*.dll" to="*.dll"/>
            <arg value="-s"/>
            <srcfile/>
            <arg value="-o"/>
            <targetfile/>
        </apply>
        <copy todir="${dist.dir}">
            <fileset dir="${lib.dir}" includes="*.dll"/>
        </copy>
    </target>

Let's go through it bit at a time:

The typedef statements pull in the cpptasks extension.
The mkdir makes sure the output directory exists - this rule runs before the JAR file is generated, so we need to manually create the output directory.
The javah section runs javah to generate a C header file from the OziAPI.java file, which contains the native function definitions. This is useful to make sure you get the function prototypes correct.
The next section runs the batch file created in step 8 over each of the generated class files to produce the corresponding text files containing the signatures of the methods and fields. These are placed in the source directory, but that can be changed to suit.
There also isn't any obvious way of running dlltool from within the cpptasks framework, so it's necessay to manually check the dependencies between the def file and the resulting library, and rebuild if necessary. That's done by the second apply section.
The cc section has a few things that need clarification:
- The linkerarg with the -o is to work around the bug I mentioned above - without it the cc task thinks that it is running on Unix rather than Win32 and generates libOziAPIJava.so instead of OziAPIJava.dll.
- --kill-at stops the linker putting the @ decoration on the generated code and means that the functions can be linked to correctly.
The -post-jar section strips and copies the resulting DLL to the directory established in step 6, along with any other required DLLs that have been put in the ${lib.dir} directory.

Although it took a bit of fiddling to get all the bits to play together, the process of building DLLs is far easier than it was in the past - the work that the gcc and MinGW crowd have done to do all the dirty work for you is really very impressive.

JNI_OnUnload(): mostly useless

Sat, 18 Feb 2006 16:11:26 GMT

I've been writing a JNI wrapper that requires the creation of a native thread and I've set things up using a JNI_OnLoad() function to initialise the DLL and create an event handling thread thread. I also used the JNI_OnUnload() function to kill the thread and clean up the DLL, but what was puzzling me was that although JNI_OnLoad() was being called OK, JNI_OnUnload() was never being called, and because the thread was attached to the JVM via a call to AttachCurrentThread(), the JVM would never exit as it still had an active thread. A simple workaround was to attach the thread to the JVM as a daemon thread using AttachCurrentThreadAsDaemon as daemon threads don't keep the JVM alive, but that still meant the DLL wasn't being cleaned up properly.

Google revealed a post on the Java Forums which explained that the ClassLoader was keeping a reference to the class containing the native code wrapping the DLL, and that was preventing the JNI_OnUnload() function from being called. The post also explains that if you make a call to System.runFinalizersOnExit() then the finalizer for the ClassLoader will be called on exit and that in turn will call the native code's JNI_OnUnload() method, and a simple experiment proves that is indeed the case. However the System.runFinalizersOnExit() method is deprecated:

This method is inherently unsafe. It may result in finalizers being called on live objects while other threads are concurrently manipulating those objects, resulting in erratic behavior or deadlock.

In light of this it appears that although JNI_OnLoad() is useful, JNI_OnUnload() is less than useful. There is a workaround, which is to register a native exit callback using Runtime.addShutdownHook() and do the cleanup that way, but it's kind of broken that JNI_OnUnload() doesn't actually do what it is supposed to, and even more odd that the JNI documentation is completely silent as to why it doesn't actually work. I think I feel a bug report coming on ;-)

WonDLLand revisited

Sun, 15 Jan 2006 15:26:11 GMT

I previously documented my problems getting my Java/JNI wrapper for OziAPI to work. As I said in my previous post, some of my problems were down to the OziAPI DLL not getting a chance to clean up properly when the application exited. Over the Xmas break I continued hacking away and wrapping more of the interface, but when I got to the OziExplorer callback hooks I hit another showstopper. The hooks allow you to trap mouse clicks on the map displayed in OziExplorer, but every time I activated one of the callback hooks and then clicked on a map the application hung, and it stayed hung until I quit the Java application. My initial thought was that I was falling afoul of the awful mess of calling convention types on Win32 and that something was barfing on a malformed stack frame somewhere on the round trip from my Java app to OziExplorer and back. I was particularly suspicious because I was using the MinGW tools to build the DLL containing my JNI code rather than the Microsoft tools.

To try to track down the root cause I hacked together a console-only C program and DLL to mimic my Java/JNI setup, and whilst that worked fine with the non-callback OziAPI functions (as did the Java/JNI version), any callback functions hung in just the same way as the Java/JNI version. I noticed that the Visual C++ example included with the OziAPI DLL contained a Windows GetMessage loop, so I added one to my toy program and hey presto, it worked! This implied that OziAPI uses windows messages to implement the callback mechanism, and an email to Des Newman, the OziExplorer developer, confirmed that was in fact the case.

That didn't really help explain what was wrong with the Java/JNI setup - the Java code was a Swing application, so it had to contain a Windows dispatch loop anyway - right? What on earth was going on? I was more more less ready to admit defeat when I stumbled across an old JavaWorld article that contained the following:

Messages are not sent directly to windows, but put on an event queue owned by a thread. The thread must occasionally check for messages on its queue, and choose to either deal with them or delegate them to other callbacks ... we cannot be sure that these threads (which are owned by the VM process) check their Win32 message queues and delegate messages. In this case, in fact, they don't. Because of this, we will create our own thread, with our own message queue handling, and make sure all our windows are created within its context. It is simple to asynchronously delegate work to our worker thread by posting custom messages to its message queue.

Ahah! So it appeared that it is necessary to have a custom dispatch loop to handle the Windows messages dispatched by the OziAPI callback hooks. However, because this thread has in turn got to be able to dispatch the callbacks to Java methods, we have to play nicely with the JVM as well. We also have to make sure that the events from the OziAPI DLL get dispatched to our dispatch thread - some experimentation revealed that OziAPI sends them to the first thread that makes a callback-related OziAPI call. Putting this all together, here's what is necessary to get it to work:

Create a native Windows thread.
Call PeekMessage(&msg, NULL, WM_USER, WM_USER, PM_NOREMOVE) to force creation of a new Windows message queue.
Make a dummmy oziMapSingleClickOFF() call so OziAPI routes the callbacks to the new thread.
Attach the new thread to the JVM with a call to AttachCurrentThread()
Enter a message dispatch loop to handle the callback events.

The various OziAPI calls necessary to enable and disable the callback hooks are also made from inside the new thread - the event loop responds to custom WM_APP messages and enables or disables the callbacks as required. The callbacks themselves are handled by C routines that vector the events to the appropriate Java method calls. I've left out all details of the necessary inter-thread synchronisation that's needed, but that's an overview of how it all hangs together.

I'm still working on wrapping the rest of the API - it's rather large so it is going to take a while, but once I have it knocked into shape I'm intending to release the code here on SourceForge.

Alan in wonDLLand

Wed, 14 Sep 2005 14:14:36 GMT

Yesterday evening I had another poke at the Java wrapper for OziExplorer that I'm sporadically working on, OziExplorer is the GPS mapping application that I use. It's a pretty fat API so I'm gradually chipping away at it. My latest tweak was to add a simple Swing GUI to my test app, but as soon as I did it blew up every time I exited with two rather foreboding messages, The exception unknown software exception (oxoeedfade) occurred in the application at location 0x7c81eb33 and Runtime error 217 at 0009D54. Google told me that second message was coming from Delphi - OziAPI.dll is generated with Delphi, but didn't shed much light on exactly what was causing the error. Some experimentation revealed that the problem was actually nothing to do with Swing, I could get the same effect by just calling System.exit immediately after calling any of the functions in the Delphi DLL. If I just let the program fall off the end of main the problem didn't happen, which suggested that whatever was going belly up was being caused by something that System.exit was doing, either directly or by indirectly perturbing the ordering of the JVM exit processing.

A bit more googling revealed that other people had hit the same problem and that one workaround was to manually open the DLL with LoadLibrary, find the symbol addresses via GetProcAddress and finally manually free the DLL with FreeLibrary on exit. (For those in the Solaris seats that's the Win32 equivalent of dlopen, dlysm and dlclose). This suggested to me that the problem was something to do with the timing of the DLL initialisation and/or cleanup. In my case I was pulling in the OziAPI DLL via a linker dependency from the JNI DLL, and I was loathe to have to manually pull in OziAPI.dll and look up the symbols just to work around this problem. Some more spelunking through the Microsoft documentation revealed the following interesting snippets:

If you terminate a process by calling TerminateProcess or TerminateJobObject, the DLLs of that process do not receive DLL_PROCESS_DETACH notifications. If you terminate a thread by calling TerminateThread, the DLLs of that thread do not receive DLL_THREAD_DETACH notifications.

The TerminateProcess function is used to unconditionally cause a process to exit. The state of global data maintained by dynamic-link libraries (DLLs) may be compromised if TerminateProcess is used rather than ExitProcess.

I grabbed a copy of strace for NT and traced the execution of my test application, and although I could see calls to TerminateProcess I couldn't see any calls at all to ExitProcess, not only when I called System.exit but also when I let the program fall of the end of main. Hmm. If that was what was happening there didn't seem to be much I could do to change the behaviour of System.exit, but I already knew that if the process exited by falling off the end of main the problem didn't occur - what I needed to do was to find out how to make that happen from inside a Swing callback. I was wandering around the JDK documentation when I found an interesting document titled AWT Threading Issues, which says:

Therefore, a stand-alone AWT application that wishes to exit cleanly without calling System.exit must:

Make sure that all AWT or Swing components are made undisplayable when the application finishes. This can be done by calling Window.dispose on all top-level Windows. See Frame.getFrames.
Make sure that no method of AWT event listeners registered by the application with any AWT or Swing component can run into an infinite loop or hang indefinitely. For example, an AWT listener method triggered by some AWT event can post a new AWT event of the same type to the EventQueue. The argument is that methods of AWT event listeners are typically executed on helper threads.

So the code to work around my problem turned out to be trivial, I just needed to put the following in my exit button callback to make sure that all the threads in the application exit cleanly:

        for (Frame f : Frame.getFrames()) {
            f.dispose();
        }

Hey presto, everything now works. Obviously if the application creates it's own threads they will also need to be gracefully terminated. I'm still discussing the exact cause of the problem with the JVM folks, but for now I'm happy that I've got a workaround. Hopefully this information will save someone some grief as my searching revealed that quite a few people had been hit by this issue but that nobody quite understood how to work around it other than the nasty manual DLL loading hack.