1--- 2layout: default 3title: Packaging ICU4C 4nav_order: 3 5parent: ICU Data 6--- 7<!-- 8© 2020 and later: Unicode, Inc. and others. 9License & terms of use: http://www.unicode.org/copyright.html 10--> 11 12# Packaging ICU4C 13{: .no_toc } 14 15## Contents 16{: .no_toc .text-delta } 17 181. TOC 19{:toc} 20 21--- 22 23## Overview 24 25This chapter describes, for the advanced user, how to package ICU4C for 26distribution, whether alone, as part of an application, or as part of the 27operating system. 28 29## Making ICU Smaller 30 31The ICU project is intended to provide everything an application might need in 32order to process Unicode. However, in doing so, the results may become quite 33large on disk. A default build of ICU normally results in over 16 MB of data, 34and a substantial amount of object code. This section describes some techniques 35to reduce the size of ICU to only the items which are required for your 36application. 37 38### Link to ICU statically 39 40If you add the `--enable-static` option to the ICU command line build (Makefile 41or cygwin), ICU will also build a static library version which you can link to 42only the exact functions your application needs. Users of your ICU must compile 43with -DU_STATIC_IMPLEMENTATION. Also see [How To Use ICU](../howtouseicu.md). 44 45### Reduce the number of libraries used 46 47ICU consists of a number of different libraries. The library dependency chart in the [Design](../design#library-dependencies-c) 48chapter can be used to understand and 49determine the exact set of libraries needed. 50 51### Disable ICU features 52 53Certain features of ICU may be turned on and off through preprocessor defines. 54These switches are located in the file "uconfig.h", and disable the code for 55certain features from being built. 56 57All of these switches are defined to '0' by default, unless overridden by the 58build environment, or by modifying uconfig.h itself. 59 60| Switch Name | Library | Effect if #defined to '1' | 61|--------------------------------|------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| 62| UCONFIG_ONLY_COLLATION | common & i18n | Turn off all other modules named here except collation and legacy conversion | 63| UCONFIG_NO_LEGACY_CONVERSION | common | Turn off conversion apart from UTF, CESU-8, SCSU, BOCU-1, US-ASCII, and ISO-8859-1. Not possible to turn off legacy conversion on EBCDIC platforms. | 64| UCONFIG_NO_BREAK_ITERATION | common | Turn off break iteration | 65| UCONFIG_NO_COLLATION | i18n | Turn off collation and collation-based string search. | 66| UCONFIG_NO_FORMATTING | i18n | Turn off all formatting (date, time, number, etc), and calendar/timezone services. | 67| UCONFIG_NO_TRANSLITERATION | i18n | Turn off script-to-script transliteration | 68| UCONFIG_NO_REGULAR_EXPRESSIONS | i18n | Turn off the regular expression functionality | 69 70> :point_right: **NOTE**: *These switches do not necessarily disable data generation. For example, disabling formatting does not prevent formatting data from being built into the resource bundles. See the section on ICU data, for information on changing data packaging.* 71*However, some ICU data builders will not function with these switches set, such 72as UCONFIG_NO_FILE_IO or UCONFIG_NO_REGULAR_EXPRESSIONS. If using these 73switches, it is best to use pre-built ICU data, such as is the default for ICU 74source downloads, as opposed to data builds "from scratch" out of SVN.* 75 76#### Using UCONFIG switches with Environment Variables 77 78This method involves setting an environment variable when ICU is built. For 79example, on a POSIX-like platform, settings may be chosen at the point 80runConfigureICU is run: 81 82```shell 83env CPPFLAGS="-DUCONFIG_NO_COLLATION=1 -DUCONFIGU_NO_FORMATTING=1" \ 84 runConfigureICU SOLARISCC ... 85``` 86 87> :point_right: **Note**: When end-user code is compiled, 88> it must also have the same CPPFLAGS 89> set, or else calling some functions may result in a link failure. 90 91#### Using UCONFIG switches by changing uconfig.h 92 93This method involves modifying the source file 94icu/source/common/unicode/uconfig.h directly, before ICU is built. It has the 95advantage that the configuration change is propagated to all clients who compile 96against this build of ICU, however the altered file must be tracked when the 97next version of ICU is installed. 98 99Modify 'uconfig.h' to add the following lines before the first #ifndef 100UCONFIG_... section 101 102```c 103#ifndef UCONFIG_NO_COLLATION 104#define UCONFIG_NO_COLLATION 1 105#enddif 106#ifndef UCONFIG_NO_FORMATTING 107#define UCONFIG_NO_FORMATTING 1 108#endif 109``` 110 111### Reduce ICU Data used 112 113There are many ways in which ICU data may be reduced. If only certain locales or 114converters will be used, others may be removed. Additionally, data may be 115packaged as individual files or interchangeable archives (.dat files), allowing 116data to be installed and removed without rebuilding ICU. For details, see the 117[ICU Data](../icudata.md) chapter. 118 119## ICU Versions 120 121(This section assumes the reader is familiar with ICU version numbers (§) as 122covered in the [Design](../design.md) chapter, and filename conventions for 123libraries in the 124[ReadMe](https://github.com/unicode-org/icu/blob/master/icu4c/readme.html#HowToPackage) 125.) 126 127### POSIX Library Names 128 129The following table gives an example of the dynamically linked library and 130symbolic links built by ICU for the common ('uc') library, version 5.4.3, for 131Linux 132 133| File | Links to | Purpose | 134|------------------|------------------|------------------------------------------------------------------------------------| 135| `libicuuc.so` | `libicuuc.so.54.3` | Required for link: Applications compiled with ' -licuuc' will follow this symlink. | 136| `libicuuc.so.54` | `libicuuc.so.54.3` | Required for runtime: This name is what applications actually link against. | 137| `libicuuc.so.54.3` | Actual library | Required for runtime and link. Contains the name `libicuuc.so.54`. | 138 139> :point_right: **Note**: This discussion gives 140> Linux as an example, but it is typical for most platforms, 141> of which AIX and 390 (zOS) are exceptions. 142 143An application compiled with '-licuuc' will follow the symlink from `libicuuc.so` 144to `libicuuc.so.54.3`, and will actually read the file `libicuuc.so.54.3`. (fully 145qualified). This library file has an embedded name (SONAME) of `libicuuc.so.54`, 146that is, with only the major and minor number. The linker will write **this** 147name into the client application, because Binary compatibility is for versions 148that share the same major+minor number. 149 150If ICU version 5.4.**7** is subsequently installed, the following files may be 151updated. 152 153| File | Links to | Purpose | 154|------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| 155| `libicuuc.so` | `libicuuc.so.54.7` | Required for link: Newly linked applications will follow this link, which should not cause any functional difference at link time. | 156| libicuuc.so.54` | `libicuuc.so.54.7` | Required for runtime: Because it now links to version .7, existing applications linked to version 5.4.3 will follow this link and use the 5.4.7 code. | 157| `libicuuc.so.54.7` | Actual library | Required for runtime and link. Contains the name `libicuuc.so.54`. | 158 159If ICU version 5.6.3 or 3.2.9 were installed, they would not affect 160already-linked applications, because the major+minor numbers are different - 56 161and 32, respectively, as opposed to 54. They would, however, replace the link 162`libicuuc.so`, which controls which version of ICU newly-linked applications 163use. 164 165In summary, what files should an application distribute in order to include a 166functional runtime copy of ICU 5.4.3? The above application should distribute 167`libicuuc.so.54.3` and the symbolic link `libicuuc.so.54`. (If symbolic links pose 168difficulty, `libicuuc.so.54.3` may be renamed to `libicuuc.so.54`, and only 169`libicuuc.so.54` distributed. This is less informative, but functional.) 170 171### POSIX Library suffix 172 173The --with-library-suffix option may be used with runConfigureICU or configure, 174to distinguish on disk specially modified versions of ICU. For example, the 175option --with-library-suffix=**myapp** will produce libraries with names such as 176libicuuc**myapp**.so.54.3, thus preventing another ICU user from using myapp's 177custom ICU libraries. 178 179While two or more versions of ICU may be linked into the same application as 180long as the major and minor numbers are different, changing the library suffix 181is not sufficient to allow the same version of ICU to be linked. In other words, 182linking ICU 5.4.3, 5.6.3, and 3.2.9 together is allowed, but 5.4.3 and 5.4.7 may 183not be linked together, nor may 5.4.3 and 5.4.3-myapp be linked together. 184 185### Windows library names 186 187Assuming ICU version 5.4.3, Windows library names will follow this pattern: 188 189| File | Purpose | 190|---------------|--------------------------------------------------------------------------------------------| 191| `icu`**uc**`.lib` | Release Link-time library. Needed for development. Contains `icuuc54.dll` name internally. | 192| `icuuc54.dll` | Release runtime library. Needed for runtime. | 193| `icuuc`**d**`.lib` | Debug link-time library (The `d` suffix indicates debug) | 194| `icuuc54`**d**`.dll` | Debug runtime library. | 195 196Debug applications must be linked with debug libraries, and release applications 197with release libraries. 198 199When a new version of ICU is installed, the .lib files will be replaced so as to 200keep new compiles in sync with the newly installed header files, and the latest 201DLL. As well, if the new ICU version has the same major+minor version (such as 2025.4.7), then DLLs will be replaced, as they are binary compatible. However, if 203an ICU with a different major+minor version is installed, such as 5.5, then new 204DLLs will be copied with names such as 'icuuc55.dll'. 205 206## Packaging ICU4C as Part of the Operating System 207 208The services which are now known as ICU were written to provide operating 209system-level and application environment-level services. Several operating 210systems include ICU as a standard or optional package. 211See [ICU Binary Compatibility](../design#icu-binary-compatibility) for 212more details. 213