README.txt
1*********************************************************************
2*** © 2019 and later: Unicode, Inc. and others. ***
3*** License & terms of use: http://www.unicode.org/copyright.html ***
4*********************************************************************
5
6Basic instructions for running the LdmlConverter via Maven
7==========================================================
8
9Requirements
10------------
11
12* A CLDR release for supplying CLDR data and the CLDR API.
13* The Maven build tool
14* The Ant build tool
15
16Important directories
17---------------------
18
19TOOLS_ROOT: Path to root of ICU tools directory, below which are (e.g.) the
20 cldr/ and unicodetools/ directories.
21
22CLDR_DIR: This is the path to the to root of standard CLDR sources, below
23 which are the common/ and tools/ directories.
24
25CLDR_DATA_DIR: The top-level directory for the CLDR production data (typically
26 the "production" directory in the staging repository). Usually
27 generated locally or obtained from:
28 https://github.com/unicode-org/cldr-staging/tree/main/production
29
30In Posix systems, it's best to set these as exported shell variables, and any
31following instructions assume they have been set accordingly:
32
33$ export TOOLS_ROOT=/path/to/icu/tools
34$ export CLDR_DIR=/path/to/cldr
35$ export CLDR_DATA_DIR=/path/to/cldr-staging/production
36
37Note that you should not attempt to use data from the CLDR project directory
38(where the CLDR API code exists) for conversion into ICU data. The process now
39relies on a pre-processing step, and the CLDR data must come from the separate
40"staging" repository (i.e. https://github.com/unicode-org/cldr-staging) or be
41pre-processed locally into a different directory.
42
43
44Initial Setup
45-------------
46
47This project relies on the Maven build tool for managing dependencies and uses
48Ant for configuration purposes, so both will need to be installed. On a Debian
49based system, this should be as simple as:
50
51$ sudo apt-get install maven ant
52
53You must also install an additional CLDR JAR file the local Maven repository at
54$TOOLS_ROOT/cldr/lib (see the README.txt in that directory for more
55information).
56
57$ cd "$TOOLS_ROOT/cldr/lib"
58$ ./install-cldr-jars.sh "$CLDR_DIR"
59
60
61Generating all ICU data and source code
62---------------------------------------
63
64$ cd "$TOOLS_ROOT/cldr/cldr-to-icu"
65$ ant -f build-icu-data.xml
66
67
68Other Examples
69--------------
70
71* Outputting a subset of the supplemental data into a specified directory:
72
73 $ ant -f build-icu-data.xml -DoutDir=/tmp/cldr -DoutputTypes=plurals,dayPeriods -DdontGenCode=true
74
75 Note: Output types can be listed with mixedCase, lower_underscore or UPPER_UNDERSCORE.
76 Pass '-DoutputTypes=help' to see the full list.
77
78
79* Outputting only a subset of locale IDs (and all the supplemental data):
80
81 $ ant -f build-icu-data.xml -DoutDir=/tmp/cldr -DlocaleIdFilter='(zh|yue).*' -DdontGenCode=true
82
83
84* Overriding the default CLDR version string (which normally matches the CLDR library code):
85
86 $ ant -f build-icu-data.xml -DcldrVersion="36.1"
87
88
89See build-icu-data.xml for documentation of all options and additional customization.
90
91
92Running unit tests
93------------------
94
95$ mvn test -DCLDR_DIR="$CLDR_DATA_DIR"
96
97
98Importing and running from an IDE
99---------------------------------
100
101This project should be easy to import into an IDE which supports Maven development, such
102as IntelliJ or Eclipse. It uses a local Maven repository directory for the unpublished
103CLDR libraries (which are included in the project), but otherwise gets all dependencies
104via Maven's public repositories.
105