[apple/icu.git] / icuSources / samples / legacy / README

Copyright (c) 2002, International Business Machines Corporation and others. All Rights Reserved.
This example demonstrates running an instance of  ICU 1.8.1. together with a current version of ICU. It only tests u_getVersion and several collation APIs. 

Generally, one should be able to simultaneously use one or more versions of ICU 2.0 or higher and one version of ICU 1.8.1 or lower. 

What is it all about: Let's say you have a 10 Tb database indexed using ICU 1.8.1. sortkeys. New ICU comes out, with neat new features you would like to use, but also with new sortkeys and you don't care to reindex your 10 Tb database. What to do then??? You can use ICU 1.8.1. in one of your compilation units and current version in all the others. So, you can use old collation until you decide to reindex. 

You cannot mix two versions of ICU in the same compilation unit. You cannot automatically use more than one legacy version of ICU.

In order to make the compilation unit use old version of ICU, you have to do a couple of things:
1) change it's include path so that it includes header files from the old versions
2) explicitly add old libraries to the linker.
3) make sure old data can be found (if legacy code needs data).

Building and running of the example:

Linux:
To make it work, you should build and install both the current ICU and ICU 1.8.1. Put both data libraries to wherever ICU_DATA points (usually it is $(prefix)/share/icu/$(icu_version)/). If data libraries are used, then check for $(prefix)/lib/icu/1.8.1 which should contain libicudata.so and libicudt18*.so
2. Copy libicuuc.so.18* and libicui18n.so.18* to $(prefix)/lib directory, together with current libraries). 
3. Should work on other Unixes.


Change $ICU_PREFIX to point to the current installation, and $ICU_LEGACY to point to 1.8.1 installation. $ICU_LEGACY is needed solely to access the 1.8.1 include directory through $LEGACY_INCLUDE variable, so if you want to move the 1.8.1. include directory, you can set $LEGACY_INCLUDE directly to that directory.

Run make check. You should get two different libraries running at the same time.

Win32:
Build both current ICU and ICU 1.8.1. Take icuuc18.dll, icuin18.dll and icudt18l.dll and put them somewhere in PATH (a sane place would be wherever current dlls go). 

Edit the include directory for oldcol.cpp so that it points to the include directory of ICU 1.8.1.
Edit the two library entries with path so that they point to .lib files for your version of ICU.

Hit F7, followed by ctrl-F5.

Troubleshooting (all platforms):
Sample won't compile: this is quite unlikely, but the most probable reason is that include files cannot be found. 
Sample won't link: The path for 1.8.1. libraries is broken. Edit it so that it  reflects the path to your libraries.
Linker says: "Undefined symbol u_getVersion()" (or something similar): path to 1.8.1. libraries is bad.
Linker says: "Undefined symbol u_getVersion()_X_Y" (or something similar): path to current libraries is bad.
Legacy crashes horribly: Sorry, didn't put any error checking. If legacy crashes that's most probably because it cannot find the data libraries. You can see which data library is not found by the part of the program that is running. Make sure program can find tha data library either by putting it where ever ICU_DATA points to OR by putting the DLL version of the data library somewhere on your PATH.
Commit	Line	Data
b75a7d8f A	1	Copyright (c) 2002, International Business Machines Corporation and others. All Rights Reserved.
	2	This example demonstrates running an instance of ICU 1.8.1. together with a current version of ICU. It only tests u_getVersion and several collation APIs.
	3
	4	Generally, one should be able to simultaneously use one or more versions of ICU 2.0 or higher and one version of ICU 1.8.1 or lower.
	5
	6	What is it all about: Let's say you have a 10 Tb database indexed using ICU 1.8.1. sortkeys. New ICU comes out, with neat new features you would like to use, but also with new sortkeys and you don't care to reindex your 10 Tb database. What to do then??? You can use ICU 1.8.1. in one of your compilation units and current version in all the others. So, you can use old collation until you decide to reindex.
	7
	8	You cannot mix two versions of ICU in the same compilation unit. You cannot automatically use more than one legacy version of ICU.
	9
	10	In order to make the compilation unit use old version of ICU, you have to do a couple of things:
	11	1) change it's include path so that it includes header files from the old versions
	12	2) explicitly add old libraries to the linker.
	13	3) make sure old data can be found (if legacy code needs data).
	14
	15	Building and running of the example:
	16
	17	Linux:
	18	To make it work, you should build and install both the current ICU and ICU 1.8.1. Put both data libraries to wherever ICU_DATA points (usually it is $(prefix)/share/icu/$(icu_version)/). If data libraries are used, then check for $(prefix)/lib/icu/1.8.1 which should contain libicudata.so and libicudt18*.so
	19	2. Copy libicuuc.so.18* and libicui18n.so.18* to $(prefix)/lib directory, together with current libraries).
	20	3. Should work on other Unixes.
	21
	22
	23	Change $ICU_PREFIX to point to the current installation, and $ICU_LEGACY to point to 1.8.1 installation. $ICU_LEGACY is needed solely to access the 1.8.1 include directory through $LEGACY_INCLUDE variable, so if you want to move the 1.8.1. include directory, you can set $LEGACY_INCLUDE directly to that directory.
	24
	25	Run make check. You should get two different libraries running at the same time.
	26
	27	Win32:
	28	Build both current ICU and ICU 1.8.1. Take icuuc18.dll, icuin18.dll and icudt18l.dll and put them somewhere in PATH (a sane place would be wherever current dlls go).
	29
	30	Edit the include directory for oldcol.cpp so that it points to the include directory of ICU 1.8.1.
	31	Edit the two library entries with path so that they point to .lib files for your version of ICU.
	32
	33	Hit F7, followed by ctrl-F5.
	34
	35	Troubleshooting (all platforms):
	36	Sample won't compile: this is quite unlikely, but the most probable reason is that include files cannot be found.
	37	Sample won't link: The path for 1.8.1. libraries is broken. Edit it so that it reflects the path to your libraries.
	38	Linker says: "Undefined symbol u_getVersion()" (or something similar): path to 1.8.1. libraries is bad.
	39	Linker says: "Undefined symbol u_getVersion()_X_Y" (or something similar): path to current libraries is bad.
	40	Legacy crashes horribly: Sorry, didn't put any error checking. If legacy crashes that's most probably because it cannot find the data libraries. You can see which data library is not found by the part of the program that is running. Make sure program can find tha data library either by putting it where ever ICU_DATA points to OR by putting the DLL version of the data library somewhere on your PATH.
	41