|
Serialization
Implementation Notes
|
- Character Encoding
- Specific Compiler/Library Issues
- 44.X
- Intel 8.0
- Visual C++ 8.0
- Visual C++ 7.1
- Comeau 4.3.3
- Code Warrior 9.x
- Code Warrior 8.3
- TRU64
- Dinkumware Library
- STLPort 4.5.3
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.
- All text archives (i.e.
text_?archive
) will produce
text output in the current stream locale
. Generally this will
produce no changes in string data.
- To produce binary output with Microsoft compilers, the stream
will have to be opened with mode
ios::binary
.
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 ios::binary
is not required and is ignored if used.
- character XML archives (i.e. xml_oarchive) will produce XML output
with characters encoded according to the current stream
locale
.
- wide character XML archives (i.e. xml_woarchive) will produce
files encoded in UTF-8.
This character encoding is implemented by changing the locale
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 boost::archive::no_codecvt
when the archive is opened. In this case, the stream locale
will
not be changed by the serialization library.
Note that the code conversion included for wide character text and XML
archives could alter std::string
data stored in archives.
Suppose a normal (multi-byte) character string
is written to a wide character stream. Our system uses the current locale
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 locale
on the platform that reads the archive is different than
the locale
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 locale
dependent multi-byte strings or be sure that
the locale
is set correctly before reading the archive.
To produce wide character text output (i.e. 16 bit characters on Win32 systems),
do the following.
- Open a wide character stream.
- Alter the stream
locale
to use
boost::archive::codecvt_null<OStream::char_type>
- Create the archive with the flag
no_codecvt
.
Naturally, the input process has to be symmetrical.
No known issues. All tests compile and run in debug and release modes.
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:
/wd4996
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
demo_portable_iarchive.cpp
would have to be reformulated as a library or dll
similar to the pre-defined archives in order to function.
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.
This compiler can treat wchar_t
as either
a short integer or an intrinsic type.
If /Zc:wchar_t
is specified on the
compile command line, wchar_t
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 - BUT - both the library AND the application
must be compiled with the same switch settings. Note that BJAM
includes this switch by default. So if want to use the libraries that
BJAM
builds, you should include this switch
when you compile your own applications.
Using the Visual C++ IDE
The library includes a VC++ 7.1 "Solution" - BoostSerializationLibrary
along with a set of project files - one for each demo and test. Consider the following if you
decide to use these configurations.
- The projects assume that the tests have been built with bjam using the default
locations. This will result in a
bin
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.
- There are project configurations for all the combinations of build variants that boost
supports. That is for release, debug, static, static multi-threading, etc..
- If you want to use/debug the DLL versions of libraries and corresponding tests, alter
the project file to define
BOOST_ALL_DYN_LINK=1
.
Note that for the executables to run, the PATH
environmental variable will have to include the directories that contain the DLL versions of
the boost libraries.
- 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.
- 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.
- To test that boost libraries are built correctly, one can build and test them the way we do.
This entails:
- downloading a copy of bjam.exe
- building process_jam_log
- building compiler_status
- invoking runtest.bat
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.
- This compiler fails to make a DLL with export under windows.
- The associated library - libcomo fails when using a codecvt facet.
This generates a failure with all wide character archives.
- the test_set fails by going into an infinite memory leak.
- Some tests and demos fail - still under investigation
all the above issues for Code Warrior 9.x plus:
- This compiler only supports templated streams with the static library version.
- The above inhibits the build of DLL versions of the library.
- Some demos fail - still under investigation
All tests and demos pass except for test_variant. Boost Variant doesn't function
wih this compiler
Several compilers, including Visual C++ 6.0, use an older dinkumware library.
These platforms have several issues:
- The dinkumware library shipped with this compiler does not change the locale facet
of an i/o stream unless the
imbue
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 no_codecvt
flag. Note this problem will
occur on all compilers shipped with this library.
- Other issues have been worked around in the file.
dinkumware.hpp
- when built to use the dynamic linking versions of the C++ runtime code (dynamic)
all tests fail to link. This is due to a missing symbol in the stlport library related
to custom codecvt facets.
- 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.
Revised 1 November, 2004
© Copyright Robert Ramey 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)