source: downloads/boost_1_33_1/libs/date_time/xmldoc/buildinfo.xml @ 12

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" 
"../../../tools/boostbook/dtd/boostbook.dtd">

<!-- Copyright (c) 2001-2004 CrystalClear Software, Inc.
     Subject to the Boost Software License, Version 1.0. 
     (See accompanying file LICENSE-1.0 or  http://www.boost.org/LICENSE-1.0)
-->

<section id="date_time.buildinfo">
  <title>Build-Compiler Information</title>

  <para>
    <link linkend="overview">Overview</link> --
    <link linkend="compile_options">Compilation Options</link> --
    <link linkend="portability">Compiler/Portability Notes</link> --
    <link linkend="dir_structure">Directory Structure</link> --
    <link linkend="other_boost_libs">Required Boost Libraries</link>
  </para>

  <anchor id="overview" />
  <bridgehead renderas="sect3">Overview</bridgehead>
  <para>
    The library has several functions that require the creation of a library file. The Jamfile in the build directory will produce a "static" library (libboost_date_time) and a "dynamic/shared" library (boost_date_time) that contains these functions. 
  </para>
  
  <anchor id="compile_options" />
  <bridgehead renderas="sect3">Compilation Options</bridgehead>
  <para>
    By default the posix_time system uses a single 64 bit integer internally to provide a microsecond level resolution. As an alternative, a combination of a 64 bit integer and a 32 bit integer (96 bit resolution) can be used to provide nano-second level resolutions. The default implementation may provide better performance and more compact memory usage for many applications that do not require nano-second resolutions. 
  </para>
  <para>
    To use the alternate resolution (96 bit nanosecond) the variable <code>BOOST_DATE_TIME_POSIX_TIME_STD_CONFIG</code> must be defined in the library users project files (ie Makefile, Jamfile, etc). This macro is not used by the Gregorian system and therefore has no effect when building the library.
  </para>
  <para>As of version 1.33, the date_time library introduced a new IO streaming system. Some compilers are not capable of utilizing this new system. For those compilers the earlier ("legacy") IO system is still available. Non-supported compilers will select the legacy system automatically but the user can force the usage of the legacy system by defining <code>USE_DATE_TIME_PRE_1_33_FACET_IO</code>.</para>

  <para>As a convenience, <code>date_time</code> has provided some <link linkend="additional_duration_types">additional duration types</link>. Use of these types may have unexpected results due to the snap-to-end-of-month behavior (see <link linkend="snap_to_details">Reversibility of Operations Pitfall</link> for complete details and examples). These types are enabled by default. To disable these types, simply undefine <code>BOOST_DATE_TIME_OPTIONAL_GREGORIAN_TYPES</code> in your project file.</para>

  <para>Another convenience is the default constructors for <code><link linkend="date_time.gregorian.date_class">date</link></code>, and <code><link linkend="date_time.posix_time.ptime_class">ptime</link></code>. These constructors are enabled by default. To disable them, simply define <code>DATE_TIME_NO_DEFAULT_CONSTRUCTOR</code> in your project file.</para>

  <anchor id="portability" />
  <bridgehead renderas="sect3">Compiler/Portability Notes</bridgehead>
  <para>
    The Boost Date-Time library has been built and tested with many compilers. However, some compilers and standard libraries have issues. While some of these issues can be worked around, others are difficult to work around. The following compilers fully support all aspects of the library:
    <itemizedlist mark="bullet">
      <listitem>GCC 3.2 - 3.4, 4.0 on Linux</listitem>
      <listitem>GCC 3.3 on Darwin</listitem>
      <listitem>GCC 3.3 on Solaris</listitem>
      <listitem>GCC 3.2 (cygwin) *</listitem>
      <listitem>MinGW 3.2 *</listitem>
      <listitem>MSVC 7.1 </listitem>
      <listitem>Intel 8.1 Linux and Windows</listitem>
    </itemizedlist>
    * These compilers do not support the <code>wstring/wstream</code> aspects of the <code>date_time</code> library.
  </para>
  <para>
    In particular, a lack of support for standard locales limits the ability of the library to support iostream based input output. For these compilers a set of more limited string based input-output is provided. Some compilers/standard libraries with this limitation include: 
    <itemizedlist mark="bullet">
      <listitem>GCC 2.9x on Linux</listitem>
      <listitem>Borland 5.1.1 and 5.6</listitem>
      <listitem>MSVC 7.0</listitem>
      <listitem>MSVC 6 SP5 </listitem>
    </itemizedlist>
  </para>
  <para>
  Metrowerks Code Warrior 9.4 has some input I/O limitations, but is otherwise
  fully supported.
  </para>
  <bridgehead renderas="sect5">Visual Studio &amp; STLPort</bridgehead>
  <para>There is a known issue with Visual Studio (7.0 &amp; 7.1) and STLPort. The build errors typically make reference to a type issue or 'no acceptable conversion' and are attempting to instantiate a template with <code>wchar_t</code>. The default build of STLPort does not support <code>wchar_t</code>. There are two possible workarounds for this issue. The simplest is the user can build date_time with no wide stream/string etc. The other is to rebuild STLPort with wchar_t support.
  </para>
  <para>To build date_time with no wide stream/string etc, execute the following command from <code>$BOOST_ROOT</code>:
    <screen>bjam -a "-sTOOLS=vc-7_1-stlport" "-sSTLPORT_PATH=..." \
     "-sBUILD=&lt;define>BOOST_NO_STD_WSTRING"           \
     --stagedir=... --with-date_time stage</screen>
    (replace the ellipsis with the correct paths for the build system and adjust the <code>TOOLS</code> to the proper toolset if necessary)
  </para>
  <para>Rebuilding STLPort with <code>wchar_t</code> support involves placing <code>/Zc:wchar_t</code> in the STLPort makefile. Date_time should then be built with the following command from <code>$BOOST_ROOT</code>:
    <screen>bjam -a "-sTOOLS=vc-7_1-stlport" "-sSTLPORT_PATH=..." \
     "-sBUILD=&amp;native-wchar_t>on"                     \
     --stagedir=... --with-date_time stage</screen>
    (replace the ellipsis with the correct paths for the build system and adjust the <code>TOOLS</code> to the proper toolset if necessary)
  </para>
  
  <anchor id="dir_structure" />
  <bridgehead renderas="sect3">Directory Structure</bridgehead>
  <para>
    The directory tree has the following structure:
    <programlisting>/boost/date_time                    -- common headers and template code
/boost/date_time/gregorian          -- Gregorian date system header files
/boost/date_time/posix_time         -- Posix time system headers
/boost/date_time/local_time         -- Local time system headers
/libs/date_time/build               -- build files and output directory
/libs/date_time/test                -- test battery for generic code
/libs/date_time/test/gregorian      -- test battery for the Gregorian system
/libs/date_time/test/posix_time     -- test battery for the posix_time system
/libs/date_time/test/local_time     -- test battery for the local_time system
/libs/date_time/examples/gregorian  -- example programs for dates
/libs/date_time/examples/posix_time -- time example programs
/libs/date_time/examples/local_time -- nifty example programs
/libs/date_time/src/gregorian       -- cpp files for libboost_date_time
/libs/date_time/src/posix_time      -- empty (one file, but no source code...)</programlisting>
  </para>
  
  <anchor id="other_boost_libs" />
  <bridgehead renderas="sect3">Required Boost Libraries</bridgehead>
  <para>
    Various parts of date-time depend on other boost libraries.  These include:
    <itemizedlist mark="bullet">
      <listitem><ulink url="../../libs/tokenizer/index.html">boost.tokenizer</ulink> </listitem>
      <listitem><ulink url="../../libs/integer/cstdint.htm">boost.integer(cstdint)</ulink> </listitem>
      <listitem><ulink url="../../libs/utility/operators.htm">boost.operators</ulink> </listitem>
      <listitem><ulink url="../../libs/conversion/lexical_cast.htm">boost::lexical_cast </ulink> </listitem>
      <listitem><ulink url="../../libs/smart_ptr/smart_ptr.htm">boost::smart_ptr </ulink> </listitem>
      <listitem><ulink url="../../libs/algorithm/string/index.html">boost::string_algorithms </ulink> </listitem>
    </itemizedlist>
    so at least these libraries need to be installed. 
  </para>
</section>