Building The library

• Building Boost.Locale
  • Dependencies
  • Building Process
  • Build Options
  • Running Unit Tests
• Binary Compatibility

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.