387 lines
17 KiB
HTML
387 lines
17 KiB
HTML
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
||
<html>
|
||
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||
<title>ReadMe for ICU4J</title>
|
||
</head>
|
||
|
||
<body bgcolor="#FFFFFF" link="#0000FF" vlink="#800080" lang="EN-US">
|
||
|
||
<h2>ReadMe: International Components for Unicode for Java</h2>
|
||
|
||
<p>Version: 1.3 Mar 23 2001 </p>
|
||
|
||
<hr size="2" width="100%" align="center">
|
||
|
||
<p>COPYRIGHT: <br>
|
||
Copyright (c) 2001 International Business Machines Corporation and others. All Rights
|
||
Reserved. </p>
|
||
|
||
<hr size="2" width="100%" align="center">
|
||
|
||
<h3><u>Contents</u></h3>
|
||
|
||
<ul type="disc">
|
||
<li><a href="#introduction">Introduction</a></li>
|
||
<li><a href="#WhatContain">What the International Components for Unicode for Java Contains</a></li>
|
||
<li><a href="#API">API overview</a></li>
|
||
<li><a href="#PlatformDependencies">Platform Dependencies</a></li>
|
||
<li><a href="#HowToInstallJavac">How to Install and Build</a></li>
|
||
<li><a href="#WhereToFindMore">Where to Find More Information</a></li>
|
||
<li><a href="#SubmittingComments">Submitting Comments, Requesting Features and Reporting
|
||
Bugs</a></li>
|
||
</ul>
|
||
|
||
<h3><a NAME="introduction"></a><u>Introduction</u></h3>
|
||
|
||
<p>Today's software market is a global one in which it is desirable to develop and
|
||
maintain one application that supports a wide variety of national languages. International
|
||
Components for Unicode for Java provides the following tools to help you write language
|
||
independent applications:
|
||
|
||
<ul type="disc">
|
||
<li>International Calendars – Arabic, Buddhist, Hebrew, Japanese</li>
|
||
<li>Unicode Normalization – Canonical text representation for W3C</li>
|
||
<li>Number Format Enhancements – Scientific Notation, Spelled-out, ...</li>
|
||
<li>Enhanced word-break detection – Rule-based, supports Thai</li>
|
||
<li>Unicode Text Searching – Efficient multi-lingual searching</li>
|
||
<li>Unicode Text Compression – 2:1 compression on English Unicode text</li>
|
||
</ul>
|
||
|
||
<p>Your comments are important to making this release successful. We are committed
|
||
to fixing any bugs, and will also use your feedback to help plan future releases. </p>
|
||
|
||
<p><b><u>IMPORTANT</u>: Please make sure you understand the <a href="license.html">Copyright
|
||
and License information</a>.</b></p>
|
||
|
||
<h3><a NAME="WhatContain"></a><u>What the International Components for Unicode for Java
|
||
Contains</u></h3>
|
||
|
||
<p>There are two ways to download the ICU4J releases,
|
||
|
||
<ul type="disc">
|
||
<li><b>Official Release Snapshot:</b><br>
|
||
If you want to use ICU4J (as opposed to developing it), your best bet is to download an
|
||
official, packaged ICU4J version of the ICU4J source code. These versions are tested
|
||
more thoroughly than day-to-day development builds, and they are packaged in zip and tar
|
||
files for convenient download. These packaged files can be found at <a
|
||
href="http://oss.software.ibm.com/developerworks/opensource/icu4j/download/index.html">http://oss.software.ibm.com/developerworks/opensource/icu4j/download/index.html</a>.
|
||
<br>
|
||
If packaged snapshot is named <b>ICU4JXXXXXX.zip </b>, XXXXXX is the release version
|
||
number. <br>
|
||
Please unzip this file. It will re-construct the source directory. </li>
|
||
</ul>
|
||
|
||
<ul type="disc">
|
||
<li><b>CVS Source Repository:</b><br>
|
||
If you are interested in developing features, patches, or bug fixes for ICU4J, you should
|
||
probably be working with the latest version of the ICU4J source code. You will need to
|
||
check the code out of our CVS repository to ensure that you have the most recent version
|
||
of all of the files. There are several ways to do this: <br>
|
||
<ul type="circle">
|
||
<li>WebCVS:<br>
|
||
If you want to browse the code and only make occasional downloads, you may want to use
|
||
WebCVS. It provides a convenient, web-based interface for browsing and downloading the
|
||
latest version of the ICU4J source code and documentation. You can also view each file's
|
||
revision history, display the differences between individual revisions, determine which
|
||
revisions were part of which official release, and so on. <br>
|
||
</li>
|
||
<li>WinCVS:<br>
|
||
If you will be doing serious work on ICU4J, you should probably install a CVS client on
|
||
your own machine so that you can do batch operations without going through the WebCVS
|
||
interface. On Windows, we suggest the WinCVS client. The following is the example
|
||
instruction on how to download ICU4J via WinCVS: <ol>
|
||
<li>Install the WinCVS client, which you can download from the <a
|
||
href="http://www.wincvs.org">http://www.wincvs.org</a>.</li>
|
||
<li>Select <strong>Preferences</strong> from the <strong>Admin</strong> menu.<ol type="a">
|
||
<li>On the <strong>General</strong> tab panel: Set your <strong>CVSROOT</strong> to "<strong>:pserver:anoncvs@oss.software.ibm.com:/usr/cvs/icu4j</strong>".<br>
|
||
Leave other options on this page at their default.</li>
|
||
<li>On the <strong>Ports</strong> tab panel: Check the <strong>pserver</strong> checkbox and
|
||
enter port <strong>2401</strong>.</li>
|
||
</ol>
|
||
</li>
|
||
<li>Click on the Login menu button (<strong>Admin</strong> menu). Enter in "<strong>anoncvs</strong>" when requested.</li>
|
||
<li>To extract the most recent version of ICU4J, select <strong>Checkout module</strong>
|
||
from the <strong>Create</strong> menu. Specify "<strong>icu4j</strong>" for the
|
||
module name. This will create a new copy of the workspace on your local hard drive.</li>
|
||
<li>In the future, you can download updated files from the repository to your hard drive
|
||
using the <strong>Update selection</strong> item in the <strong>Modify</strong> menu.<br>
|
||
</li>
|
||
</ol>
|
||
</li>
|
||
<li>CVS command line:<br>
|
||
You can also check out the repository anonymously on UNIX using the following commands,
|
||
after first setting your CVSROOT to point to the ICU4J repository: <pre><code>export CVSROOT=:pserver:anoncvs@oss.software.ibm.com:/usr/cvs/icu4j
|
||
cvs login CVS password: anoncvs
|
||
cvs checkout icu4j
|
||
cvs logout</code></pre>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<p>For more details on how to download ICU4J directly from the web site, please also see <a
|
||
href="/developerworks/opensource/icu4j/download/index.html">http:/oss.software.ibm.com/developerworks/opensource/icu4j/download/index.html</a>
|
||
</p>
|
||
|
||
<p>Below, <b>$Root</b> is the placement of the icu directory in your file system, like
|
||
"drive:\...\icu4j" in your environment. "drive:\..." stands for any
|
||
drive and any directory on that drive that you chose to install icu4j into. </p>
|
||
|
||
<p><b>The following files describe the code drop:</b></p>
|
||
|
||
<table BORDER="1" CELLPADDING="0">
|
||
<tr>
|
||
<td>readme.html (this file)</td>
|
||
<td>describes the International Components for Unicode for Java</td>
|
||
</tr>
|
||
<tr>
|
||
<td>license.html</td>
|
||
<td>contains IBM's public license</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p><b>The source directories mirror package structure of the code. The following
|
||
directories contain source code and data files:</b> </p>
|
||
|
||
<table BORDER="1" CELLPADDING="0" WIDTH="623">
|
||
<tr>
|
||
<td WIDTH="20%">$Root/src/data/</td>
|
||
<td WIDTH="80%">Various data files used to generate ICU4J classes. Most of the files
|
||
contain Unicode information that is available from <a href="http://www.unicode.org/">http://www.unicode.org/</a>.
|
||
Used only by tools in the src/com/ibm/tools.</td>
|
||
</tr>
|
||
<tr>
|
||
<td WIDTH="20%">$Root/src/com/ibm/demo</td>
|
||
<td WIDTH="80%">Demonstration applications and Applets.</td>
|
||
</tr>
|
||
<tr>
|
||
<td WIDTH="20%">$Root/src/com/ibm/test</td>
|
||
<td WIDTH="80%">Tests for various ICU4J components.. For information about running the
|
||
tests, see <a href="../../../../icu4j/icu4jhtml/com/ibm/test/topleveltest/TestAll.html">$Root/doc/com/ibm/test/TestAll.html</a>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td WIDTH="20%">$Root/src/com/ibm/tools</td>
|
||
<td WIDTH="80%">Various tools used to generate ICU4J classes.</td>
|
||
</tr>
|
||
<tr>
|
||
<td WIDTH="20%">$Root/src/com/ibm/text</td>
|
||
<td WIDTH="80%">The following components: <ul>
|
||
<li>RuleBasedBreakIterator</li>
|
||
<li>DictionaryBasedBreakIterator</li>
|
||
<li>Transliterator</li>
|
||
<li>Normalizer</li>
|
||
<li>BigNumberFormat</li>
|
||
<li>StringSearch</li>
|
||
<li>Unicode compression</li>
|
||
</ul>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td WIDTH="20%">$Root/src/com/ibm/util</td>
|
||
<td WIDTH="80%">Calendars and Holidays</td>
|
||
</tr>
|
||
<tr>
|
||
<td WIDTH="20%">$Root/build</td>
|
||
<td WIDTH="80%">Additional classes needed to build using Ant</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p><b>The following directories are populated when you've built everything:</b> </p>
|
||
|
||
<table BORDER="1" CELLPADDING="0">
|
||
<tr>
|
||
<td>$Root/classes/</td>
|
||
<td>contains all class files</td>
|
||
</tr>
|
||
<tr>
|
||
<td>$Root/docs</td>
|
||
<td>contains JavaDoc for all packages</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p><b>Data organization:</b> </p>
|
||
|
||
<p>Data is stored in various locations in ICU4J:
|
||
|
||
<ul>
|
||
<li>Data that is "raw" data goes into <strong>$Root/src/data</strong>. This
|
||
includes things like the raw Unicode database. <strong>$Root/src/data</strong> does <em>not</em>
|
||
contain <strong>.java</strong> source files.</li>
|
||
<li>Data that is in the form of a Java class, typically a ResourceBundle, but not
|
||
necessarily, goes into one of the packages <code>com.ibm.util.resources</code> or <code>com.ibm.text.resources</code>,
|
||
depending on whether the associated code lives in <code>com.ibm.util</code> or <code>com.ibm.text</code>.</li>
|
||
<li>Data that is not part of ICU4J proper (or its base tool set), but rather part of a test,
|
||
sample, or demo, should go near the source code of its owner. This makes it easy to ship a
|
||
core ICU4J release without optional components.</li>
|
||
</ul>
|
||
|
||
<h3><u><a name="API"></a>API Overview</u></h3>
|
||
|
||
<p>The complete API documentation is available on the ICU4J web site:
|
||
|
||
<ul>
|
||
<li><a href="../../../../icu4j/icu4jhtml/index.html">Complete index</a></li>
|
||
<li>International Calendars – <a href="../../../../icu4j/icu4jhtml/com/ibm/util/IslamicCalendar.html">Islamic</a>,
|
||
<a href="../../../../icu4j/icu4jhtml/com/ibm/util/BuddhistCalendar.html">Buddhist</a>, <a
|
||
href="../../../../icu4j/icu4jhtml/com/ibm/util/HebrewCalendar.html">Hebrew</a>, <a
|
||
href="../../../../icu4j/icu4jhtml/com/ibm/util/JapaneseCalendar.html">Japanese</a></li>
|
||
<li><a href="../../../../icu4j/icu4jhtml/com/ibm/text/Normalizer.html">Unicode Normalization</a> –
|
||
Canonical text representation for W3C</li>
|
||
<li><a href="../../../../icu4j/icu4jhtml/com/ibm/text/NumberFormat.html">Number Format Enhancements</a> –
|
||
Scientific Notation, Spelled-out, ...</li>
|
||
<li><a href="../../../../icu4j/icu4jhtml/com/ibm/text/BreakIterator.html">Enhanced word-break detection</a>
|
||
– Rule-based, supports Thai</li>
|
||
<li><a href="../../../../icu4j/icu4jhtml/com/ibm/text/StringSearch.html">Unicode Text Searching</a> –
|
||
Efficient multi-lingual searching</li>
|
||
<li>Unicode Text <a href="../../../../icu4j/icu4jhtml/com/ibm/text/UnicodeCompressor.html">Compression</a> &
|
||
<a href="../../../../icu4j/icu4jhtml/com/ibm/text/UnicodeDecompressor.html">Decompression</a> – 2:1
|
||
compression on English Unicode text</li>
|
||
</ul>
|
||
|
||
<h3><a NAME="PlatformDependencies"></a><u>Platform Dependencies</u></h3>
|
||
|
||
<p>Parts of ICU4J depend on functionality that is only available in Java2 (JDk1.2) or
|
||
later, although some components work under 1.1. However, all components should be
|
||
compiled using a Java2 compiler as even components that run using a 1.1.x JVM may require
|
||
language features that are only present in 1.2. Currently 1.1.x is unsupported and
|
||
untested and you use the components on a 1.1.x system at your own risk. </p>
|
||
|
||
<h3><a NAME="HowToInstallJavac"></a><u>How to Install and Build</u></h3>
|
||
|
||
<p>To install ICU4J, simply place the prebuilt jar file <strong>icu4j.jar</strong> on your
|
||
Java CLASSPATH. No other files are needed.</p>
|
||
|
||
<p>The prerequisites for building ICU4J are a working JDK and the Ant build system:
|
||
|
||
<ul>
|
||
<li>First install a recent JDK, at least version 1.2.</li>
|
||
<li>Next install the <a href="http://jakarta.apache.org/ant/"><strong>Ant</strong></a> build
|
||
system, part of the Apache Software Foundation's <a href="http://jakarta.apache.org/"><strong>Jakarta</strong></a>
|
||
project. Ant is a portable, Java-based build system similar to make. ICU4J uses Ant
|
||
because it introduces no other dependencies, it's portable, and it's easier to manage than
|
||
a collection of makefiles. We currently build ICU4J using a single makefile on both
|
||
Windows 9x and Linux using Ant.</li>
|
||
<li>Installing Ant is straightforward. Download it (see <a
|
||
href="http://jakarta.apache.org/downloads/binindex.html">http://jakarta.apache.org/downloads/binindex.html</a>),
|
||
extract it onto your system, set some environment variables, and add its bin directory to
|
||
your path. For example:<pre> set JAVA_HOME=C:\jdk1.2.2
|
||
set ANT_HOME=C:\jakarta-ant
|
||
set PATH=%PATH%;%ANT_HOME%\bin
|
||
call antsetup</pre>
|
||
<p>See the current Ant documentation for details.</p>
|
||
</li>
|
||
<li>It's recommended to install both the JDK and Ant somewhere <em>outside</em> the ICU4J
|
||
directory, to keep them out of CVS's hair. For example, on Linux you might install these
|
||
in /usr/local.</li>
|
||
</ul>
|
||
|
||
<p>Once Ant is installed, building is just a matter of typing <strong>ant</strong> in the
|
||
ICU4J root directory. This causes the Ant build system to perform a build as specified by
|
||
the file <strong>build.xml</strong>, located in the ICU4J root directory. You can give Ant
|
||
options like -verbose, and you can specify targets. Ant will only build what's been
|
||
changed and will resolve dependencies properly.</p>
|
||
|
||
<blockquote>
|
||
<pre>F:\icu4j>ant tests
|
||
Buildfile: build.xml
|
||
Project base dir set to: F:\icu4j
|
||
Executing Target: core
|
||
Compiling 71 source files to F:\icu4j\classes
|
||
Executing Target: tests
|
||
Compiling 24 source files to F:\icu4j\classes
|
||
Completed in 19 seconds</pre>
|
||
</blockquote>
|
||
|
||
<p>Current targets that you can give after <strong>ant</strong>:</p>
|
||
<div align="left">
|
||
|
||
<table border="1" cellpadding="0">
|
||
<tr>
|
||
<td>all</td>
|
||
<td>Build all targets.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>core</td>
|
||
<td>Build the main class files in the subdirectory <strong>classes</strong>. If no target
|
||
is specified, core is assumed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tests</td>
|
||
<td>Build the test class files.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>demos</td>
|
||
<td>Build the demos.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tools</td>
|
||
<td>Build the tools.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>docs</td>
|
||
<td>Run javadoc over the main class files, generating an HTML documentation tree in the
|
||
subdirectory <strong>docs</strong>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>jar</td>
|
||
<td>Create a jar archive <strong>icu4j.jar</strong> in the root ICU4J directory containing
|
||
the main class files.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>zip</td>
|
||
<td>Create a zip archive of the source, docs, and jar file for distribution, excluding
|
||
unwanted things like CVS directories and emacs backup files. The zip file <strong>icu4jYYYYMMDD.zip</strong>
|
||
will be created in the directory <em>above</em> the root ICU4J directory, where YYYYMMDD
|
||
is today's date. Any existing file of that name will be overwritten.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>zipsrc</td>
|
||
<td>Like the <strong>zip</strong> target, without the docs and the jar file. The zip file <strong>icu4jsrcYYYYMMDD.zip</strong>
|
||
will be created in the directory <em>above</em> the root ICU4J directory.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>clean</td>
|
||
<td>Remove all built targets, leaving the source.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
|
||
<p>For more information, read the Ant documentation and the <strong>build.xml</strong>
|
||
file.</p>
|
||
|
||
<p>After doing a build it is a good idea to run all the tests by typeing "java
|
||
-classpath classes com.ibm.test.TestAll". </p>
|
||
|
||
<p>(As an alternative to using Ant, you can build simply by running javac and javadoc
|
||
directly. This is not recommended, but a Windows batch file "buildall.bat"
|
||
exists to get you started if you're really allergic to build systems. You may have to
|
||
create destination directories.)</p>
|
||
|
||
<h3><a name="WhereToFindMore"></a><u>Where to Find More Information</u></h3>
|
||
|
||
<p><a href="http://oss.software.ibm.com/icu4j">http://oss.software.ibm.com/icu4j</a> is a
|
||
pointer to general information about the International Components for Unicode in Java </p>
|
||
|
||
<p><a href="http://www.ibm.com/developer/unicode">http://www.ibm.com/developer/unicode</a> is a pointer to
|
||
information on how to make applications global. </p>
|
||
|
||
<h3><a NAME="SubmittingComments"></a><u>Submitting Comments, Requesting Features and
|
||
Reporting Bugs</u></h3>
|
||
|
||
<p>To submit comments, request features and report bugs, contact us through the <a href=http://oss.software.ibm.com/icu4j/archives/index.html>ICU4J mailing list</a>.<br>
|
||
While we are not able to respond individually to each comment, we do review all comments. </p>
|
||
|
||
<hr size="2" width="100%" align="center">
|
||
|
||
<p>Copyright <20> 2001 International Business Machines Corporation and others. All Rights
|
||
Reserved. <br>
|
||
IBM Center for Java Technology Silicon Valley, <br>
|
||
10275 N De Anza Blvd., Cupertino, CA 95014 <br>
|
||
All rights reserved. </p>
|
||
|
||
<hr size="2" width="100%" align="center">
|
||
</body>
|
||
</html>
|