1#!/bin/cat 2# 3# Copyright (C) 2017 and later: Unicode, Inc. and others. 4# License & terms of use: http://www.unicode.org/copyright.html 5# 6# Copyright (c) 2009-2012 IBM Corp. and Others. All Rights Reserved 7 8# ICU Provider Feature. - $Id$ 9 10* Note, as of ICU49 this is a technology preview. 11 12BUILDING: 13 141a. Download the ICU source (.tgz) you wish to TARGET (i.e. link your 15application against). This must be the ICU49 branch 16http://source.icu-project.org/repos/icu/icu/branches/srl/ucol8157 at 17this writing. 18 191b. Download one or more ICUs (.tgz) you wish to have AVAILABLE (via 20the provider interface). As of this writing, 49, 4.8.1.1, 4.6.x, 4.4.x, 4.2.0.1, 3.8.1, 3.6, 3.4.1, and 3.2.1 have been tested. 21 22 Note that the MAJOR+MINOR version numbers must not conflict between the TARGET and AVAILABLE ICUs. Only one ICU of each major+minor is allowed. 23 So, only one 4.4.X, one 3.8.X, etc. This is due to ICU binary compatibility rules. 24 25 261c. Copy the ICUs (named as they were downloaded) into the ../../packages/ directory relative to this readme. 27 282a. Copy the file "Makefile.local-sample" into a new file "Makefile.local". 29 302b. Edit the Makefile.local to modify the PROVIDER_TARGET and 31PROVIDER_AVAILABLE settings. 32 33 Note that if you have a special installation of the current ICU 34 (ICU 49) that you want to be the target, you can set PLUGLIB_INST 35 to the installed ICU path. You must still set PROVIDER_TARGET. 36 373. Check the makefile settings by running 'make info', you should see output similar to the following: 38 39 ICU Provider Build 40 Targetting Provider against ICU 49 (49, major 49) 41 Available plugins: 3.8.1 4.2.0.1 (3_8_1 4_2_0_1) 42 Available keywords: 43 ...@provider=icu38 44 ...@provider=icu42 45 Plugin library will be libicuprov.49.so 46 47 Available ICU tarballs: icu4c-3_8_1-src.tgz icu4c-4_2_0_1-src.tgz icu4c-4_4_2-src.tgz 48 Available ICU versions: 3.8.1 4.2.0.1 4.4.2 49 50 51 The last two lines show which ICU .tgz files are available. If a version is not listed, make sure the filename is as above. 52 534. Now, you are ready to build and test. 54 55(Note: you can set the variables CC, CXX, CXXFLAGS, and CFLAGS to set 56the compiler options. ) 57 58 make check 59 60 This will take quite a while as it has to build N copies of ICU. 61 62 When done, it should show a list of collation keys, and indicate that there were differences between ICU 3.8, 4.4, 4.2. You may need to modify coldiff.cpp if you are using a different set of ICU versions. 63 645. You can test in an 'installed' ICU (not the system install) with this command: 65 66 make install-check 67 68DEPLOYING: 69 706. To install the plugin in your own ICU, copy out/icuplugins44.txt into your lib/icu, and out/lib/libicuprov.44.so into your lib/ directories where ICU is installed. 71 72 Note that running 'icuinfo' will tell you where the plugin file is expected to be located, and 'icuinfo -L' will debug any load issues. 73 74USING: 75 76Collators opened with an id such as that shown in 'make info', such as 'en_US@provider=icu38' will load, for example, an ICU 3.8 collator. 77 78Date Formats opened (udat_open) will also load a different date 79format, but only through 'udat_open'. 80 81 82 83 84--------------------------- 85THEORY (INTERNAL USE ONLY!) 86 87For discussion: assume TARGET 50.0.2 and PROVIDER 4.0.1 88 89i. GENERAL 90 91 The "front end" for each module (date, collator, ..) is built once for the target version, and the "back end" glue is built once for each provider version. (TODO: fix wording here.) 92 93 The oicu.h header, combined with the generated gluren.h, provides a "renamed" symbol such as (literally) OICU_ucol_strcoll which is #defined to some specific version, such as ucol_strcoll_4_0. So, you can call the OICU_ version meaning "Old ICU". Thus, you have the ICU 4.0 function defined as an extern, by its explicit name, within the ICU 50 space. 94 95 The icuglue/glver.h header file contains multiple calls to, for example, GLUE_VER(4_0_1) GLUE_VER(49_1_2) ... 96 A module can redefine GLUE_VER in order to do some "each-version" process. Thus, glver.h can be #included multiple times.. 97 98 Generally, a locale such as en_US@sp=icu40 will refer to an ICU 4.0 provider. 99 100 There are lots of version-specific #ifdefs used to deal with the vagaries of a decade of ICU changes. 101 102ii. COLLATORS 103 104 For each back end, there's an icu_50::Collator class named, say, glueCollator4_0_1 which is implemented in the TARGET space. However, each function of this class, such as "compare", is implemented by calling, for example, OICU_ucol_strcoll. As noted above, this is directly calling ucol_strcoll_4_0. This is where the cross-version calls happen. Such glue code must be very careful not to, for example, call ucol_open_4_0 and pass the result to ucol_close_50 ! 105 106 The FE builds a CollatorFactory subclass, VersionCollatorFactory. It registers a collator for every localeid it can support. This is done by calling each glueCollator* subclass's static ::countAvailable and appendAvailable functions directly. 107 108 The plugin simply registers and unregisters the VCF. Such collators are available to both C++ and C API, including the shortstring interface, using the _PICU## short string tag. 109 110iii. DATE FORMATTERS 111 112 Date formatters work in a similar fashion to collators. DateFormat subclasses are registered which are implemented in terms of OICU_udat_* functions. A "DateFormatOpener" (factory equivalent) is registered to allow udat_open to process correctly. C++ date format registration is not addressed as of this writing. 113 114 115