123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255 |
- <!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
- <html>
- <!--
- (C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
- Use, modification and distribution is subject to the Boost Software
- License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
- http://www.boost.org/LICENSE_1_0.txt)
- -->
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <link rel="stylesheet" type="text/css" href="../../../boost.css">
- <link rel="stylesheet" type="text/css" href="style.css">
- <title>Serialization - Implementation Notes</title>
- </head>
- <body link="#0000ff" vlink="#800080">
- <table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
- <tr>
- <td valign="top" width="300">
- <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
- </td>
- <td valign="top">
- <h1 align="center">Serialization</h1>
- <h2 align="center">Implementation Notes</h2>
- </td>
- </tr>
- </table>
- <hr>
- <dl class="page-index">
- <dt><a href="#charencoding">Character Encoding</a>
- <dt><a href="#othercompilerissues">Specific Compiler/Library Issues</a>
- <dl class="page-index">
- <dt><a href="#gcc4x">44.X</a>
- <dt><a href="#intel80">Intel 8.0</a>
- <dt><a href="#vc80">Visual C++ 8.0</a>
- <dt><a href="#vc71">Visual C++ 7.1</a>
- <dt><a href="#comeau">Comeau 4.3.3</a>
- <dt><a href="#codewarrior9">Code Warrior 9.x</a>
- <dt><a href="#codewarrior">Code Warrior 8.3</a>
- <dt><a href="#tru64">TRU64</a>
- <dt><a href="#dinkumware">Dinkumware Library</a>
- <dt><a href="#stlport">STLPort 4.5.3</a>
- </dl>
- </dl>
- <h3><a name="charencoding">Character Encoding</a></h3>
- The whole question of character encoding combined with wide characters
- is much more complicated than it would seem to be. The current library
- defines in 3 formats (text, binary, and XML), wide and narrow characters,
- and attempts to be portable between compiler libraries. The results of
- a rather long consideration of all these factors has been to set
- default encoding according to the following rules.
- <ul>
- <li>All text archives (i.e. <code style="white-space: normal">text_?archive</code>) will produce
- text output in the current stream <code style="white-space: normal">locale</code>. Generally this will
- produce no changes in string data.
- <li>To produce binary output with Microsoft compilers, the stream
- will have to be opened with mode <code style="white-space: normal">ios::binary</code>.
- Failure to do so will result in 0x0d characters (carriage-return)
- characters being removed from the input stream if they are followed
- by a 0x0a character (line-feed). This could corrupt the input
- and make the file unreadable. On UNIX systems the <code style="white-space: normal">ios::binary</code>
- is not required and is ignored if used.
- <li>character XML archives (i.e. xml_oarchive) will produce XML output
- with characters encoded according to the current stream <code style="white-space: normal">locale</code>.
- <li>wide character XML archives (i.e. xml_woarchive) will produce
- files encoded in UTF-8.
- </ul>
- This character encoding is implemented by changing the <code style="white-space: normal">locale</code> of the
- i/o stream used by an archive when the archive is constructed, the stream
- locale is changed back to its original value. This action can be overridden
- by specifying <code style="white-space: normal">boost::archive::no_codecvt</code>
- when the archive is opened. In this case, the stream <code style="white-space: normal">locale</code> will
- not be changed by the serialization library.
- <p>
- Note that the code conversion included for wide character text and XML
- archives could alter <code style="white-space: normal">std::string</code> data stored in archives.
- Suppose a normal (multi-byte) character string
- is written to a wide character stream. Our system uses the current <code style="white-space: normal">locale</code>
- to translate it to a wide character string before writing it out.
- Upon reading, it is translated back to a (multi-byte)string.
- If the <code style="white-space: normal">locale</code> on the platform that reads the archive is different than
- the <code style="white-space: normal">locale</code> on the platform that wrote the stream, the actual string data
- may be altered by the serialization process. To avoid this, either
- avoid usage of <code style="white-space: normal">locale</code> dependent multi-byte strings or be sure that
- the <code style="white-space: normal">locale</code> is set correctly before reading the archive.
- <p>
- To produce wide character text output (i.e. 16 bit characters on Win32 systems),
- do the following.
- <ul>
- <li>Open a wide character stream.
- <li>Alter the stream <code style="white-space: normal">locale</code> to use
- <code style="white-space: normal">boost::archive::codecvt_null<OStream::char_type></code>
- <li>Create the archive with the flag <code style="white-space: normal">no_codecvt</code>.
- </ul>
- Naturally, the input process has to be symmetrical.
- <h3><a name="othercompilerissues">Specific Compiler/Library Issues</a></h3>
- <h4><a name="gcc4x">GCC 4.X</a></h4>
- <ul>
- <li>GCC versions for Cygwin and MinGW fail to support wide character I/O.
- So all tests using wide char I/O fail. Note that if wide character I/O support
- is added with STLPort, all tests complete successfully.
- <li>This compiler generates long warning messages related to the usage of
- non virtual destructors in polymorphic classes. These warnings have been
- carefully considered and the code that generates these warning has been
- unchanged. In this case the warning should should be ignored as in certain
- usages of the library, making the destructors virtual could lead to problems.
- As an alternative, base class destructors have been made "protected" to
- address the concerns that motivate these warning messages. When building
- the serialization library and tests with bjam, these warnings are suppressed.
- When building one's own applications, these warnings can be suppressed by
- adding the following to the compiler command line:
- <pre><code>
- -Wno-non-virtual-dtor
- -Wno-ctor-dtor-privacy
- </code></pre>
- </ul>
- <h4><a name="intel80">Intel C++ 8.0</a></h4>
- No known issues. All tests compile and run in debug and release modes.
- <h4><a name="vc80">Visual C++ 8.0</a></h4>
- This compiler emits warnings for calls to functions from the standard
- library which are deemed security risks. The serialization depends upon
- making some of these calls so programs which use the serialization library
- will get warning messages. These messages can be suppressed from the command
- line by including the following switch:
- <pre><code>
- /wd4996
- </code></pre>
- <h4><a name="vc71">Visual C++ 7.1</a></h4>
- Derivation from an archive class defined in a DLL as described in ... will not work.
- This is due to the way that VC++ handles templated code with __decl(dllexport) and
- __decl(dllimport) specifications. Basically, this compiler requires that all the
- instantiations have the same specification - even though they have different
- template arguments. The example <code style="white-space: normal">
- demo_portable_iarchive.cpp</code> would have to be reformulated as a library or dll
- similar to the pre-defined archives in order to function.
- <p>
- This compiler does not have RTTI or exception handling turned on by default. Although
- they are not strictly necessary to use the serialization package, the example and test
- programs presume that they are enabled. So be sure your command line or IDE settings
- enable these features if you want to build and run these programs.
- <p>
- This compiler can treat <code style="white-space: normal">wchar_t</code> as either
- a short integer or an intrinsic type.
- If <code style="white-space: normal">/Zc:wchar_t</code> is specified on the
- compile command line, <code style="white-space: normal">wchar_t</code> will be
- considered an intrinsic type - otherwise
- it will be treated as a synonym for a 16 bit integer. The library can be used
- either way - <strong>BUT</strong> - both the libray <strong>AND</strong> the application
- must be compiled with the same switch settings. Note that <code style="white-space: normal">BJAM</code>
- includes this switch by default. So if want to use the libraries that
- <code style="white-space: normal">BJAM</code> builds, you should include this switch
- when you compile your own applications.
- <h5>Using the Visual C++ IDE</h5>
- The library includes a VC++ 7.1 "Solution" - <code style="white-space: normal">BoostSerializationLibrary</code>
- along with a set of project files - one for each demo and test. Consider the following if you
- decide to use these configurations.
- <ul>
- <li>The projects assume that the tests have been built with bjam using the default
- locations. This will result in a <code style="white-space: normal">bin</code> subdirectory
- within one's main boost directory. Below this there is a whole structure which maintains
- object and library files according to the type of build. The easiest way to build this is to
- invoke the runtest script which uses bjam (see below). If the libraries are not in these locations,
- the projects will have to be modified accordingly.
- <li>There are project configurations for all the combinations of build variants that boost
- supports. That is for release, debug, static, static multi-threading, etc..
- <li>If you want to use/debug the DLL versions of libraries and corresponding tests, alter
- the project file to define <code style="white-space: normal">BOOST_ALL_DYN_LINK=1</code>.
- Note that for the executables to run, the <code style="white-space: normal">PATH</code>
- environmental variable will have to include the directories that contain the DLL versions of
- the boost libraries.
- <li>If you have difficulties building your own projects and linking with the boost libraries,
- compare the project settings of your own projects with the ones here. VC sometimes requires
- consistent settings between projects and the libraries they use in order to link properly.
- In particular, check support for exceptions, runtime typing(RTTI), and intrinsic support for
- wide characters. The standard version of this library presumes that these facilities are
- enabled. Projects generated by the IDE wizard do not have these features enabled by default.
- <li>Frequently when trying to build a project or view project properties, one is presented with
- a message box with the message "unspecified error". This seems to occur when one changes the
- build configuration selection. It turns out this can be "fixed" by going to the "Build"
- menu item, selecting "Configuration Manager" and selecting a build configuration for the project
- you're working with.
- <li>To test that boost libraries are built correctly, one can build and test them the way we do.
- This entails:
- <ol>
- <li>downloading a copy of bjam.exe
- <li>building process_jam_log
- <li>building compiler_status
- <li>invoking runtest.bat
- </ol>
- This will build the serialization library and run the tests on your system. If there are more than a
- a couple of test failures, you likely won't be able to get your own projects working. If most of the
- tests pass, you can be confident that your own projects will work once you get your project settings
- in sync with those included here.
- </ul>
- <h4><a name="comeau">Comeau 4.3.3</a></h4>
- <ul>
- <li>This compiler fails to make a DLL with export under windows.
- <li>The associated library - libcomo fails when using a codecvt facet.
- This generates a failure with all wide character archives.
- <li>the test_set fails by going into an infinite memory leak.
- </ul>
- <h4><a name="codewarrior9">Code Warrior 9.x</a></h4>
- <ul>
- <li>Some tests and demos fail - still under investigation
- </ul>
- <h4><a name="codewarrior">Code Warrior 8.3</a></h4>
- all the above issues for Code Warrior 9.x plus:
- <ul>
- <li>This compiler only supports templated streams with the static library version.
- <li>The above inhibits the build of DLL versions of the library.
- <li>Some demos fail - still under investigation
- </ul>
- <h4><a name="tru64">TRU64</a></h4>
- All tests and demos pass except for test_variant. Boost Variant doesn't function
- wih this compiler
- <h4><a name="dinkumware">Dinkumware Library</a></h4>
- Several compilers, including Visual C++ 6.0, use an older dinkumware library.
- These platforms have several issues:
- <ul>
- <li>The dinkumware library shipped with this compiler does not change the locale facet
- of an i/o stream unless the <code style="white-space: normal">imbue</code> function is called before the
- stream is opened. In order to use this library with this environment to generate UTF-8
- files, one cannot depend on the "automatic" setting of locale that archives implement. The
- stream locale must be set explicitly on the stream before an archive is opened on it. The
- archive should be opened with the <code style="white-space: normal">no_codecvt</code> flag. Note this problem will
- occur on all compilers shipped with this library.
- <li>Other issues have been worked around in the file.
- <a href="../../../boost/archive/dinkumware.hpp" target="dinkumware_hpp">dinkumware.hpp</a>
- </ul>
- <h4><a name="stlport">STLPort 4.5.3</a></h4>
- <ul>
- <li>when built to use the dynamic linking versions of the C++ runtime code (<runtime-link>dynamic)
- all tests fail to link. This is due to a missing symbol in the stlport library related
- to custom codecvt facets.
- <li>the test_set fails to run correctly. It seems the hashed set iterator doesn't
- implement the ++ operator correctly. This causes the test to fail by consuming all available
- memory. Given this, this test is commented out.
- </ul>
- <hr>
- <p>Revised 1 November, 2004
- <p><i>© Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2015.
- Distributed under the Boost Software License, Version 1.0. (See
- accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- </i></p>
- </body>
- </html>
|