Boost.Locale
Building The library

Building Boost.Locale

Dependencies

  • ICU library 3.6 or above is strongly recommended
  • If no ICU library is given, iconv support is required under POSIX platforms.

Platform Notes

  • If you use Boost.Locale on Windows with MinGW/GCC < 4.5 you'll be able to use static version only. Mingw/GCC prior to 4.5 have no support of dynamic runtime linking.
    Using Boost.Locale DLL's with MinGW gcc also requires dynamic linking with the runtime libraries libstdc++ and libgcc. Some gcc builds use static linking by default so make sure you use correct link options with your compiler when you build your own programs.
  • The AIX's iconv misses important character sets that Boost.Locale requires, so you need to either use GNU iconv or link with ICU library.
  • If iconv library is not found on Darwin/Mac OS X builds make sure there is no multiple iconv installations and provide -sICONV_PATH build option to point to correct location of iconv library.

Building Process

Now all you need to do is invoke bjam command:

./bjam --with-locale stage

Or on Windows

.\bjam --with-locale stage

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

For example:

  • If your icu build is placed at /opt/icu46 such that the files are placed like
    /opt/icu46/include/unicode/uversion.h
    /opt/icu46/include/unicode/calendar.h
    ...
    /opt/icu46/lib/libicudata.so
    /opt/icu46/lib/libicui18n.so
    ...
    then you need to provide an option -sICU_PATH=/opt/icu46
        ./bjam --with-locale -sICU_PATH=/opt/icu46  stage
        
  • If your icu build is placed at c:\icu46 such that the files are placed like
    c:\icu46\include\unicode\uversion.h
    c:\icu46\include\unicode\calendar.h
    ...
    c:\icu46\bin\icudt.dll
    c:\icu46\bin\icuin.dll
    ...
    c:\icu46\lib\icudt.lib
    c:\icu46\lib\icuin.lib
    ...
    then you need to provide an option -sICU_PATH=c:\icu46
        .\bjam --with-locale -sICU_PATH=c:\icu46  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 link correctly debug and release versions of boost_locale library.

Build Options

Boost.Locale supports following options with values off or on

  • boost.locale.icu=off disable build of ICU backend even if ICU library exists
  • boost.locale.iconv=off or boost.locale.iconv=on enable or disable use of iconv library. It is off by default on Windows and Solaris
  • boost.locale.winapi=off - disable winapi backend, it is on by default on Windows and Cygwin
  • boost.locale.std=off or boost.locale.winapi=on Disable or enable std backends. std backend is disabled by default when using Sun Studio.
  • boost.locale.posix=on or boost.locale.posix=off Enable or disable support of POSIX backend, it is on by default on Linux and Mac OS X

Also Boost.Locale supports following options

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

For example:

  • Build the library on Windows with ICU backend only:
        .\bjam boost.locale.winapi=off boost.locale.std=off -sICU_PATH=c:\icu46 --with-locale stage
        
  • Build the library on Linux with std backend only
        .\bjam boost.locale.posix=off boost.locale.icu=off --with-locale stage
        

Running Unit Tests

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

./bjam 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 with it.

However this definitely has an effect on some features. For example, if you try to use boundary analysis or a calendar facet when the library does not support the icu backend you would get an exception.