• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 filetype=cpp.doxygen
2
3//
4//  Copyright (c) 2009-2011 Artyom Beilis (Tonkikh)
5//
6//  Distributed under the Boost Software License, Version 1.0. (See
7//  accompanying file LICENSE_1_0.txt or copy at
8//  http://www.boost.org/LICENSE_1_0.txt)
9//
10
11
12/*!
13\page building_boost_locale Building The library
14
15- \ref building_boost_locale_bb
16    - \ref bb_building_deps
17    - \ref bb_building_proc
18    - \ref bb_build_opts
19    - \ref bb_build_test
20- \ref binary_compatibility
21
22
23\section building_boost_locale_bb Building Boost.Locale
24
25\subsection bb_building_deps Dependencies
26
27- ICU library 3.6 or above is strongly recommended
28- If no ICU library is given, iconv support is required under POSIX platforms.
29
30\subsection bb_platform_opts Platform Notes
31
32-   If you use Boost.Locale on Windows with MinGW/GCC < 4.5 you'll be
33    able to use static version only. Mingw/GCC prior to 4.5 have no
34    support of dynamic runtime linking.\n
35    Using Boost.Locale DLL's with MinGW gcc also requires dynamic linking
36    with the runtime libraries libstdc++ and libgcc. Some gcc builds use
37    static linking by default so make sure you use correct link options
38    with your compiler when you build your own programs.
39-   The AIX's iconv misses important character sets that Boost.Locale requires,
40    so you need to either use GNU iconv or link with ICU library.
41-   If iconv library is not found on Darwin/Mac OS X builds make sure there
42    is no multiple iconv installations and provide -sICONV_PATH build option
43    to point to correct location of iconv library.
44
45\subsection bb_building_proc Building Process
46
47Now all you need to do is invoke bjam command:
48
49\verbatim
50./bjam --with-locale stage
51\endverbatim
52
53Or on Windows
54\verbatim
55.\bjam --with-locale stage
56\endverbatim
57
58If you are using custom ICU build or you are using Microsoft Windows
59you need to provide a path to location of ICU library using \c -sICU_PATH option
60
61For example:
62
63-   If your icu build is placed at \c /opt/icu46 such that the files are placed like\n
64    \c /opt/icu46/include/unicode/uversion.h\n
65    \c /opt/icu46/include/unicode/calendar.h\n
66    \c ... \n
67    \c /opt/icu46/lib/libicudata.so \n
68    \c /opt/icu46/lib/libicui18n.so \n
69    \c ... \n
70    then you need to provide an option \c -sICU_PATH=/opt/icu46
71    \verbatim
72    ./bjam --with-locale -sICU_PATH=/opt/icu46  stage
73    \endverbatim
74-   If your icu build is placed at <tt>c:\\icu46</tt> such that the files are placed like \n
75    <tt>c:\\icu46\\include\\unicode\\uversion.h</tt>  \n
76    <tt>c:\\icu46\\include\\unicode\\calendar.h</tt> \n
77    <tt>...</tt> \n
78    <tt>c:\\icu46\\bin\\icudt.dll</tt> \n
79    <tt>c:\\icu46\\bin\\icuin.dll</tt> \n
80    <tt>...</tt> \n
81    <tt>c:\\icu46\\lib\\icudt.lib</tt> \n
82    <tt>c:\\icu46\\lib\\icuin.lib</tt> \n
83    <tt>...</tt> \n
84    then you need to provide an option \c -sICU_PATH=c:\\icu46
85    \verbatim
86    .\bjam --with-locale -sICU_PATH=c:\icu46  stage
87    \endverbatim
88
89\note Don't forget to put both debug and release versions of ICU libraries in this path
90when using Microsoft Visual Studio  so Boost.Build will link correctly debug and release
91versions of boost_locale library.
92
93\section bb_build_opts Build Options
94
95Boost.Locale supports following options with values \c off or \c on
96
97- \c boost.locale.icu=off disable build of ICU backend even if ICU library exists
98- \c boost.locale.iconv=off or \c boost.locale.iconv=on enable or disable use of iconv
99     library. It is off by default on Windows and Solaris
100- \c boost.locale.winapi=off - disable winapi backend, it is on by default on Windows and Cygwin
101- \c boost.locale.std=off or \c boost.locale.winapi=on Disable or enable std backends. \c std backend
102     is disabled by default when using Sun Studio.
103- \c boost.locale.posix=on or \c boost.locale.posix=off Enable or disable support of POSIX backend,
104     it is on by default on Linux and Mac OS X
105
106Also Boost.Locale supports following options
107
108- \c -sICU_PATH=/path/to/location/of/icu - the location of custom ICU library
109- \c -sICONV_PATH=/path/to/location/of/iconv - the location of custom iconv library
110
111
112For example:
113
114-   Build the library on Windows with ICU backend only:
115    \verbatim
116    .\bjam boost.locale.winapi=off boost.locale.std=off -sICU_PATH=c:\icu46 --with-locale stage
117    \endverbatim
118-   Build the library on Linux with std backend only
119    \verbatim
120    .\bjam boost.locale.posix=off boost.locale.icu=off --with-locale stage
121    \endverbatim
122
123\section bb_build_test Running Unit Tests
124
125You can run unit tests by invoking \c bjam with \c libs/locale/test project parameter
126\verbatim
127./bjam libs/locale/test
128\endverbatim
129
130\section binary_compatibility Binary Compatibility
131
132Boost.Locale is built with binary compatibility in mind. Switching localization back ends on or off,
133or using iconv or not, does not affect binary compatibility. So if a dynamic library was built
134with all possible backends, other dynamic libraries compiled with, for example, only the \c std, \c posix
135or \c winapi backends would still be binary-compatible with it.
136
137However this definitely has an effect on some features. For example, if you
138try to use boundary analysis or a calendar facet when the library does not support the icu backend
139you would get an exception.
140
141*/
142
143
144