1# Notes about the `tools/icu` subdirectory 2 3This directory contains tools, data, and information about the [ICU](http://icu-project.org) 4(International Components for Unicode) integration. ICU is used to provide 5internationalization functionality. 6 7* `patches/` are one-off patches, actually entire source file replacements, 8 organized by ICU version number. 9* `icu_small.json` controls the "small" (English only) ICU. It is input to 10 `icutrim.py` 11* `icu-generic.gyp` is the build file used for most ICU builds within ICU. 12 <!-- have fun --> 13* `icu-system.gyp` is an alternate build file used when `--with-intl=system-icu` 14 is invoked. It builds against the `pkg-config` located ICU. 15* `iculslocs.cc` is source for the `iculslocs` utility, invoked by `icutrim.py` 16 as part of repackaging. Not used separately. See source for more details. 17* `no-op.cc` — empty function to convince gyp to use a C++ compiler. 18* `README.md` — you are here 19* `shrink-icu-src.py` — this is used during upgrade (see guide below) 20 21## How to upgrade ICU 22 23* Make sure your Node.js workspace is clean (clean `git status`) should be 24 sufficient. 25* Configure Node.js with the specific [ICU version](http://icu-project.org/download) 26 you want to upgrade to, for example: 27 28```bash 29./configure \ 30 --with-intl=small-icu \ 31 --with-icu-source=http://download.icu-project.org/files/icu4c/58.1/icu4c-58_1-src.tgz 32make 33``` 34 35> _Note_ in theory, the equivalent `vcbuild.bat` commands should work also, 36> but the commands below are makefile-centric. 37 38* If there are ICU version-specific changes needed, you may need to make changes 39 in `icu-generic.gyp` or add patch files to `tools/icu/patches`. 40 * Specifically, look for the lists in `sources!` in the `icu-generic.gyp` for 41 files to exclude. 42 43* Verify the Node.js build works: 44 45```bash 46make test-ci 47``` 48 49Also running 50 51<!-- eslint-disable strict --> 52 53```js 54new Intl.DateTimeFormat('es', {month: 'long'}).format(new Date(9E8)); 55``` 56 57…Should return `January` not `enero`. 58 59* Now, copy `deps/icu` over to `deps/icu-small` 60 61```bash 62python tools/icu/shrink-icu-src.py 63``` 64 65* Now, do a clean rebuild of Node.js to test: 66 67```bash 68make -k distclean 69./configure 70make 71``` 72 73* Test this newly default-generated Node.js 74 75<!-- eslint-disable strict --> 76 77```js 78process.versions.icu; 79new Intl.DateTimeFormat('es', {month: 'long'}).format(new Date(9E8)); 80``` 81 82(This should print your updated ICU version number, and also `January` again.) 83 84You are ready to check in the updated `deps/small-icu`. This is a big commit, 85so make this a separate commit from the smaller changes. 86 87* Now, rebuild the Node.js license. 88 89```bash 90# clean up - remove deps/icu 91make clean 92tools/license-builder.sh 93``` 94 95* Update the URL and hash for the full ICU file in `tools/icu/current_ver.dep`. 96It should match the ICU URL used in the first step. When this is done, the 97following should build with full ICU. 98 99```bash 100# clean up 101rm -rf out deps/icu deps/icu4c* 102./configure --with-intl=full-icu --download=all 103make 104make test-ci 105``` 106 107* commit the change to `tools/icu/current_ver.dep` and `LICENSE` files. 108 109 * Note: To simplify review, I often will “pre-land” this patch, meaning that 110 I run the patch through `curl -L https://github.com/nodejs/node/pull/xxx.patch 111 | git am -3 --whitespace=fix` per the collaborator’s guide… and then push that 112 patched branch into my PR's branch. This reduces the whitespace changes that 113 show up in the PR, since the final land will eliminate those anyway. 114 115----- 116 117## Postscript about the tools 118 119The files in this directory were written for the Node.js effort. 120It was the intent of their author (Steven R. Loomis / srl295) to 121merge them upstream into ICU, pending much discussion within the 122ICU-TC. 123 124`icu_small.json` is somewhat node-specific as it specifies a "small ICU" 125configuration file for the `icutrim.py` script. `icutrim.py` and 126`iculslocs.cpp` may themselves be superseded by components built into 127ICU in the future. As of this writing, however, the tools are separate 128entities within Node.js, although theyare being scrutinized by interested 129members of the ICU-TC. The “upstream” ICU bugs are given below. 130 131* [#10919](http://bugs.icu-project.org/trac/ticket/10919) 132 (experimental branch - may copy any source patches here) 133* [#10922](http://bugs.icu-project.org/trac/ticket/10922) 134 (data packaging improvements) 135* [#10923](http://bugs.icu-project.org/trac/ticket/10923) 136 (rewrite data building in python) 137