Boost.Locale: Building The library

# Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

# 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.