1 This directory contains tools for ICU updates. 2 3 Data update tools 4 ================= 5 6 updateicudata.py 7 - regerates the ICU data files. 8 ICU and CTS tests for libcore should be run before and 9 after. 10 11 See $ANDROID_BUILD_TOP/system/timezone for tools related to time zone updates. 12 13 Source code updates 14 =================== 15 16 The source code in android_icu4j is generated from the source code in icu4j. 17 18 Changes to upstream ICU4J can fall into one of three categories: 19 20 1) Back-ported upstream ICU patches or other ICU behavior changes made for Android that cannot be 21 upstreamed. 22 2) Mechanical changes related to ICU4J being repackaged on Android under android.icu, the exposure 23 of a subset of ICU in the Android SDK, or Android's platform or documentation build process. 24 3) JavaDoc patches to replace ICU documentation that is incorrect/confusing for Android developers. 25 26 Do not change the code in android_icu4j/src or android_icu4j/resources directly: instead you 27 change the icu4j source, the transformation rules used by currysrc or the javadoc patch files. 28 29 All changes made to icu4j should be accompanied by changes in android_icu4j and vice versa. 30 31 Regenerating android_icu4j 32 -------------------------- 33 34 After making changes (described below) the source code can be regenerated using: 35 36 source build/envsetup.sh 37 lunch 38 39 cd external/icu/tools/srcgen 40 ./generate_android_icu4j.sh 41 42 The code in android_icu4j will be regenerated and should contain the changes you made 43 in icu4j. Confirm the diffs are what you intended. Commit both at the same time. 44 45 Applying upstream and behavioral patches to ICU4J 46 ------------------------------------------------- 47 48 Upstream patches and other code changes that modify ICU4J behavior are made in the icu4j 49 source code before android_icu4j is generated. Apply ICU patches as normal and confirm that the 50 ICU tests pass. 51 52 Modifying the code gen 53 ---------------------- 54 55 android_icu4j is initially generated using a Java tool found in tools/srcgen. 56 57 The "rules" that transform the source are configured in 58 src/main/java/com/android/icu4j/srcgen/Icu4jTransform.java. 59 60 Adding a Javadoc local patch 61 ---------------------------- 62 63 ICU4J has Javadoc patches specific to Android only and they can't be upstreamed. 64 65 To reduce the maintenance cost of reapplying these changes when we upgrade ICU we store the patches 66 in the javadoc_patches directory. The use of the patch command also helps detect when changes 67 have been made to the upstream documentation being replaced that might otherwise be missed. 68 69 Changes are stored in separate files, one for each source file. This avoids maintaining a monolithic 70 patch file. 71 72 Javadoc changes are applied by the generate_android_icu4j.sh script automatically during post-srcgen 73 step. 74 75 WARNING: DO NOT add any behavioral changes in these patches. Behavioral code changes should be made 76 to icu4j directly. 77 78 To add a new Javadoc local patch: 79 80 1. Run ./generate_android_icu4j.sh 81 2. Use your IDE to change the required javadoc under android_icu4j 82 3. Run javadoc_patches/create_patches_i.sh 83 4. Run ./generate_android_icu4j.sh again 84 85 Re-generate all javadoc patches 86 ------------------------------- 87 88 If you want to regenerate all of the Javadoc patch files you can do so by running: 89 90 ./javadoc_patches/create_patches.sh 91 92