ceph/src/boost/libs/serialization/doc/implementation.html

   1 <!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!--
   4 (C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
   5 Use, modification and distribution is subject to the Boost Software
   6 License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
   7 http://www.boost.org/LICENSE_1_0.txt)
   8 -->
   9 <head>
  10 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  11 <link rel="stylesheet" type="text/css" href="../../../boost.css">
  12 <link rel="stylesheet" type="text/css" href="style.css">
  13 <title>Serialization - Implementation Notes</title>
  14 </head>
  15 <body link="#0000ff" vlink="#800080">
  16 <table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
  17   <tr>
  18     <td valign="top" width="300">
  19       <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
  20     </td>
  21     <td valign="top">
  22       <h1 align="center">Serialization</h1>
  23       <h2 align="center">Implementation Notes</h2>
  24     </td>
  25   </tr>
  26 </table>
  27 <hr>
  28 <dl class="page-index">
  29   <dt><a href="#charencoding">Character Encoding</a>
  30   <dt><a href="#othercompilerissues">Specific Compiler/Library Issues</a>
  31   <dl class="page-index">
  32     <dt><a href="#gcc4x">44.X</a>
  33     <dt><a href="#intel80">Intel 8.0</a>
  34     <dt><a href="#vc80">Visual C++ 8.0</a>
  35     <dt><a href="#vc71">Visual C++ 7.1</a>
  36     <dt><a href="#comeau">Comeau 4.3.3</a>
  37     <dt><a href="#codewarrior9">Code Warrior 9.x</a>
  38     <dt><a href="#codewarrior">Code Warrior 8.3</a>
  39     <dt><a href="#tru64">TRU64</a>
  40     <dt><a href="#dinkumware">Dinkumware Library</a>
  41     <dt><a href="#stlport">STLPort 4.5.3</a>
  42   </dl>
  43 </dl>
  44
  45 <h3><a name="charencoding">Character Encoding</a></h3>
  46 The whole question of character encoding combined with wide characters
  47 is much more complicated than it would seem to be. The current library
  48 defines in 3 formats (text, binary, and XML), wide and narrow characters,
  49 and attempts to be portable between compiler libraries.  The results of
  50 a rather long consideration of all these factors has been to set
  51 default encoding according to the following rules.
  52 <ul>
  53   <li>All text archives (i.e. <code style="white-space: normal">text_?archive</code>) will produce
  54       text output in the current stream <code style="white-space: normal">locale</code>.  Generally this will
  55       produce no changes in string data.
  56   <li>To produce binary output with Microsoft compilers, the stream
  57       will have to be opened with mode <code style="white-space: normal">ios::binary</code>.
  58       Failure to do so will result in 0x0d characters (carriage-return)
  59       characters being removed from the input stream if they are followed
  60       by a 0x0a character (line-feed).  This could corrupt the input
  61       and make the file unreadable.  On UNIX systems the <code style="white-space: normal">ios::binary</code>
  62       is not required and is ignored if used.
  63   <li>character XML archives (i.e. xml_oarchive) will produce XML output
  64       with characters encoded according to the current stream <code style="white-space: normal">locale</code>.
  65   <li>wide character XML archives (i.e. xml_woarchive) will produce
  66       files encoded in UTF-8.
  67 </ul>
  68 This character encoding is implemented by changing the <code style="white-space: normal">locale</code> of the
  69 i/o stream used by an archive when the archive is constructed, the stream
  70 locale is changed back to its original value. This action can be overridden
  71 by specifying <code style="white-space: normal">boost::archive::no_codecvt</code>
  72 when the archive is opened.  In this case, the stream <code style="white-space: normal">locale</code> will
  73 not be changed by the serialization library.
  74 <p>
  75 Note that the code conversion included for wide character text and XML
  76 archives could alter <code style="white-space: normal">std::string</code> data stored in archives.
  77 Suppose a normal (multi-byte) character string
  78 is written to a wide character stream.  Our system uses the current <code style="white-space: normal">locale</code>
  79 to translate it to a wide character string before writing it out.
  80 Upon reading, it is translated back to a (multi-byte)string.
  81 If the <code style="white-space: normal">locale</code> on the platform that reads the archive is different than
  82 the <code style="white-space: normal">locale</code> on the platform that wrote the stream, the actual string data
  83 may be altered by the serialization process. To avoid this, either
  84 avoid usage of <code style="white-space: normal">locale</code> dependent multi-byte strings or be sure that
  85 the <code style="white-space: normal">locale</code> is set correctly before reading the archive.
  86 <p>
  87 To produce wide character text output (i.e. 16 bit characters on Win32 systems),
  88 do the following.
  89 <ul>
  90   <li>Open a wide character stream.
  91   <li>Alter the stream <code style="white-space: normal">locale</code> to use
  92      <code style="white-space: normal">boost::archive::codecvt_null&lt;OStream::char_type&gt;</code>
  93   <li>Create the archive with the flag <code style="white-space: normal">no_codecvt</code>.
  94 </ul>
  95 Naturally, the input process has to be symmetrical.
  96 <h3><a name="othercompilerissues">Specific Compiler/Library Issues</a></h3>
  97 <h4><a name="gcc4x">GCC 4.X</a></h4>
  98 <ul>
  99     <li>GCC versions for Cygwin and MinGW fail to support wide character I/O.
 100     So all tests using wide char I/O fail.  Note that if wide character I/O support
 101     is added with STLPort, all tests complete successfully.
 102     <li>This compiler generates long warning messages related to the usage of
 103     non virtual destructors in polymorphic classes.  These warnings have been
 104     carefully considered and the code that generates these warning has been
 105     unchanged.  In this case the warning should should be ignored as in certain
 106     usages of the library, making the destructors virtual could lead to problems.
 107     As an alternative, base class destructors have been made "protected" to
 108     address the concerns that motivate these warning messages.  When building
 109     the serialization library and tests with bjam, these warnings are suppressed.
 110     When building one's own applications, these warnings can be suppressed by
 111     adding the following to the compiler command line:
 112     <pre><code>
 113     -Wno-non-virtual-dtor
 114     -Wno-ctor-dtor-privacy
 115     </code></pre>
 116 </ul>
 117 <h4><a name="intel80">Intel C++ 8.0</a></h4>
 118 No known issues. All tests compile and run in debug and release modes.
 119
 120 <h4><a name="vc80">Visual C++ 8.0</a></h4>
 121 This compiler emits warnings for calls to functions from the standard
 122 library which are deemed security risks.  The serialization depends upon
 123 making some of these calls so programs which use the serialization library
 124 will get warning messages.  These messages can be suppressed from the command
 125 line by including the following switch:
 126     <pre><code>
 127     /wd4996
 128     </code></pre>
 129
 130 <h4><a name="vc71">Visual C++ 7.1</a></h4>
 131 Derivation from an archive class defined in a DLL as described in ... will not work.
 132 This is due to the way that VC++ handles templated code with __decl(dllexport) and
 133 __decl(dllimport) specifications.  Basically, this compiler requires that all the
 134 instantiations have the same specification - even though they have different
 135 template arguments. The example <code style="white-space: normal">
 136 demo_portable_iarchive.cpp</code> would have to be reformulated as a library or dll
 137 similar to the pre-defined archives in order to function.
 138 <p>
 139 This compiler does not have RTTI or exception handling turned on by default.  Although
 140 they are not strictly necessary to use the serialization package, the example and test
 141 programs presume that they are enabled.  So be sure your command line or IDE settings
 142 enable these features if you want to build and run these programs.
 143 <p>
 144 This compiler can treat <code style="white-space: normal">wchar_t</code> as either
 145 a short integer or an intrinsic type.
 146 If <code style="white-space: normal">/Zc:wchar_t</code> is specified on the
 147 compile command line, <code style="white-space: normal">wchar_t</code> will be
 148 considered an intrinsic type - otherwise
 149 it will be treated as a synonym for a 16 bit integer.  The library can be used
 150 either way - <strong>BUT</strong> - both the libray <strong>AND</strong> the application
 151 must be  compiled with the same switch settings.  Note that <code style="white-space: normal">BJAM</code>
 152 includes this switch by default.  So if want to use the libraries that
 153 <code style="white-space: normal">BJAM</code> builds, you should include this switch
 154 when you compile your own applications.
 155 <h5>Using the Visual C++ IDE</h5>
 156 The library includes a VC++ 7.1 "Solution" - <code style="white-space: normal">BoostSerializationLibrary</code>
 157 along with a set of project files - one for each demo and test. Consider the following if you
 158 decide to use these configurations.
 159 <ul>
 160     <li>The projects assume that the tests have been built with bjam using the default
 161     locations.  This will result in a <code style="white-space: normal">bin</code> subdirectory
 162     within one's main boost directory.  Below this there is a whole structure which maintains
 163     object and library files according to the type of build.  The easiest way to build this is to
 164     invoke the runtest script which uses bjam (see below).  If the libraries are not in these locations,
 165     the projects will have to be modified accordingly.
 166     <li>There are project configurations for all the combinations of build variants that boost
 167     supports. That is for release, debug, static, static multi-threading, etc..
 168     <li>If you want to use/debug the DLL versions of libraries and corresponding tests, alter
 169     the project file to define <code style="white-space: normal">BOOST_ALL_DYN_LINK=1</code>.
 170     Note that for the executables to run, the <code style="white-space: normal">PATH</code>
 171     environmental variable will have to include the directories that contain the DLL versions of
 172     the boost libraries.
 173     <li>If you have difficulties building your own projects and linking with the boost libraries,
 174     compare the project settings of your own projects with the ones here.  VC sometimes requires
 175     consistent settings between projects and the libraries they use in order to link properly.
 176     In particular, check support for exceptions, runtime typing(RTTI), and intrinsic support for
 177     wide characters.  The standard version of this library presumes that these facilities are
 178     enabled.  Projects generated by the IDE wizard do not have these features enabled by default.
 179     <li>Frequently when trying to build a project or view project properties, one is presented with
 180     a message box with the message "unspecified error".  This seems to occur when one changes the
 181     build configuration selection.  It turns out this can be "fixed" by going to the "Build"
 182     menu item, selecting "Configuration Manager" and selecting a build configuration for the project
 183     you're working with.
 184     <li>To test that boost libraries are built correctly, one can build and test them the way we do.
 185     This entails:
 186     <ol>
 187         <li>downloading a copy of bjam.exe
 188         <li>building process_jam_log
 189         <li>building compiler_status
 190         <li>invoking runtest.bat
 191     </ol>
 192     This will build the serialization library and run the tests on your system. If there are more than a
 193     a couple of test failures, you likely won't be able to get your own projects working.  If most of the
 194     tests pass, you can be confident that your own projects will work once you get your project settings
 195     in sync with those included here.
 196 </ul>
 197
 198 <h4><a name="comeau">Comeau 4.3.3</a></h4>
 199 <ul>
 200     <li>This compiler fails to make a DLL with export under windows.
 201     <li>The associated library - libcomo fails when using a codecvt facet.
 202     This generates a failure with all wide character archives.
 203     <li>the test_set fails by going into an infinite memory leak.
 204 </ul>
 205
 206 <h4><a name="codewarrior9">Code Warrior 9.x</a></h4>
 207 <ul>
 208     <li>Some tests and demos fail - still under investigation
 209 </ul>
 210
 211 <h4><a name="codewarrior">Code Warrior 8.3</a></h4>
 212 all the above issues for Code Warrior 9.x plus:
 213 <ul>
 214     <li>This compiler only supports templated streams with the static library version.
 215     <li>The above inhibits the build of DLL versions of the library.
 216     <li>Some demos fail - still under investigation
 217 </ul>
 218
 219 <h4><a name="tru64">TRU64</a></h4>
 220 All tests and demos pass except for test_variant.  Boost Variant doesn't function
 221 wih this compiler
 222
 223 <h4><a name="dinkumware">Dinkumware Library</a></h4>
 224 Several compilers, including Visual C++ 6.0, use an older dinkumware library.
 225 These platforms have several issues:
 226 <ul>
 227     <li>The dinkumware library shipped with this compiler does not change the locale facet
 228     of an i/o stream unless the <code style="white-space: normal">imbue</code> function is called before the
 229     stream is opened.  In order to use this library with this environment to generate UTF-8
 230     files, one cannot depend on the "automatic" setting of locale that archives implement. The
 231     stream locale must be set explicitly on the stream before an archive is opened on it.  The
 232     archive should be opened with the <code style="white-space: normal">no_codecvt</code> flag.  Note this problem will
 233     occur on all compilers shipped with this library.
 234     <li>Other issues have been worked around in the file.
 235     <a href="../../../boost/archive/dinkumware.hpp" target="dinkumware_hpp">dinkumware.hpp</a>
 236 </ul>
 237
 238 <h4><a name="stlport">STLPort 4.5.3</a></h4>
 239 <ul>
 240     <li>when built to use the dynamic linking versions of the C++ runtime code (<runtime-link>dynamic)
 241     all tests fail to link.  This is due to a missing symbol in the stlport library related
 242     to custom codecvt facets.
 243     <li>the test_set fails to run correctly. It seems the hashed set iterator doesn't
 244     implement the ++ operator correctly.  This causes the test to fail by consuming all available
 245     memory.  Given this, this test is commented out.
 246 </ul>
 247
 248 <hr>
 249 <p>Revised 1 November, 2004
 250 <p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2015.
 251 Distributed under the Boost Software License, Version 1.0. (See
 252 accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 253 </i></p>
 254 </body>
 255 </html>