]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
47 | Now all you need to do is invoke bjam command: | |
48 | ||
49 | \verbatim | |
50 | ./bjam --with-locale stage | |
51 | \endverbatim | |
52 | ||
53 | Or on Windows | |
54 | \verbatim | |
55 | .\bjam --with-locale stage | |
56 | \endverbatim | |
57 | ||
58 | If you are using custom ICU build or you are using Microsoft Windows | |
59 | you need to provide a path to location of ICU library using \c -sICU_PATH option | |
60 | ||
61 | For 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 | |
90 | when using Microsoft Visual Studio so Boost.Build will link correctly debug and release | |
91 | versions of boost_locale library. | |
92 | ||
93 | \section bb_build_opts Build Options | |
94 | ||
95 | Boost.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 | ||
106 | Also 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 | ||
112 | For 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 | ||
125 | You 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 | ||
132 | Boost.Locale is built with binary compatibility in mind. Switching localization back ends on or off, | |
133 | or using iconv or not, does not affect binary compatibility. So if a dynamic library was built | |
134 | with all possible backends, other dynamic libraries compiled with, for example, only the \c std, \c posix | |
135 | or \c winapi backends would still be binary-compatible with it. | |
136 | ||
137 | However this definitely has an effect on some features. For example, if you | |
138 | try to use boundary analysis or a calendar facet when the library does not support the icu backend | |
139 | you would get an exception. | |
140 | ||
141 | */ | |
142 | ||
143 |