This chapter describes, for the advanced user, how to package ICU4C for distribution, whether alone, as part of an application, or as part of the operating system.
The ICU project is intended to provide everything an application might need in order to process Unicode. However, in doing so, the results may become quite large on disk. A default build of ICU normally results in over 16 MB of data, and a substantial amount of object code. This section describes some techniques to reduce the size of ICU to only the items which are required for your application.
If you add the
ICU consists of a number of different libraries. The library dependency chart (§) in the Design chapter can be used to understand and determine the exact set of libraries needed.
Certain features of ICU may be turned on and off through preprocessor defines. These switches are located in the file "uconfig.h", and disable the code for certain features from being built.
All of these switches are defined to '0' by default, unless overridden by the build environment, or by modifying uconfig.h itself.
This method involves setting an environment variable when ICU is built. For example, on a POSIX-like platform, settings may be chosen at the point runConfigureICU is run:
Note that when end-user code is compiled, it must also have the same CPPFLAGS set, or else calling some functions may result in a link failure.
This method involves modifying the source file icu/source/common/unicode/uconfig.h directly, before ICU is built. It has the advantage that the configuration change is propagated to all clients who compile against this build of ICU, however the altered file must be tracked when the next version of ICU is installed.
Modify 'uconfig.h' to add the following lines before the first #ifndef UCONFIG_... section
There are many ways in which ICU data may be reduced. If only certain locales or converters will be used, others may be removed. Additionally, data may be packaged as individual files or interchangeable archives (.dat files), allowing data to be installed and removed without rebuilding ICU. For details, see the ICU Data chapter.
The following table gives an example of the dynamically linked library and symbolic links built by ICU for the common ('uc') library, version 5.4.3, for Linux
An application compiled with '-licuuc' will follow the symlink from libicuuc.so to libicuuc.so.54.3, and will actually read the file libicuuc.so.54.3. (fully qualified). This library file has an embedded name (SONAME) of libicuuc.so.54, that is, with only the major and minor number. The linker will write this name into the client application, because Binary compatibility is for versions that share the same major+minor number.
If ICU version 5.4.7 is subsequently installed, the following files may be updated.
If ICU version 5.6.3 or 3.2.9 were installed, they would not affect already-linked applications, because the major+minor numbers are different - 56 and 32, respectively, as opposed to 54. They would, however, replace the link 'libicuuc.so', which controls which version of ICU newly-linked applications use.
In summary, what files should an application distribute in order to include a functional runtime copy of ICU 5.4.3? The above application should distribute libicuuc.so.54.3 and the symbolic link libicuuc.so.54. (If symbolic links pose difficulty, libicuuc.so.54.3 may be renamed to libicuuc.so.54, and only libicuuc.so.54 distributed. This is less informative, but functional.)
The --with-library-suffix option may be used with runConfigureICU or configure, to distinguish on disk specially modified versions of ICU. For example, the option --with-library-suffix=myapp will produce libraries with names such as libicuucmyapp.so.54.3, thus preventing another ICU user from using myapp's custom ICU libraries.
While two or more versions of ICU may be linked into the same application as long as the major and minor numbers are different, changing the library suffix is not sufficient to allow the same version of ICU to be linked. In other words, linking ICU 5.4.3, 5.6.3, and 3.2.9 together is allowed, but 5.4.3 and 5.4.7 may not be linked together, nor may 5.4.3 and 5.4.3-myapp be linked together.
Assuming ICU version 5.4.3, Windows library names will follow this pattern:
Debug applications must be linked with debug libraries, and release applications with release libraries.
When a new version of ICU is installed, the .lib files will be replaced so as to keep new compiles in sync with the newly installed header files, and the latest DLL. As well, if the new ICU version has the same major+minor version (such as 5.4.7), then DLLs will be replaced, as they are binary compatible. However, if an ICU with a different major+minor version is installed, such as 5.5, then new DLLs will be copied with names such as 'icuuc55.dll'.ICU Architectural Design chapter for more details.