Boost.Locale
Building the Library

Building Boost.Locale

Dependencies

  • ICU library 4.8.1 or above is required for builds with ICU
  • If no ICU library is given, iconv support is required on POSIX platforms.

Platform Notes

  • Using Boost.Locale DLL's with MinGW gcc requires dynamic linking with the runtime libraries libstdc++ and libgcc. Some gcc builds use static linking by default so make sure you use the correct link options.
  • The AIX's iconv misses important character sets that Boost.Locale requires, so you need to either use GNU iconv or link with the ICU library.
  • If the iconv library is not found on Darwin/Mac OS X builds make sure there are not multiple iconv installations and provide the -sICONV_PATH build option to point to the correct location of the iconv library.

Building Process

Now all you need to do is to invoke b2:

./b2 --with-locale stage

Or on Windows

.\b2 --with-locale stage

If you are using a custom ICU build or you are using Microsoft Windows, you need to provide a path to the location of the ICU library using the -sICU_PATH option

For example:

  • If your icu build is placed at /opt/icu48 such that the files are placed like
    /opt/icu48/include/unicode/uversion.h
    /opt/icu48/include/unicode/calendar.h
    ...
    /opt/icu48/lib/libicudata.so
    /opt/icu48/lib/libicui18n.so
    ...
    then you need to provide an option -sICU_PATH=/opt/icu48
        ./b2 --with-locale -sICU_PATH=/opt/icu48  stage
    
  • If your icu build is placed at C:\icu48 such that the files are placed like
    C:\icu48\include\unicode\uversion.h
    C:\icu48\include\unicode\calendar.h
    ...
    C:\icu48\bin\icudt.dll
    C:\icu48\bin\icuin.dll
    ...
    C:\icu48\lib\icudt.lib
    C:\icu48\lib\icuin.lib
    ...
    then you need to provide an option -sICU_PATH=C:\icu48
        .\b2 --with-locale -sICU_PATH=C:\icu48  stage
    
Note
Don't forget to put both debug and release versions of ICU libraries in this path when using Microsoft Visual Studio so Boost.Build will correctly link debug and release versions of Boost.Locale.

Build Options

Boost.Locale supports the following options with values off or on

  • boost.locale.icu=off prevents building the ICU backend even if the ICU library exists
  • boost.locale.iconv enables or disables the iconv backend. It is off by default on Windows and Solaris
  • boost.locale.winapi=off disables the winapi backend. It is on by default on Windows and Cygwin
  • boost.locale.std enables or disables the std backend. The std backend is disabled by default when using Sun Studio.
  • boost.locale.posix enables or disables support of the POSIX backend. It is on by default on Linux and Mac OS X

Also Boost.Locale supports the following options

  • -sICU_PATH=/path/to/location/of/icu - the location of the ICU library
  • -sICONV_PATH=/path/to/location/of/iconv - the location of the iconv library

For example:

  • Build the library on Windows with the ICU backend only:
        .\b2 boost.locale.winapi=off boost.locale.std=off -sICU_PATH=C:\icu48 --with-locale stage
    
  • Build the library on Linux with the std backend only
        ./b2 boost.locale.posix=off boost.locale.icu=off --with-locale stage
    

Running Unit Tests

You can run unit tests by invoking b2 with the libs/locale/test project parameter

./b2 libs/locale/test

Binary Compatibility

Boost.Locale is built with binary compatibility in mind. Switching localization back ends on or off, or using iconv or not, does not affect binary compatibility. So if a dynamic library was built with all possible backends, other dynamic libraries compiled with, for example, only the std, posix or winapi backends would still be binary-compatible.

Using a feature not included in the binary will result in an exception. For example, if you try to use boundary analysis or a calendar facet when the library does not support the ICU backend, you will get an exception.