1--- 2layout: default 3title: How To Use ICU 4nav_order: 2 5parent: ICU 6--- 7<!-- 8© 2020 and later: Unicode, Inc. and others. 9License & terms of use: http://www.unicode.org/copyright.html 10--> 11 12# How To Use ICU 13{: .no_toc } 14 15## Contents 16{: .no_toc .text-delta } 17 181. TOC 19{:toc} 20 21--- 22 23# Overview 24 25ICU builds and installs as relatively standard libraries. For details about 26building, installing and porting see the [ICU4C 27readme](https://htmlpreview.github.io/?https://github.com/unicode-org/icu/blob/master/icu4c/readme.html) and the 28[ICU4J readme](https://htmlpreview.github.io/?https://github.com/unicode-org/icu/blob/master/icu4j/readme.html). 29In addition, ICU4C installs several scripts and makefile fragments that help 30build other code using ICU. 31 32For C++, note that there are [Recommended Build 33Options](https://htmlpreview.github.io/?https://github.com/unicode-org/icu/blob/master/icu4c/readme.html#RecBuild) 34(both for normal use and for ICU as system-level libraries) which are not 35default simply for compatibility with older ICU-using code. 36 37Starting with ICU 49, the ICU4C readme has a short section about 38[User-Configurable 39Settings](https://htmlpreview.github.io/?https://github.com/unicode-org/icu/blob/master/icu4c/readme.html#UserConfig). 40 41## C++ Makefiles 42 43The recommended way to use ICU in Makefiles is to use the 44[pkg-config](http://pkg-config.freedesktop.org/) files which are installed by 45ICU upon "`make install`". There are files for various libraries and components. 46This is preferred over the deprecated icu-config script. 47 48This table shows the package names used within pkg-config. 49 50|**Package**|**Contents**| 51|------|--------------------| 52|icu-uc|Common (uc) and Data (dt/data) libraries| 53|icu-i18n|Internationalization (in/i18n) library|icu-le [Layout Engine](layoutengine/index.md)| 54|icu-lx|Paragraph Layout| 55|icu-io|[Ustdio](io/ustdio.md)/[iostream](io/ustream.md) library (icuio) 56 57For example, to compile a simple application, you could run the following 58command. See the [pkg-config](http://pkg-config.freedesktop.org/) manpage for 59more details. 60 61 c++ -o test test.c `pkg-config --libs --cflags icu-uc icu-io` 62 63ICU installs the pkg-config (.pc) files in `$(prefix)/lib/pkgconfig` (where 64`$(prefix)` is the installation prefix for ICU). Note that you may need to add 65`$(prefix)/lib/pkgconfig` to the `PKG_CONFIG_PATH` variable. 66 67### ICU in a small project 68 69For small projects, it may be convenient to take advantage of 70ICU's `autoconf`'ed files. ICU `make install` writes 71`$(prefix)/lib/icu/Makefile.inc` which defines most of the necessary *make* 72variables such as `$(CXX)`, `$(CXXFLAGS)`, `$(ICULIBS)`, `$(INVOKE)`, `$(ICUPKG)`, 73`$(datadir)`, etc. 74 75By itself, `Makefile.inc` is incomplete. It assumes that it will be included into another 76`Makefile` which will define `$(srcdir)`, `$(DYNAMICCXXFLAGS)` and similar values. 77 78In this case, it is probably best to copy ICU's 79`autoconf`'ed top-level `./Makefile` and/or library-target-style `i18n/Makefile` and/or 80binary-target-style `tools/icupkg/Makefile`. Then modify them as needed. 81 82### ICU in a medium-sized project 83 84If you use your own `autoconf`/`CMake`/... setup, consider cherry-picking only the 85definitions needed, for example paths to specific ICU data and tools. 86This is often preferable to taking the entire `Makefile.inc` and 87overriding (many) definitions that are different. 88 89For selective ICU definitions, use the installed 90`$(prefix)/bin/icu-config` script. 91Its contents are synchronized with `$(prefix)/lib/icu/Makefile.inc`. 92For example, use `icu-config --invoke=icupkg` to invoke the ICU .dat packaging tool. 93 94### ICU in a large project 95 96In this case, you probably have your own build system. Just use ICU's public header 97files, `.so` files, etc. See the next section, "C++ With Your Own Build System". 98 99## Notes on `icu-config` 100 101> :point_right: **Note**: **icu-config is deprecated, and no longer recommended for 102> production use. Please use pkg-config files or other options.** 103 104As of ICU 63.1, [icu-config has been deprecated 105(ICU-10464)](https://unicode-org.atlassian.net/browse/ICU-10464). 106`icu-config` may be disabled by default in the future. 107As of ICU 63.1, you may enable or disable 63.1 with a configure flag: 108`--enable-icu-config` or `--disable-icu-config` 109 110`icu-config` is installed (by ICU's `make install`) into `$(prefix)/bin/icu-config`. 111It can be convenient for **trivial, single-file programs** that use ICU. For 112example, you could compile and build a small program with this command line: 113 114 icu-config --cxx --cxxflags --cppflags --ldflags -o sample sample.cpp 115 116Detailed usage of `icu-config` script is described in its `man` page. 117 118## C++ With Your Own Build System 119 120If you are not using the standard build system, you will need to construct your 121own system. Here are a couple of starting points: 122 123* At least for initial bring-up, use pre-built data files from the ICU 124 download or from a normally-built ICU. Copy the icudt***XXx*.dat file from 125 `icu/source/data/in/` or `icu/source/data/out/tmp/` in either of these two 126 locations, into `icu/source/data/in/`** on your target ICU system. That way, 127 you won't need to build ICU's data-generation tools. 128* Don't compile all files. Look in the `Makefile.in` files for `OBJECTS=` 129 clauses which will indicate which source files should be compiled. (Some .c 130 files are #included into others and cannot be compiled by themselves.) 131* ICU does not throw or handle exceptions. Consider turning them off via g++'s 132 `-fno-exceptions` or equivalent. 133* Each ICU library needs to be compiled with -DU_COMMON_IMPLEMENTATION, 134 -DU_I18N_IMPLEMENTATION etc. as appropriate. See unicode/utypes.h for the 135 set of such macros. If you build one single DLL (shared library) for all of 136 ICU, also use -DU_COMBINED_IMPLEMENTATION. If you build ICU as 137 statically-linked libraries, use -DU_STATIC_IMPLEMENTATION. 138* Use the [icu-support mailing list](http://site.icu-project.org/contacts). 139 Ask for help and guidance on your strategy. 140* Up until ICU 4.8, there are one or two header files (platform.h, icucfg.h) 141 that are generated by autoconf/configure and thus differ by platform, 142 sometimes even by target settings on a single platform (e.g., AIX 32-bit vs. 143 64-bit, Mac OS X universal binaries PowerPC vs. x86). If you do not use 144 autoconf, you probably need to configure-generate these header files for 145 your target platforms and select among them, or merge the generated headers 146 if they are similar, or simulate their generation by other means. 147* Starting with ICU 49, all source code files are fixed (not generated). In 148 particular, there is one single platform.h file which determines 149 platform-specific settings via `#if ...` 150 151## C++ Namespace 152 153ICU C++ APIs are normally defined in a versioned namespace, for example 154"icu_50". There is a stable "icu" alias which should be used instead. (Entry 155point versioning is only to allow for multiple ICU versions linked into one 156program. [It is optional and should be off for system 157libraries.](https://htmlpreview.github.io/?https://github.com/unicode-org/icu/blob/master/icu4c/readme.html#RecBuild)) 158 159By default, and only for backward compatibility, the ICU headers contain a line 160`using namespace icu_50;` which makes all ICU APIs visible in/with the global 161namespace (and potentially collide with non-ICU APIs there). One of the 162[Recommended Build 163Options](https://htmlpreview.github.io/?https://github.com/unicode-org/icu/blob/master/icu4c/readme.html#RecBuild) 164is to turn this off. 165 166To write forward declarations, use 167 168 U_NAMESPACE_BEGIN 169 class UnicodeSet; 170 class UnicodeString; 171 U_NAMESPACE_END 172 173To qualify an ICU class name, use the "icu" alias: 174 175 static myFunction(const icu::UnicodeString &s) {...} 176 177Frequently used ICU classes can be made easier to use in .cpp files with 178 179 using icu::UnicodeSet; 180 using icu::UnicodeString; 181 182## Other Notes 183 184### Helper Install Utilities 185 186ICU installs `$(prefix)/share/icu/$(VERSION)/install-sh` and 187`$(prefix)/share/icu/$(VERSION)/mkinstalldirs`. These may be used by ICU tools and 188samples. Their paths are given in the installed `Makefile.inc` (see above). 189 190### Data Packaging Settings 191 192The `pkgdata` tool (see [Packaging ICU4C](packaging/index.md) ) makes use of the 193installed file `**$(prefix)/lib/icu/pkgdata.inc**` to set parameters for data 194packaging operations that require use of platform compilers and linkers ( in 195`static` or `dll` mode). `pkgdata` uses the icu-config script in order to locate 196**pkgdata.inc**. If you are not building ICU using the supplied tools, you may 197need to modify this file directly to allow `static` and `dll` modes to function. 198 199### Building and Running Trivial C/C++ Programs with `icurun` 200 201For building and running trivial (one-compilation-unit) programs with an 202installed ICU4C, the shell script 203[icurun](https://github.com/unicode-org/icu/blob/master/tools/scripts/icurun) 204may be used. For detailed help, see the top of that script. 205As an example, if ICU is installed to the prefix **/opt/local** and the current 206directory contains two sample programs "test1.cpp" and "test2.c", they may be 207compiled and run with any of the following commands. The "-i" option specifies 208either the installed icu-config script, or the directory containing that script, 209or the path to a 'bin' directory. 210 211* `icurun **-i /opt/local** test1.cpp` 212* `icurun **-i /opt/local/bin** test2.c` 213* `icurun **-i /opt/local/bin/icu-config** test1.cpp` 214 215If "icu-config" is on the PATH, the -i option may be omitted: 216 217* `icurun test1.cpp` 218 219Any additional arguments will be passed to the program. 220 221* `icurun test1.cpp *args...*` 222 223*Please give feedback to the [icu-support mailing list](http://site.icu-project.org/contacts), 224and refer to [Ticket #8481](https://unicode-org.atlassian.net/browse/ICU-8481).* 225