| Brian Silverman | 8867871 | 2018-08-04 23:56:48 -0700 | [diff] [blame^] | 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<OStream::char_type></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>© 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> |