1<!-- 2© 2020 and later: Unicode, Inc. and others. 3License & terms of use: http://www.unicode.org/copyright.html 4--> 5 6# Updating Measure Unit with new CLDR data 7 8This document explains how to update the C++ and Java version of the MeasureUnit 9class with new CLDR data. 10 11Code is generated by running MeasureUnitTest.java unit tests, which writes 12generated code to System.out. Two ways to access this: 13 141. Within **eclipse**: 15 - Open MeasureUnitTest.java, run it by clicking on the green play button on 16 menu bar. 17 - Copy the generated code from the eclipse console to the clipboard. 18 192. With **ant**: 20 - Run: `ant checkTest 21 -Dtestclass='com.ibm.icu.dev.test.format.MeasureUnitTest'` 22 - Open the checkTest output: `out/junit-results/checkTest/html/index.html` 23 - Navigate to "System.out" at the bottom of the MeasureUnitTest page to find 24 the generated code, and copy to the clipboard. 25 26After syncing CLDR data with ICU do the following. This documentation assumes 27that you are updating the MeasureUnit clases for ICU 68. 28 29* Check out 30 $GIT_ROOT/icu4j/main/tests/core/src/com/ibm/icu/dev/test/format/MeasureUnitTest.java 31* Open MeasureUnitTest.java. 32* Find the `testZZZ` test, its code should all be commented out. This test will 33 execute last and will run the desired code. 34 35 Make sure DRAFT_VERSIONS at top of MeasureUnitTest.java is set correctly. 36 These are the ICU versions that have draft methods. 37 38## Update MeasureUnit.java 39 40* Change `testZZZ` to run `generateConstants(“68”); // ICU 68.` 41* Run MeasureUnitTest.java, copy the generated code (see instructions above). 42* Open MeasureUnit.java: 43 $GIT_ROOT/icu4j/main/classes/core/src/com/ibm/icu/util/MeasureUnit.java 44* Look for line containing: 45 46 `// Start generated MeasureUnit constants` 47* Look for line containing: 48 49 `// End generated MeasureUnit constants` 50* Replace all the generated code in between with the contents of the clipboard 51* Run the MeasureUnitTest.java to ensure that the new code is backward 52 compatible. These compatibility tests are called something like 53 `TestCompatible65`, which tests backward compatibility with ICU 65. 54* Create a compatibility test for ICU 68. Change `testZZZ` to run 55 `generateBackwardCompatibilityTest(“68”)` 56* Run tests. 57* Copy generated test (see instructions above) into MeasureUnitTest.java 58* Run tests again to ensure that new code is backward compatible with itself 59 60## Update ICU4C 61 62* checkout ICU4C 63 64### Update measunit.h 65 66* Change testZZZ to run `generateCXXHConstants(“68”); // ICU 68`. 67* Run MeasureUnitTest.java, copy the generated code (see instructions above). 68* Open $GIT_ROOT/icu4c/source/i18n/unicode/measunit.h. Look for line containing: 69 70 `// Start generated createXXX methods` 71* Look for line: 72 73 `// End generated createXXX methods` 74* Replace all the generated code in between with the contents of the clipboard 75 76### Update measunit.cpp 77 78* Change testZZZ to run generateCXXConstants(); 79* Run MeasureUnitTest.java, copy the generated code (see instructions above). 80* Open $GIT_ROOT/icu4c/source/i18n/measunit.cpp. Look for line containing: 81 82 `// Start generated code for measunit.cpp` 83* Look for lines 84 85 `// End generated code for measunit.cpp` 86* Replace all the generated code in between with the contents of the clipboard 87 88### Run C++ tests 89 90* Run `./intltest format/MeasureFormatTest` from `test/intltest` to ensure new 91 code is backward compatible. 92* Create a compatibility test for ICU 68. Change `testZZZ` in eclipse to run 93 `generateCXXBackwardCompatibilityTest(“68”)` 94* Run tests. 95* Copy generated test (see instructions above) into 96 $GIT_ROOT/icu4c/source/test/intltest/measfmttest.cpp. Make other necessary 97 changes to make test compile. You can find these changes by searching for 98 `TestCompatible65()` 99* Run tests again to ensure that new code is backward compatible with itself 100 101## Finishing changes 102 103These last changes are necessary to permanently record the ICU version number of 104any new measure units. Without these changes any new functions for this release 105will be considered new for the next release too. 106 107* Change `testZZZ` to run `updateJAVAVersions(“68”);` 108* Run MeasureUnitTest.java, copy the generated code (see instructions above). 109* Append the clipboard contents to the values of the JAVA_VERSIONS variable 110 near the top of MeasureUnitTest.java. 111 112 **Important:** what you are copying are just the new functions for the current 113 ICU version, in this case 68. Therefore append, do not replace. 114 115## Updating units.txt and unitConstants 116 117The standard ldml2icu process is used to update ICU's resource files (see 118[cldr-icu-readme.txt](https://github.com/unicode-org/icu/blob/master/icu4c/source/data/cldr-icu-readme.txt)). 119CLDR's units.xml defines conversion rates in terms of some constants defined in 120`unitConstants`. 121 122For efficiency and simplicity, ICU does not read `unitConstants` from the 123resource file. If any new constants are added, some code changes would be 124needed. This would be caught by `testUnitConstantFreshness` unit test in 125`units_test.cpp`. 126 127They are hard-coded: 128* Java: `UnitConverter.java` has the constant names in 129 `UnitConverter.Factor.addEntity()` and constant values in 130 `UnitConverter.Factor.getConversionRate()`. 131* C++: `units_converter.cpp` has the constant names in 132 `addSingleFactorConstant()`, with the constant values in `double 133 constantsValues[]` in the `units_converter.h` header file. 134