From f36331c1bfa4c4c202346b05dc3bd672f653e4df Mon Sep 17 00:00:00 2001 From: "Steven R. Loomis" Date: Fri, 22 Nov 2019 15:10:01 -0800 Subject: doc,deps: document how to maintain ICU in Node.js - update v8 guide to mention ICU - move content from the tools/icu/README.md but leave a pointer Fixes: https://github.com/nodejs/node/issues/26108 Co-Authored-By: Vse Mozhet Byt PR-URL: https://github.com/nodejs/node/pull/30607 Reviewed-By: Ujjwal Sharma Reviewed-By: Richard Lau Reviewed-By: Myles Borins --- tools/icu/README.md | 133 +++++++--------------------------------------------- 1 file changed, 18 insertions(+), 115 deletions(-) (limited to 'tools') diff --git a/tools/icu/README.md b/tools/icu/README.md index 89a70e7087..1af39941b5 100644 --- a/tools/icu/README.md +++ b/tools/icu/README.md @@ -1,8 +1,9 @@ # Notes about the `tools/icu` subdirectory -This directory contains tools, data, and information about the [ICU](http://icu-project.org) -(International Components for Unicode) integration. ICU is used to provide -internationalization functionality. +This directory contains tools, data, and information about the +International Components for Unicode integration. [ICU][] is used +both by V8 and also by +Node.js itself to provide internationalization functionality. * `patches/` are one-off patches, actually entire source file replacements, organized by ICU version number. @@ -18,119 +19,21 @@ internationalization functionality. * `README.md` — you are here * `shrink-icu-src.py` — this is used during upgrade (see guide below) -## How to upgrade ICU +Note: +> The files in this directory were written for the Node.js v0.12 effort. +> The original intent was to merge the tools such as `icutrim.py` and `iculslocs.cc` +> back into ICU. ICU has gained its own “data slicer” tool. +> There is an issue open, https://github.com/nodejs/node/issues/25136 +> for replacing `icutrim.py` with the [ICU data slicer][]. -* Make sure your Node.js workspace is clean (clean `git status`) should be - sufficient. -* Configure Node.js with the specific [ICU version](http://icu-project.org/download) - you want to upgrade to, for example: +## See Also -```shell -./configure \ - --with-intl=full-icu \ - --with-icu-source=http://download.icu-project.org/files/icu4c/58.1/icu4c-58_1-src.tgz -make -``` +* [docs/guides/maintaining-icu.md](../../doc/guides/maintaining-icu.md) for +information on maintaining ICU in Node.js -> _Note_ in theory, the equivalent `vcbuild.bat` commands should work also, -> but the commands below are makefile-centric. +* [docs/api/intl.md](../../doc/api/intl.md) for information on the +internationalization-related APIs in Node.js +* [The ICU Homepage][ICU] -* If there are ICU version-specific changes needed, you may need to make changes - in `icu-generic.gyp` or add patch files to `tools/icu/patches`. - * Specifically, look for the lists in `sources!` in the `icu-generic.gyp` for - files to exclude. - -* Verify the Node.js build works: - -```shell -make test-ci -``` - -Also running - - - -```js -new Intl.DateTimeFormat('es', {month: 'long'}).format(new Date(9E8)); -``` - -…Should return `enero` not `January`. - -* Now, copy `deps/icu` over to `deps/icu-small` - -```shell -python tools/icu/shrink-icu-src.py -``` - -* Now, do a clean rebuild of Node.js to test: - -```shell -make -k distclean -./configure -make -``` - -* Test this newly default-generated Node.js - - - -```js -process.versions.icu; -new Intl.DateTimeFormat('es', {month: 'long'}).format(new Date(9E8)); -``` - -(This should print your updated ICU version number, and also `January` again.) - -You are ready to check in the updated `deps/small-icu`. This is a big commit, -so make this a separate commit from the smaller changes. - -* Now, rebuild the Node.js license. - -```shell -# clean up - remove deps/icu -make clean -tools/license-builder.sh -``` - -* Update the URL and hash for the full ICU file in `tools/icu/current_ver.dep`. -It should match the ICU URL used in the first step. When this is done, the -following should build with small ICU. - -```shell -# clean up -rm -rf out deps/icu deps/icu4c* -./configure --with-intl=small-icu --download=all -make -make test-ci -``` - -* commit the change to `tools/icu/current_ver.dep` and `LICENSE` files. - - * Note: To simplify review, I often will “pre-land” this patch, meaning that - I run the patch through `curl -L https://github.com/nodejs/node/pull/xxx.patch - | git am -3 --whitespace=fix` per the collaborator’s guide… and then push that - patched branch into my PR's branch. This reduces the whitespace changes that - show up in the PR, since the final land will eliminate those anyway. - ------ - -## Postscript about the tools - -The files in this directory were written for the Node.js effort. -It was the intent of their author (Steven R. Loomis / srl295) to -merge them upstream into ICU, pending much discussion within the -ICU-TC. - -`icu_small.json` is somewhat node-specific as it specifies a "small ICU" -configuration file for the `icutrim.py` script. `icutrim.py` and -`iculslocs.cpp` may themselves be superseded by components built into -ICU in the future. As of this writing, however, the tools are separate -entities within Node.js, although theyare being scrutinized by interested -members of the ICU-TC. The “upstream” ICU bugs are given below. - -* [#10919](http://bugs.icu-project.org/trac/ticket/10919) - (experimental branch - may copy any source patches here) -* [#10922](http://bugs.icu-project.org/trac/ticket/10922) - (data packaging improvements) -* [#10923](http://bugs.icu-project.org/trac/ticket/10923) - (rewrite data building in python) +[ICU data slicer]: https://github.com/unicode-org/icu/blob/master/docs/userguide/icu_data/buildtool.md +[ICU]: http://icu-project.org -- cgit v1.2.3