# *****************************************************************************
# *
# *   Copyright (C) 1995-2002, International Business Machines
# *   Corporation and others.  All Rights Reserved.
# *
# *   Author: Ram Viswanadha
# *     IBM
# *****************************************************************************

   README

ICU4JNI Version 2.1

Contents

* Introduction
* License Information
* System Requirements
* Installation

Introduction

ICU4JNI contains Java Native Interface wrappers for ICU4C's character set conversion and collation libraries.
These wrappers provide increased performace of conversion and collation, and complete compatibility with ICU4C.

License Information

The ICU projects (ICU4C and ICU4J) have changed their licenses from the IPL (IBM Public License) to the X license. The X license is a non-viral and recommended free software license that is compatible with the GNU GPL license. This is effective starting with release 1.8.1 of ICU4C and release 1.3.1 of ICU4J. All previous ICU releases will continue to utilize the IPL. New ICU releases will adopt the X license. The users of previous releases of ICU will need to accept the terms and conditions of the X license in order to adopt the new ICU releases. The main effect of the change is to provide GPL compatibility. The X license is listed as GPL compatible, see the gnu page at http://www.gnu.org/philosophy/license-list.html#GPLCompatibleLicenses The text of the X license is available at http://www.x.org/terms.htm. The IBM version contains the essential text of the license, omitting the X-specific trademarks and copyright notices. For more details please see the press announcement and the Project FAQ.

System Requirements

 * JDK1.3
 * ICU4C built and installed

Systems Supported

Operating System	Compiler	Additional Requirements
AIX 5.1	xlC	gmake
Solaris 2.7	GCC	gmake
Win2000	CL	nmake

Installation

UNIX

1. Download and install ICU4C from http://oss.software.ibm.com/icu
2. Set the ICU_DATA environment variable if trying to build with ICU 1.8.1 or earlier. E.g. if ICU has been installed in /usr/local/lib:
      export ICU_DATA=/usr/local/lib/icu/<icu_version>/
3. Set the JAVA_HOME environment variable, e.g.:
      export JAVA_HOME=/java/jdk1.3
4. Run configure with prefix and jdk options, ./configure --prefix=<path to the directory where ICU is installed> --<enable/disable>-jdk14, e.g.:
      ./configure --prefix=/usr/local/ --enable-jdk14
5. Run make check to build and run tests

Win32

Make is configured to build with or without JDK 1.4, and with the ICU_DATA environment variable defined or not.

1. Download and install ICU4C from http://oss.software.ibm.com/icu
   If trying to build with ICU 1.8.1 or earlier, set the ICU_DATA environment variable, e.g:
      set ICU_DATA=<icu_dir>\source\data
   (or pass ICUBIN on the command line as described below)
2. Set the JAVA_HOME environment variable or pass JAVAPATH on the command
3. line., e.g.:
      set JAVA_HOME=c:\jdk1.3
4. Make sure the <icu_dir>\bin directory is in your path.
5. Ensure that your environment is set right for the C compilation. For Microsoft C
6. compilers, ensure that vcvars32.bat has been ran to set the environment variables.
7. Run nmake with the supplied win32 makefile. You can set the configuration option by defining CFG. Also, if ICU_DATA is not set, you can provide the path to the ICU bin directory by defining ICUBIN.
• To set configuration options define CFG to either Debug or Release, default is Debug
• If ICU_DATA is not set, define ICUBIN=<icu>/bin

For example:
   nmake /f makefile-win32 CFG="Debug" ICUBIN="c:\icu\bin"

For building with JDK 1.4 type the following command

nmake /f makefile-win32 CFG="Debug" ICUBIN="<location of ICU>\icu\bin" JDK14="TRUE" JAVAPATH="<location of JDK>\bin"

For building with JDK1.3 type the following command

nmake /f makefile-win32 CFG="Debug" ICUBIN="<location of ICU>\bin" JDK14="FALSE" JAVAPATH="<location of JDK>\bin"

8. The files are built in the <jniroot>/build directory. The test is com.ibm.icu4jni.test.TestAll. You must define the library path to point to the jni library, and set the classpath to point to the icu4jni class files. E.g.:
      java -Djava.library.path=c:\icu4jni\build\lib -classpath=c:\icu4jni\build\classes com.ibm.icu4jni.test.TestAll
   Alternatively, you can also run the test by making the 'check' target, e.g.:
      <full nmake command as described above> check

For Integrating into JVM only

 * Place the java source files in $(TARGETDIR)/com,i.e, <jdksource>/com
 * Add the following lines to <jdk>/make/mkinclude/java_java.jmk
  $(TARGDIR)com/ibm/icu4jni/ICUJNIInterface.java \
  $(TARGDIR)com/ibm/icu4jni/CharToByteConverterICU.java \
  $(TARGDIR)com/ibm/icu4jni/ByteToCharConverterICU.java \
  # the files below are test classes
  $(TARGDIR)com/ibm/icu4jni/ByteToCharGB18030.java \
  $(TARGDIR)com/ibm/icu4jni/CharToByteGB18030.java \
 * The JNI wrappers work under the assumption that ICU4C is available and installed on the target platform.
 * For adding additional codepages open CharacterEncoding.java in <jdksource>/sun/io directory and add the
   aliases to the converter
  for eg:
  For GB18030 support you add:
  aliasTable.put( "gb18030" , "GB18030");
  aliasTable.put( "gb-18030", "GB18030");
  aliasTable.put( "gb_18030", "GB18030");
  aliasTable.put( "GB-18030", "GB18030");
 * Compile JNI wrapper code into dll/so using a C compiler
 * Package the ICUJNIInterface.dll <jdkbuild>/<platform>/bin directory
 * Rebuild the JDK source