1Copyright (c) 2002, International Business Machines Corporation and others. All Rights Reserved.
2This 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
4Generally, 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
6What 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
8You cannot mix two versions of ICU in the same compilation unit. You cannot automatically use more than one legacy version of ICU.
9
10In order to make the compilation unit use old version of ICU, you have to do a couple of things:
111) change it's include path so that it includes header files from the old versions
122) explicitly add old libraries to the linker.
133) make sure old data can be found (if legacy code needs data).
14
15Building and running of the example:
16
17Linux:
18To 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
192. Copy libicuuc.so.18* and libicui18n.so.18* to $(prefix)/lib directory, together with current libraries).
203. Should work on other Unixes.
21
22
23Change $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
25Run make check. You should get two different libraries running at the same time.
26
27Win32:
28Build 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
30Edit the include directory for oldcol.cpp so that it points to the include directory of ICU 1.8.1.
31Edit the two library entries with path so that they point to .lib files for your version of ICU.
32
33Hit F7, followed by ctrl-F5.
34
35Troubleshooting (all platforms):
36Sample won't compile: this is quite unlikely, but the most probable reason is that include files cannot be found.
37Sample won't link: The path for 1.8.1. libraries is broken. Edit it so that it  reflects the path to your libraries.
38Linker says: "Undefined symbol u_getVersion()" (or something similar): path to 1.8.1. libraries is bad.
39Linker says: "Undefined symbol u_getVersion()_X_Y" (or something similar): path to current libraries is bad.
40Legacy 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
42