A Developers Introduction to Jawin


The information in this document is NOT necessary to use Jawin successfully in a project, as it is mostly centered around helping developers on the Jawin Project getting started with development on Jawin.


  1. Checkout of Jawin from SourceForge.net
  2. Building Jawin
    1. Requirements and setting up your environment
    2. Ant
    3. Build folders
    4. Ant targets
    5. Tested Environments
  3. C++ development
    1. Using MS Visual C++
    2. The compiled files in the bin-folder
  4. Testing with JUnit
    1. Running the JUnit tests
    2. Writing a JUnit test for Jawin marshalling

1. Checkout of Jawin from SourceForge.net

SourceForge.net has detailed information on the Jawin CVS-page about how to set up your CVS-client for checking out the Jawin source.

Notice that an anonymous checkout option is available for users interested in building Jawin themselves without joining the Jawin developer team. Please be aware that the anonymous CVS-server is a mirror of the developer CVS-server. Synchronization between the two servers should, as the time of this writing, occur every 5 hours, so a certain lag should be expected on the anonymous CVS (this lag is also present for the web-based CVS repository viewer). Please check the SourceForge Site Status for issues regarding unexpected lags in the synchronization.

TODO - Roger, you mentioned something about an incorrect LF setting for WinCVS - should we mention the correct way to set it in this section so as to avoid other repeating the same error.

2. Building Jawin

2.1. Requirements and setting up your environment

For building only the Java source, the following is necessary:

For building the CPP source, the following is also necessary:

All tools must be configured to run from your command line.

For VC++ this means getting msdev.exe to run. If you did not choose to modify the environment variables during installation of VC++, it should be possible to set the correct environment on a single command line instance, by executing the VCVARS32.BAT-file present in the VC++ VC98/Bin-folder. If this file is not present on your installation, you might be able to get msdev.exe running by adding the following directories to your path (please replace C:/Program Files/Microsoft Visual Studio with your installation path for VC++):

If your JAVA_HOME environment variable is set correctly as mentioned above, it should not be necessary to add the JNI header files to the global VC++ include-list.

With respect to getting the standard Java tools and/or Ant configured to run from the command line, please consult the installation instructions for these tools.

Please notice that we have NOT tested all combinations of the above software, and can not guarentee that no problems will occur, even though your installation fullfills the above list(s). In Tested Environments below we have listed different combinations that are known to have been successfully working for building Jawin (at some point in time at least).

2.2. Ant

The Ant build file (build.xml) is present in the root directory for the checked out Jawin source. As always the command:

ant -projecthelp

will give a quick overview of the different available targets.

Two property files are looked for by the build file:

these are just standard Java property files (on the format name = value). Note that no user.properties file exists in the source checked out from CVS (and neither should your local user.properties ever be committed to CVS), as this is a file for overriding the default properties set in global.properties on a per user basis. So if you need to set a particular property to something non-standard, create a user.properties file and set the property in that file, since it will then take precedence over the value specified in the global.properties.

It is also possible to specify the property on the command line, with the standard -D-option (like: -Dproperty=value). Properties specified this way take precedence over values in both user.properties and global.properties.

Pt. only the following properties are relevant to specify in a user.properties file:

cpp.compile.enabled true/false false For enabling or disabling cpp compilation, this should be set to true if you need to compile/recompile the native C++ code.
typebrowser.maxmemory -Xmx-format 256M The maximum heap size for the Jawin Type Browser when launched from the Ant file with the typebrowser target. Increase this value if you see java.lang.OutOfMemoryError (see the Java documentation for the exact format of -Xmx<size>).
sourceforge.password email-adress [empty] The password for the FTP project upload service at SourceForge.net. This is ONLY needed for the upload-target, which should only be used by project admins. Please see the Guide to the SourceForce.net File Release System (FRS) for more information.

2.3. Build folders

The different Ant targets generates code to the following folders, which should never be checked into CVS or used for storing information (as the clean-target will remove these folders):

build The target for both the C++ and java compilations.
dist The folder containing a distribution equal to the binary Jawin releases, this includes jars, DLL's and doc-files.
deploy The folder containing a zipped, upload-ready jawin release. This folder also contains a copy of the docs folder ready for upload to the web-site for Jawin (certain replaces have been done during the copy to this folder - replaces that makes this folder a little bit different than the docs-folder contained in the dist-folder, eg. other SourceForge.net image sources are used for the web-site for traffic accounting).

2.4. Ant targets

The following Ant main targets exists (sorted by expected usage):

dist (default target) Compiles all java and cpp-code (if cpp.compile.enabled=true), and package all distribution relevant binary and config files to the dist-folder. The native DLL-files are located in the dist/bin-folder, the jawin.jar in the dist/lib-folder and the Jawin Type Browser with all configuration in the dist/typebrowser-folder.
test Run the unit tests. Since this uses the junit-task, you must have set up JUnit correctly in Ant to run this task. Please see the Testing with JUnit-section on how to do this.

The test-reports will be generated into the dist/test-reports-folder.
clean Clean all generated files. This includes deleting the three build folders mentioned in Build folders. If cpp.compile.enabled=true the MAKE CLEAN-command will be executed on the cpp-projects.
doc Generates complete documentation (including javadocs) to the dist/docs folder. For most of the standard HTML-files this step make a copy with replace for certain patterns. Besides this the documentation are equal to the files in the docs-folder.
deploy Generates the upload-ready files for a Jawin release into the deploy-folder. This target depends on the clean target to make sure all code, javadoc, etc. will be build from scratch.

Besides these main targets, the following targets may be relevant in special situations, or to certain developers:

typebrowser For launching the Jawin Type Browser. Please be aware that you must manually have run'ed at least the java-compile target before launching JTB with this target.

The TypeLibWrapper.dll will be located according to the following rule:
  • If cpp.compile.enabled=false (the default) the bin-dir will be set as the java.library.path.
  • If cpp.compile.enabled=true the build/bin-dir will be set as the java.library.path.
cpp-compile Compiles the CPP-code - requires that cpp.compile.enabled=true. Depends on java-compile to javah-compile the JNI header files.
java-compile Compiles the java-code.
javadoc A subset of the doc-target. Generates the javadocs for Jawin to the dist/docs/api-folder.
web Generates the Jawin website ready for upload to SourceForge.net.
upload ONLY FOR PROJECT ADMINS. Uploads a new Jawin release to SourceForge.net. This can only be done if the file deploy/jawin-${app.version}.zip-exists (this archive will be created when the deploy-target is run), AND the sourceforge.password has been set. Please consult the Guide to the SourceForce.net File Release System (FRS) for information about uploading releases.

Notice that this target uses the Ant optional FTP-task, which requires external libraries, please consult the Ant documentation for information on this.

2.5. Tested Environments

Developer environments that are known to have been successfully used for building Jawin. If you have been successfull with other versions of the software, we would be grateful to hear about it on the Jawin mailing list (especially we would like to hear from somebody successfully having used Visual C++ .NET (FIXME - there is a mail from Andreas Kemkes about this on the mailing list dated 27-11-2003, I (Morten) will look into this when I can find time for it, and see what I can do to modify the build file to support .NET), or used a completely different C++ compiler, eg. GCC with MinGW).



The service pack number of a Visual Studio installation can be found by looking at the registry key:


Replace X.X with either 5.0 or 6.0. If any service packs has been installed there should be a DWORD value named "latest", whose data is the service pack number ,i.e. 5 for SP5. There should also be a string value that is the name of the service pack, i.e. "sp5" for SP5. There should be no data for this value.

2.5.1. Updating the Platform SDK

You may also need to update your header and lib-files by updating to the latest Platform SDK. This could be done by going to the Microsoft SDK Update Site.

3. C++ development

3.1. Using MS Visual C++

Since some of the header files are generated by the ant build script in the cpp-compile target, this target MUST be run before trying to use VC++. Otherwise the JNI header files will be missing in the TypeLibWrapper project (please note that since these header files are generated, they should not be added to the CVS repository).

3.2. The compiled files in the bin-folder

C++-developers should note that the files in the bin-folder are checked into CVS even though they are generated. This is necessary for the Jawin-developers that are not working on the native part of Jawin. These files are not automatically overwritten when the C++ code is build, since this would make the files seem to be changed in comparison with the files in CVS everytime they are build. The C++ build folder is therefore build/bin, and the DLL-files in this folder is used in the build-file whenever the cpp.compile.enabled-property is set to true. Otherwise the DLL-files in bin are used.

Important: Therefore the C++-developers should take care that whenever C++ code has been changed, the relevant compiled DLL's should be manually copied from the C++ build-folder to the bin-folder and be updated in the CVS-repository.

4. Testing with JUnit

4.1. Running the JUnit tests

To run the JUnit tests, you have to set up your Ant installation to use the optional tasks JUnit and JUnitReport. This is done as follows

4.1.1. The JUnit task (all JDK versions)

The JUnit 3.8.1 jar file (junit-3.8.1.jar) is present in the source distribution for Jawin in the lib/external folder. As documented in the Ant manual - JUnit task the setup is easiest done by copying this jar file to the ANT_HOME/lib folder.

4.1.2. The JUnitReport task (only for JDK 1.3)

Important: This setup is NOT needed for JDK 1.4 and 1.5, as they out-of-the-box includes the necessary XSLT processor.

To run the JUnitReport task with JDK 1.3, Xalan is required as documented in the Ant manual - JUnitReport task. The easiest way to configure Ant for this, is by copying the lib/external/xalan.jar file to the ANT_HOME/lib folder.

4.1.3. Run the tests

After the setup in the two previous sections, the tests can be run with the test target. This should generate a test report in the dist/test-reports folder.

4.2. Writing a JUnit test for Jawin marshalling

Roughly speaking, Jawin is split into two pieces: a marshalling layer that actually converts between Java and Win32/COM types, and various code generators and dynamic proxies that hide the details of invoking the marshalling layer directly. This following steps are a guide to write a unit test if you suspect a problem in the marshalling layer:

  1. Create a Win32 or COM entry point with a signature that causes the problem. There are pre-existing test harnesses for this, in the cpp/CallCOMUnitTest and cpp/testdll projects. For a COM entry point you will need to edit three files:
    1. CallCOMUnitTest.idl
    2. DualTest.h
    3. DualTest.cpp
    For a DLL entry point you can simply add the entry point to testdll.cpp.
  2. Write Java code that uses the marshalling layer to call the entry point:
    1. For Dispatch marshalling test examples, see test/org/jawin/DispatchTestBase.java.
    2. For Vtable marshalling test examples, see test/org/jawin/VtableTestBase.java.
    3. For DLL entry point test examples, see test/org/jawin/InstructionTest.java and test/org/jawin/DllTest.java.