ceph/src/boost/libs/locale/doc/building_boost_locale.txt

   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