Squashed 'third_party/boostorg/serialization/' content from commit 738695b
Change-Id: I48528198ad1f62b90288d249eb2243d4db02fd5d
git-subtree-dir: third_party/boostorg/serialization
git-subtree-split: 738695b70733f9d592a570fb17a505d6a029b48a
diff --git a/doc/implementation.html b/doc/implementation.html
new file mode 100644
index 0000000..08e9974
--- /dev/null
+++ b/doc/implementation.html
@@ -0,0 +1,255 @@
+<!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>