256 lines
14 KiB
HTML
256 lines
14 KiB
HTML
<!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>
|