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 . 5Use, modification and distribution is subject to the Boost Software 6License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at 7http://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> 46The whole question of character encoding combined with wide characters 47is much more complicated than it would seem to be. The current library 48defines in 3 formats (text, binary, and XML), wide and narrow characters, 49and attempts to be portable between compiler libraries. The results of 50a rather long consideration of all these factors has been to set 51default 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> 68This character encoding is implemented by changing the <code style="white-space: normal">locale</code> of the 69i/o stream used by an archive when the archive is constructed, the stream 70locale is changed back to its original value. This action can be overridden 71by specifying <code style="white-space: normal">boost::archive::no_codecvt</code> 72when the archive is opened. In this case, the stream <code style="white-space: normal">locale</code> will 73not be changed by the serialization library. 74<p> 75Note that the code conversion included for wide character text and XML 76archives could alter <code style="white-space: normal">std::string</code> data stored in archives. 77Suppose a normal (multi-byte) character string 78is written to a wide character stream. Our system uses the current <code style="white-space: normal">locale</code> 79to translate it to a wide character string before writing it out. 80Upon reading, it is translated back to a (multi-byte)string. 81If the <code style="white-space: normal">locale</code> on the platform that reads the archive is different than 82the <code style="white-space: normal">locale</code> on the platform that wrote the stream, the actual string data 83may be altered by the serialization process. To avoid this, either 84avoid usage of <code style="white-space: normal">locale</code> dependent multi-byte strings or be sure that 85the <code style="white-space: normal">locale</code> is set correctly before reading the archive. 86<p> 87To produce wide character text output (i.e. 16 bit characters on Win32 systems), 88do 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<OStream::char_type></code> 93 <li>Create the archive with the flag <code style="white-space: normal">no_codecvt</code>. 94</ul> 95Naturally, 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> 118No known issues. All tests compile and run in debug and release modes. 119 120<h4><a name="vc80">Visual C++ 8.0</a></h4> 121This compiler emits warnings for calls to functions from the standard 122library which are deemed security risks. The serialization depends upon 123making some of these calls so programs which use the serialization library 124will get warning messages. These messages can be suppressed from the command 125line 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> 131Derivation from an archive class defined in a DLL as described in ... will not work. 132This 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 134instantiations have the same specification - even though they have different 135template arguments. The example <code style="white-space: normal"> 136demo_portable_iarchive.cpp</code> would have to be reformulated as a library or dll 137similar to the pre-defined archives in order to function. 138<p> 139This compiler does not have RTTI or exception handling turned on by default. Although 140they are not strictly necessary to use the serialization package, the example and test 141programs presume that they are enabled. So be sure your command line or IDE settings 142enable these features if you want to build and run these programs. 143<p> 144This compiler can treat <code style="white-space: normal">wchar_t</code> as either 145a short integer or an intrinsic type. 146If <code style="white-space: normal">/Zc:wchar_t</code> is specified on the 147compile command line, <code style="white-space: normal">wchar_t</code> will be 148considered an intrinsic type - otherwise 149it will be treated as a synonym for a 16 bit integer. The library can be used 150either way - <strong>BUT</strong> - both the libray <strong>AND</strong> the application 151must be compiled with the same switch settings. Note that <code style="white-space: normal">BJAM</code> 152includes 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 154when you compile your own applications. 155<h5>Using the Visual C++ IDE</h5> 156The library includes a VC++ 7.1 "Solution" - <code style="white-space: normal">BoostSerializationLibrary</code> 157along with a set of project files - one for each demo and test. Consider the following if you 158decide 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> 212all 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> 220All tests and demos pass except for test_variant. Boost Variant doesn't function 221wih this compiler 222 223<h4><a name="dinkumware">Dinkumware Library</a></h4> 224Several compilers, including Visual C++ 6.0, use an older dinkumware library. 225These 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>© Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2015. 251Distributed under the Boost Software License, Version 1.0. (See 252accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 253</i></p> 254</body> 255</html> 256