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.
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.
For building only the Java source, the following is necessary:
For building the CPP source, the following is also necessary:
%JAVA_HOME%/include/.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++):
C:/Program Files/Microsoft Visual Studio/VC98/binC:/Program Files/Microsoft Visual Studio/COMMON/MSDev98/BinIf 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).
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:
| Property | Value-format | Default | Description |
|---|---|---|---|
| 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. |
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):
| Folder | Content |
|---|---|
| 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). |
The following Ant main targets exists (sorted by expected usage):
| Name | Description |
|---|---|
| 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:
| Name | Description |
|---|---|
| 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:
|
| 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. |
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).
JDK:
C++:
The service pack number of a Visual Studio installation can be found by looking at the registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\X.X\ServicePacks
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.
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.
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).
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.
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
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.
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.
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.
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:
test/org/jawin/DispatchTestBase.java.test/org/jawin/VtableTestBase.java.test/org/jawin/InstructionTest.java
and test/org/jawin/DllTest.java.| Copyright (c) 2000-2005, The Jawin Project - LICENSE |
|
| This documentation was written for version: 2.0, alpha 1 of Jawin. | |
| $Id: jawindeveloper.html,v 1.6 2005/03/23 20:41:03 arosii_moa Exp $ |