// vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 filetype=cpp.doxygen

//
//  Copyright (c) 2009-2011 Artyom Beilis (Tonkikh)
//
//  Distributed under the Boost Software License, Version 1.0. (See
//  accompanying file LICENSE_1_0.txt or copy at
//  http://www.boost.org/LICENSE_1_0.txt)
//


/*!
\page building_boost_locale Building The library

- \ref building_boost_locale_bb
    - \ref bb_building_deps
    - \ref bb_building_proc
    - \ref bb_build_opts
    - \ref bb_build_test
- \ref binary_compatibility


\section building_boost_locale_bb Building Boost.Locale

\subsection bb_building_deps Dependencies

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

\subsection bb_platform_opts 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.\n
    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.

\subsection bb_building_proc Building Process

Now all you need to do is invoke bjam command:

\verbatim
./bjam --with-locale stage
\endverbatim

Or on Windows
\verbatim
.\bjam --with-locale stage
\endverbatim

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 \c -sICU_PATH option

For example:

-   If your icu build is placed at \c /opt/icu46 such that the files are placed like\n
    \c /opt/icu46/include/unicode/uversion.h\n
    \c /opt/icu46/include/unicode/calendar.h\n
    \c ... \n
    \c /opt/icu46/lib/libicudata.so \n
    \c /opt/icu46/lib/libicui18n.so \n
    \c ... \n
    then you need to provide an option \c -sICU_PATH=/opt/icu46
    \verbatim
    ./bjam --with-locale -sICU_PATH=/opt/icu46  stage
    \endverbatim
-   If your icu build is placed at <tt>c:\\icu46</tt> such that the files are placed like \n
    <tt>c:\\icu46\\include\\unicode\\uversion.h</tt>  \n
    <tt>c:\\icu46\\include\\unicode\\calendar.h</tt> \n
    <tt>...</tt> \n
    <tt>c:\\icu46\\bin\\icudt.dll</tt> \n
    <tt>c:\\icu46\\bin\\icuin.dll</tt> \n
    <tt>...</tt> \n
    <tt>c:\\icu46\\lib\\icudt.lib</tt> \n
    <tt>c:\\icu46\\lib\\icuin.lib</tt> \n
    <tt>...</tt> \n
    then you need to provide an option \c -sICU_PATH=c:\\icu46
    \verbatim
    .\bjam --with-locale -sICU_PATH=c:\icu46  stage
    \endverbatim

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

\section bb_build_opts Build Options

Boost.Locale supports following options with values \c off or \c on

- \c boost.locale.icu=off disable build of ICU backend even if ICU library exists
- \c boost.locale.iconv=off or \c boost.locale.iconv=on enable or disable use of iconv
     library. It is off by default on Windows and Solaris
- \c boost.locale.winapi=off - disable winapi backend, it is on by default on Windows and Cygwin
- \c boost.locale.std=off or \c boost.locale.winapi=on Disable or enable std backends. \c std backend
     is disabled by default when using Sun Studio.
- \c boost.locale.posix=on or \c 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

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


For example:

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

\section bb_build_test Running Unit Tests

You can run unit tests by invoking \c bjam with \c libs/locale/test project parameter
\verbatim
./bjam libs/locale/test
\endverbatim

\section binary_compatibility 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 \c std, \c posix 
or \c 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.

*/