boost/more
1
0
Fork 0
mirror of https://github.com/boostorg/more.git synced 2025-01-29 04:50:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

Copied remotely

Browse Source 
[SVN r39749]
This commit is contained in:
Rene Rivera 2007-10-06 20:23:08 +00:00
parent 9d8a632059
commit 0c387c3afa
106 changed files with 0 additions and 21295 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
BoostCon07.html
View File

@ -1,12 +0,0 @@
<html>
<head>
<meta http-equiv="refresh" content="0; URL=http://www.boostcon.com">
</head>
<body>
The BoostCon site is
<a href="http://www.boostcon.com">live</a>!
</body>
</html>
<!-- Copyright David Abrahams 2006. 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) -->

12
BoostCon07_session_call.html
View File

@ -1,12 +0,0 @@
<html>
<head>
<meta http-equiv="refresh" content="0; URL=http://www.boostcon.com/program/call-for-sessions">
</head>
<body>
The BoostCon site is
<a href="http://www.boostcon.com/program/call-for-sessions">live</a>!
</body>
</html>
<!-- Copyright David Abrahams 2006. 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) -->

BIN
BoostSponsorshipAgreement.pdf
View File

Binary file not shown.

25
Jamfile.v2
View File

@ -1,25 +0,0 @@
# Copyright David Abrahams 2006. 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)
import docutils ;
import path ;
sources = getting_started.rst BoostCon07.rst ;
bases = $(sources:S=) ;
# This is a path relative to the html/ subdirectory where the
# generated output will eventually be moved.
stylesheet = "--stylesheet=../rst.css" ;
for local b in $(bases)
{
html $(b) : $(b).rst :
# <docutils-cmd>"PYTHONPATH=~/src/boost/tools && python ~/src/boost/tools/litre/active-rst.py"
# <docutils-html>"-gdt --writer=html --source-url="./$(b).rst" --link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet)
<docutils-html>"-gdt --source-url="./$(b).rst" --link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet)
;
}
alias htmls : $(bases) ;
stage . : $(bases) ;

221
background.html
View File

@ -1,221 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>
Boost Background Information
</title>
<style type="text/css">
body {
background-color: #FFFFFF;
}
p.c2 {font-style: italic; font-weight: bold}
span.c1 {color: #FFFFFF; font-family: Arial; font-size: 120%}
</style>
</head>
<body>
<table summary="Navigational header"
border="1" cellpadding="2" bgcolor="#007F7F">
<tr>
<td bgcolor="#FFFFFF">
<img src="../boost.png" alt="boost.png (6897 bytes)" width="277"
height="86">
</td>
<td>
<a href="../index.htm"><span class="c1">Home</span></a>
</td>
<td>
<a href="../libs/libraries.htm"><span class="c1">Libraries</span></a>
</td>
<td>
<a href="../people/people.htm"><span class="c1">People</span></a>
</td>
<td>
<a href="../more/faq.htm"><span class="c1">FAQ</span></a>
</td>
<td>
<a href="../more/index.htm"><span class="c1">More</span></a>
</td>
</tr>
</table>
<h1>
Boost Background Information
</h1>
<h2>
Why should an organization use Boost?
</h2>
<p>
In a word, <i><b>Productivity</b></i>. Use of high-quality libraries like
Boost speeds initial development, results in fewer bugs, reduces
reinvention-of-the-wheel, and cuts long-term maintenance costs. And since
Boost libraries tend to become de facto or de jure standards, many
programmers are already familiar with them.
</p>
<p>
Ten of the Boost libraries are included in the <a href=
"http://open-std.org/jtc1/sc22/wg21/docs/library_technical_report.html">C++
Standard Library's TR1</a>, and so are slated for later full
standardization. More Boost libraries are in the pipeline for <a href=
"http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1810.html">TR2</a>.
Using Boost libraries gives an organization a head-start in adopting new
technologies.
</p>
<p>
Many organization already use programs implemented with Boost, like Adobe
<a href="http://www.adobe.com/products/acrobat/readermain.html">Acrobat
Reader 7.0</a>.
</p>
<h2>
Who else is using Boost?
</h2>
<p>
See the <a href="../doc/html/who_s_using_boost_.html">Who's Using Boost
page</a> for a sampling. We don't know the exact numbers, but a release
gets around 100,000 downloads from SourceForge, and that is only one of
several distribution routes.
</p>
<h2>
What do others say about Boost?
</h2>
<p class="c2">
"...one of the most highly regarded and expertly designed C++ library
projects in the world."
</p>
<blockquote>
<p>
-- <a href="http://www.gotw.ca/">Herb Sutter</a> and <a href=
"http://en.wikipedia.org/wiki/Andrei_Alexandrescu">Andrei
Alexandrescu</a>, <a href=
"http://safari.awprofessional.com/?XmlId=0321113586">C++ Coding
Standards</a>
</p>
</blockquote>
<p class="c2">
"Item 55: Familiarize yourself with Boost."
</p>
<blockquote>
<p>
-- <a href="http://www.aristeia.com/">Scott Meyers</a>, <a href=
"http://www.awl.com/cseng/titles/0-321-33487-6/">Effective C++, 3rd
Ed.</a>
</p>
</blockquote>
<p class="c2">
"The obvious solution for most programmers is to use a library that
provides an elegant and efficient platform independent to needed services.
Examples are BOOST..."
</p>
<blockquote>
<p>
-- <a href="http://www.research.att.com/~bs/">Bjarne Stroustrup</a>,
<a href="http://www.research.att.com/~bs/abstraction.pdf">Abstraction,
libraries, and efficiency in C++</a>
</p>
</blockquote>
<h2>
How do users get support?
</h2>
<p>
For relatively straightforward support needs, users rely on the <a href=
"mailing_lists.htm">mailing lists</a>. One of the advantages of Boost is
the responsiveness of other users and Boost developers.
</p>
<p>
For more involved needs, <a href="links.htm#CommercialSupport">Commercial
Support</a> is available.
</p>
<h2>
What about license issues?
</h2>
<p>
Boost has its own <a href="license_info.html">license</a>, developed with
help from the Harvard Law School.&nbsp; The <a href=
"license_info.html">Boost license polices</a> encourage both commercial and
non-commercial use, and the Boost license is not related to the GPL or
other licenses - that are sometimes seen as business unfriendly.
</p>
<h2>
What about other intellectual property issues?
</h2>
<p>
The Boost libraries tend to be new, fresh, and creative designs. They are
not copies, clones, or derivations of proprietary libraries. Boost has a
firm policy to respect the IP rights of others. The development of Boost
libraries is publicly documented via the mailing lists and version control
repository. The source code has been inspected by many, many knowledgeable
programmers. Each Boost file has a copyright notice and license
information. IP issues have been reviewed by the legal teams from some of
the corporations which use Boost, and in some cases these lawyers have been
kind enough to give Boost feedback on IP issues. There are no guarantees,
but those factors all tend to reduce IP risk.
</p>
<h2>
Why would anyone give away valuable software for free?
</h2>
<p>
Businesses and other organizations often prefer to have code developed,
maintained, and improved in the open source community when it does not
contain technology specific to their application domain, because it allows
them to focus more development resources on their core business.
</p>
<p>
Individuals contribute for the technical challenge, to hone their technical
skills, for the sense of community, as part of their graduate school
programs, as a way around geographic isolation, to enhance their employment
opportunities, and as advertisements for their consulting services. There
are probably as many reasons as there are individuals. Some of the
apparently individual contributions come from employees of support
companies with contracts from businesses or other organizations who have an
interest in seeing that a library is well-maintained.
</p>
<h2>
Who pays Boost's expenses?
</h2>
<p>
Boost doesn't really have any expenses! All the infrastructure is
contributed by supporters, such as the <a href=
"http://www.osl.iu.edu/">Open Systems Lab</a> at Indiana University,&nbsp;
<a href="http://sourceforge.net/index.php">SourceForge</a>, <a href=
"http://www.boost-consulting.com/">Boost Consulting</a>, <a href=
"http://www.meta-comm.com/">MetaCommunications</a>, and the individuals,
companies, and other organizations who run the regression tests. Borland,
HP, Intel, and Microsoft have contributed compilers. And hundreds, or even
thousands, of programmers contribute their time. That's what makes Boost
possible.
</p>
<hr>
<p>
Revised <!--webbot bot="Timestamp" s-type="EDITED"
s-format="%d %B, %Y" startspan -->07 July, 2005
<!--webbot bot="Timestamp" endspan i-checksum="21138" -->
</p>
<p>
&copy; Copyright Beman Dawes 2005.
</p>
<p>
Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

538
bibliography.html
View File

@ -1,538 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Boost Bibliography</title>
</head>
<body bgColor="#ffffff">
<table summary="Navigational header" cellPadding="2" bgColor="#007f7f" border="1">
<tr>
<td bgColor="#ffffff"><IMG height="86" alt="boost.png (6897 bytes)" src="../boost.png" width="277"></td>
<td><A href="../index.htm"><font face="Arial" color="#ffffff" size="4">Home</font></A></td>
<td><A href="../libs/libraries.htm"><font face="Arial" color="#ffffff" size="4">Libraries</font></A></td>
<td><A href="../people/people.htm"><font face="Arial" color="#ffffff" size="4">People</font></A></td>
<td><A href="faq.htm"><font face="Arial" color="#ffffff" size="4">FAQ</font></A></td>
<td><A href="index.htm"><font face="Arial" color="#ffffff" size="4">More</font></A></td>
</tr>
</table>
<h1>Boost Bibliography</h1>
<p><A href="#Print_publications">Print publications about Boost or Boost Libraries</A><br>
<A href="#Online_publications">Online publications about Boost or Boost Libraries</A><br>
<A href="#Print_mentions">Print mentions of Boost or Boost Libraries</A><br>
<A href="#Online_mentions">Online mentions of Boost or Boost Libraries</A><br>
<A href="#update">How to update this page</A><br>
<a href="#Acknowledgements">Acknowledgements</a></p>
<h2><a name="Print_publications">Print publications</a> about Boost or Boost
Libraries</h2>
<table summary="List of print publications about Boost or its libraries"
style="BORDER-COLLAPSE: collapse" cellPadding="5" width="100%"
border="0">
<tr>
<td vAlign="top" align="left" width="16%"><b>[<a name="MaddockCleary00">MaddockCleary00</a>]</b></td>
<td vAlign="top" align="left" width="84%">John Maddock and Steve Cleary, <i>C++ Type
Traits</i>. Dr. Dobb's Journal, Vol. 25, Issue 10, October, 2000, page 38. <a href="http://www.boost.org/libs/type_traits/cxx_type_traits.htm">
www.boost.org/libs/type_traits/c++_type_traits.htm</a></td>
</tr>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr>
<td vAlign="top" align="left" width="16%"><b>[<a name="Maddock01">Maddock01</a>]</b></td>
<td vAlign="top" align="left" width="84%">John Maddock, <i>Regular Expressions in C++</i>.
Dr. Dobb's Journal, Vol. 26, Issue 10, October, 2001, page 21.</td>
</tr>
<tr>
<td vAlign="top" align="left" width="16%"><b>[<a name="SiekLumsdaine01">SiekLumsdaine01</a>]</b></td>
<td vAlign="top" align="left" width="84%">Jeremy Siek and Andrew Lumsdaine, <i>C++
Concept Checking</i>. Dr. Dobb's Journal, Vol. 26, Issue 6, June, 2001,
page 64.</td>
</tr>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Karlsson02">Karlsson02</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Björn Karlsson, <i>Smart Pointers in Boost</i>.
C/C++ Users Journal, April, 2002. <A href="http://www.cuj.com/documents/s=8014/cuj0204karlsson/">
www.cuj.com/documents/s=8014/cuj0204karlsson/</A>
</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Karlsson02a">Karlsson02a</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Björn Karlsson, <i>C/C++ Tip #9: Lexical
Conversions</i>. C/C++ Users Journal, November, 2002. <A href="http://www.cuj.com/documents/s=8470/cuj0211karlsson/">
www.cuj.com/documents/s=8470/cuj0211karlsson/</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Kempf02">Kempf02</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Bill Kempf, <i>The Boost.Threads Library</i>.
C/C++ Users Journal, May, 2002. <A href="http://www.cuj.com/documents/s=8013/cuj0205kempf/">
www.cuj.com/documents/s=8013/cuj0205kempf/</A></TD>
</TR>
<tr>
<td vAlign="top" align="left" width="16%"><b>[<a name="SiekLeeLumsdaine02">SiekLeeLumsdaine02</a>]</b></td>
<td vAlign="top" align="left" width="84%">
Jeremy Siek, Lie-Quan Lee and Andrew Lumsdaine, <i>The Boost Graph Library</i>.
Addison-Wesley, 2002. ISBN: 0-201-72914-8. <a href="http://www.awprofessional.com/titles/0-201-72914-8">
www.awprofessional.com/titles/0-201-72914-8/</a>
<br>A sample chapter is available at: <A href="http://tinyurl.com/24666">tinyurl.com/24666</A>
</td>
</tr>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="AbrahamsGrosse-Kunstleve03">AbrahamsGrosse-Kunstleve03</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">David Abrahams and Ralf W.
Grosse-Kunstleve, <i>Building Hybrid Systems with Boost.Python</i>. C/C++ Users
Journal, July, 2003. <A href="http://www.cuj.com/documents/s=8470/cuj0307abrahams/">
www.cuj.com/documents/s=8470/cuj0307abrahams/</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="GuzmanNuffer03">GuzmanNuffer03</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Joel de Guzman and Dan Nuffer, <i>The Spirit
Library: Inline Parsing in C++</i>. C/C++ Users Journal, September, 2003,
Vol. 21, Issue 9, page 22.</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Karlsson03">Karlsson03</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Björn Karlsson, <i>Lambda Expressions &amp;
C++</i>. C/C++ Users Journal, December, 2003, Vol. 21, Issue 12, page 20.</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Sutter03">Sutter03</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Herb Sutter, <i>Generalized Function Pointers</i>.
C/C++ Users Journal, August, 2003. <A href="http://www.cuj.com/documents/s=8464/cujcexp0308sutter/">
www.cuj.com/documents/s=8464/cujcexp0308sutter/</A>
</TD>
</TR>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="AbrahamsGurtovoy04">AbrahamsGurtovoy04</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">
David Abrahams and Aleksey Gurtovoy, <i>C++ Template Metaprogramming: Concepts,
Tools, and Techniques from Boost and Beyond</i>. Addison-Wesley, November,
2004. ISBN: 0-321-22725-5. <A href="http://www.awprofessional.com/titles/0321227255/">
www.awprofessional.com/titles/0321227255/</A>
<br>
Additional information and two sample chapters are available at: <A href="http://boost-consulting.com/tmpbook/">
boost-consulting.com/tmpbook/</A>
</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Inaba04">Inaba04</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">
Kazuhiro Inaba, <i>Boost C++ Library Programming</i>. Shuwa System, May, 2004. ISBN: 4-7980-0786-2. <A href="http://www.shuwasystem.co.jp/books/7980/0786-2/0786-2.html">
www.shuwasystem.co.jp/books/7980/0786-2/0786-2.html</A>
<br>
Additional information and a sample chapter are available at: <A href="http://www.kmonos.net/pub/BoostBook/">
www.kmonos.net/pub/BoostBook/</A>
</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Lopez04">L&oacute;pez04</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Joaqu&iacute;n M L&oacute;pez Mu&ntilde;oz,
<i>The Boost Multi-Index Containers Library</i>. C/C++ Users Journal,
September, 2004, Vol. 22, Issue 9, page 6.</TD>
</TR>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Karlsson05">Karlsson05</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">
Björn Karlsson, <i>Beyond the C++ Standard Library: An Introduction to Boost</i>. Addison-Wesley, August 31, 2005. ISBN: 0-3211-3354-4. <A href="http://www.awprofessional.com/titles/0321133544/">
www.awprofessional.com/titles/0321133544/</A>
<br>
A sample chapter is available at: <A href="http://www.awprofessional.com/content/images/0321133544/samplechapter/karlsson_ch09.pdf">
www.awprofessional.com/content/images/0321133544/samplechapter/karlsson_ch09.pdf</A>
</TD>
</TR>
</table>
<h2><a name="Online_publications">Online publications</a> about Boost or Boost
Libraries</h2>
<table summary = "Online publications"
style="BORDER-COLLAPSE: collapse" cellPadding="5" width="100%"
border="0">
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Brownell02">Brownell02</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">David Brownell, <i>C++ Techniques for
Tomorrow That Can be Implemented Today (a.k.a. Boosting your Code)</i>.
NWCPP, November 13, 2002. <A href="http://www.nwcpp.org/Meetings/2002/11.html">www.nwcpp.org/Meetings/2002/11.html</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Long02">Long02</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Matt Long, <i>Adding Regular Expressions to Your App with Regex++</i>.
The Code Project, June 18, 2002. <A href="http://www.codeproject.com/string/regex__.asp">www.codeproject.com/string/regex__.asp</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Siek02">Siek02</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Jeremy G. Siek, <i>The Boost Graph Library</i>.
InformIT, March 1, 2002. <A href="http://tinyurl.com/2hc27">tinyurl.com/2hc27</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Siek02a">Siek02a</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Jeremy G. Siek, <i>A Boost Graph Library
Tutorial</i>. InformIT, March 1, 2002. <A href="http://tinyurl.com/2sa4s">tinyurl.com/2sa4s</A></TD>
</TR>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%" height="32"><b>[<a name="Abrahams03">Abrahams03</a>]</b></TD>
<TD vAlign="top" align="left" width="84%" height="30">David Abrahams, <i>The Boost
Metaprogramming Library</i>. ACCU, 2003. <A href="http://www.boost-consulting.com/writing/ACCU_MPL_slides.ppt">
www.boost-consulting.com/writing/ACCU_MPL_slides.ppt</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Dawes03">Dawes03</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Beman Dawes, <i>Multiplatform Software
Development</i>. 2003. <A href="http://www.esva.net/~beman/multiplat_dev.ppt">www.esva.net/~beman/multiplat_dev.ppt</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left"><b>[<a name="Halleux03">Halleux03</a>]</b></TD>
<TD vAlign="top" align="left">Jonathan de Halleux, <i>Opening a door
towards Spirit: a parser framework</i>. The Code Project, March 24, 2003. <A href="http://www.codeproject.com/cpp/spiritintro.asp"> www.codeproject.com/cpp/spiritintro.asp</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left"><b>[<a name="Kaiser03">Kaiser03</a>]</b></TD>
<TD vAlign="top" align="left">Hartmut Kaiser, <i>Wave: a Standard conformant C++ preprocessor library</i>. The Code Project, March 25, 2003. <A href="http://www.codeproject.com/cpp/wave_preprocessor.asp"> www.codeproject.com/cpp/wave_preprocessor.asp</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Trentini03">Trentini03</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Matthew S. Trentini, <i>Introduction to Boost</i>.</TD>
</TR>
<tr>
<td vAlign="top" align="left" width="16%"><b>[<a name="Walker03">Walker03</a>]</b> </td>
<td vAlign="top" align="left" width="84%">Andrew Walker, <i>An Introduction to Boost</i>.
The Code Project, July 7, 2003. <a href="http://www.codeproject.com/vcpp/stl/BoostIntro.asp">
www.codeproject.com/vcpp/stl/BoostIntro.asp</a>
<br>A short and straightforward introduction to Boost. </td>
</tr>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Dawes04">Dawes04</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Beman Dawes, <i>Boost for Visual C++
Developers</i>. MSDN, May 17, 2004. <A href="http://tinyurl.com/2lzyh">tinyurl.com/2lzyh</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="DAgostino04">D'Agostino04</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Jim D'Agostino, <i>Designing Robust Objects with Boost</i>.
The Code Project, August 17, 2004. <A href="http://www.codeproject.com/cpp/Designing_Robust_Objects.asp">
www.codeproject.com/cpp/Designing_Robust_Objects.asp</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Handley04">Handley04</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Dave Handley, <i>An Introduction to the Boost Spirit Parser framework</i>.
The Code Project, October 9, 2004. <A href="http://www.codeproject.com/vcpp/stl/introduction_spirit.asp">
www.codeproject.com/vcpp/stl/introduction_spirit.asp</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Handley04a">Handley04a</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Dave Handley, <i>Implementing Semantic Actions in the Boost Spirit Parser Framework</i>.
The Code Project, October 10, 2004. <A href="http://www.codeproject.com/vcpp/stl/spirit_semantic_actions.asp">
www.codeproject.com/vcpp/stl/spirit_semantic_actions.asp</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Hauptmann04">Hauptmann04</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Peter Hauptmann, <i>Smart Pointers to boost your
code</i>. The Code Project, September 27, 2004. <A href="http://www.codeproject.com/vcpp/stl/boostsmartptr.asp">
www.codeproject.com/vcpp/stl/boostsmartptr.asp</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Hauptmann04a">Hauptmann04a</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Peter Hauptmann, <i>boost 2: shared_ptr wraps
resource handles</i>. The Code Project, October 4, 2004. <A href="http://www.codeproject.com/vcpp/stl/boostsp_handleref.asp">
www.codeproject.com/vcpp/stl/boostsp_handleref.asp</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Wikipedia04">Wikipedia04</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Wikipedia, <i>Boost</i>.
Wikipedia, The Free Encyclopedia, 2004. <A href="http://en.wikipedia.org/wiki/Boost%20library">
en.wikipedia.org/wiki/Boost_(programming)</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Witt04">Witt04</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Thomas Witt, <i>The Boost Iterator Library</i>.
ACCU Spring Conference, 2004. <A href="http://www.accu.org/conference/presentations/Witt_-_Boost_Iterator_Library.pdf">
www.accu.org/conference/presentations/Witt_-_Boost_Iterator_Library.pdf</A></TD>
</TR>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Karlsson05a">Karlsson05a</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Bjorn Karlsson, <i>How the Boost Bind Library Can Improve Your C++ Programs</i>. InformIT, August 26, 2005. <A href="http://www.informit.com/articles/article.asp?p=412354">
http://www.informit.com/articles/article.asp?p=412354</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Cogswell05">Cogswell05</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Jeff Cogswell, <i>Adding an Easy File Save and File Load Mechanism
to Your C++ Program</i>. InformIT, July 1, 2005. <A href="http://www.informit.com/articles/article.asp?p=398702">
http://www.informit.com/articles/article.asp?p=398702</A>
<br>Explains Boost.Serialization.</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Gurtovoy05">Gurtovoy05</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Aleksey Gurtovoy and David Abrahams <i>An In-Depth Look at Metafunctions in C++</i>. InformIT, April 1, 2005. <A href="http://www.informit.com/articles/article.asp?p=375705">
http://www.informit.com/articles/article.asp?p=375705</A></TD>
</TR>
</table>
<h2><a name="Print_mentions">Print mentions</a> of Boost or Boost Libraries</h2>
<table summary="Print mentions"
style="BORDER-COLLAPSE: collapse" cellPadding="5" width="100%"
border="0">
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="HyslopSutter01">HyslopSutter01</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Jim Hyslop and Herb Sutter, <i>Conversations:
I'd Hold Anything for You</i>. C/C++ Users Journal, December, 2001. <A href="http://www.cuj.com/documents/s=7988/cujcexp1912hyslop/">
www.cuj.com/documents/s=7988/cujcexp1912hyslop/</A>
<br><CODE>boost::any</CODE>
</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Meyers01">Meyers01</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Scott Meyers, <i>Item 50: Familiarize yourself with
STL-related web sites</i>. Effective STL, Addison-Wesley, 2001, page 221. ISBN: 0-201-74962-9
</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Sutter01">Sutter01</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Herb Sutter, <i>The String Formatters of
Manor Farm</i>. C/C++ Users Journal, Vol. 19, November, 2001. <A href="http://www.gotw.ca/publications/mill19.htm">
www.gotw.ca/publications/mill19.htm</A>
<br><CODE>boost::lexical_cast</CODE>
</TD>
</TR>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Ablavsky02">Ablavsky02</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Vitaly Ablavsky, <i>Applying BGL to
Computational Geometry</i>. C/C++ Users Journal, August, 2002. <A href="http://www.cuj.com/documents/s=8470/cuj0208ablavsky/">
www.cuj.com/documents/s=8470/cuj0208ablavsky/</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Alexandrescu02">Alexandrescu02</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Andrei Alexandrescu, <i>Generic&lt;Programming&gt;:
Efficient Generic Sorting and Searching in C++ (I): In Search of a Better
Search</i>. C/C++ Users Journal, October, 2002. <A href="http://www.cuj.com/documents/s=7978/cujcexp2010alexandr/">
www.cuj.com/documents/s=7978/cujcexp2010alexandr/</A>
<br><CODE>boost::type_traits</CODE>
</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="HyslopSutter02">HyslopSutter02</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Jim Hyslop and Herb Sutter, <i>Conversations:
Getting to the Point</i>. C/C++ Users Journal, July, 2002. <A href="http://www.cuj.com/documents/s=7981/cujcexp2007hyslop/">
www.cuj.com/documents/s=7981/cujcexp2007hyslop/</A>
<br>smart pointer discussion. <CODE>boost::scoped_ptr, shared_ptr, scoped_array,
shared_array.</CODE>
</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Sutter02">Sutter02</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Herb Sutter, <i>The New C++: The Group of
Seven - Extensions under Consideration for the C++ Standard Library</i>.
C/C++ Users Journal, April, 2002. <A href="http://www.cuj.com/documents/s=7984/cujcexp2004sutter/">
www.cuj.com/documents/s=7984/cujcexp2004sutter/</A>
</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Sutter02a">Sutter02a</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Herb Sutter, <i>The New C++: Smart(er)
Pointers</i>. C/C++ Users Journal, August, 2002. <A href="http://www.cuj.com/documents/s=7980/cujcexp2008sutter/">
www.cuj.com/documents/s=7980/cujcexp2008sutter/</A></TD>
</TR>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Besser03">Besser03</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Mitch Besser, <i>Generic Printable ENUM++</i>.
C/C++ Users Journal, June, 2003. <A href="http://www.cuj.com/documents/s=8470/cujboost0306besser/">
www.cuj.com/documents/s=8470/cujboost0306besser/</A>
<br>Mentions <CODE>BOOST_PP</CODE>
</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Nasonov03">Nasonov03</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Alexander Nasonov, <i>I/O System: dynamic_any
Campaign</i>. C/C++ Users Journal, September, 2003. <A href="http://www.cuj.com/documents/s=8470/cujweb0309nasonov/">
www.cuj.com/documents/s=8470/cujweb0309nasonov/</A>
<br>Improved <CODE>boost::any</CODE>
</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Sutter03a">Sutter03a</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Herb Sutter, <i>Generalizing Observer</i>.
C/C++ Users Journal, September, 2003. <A href="http://www.cuj.com/documents/s=8840/cujexp0309sutter/">
www.cuj.com/documents/s=8840/cujexp0309sutter/</A>
</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Tan03">Tan03</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Kwee H. Tan, <i>Exploring EDA Algorithms with
the Boost Graph Library</i>. C/C++ Users Journal, July, 2003. <A href="http://www.cuj.com/documents/s=8470/cuj0307tan/">
www.cuj.com/documents/s=8470/cuj0307tan/</A>
</TD>
</TR>
<tr>
<td vAlign="top" align="left" width="16%"><b>[<a name="VandervoordeJosuttis03">VandervoordeJosuttis03</a>]</b>
</td>
<td vAlign="top" align="left" width="84%">David Vandevoorde and Nicolai M.
Josuttis, <i>Using Templates in Practice</i>. C/C++ Users Journal, February,
2003. <A href="http://www.cuj.com/documents/s=8208/cujweb0302vandevoorde/web0302b.htm">
www.cuj.com/documents/s=8208/cujweb0302vandevoorde/web0302b.htm</A>
<br>Concept Check Library
</td>
</tr>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Meyers05">Meyers05</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Scott Meyers, <i>Item 55: Familiarize yourself
with Boost</i>. Effective C++, 3rd Edition, Addison-Wesley, May 12, 2005. ISBN: 0-321-33487-6
</TD>
</TR>
</table>
<h2><a name="Online_mentions">Online mentions</a> of Boost or Boost Libraries</h2>
<table summary="Online mentions"
style="BORDER-COLLAPSE: collapse" cellPadding="5" width="100%"
border="0">
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Siek01">Siek01</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Jeremy G. Siek, <i>An Implementation of Graph Isomorphism Testing</i>,
December 9, 2001. <A href="http://www.boost.org/libs/graph/doc/isomorphism-impl.pdf">
www.boost.org/libs/graph/doc/isomorphism-impl.pdf</A></TD>
</TR>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Burnap02">Burnap02</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Steven R. Burnap, <i>Boost::any</i>,
Kuro5hin, May 1, 2002. <A href="http://www.kuro5hin.org/story/2002/5/1/142321/9513">
www.kuro5hin.org/story/2002/5/1/142321/9513</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Carbon02">Carbon02</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">David S?, <i>Boost : The handy library of
handy libraries</i>. Kuro5hin, July 18, 2002. <A href="http://www.kuro5hin.org/story/2002/7/18/3313/01429">
www.kuro5hin.org/story/2002/7/18/3313/01429</A>
</TD>
</TR>
<tr>
<td vAlign="top" align="left" width="16%"><b>[<a name="Curran02">Curran02</a>]</b></td>
<td vAlign="top" align="left" width="84%">James Curran, <i>Access Raw Data with
Performance Counters in Visual C++</i>. DevX.com, October, 2002. <a href="http://www.devx.com/cplus/article/7951">
www.devx.com/cplus/article/7951</a>
<br>Devotes several paragraphs to <code>boost::shared_ptr&lt;&gt;</code>.
</td>
</tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Siek02b">Siek02b</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Jeremy G. Siek, <i>Internet Packet Routing
with the Boost Graph Library</i>. InformIT, March 1, 2002. <A href="http://tinyurl.com/26dwj">
tinyurl.com/26dwj</A></TD>
</TR>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Casad03">Casad03</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Joe Casad, <i>Introducing the Boost Corner</i>.
C/C++ Users Journal, August, 2003. <A href="http://www.cuj.com/documents/s=8470/cuj0308boostcorner/">
www.cuj.com/documents/s=8470/cuj0308boostcorner/</A>
</TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Lischner03">Lischner03</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">
Ray Lischner, <i>C++: Beyond the Standard Library</i>. O'Reilly Network, May 6,
2003. <A href="http://www.oreillynet.com/lpt/a/3683">www.oreillynet.com/lpt/a/3683</A>
<br>Mentions <CODE>tuples, shared_ptr, lambda, spirit</CODE>.
</TD>
</TR>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Inaba04a">Inaba04a</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Kazuhiro Inaba, <i>Let's Boost</i>. 2004. <A href="http://www.kmonos.net/alang/boost/">
www.kmonos.net/alang/boost/</A></TD>
</TR>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Stein04">Stein04</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">
<P>Sebastian Stein, <i>How to use Boost Test for automated testing</i>. 2004. <A href="http://www.hpfsc.de/boosttest/">
www.hpfsc.de/boosttest/</A></P>
</TD>
</TR>
<!-- year separator -->
<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
<TR>
<TD vAlign="top" align="left" width="16%"><b>[<a name="Lindrud05">Lindrud05</a>]</b></TD>
<TD vAlign="top" align="left" width="84%">Jarl Lindrud, <i>RMI for C++</i>.
The Code Project, April 11, 2005. <A href="http://www.codeproject.com/threads/RMI_For_Cpp.asp">www.codeproject.com/threads/RMI_For_Cpp.asp</A>
<br>Uses Boost.Serialization.</TD>
</TR>
</table>
<h2>How to <a name="update">update</a> this page</h2>
<p>Please help us keep this page updated - users can post new citations to the
mailing list, while Boost developers should update the page directly in CVS.</p>
<ul>
<li>
If a publication is available both in print and online, cite it in the
appropriate <i>print</i>
section, with a hyperlink to the online version.
<li>
Bookmark the contents of [...] in the first column to make it easy to link to
the entry.
<li>
Identify the first entry an author has in a given year with just the two-digit
year. Subsequent entries for the same author and year should have <b>a-z</b>
appended.
<li>
Inside each section, entries are grouped by year and, within a year, alphabetically
sorted by author name.
<li>
In the text, spell out absolute URL's so that printed versions of this page
include the full URL.
</li>
</ul>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
<p>Fredrik Blomqvist provided many of the initial citations.</p>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
17 September, 2005<!--webbot bot="Timestamp" endspan i-checksum="40409" --></p>
<p>&copy; Copyright Beman Dawes 2003</p>
<p> Distributed under the Boost Software License, Version 1.0.
(See accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

104
blanket-permission.txt
View File

@ -1,104 +0,0 @@
The following people hereby grant permission to replace all existing
licenses on their contributions to Boost with the Boost Software
License, Version 1.0. (boostinspect:nolicense boostinspect:nocopyright)
Aleksey Gurtovoy (agurtovoy@meta-comm.com)
Andrei Alexandrescu (andrewalex - at - hotmail.com) (See Boost list message of August 12, 2004 11:06:58 AM EST)
Andrew Lumsdaine ()
Anthony Williams (anthony -at- justsoftwaresolutions.co.uk(
Beman Dawes (bdawes@acm.org)
Brad King (brad.king -at- kitware.com) (See Boost list message of Wed, 21 Jul 2004 11:15:46 -0400)
Brian Osman (osman -at- vvisions.com) (See CVS log)
Bruce Barr (schmoost -at- yahoo.com) (See Boost list of Mon, 16 Aug 2004 15:06:43 -0500)
Bruno da Silva de Oliveira (bruno - at - esss.com.br)
Christain Engstrom (christian.engstrom -at- glindra.org) (See Boost list message of Mon, 30 Aug 2004 14:31:49 +0200)
Cromwell D Enage (sponage -at- yahoo.com) (See Boost list message of August 12, 2004 11:49:13 AM EST)
Dan Gohman (djg -at- cray.com) (See Boost list messsage of Sat, 21 Aug 2004 10:54:59 +0100)
Dan Nuffer (dan -at- nuffer.name)
Daniel Frey (d.frey -at- gmx.de, daniel.frey -at- aixigo.de)
Daniel Nuffer (dan -at- nuffer.name)
Darin Adler (darin -at- bentspoon.com) (Email to Andreas Huber, see change log)
Daryle Walker (darylew - at - hotmail.com)
Dave Abrahams (dave@boost-consulting.com)
Dave Moore (dmoore -at- viefinancial.com) (See Boost list message of 18 Dec 2003 15:35:50 -0500)
David Abrahams (dave@boost-consulting.com)
Dietmar Kuehl (dietmar_kuehl -at- yahoo.com) (Email to Andreas Huber, see change log)
Douglas Gregor (gregod -at- cs.rpi.edu, dgregor -at- cs.indiana.edu, doug.gregor -at- gmail.com)
Dr John Maddock (john - at - johnmaddock.co.uk)
Edward D. Brey (brey -at- ductape.net) (Email to Andreas Huber, see change log)
Eric Ford (un5o6n902 -at- sneakemail.com) (See Boost list message of Sun, 15 Aug 2004 10:29:13 +0100)
Eric Friedman (ebf@users.sourceforge.net)
Eric Niebler (eric@boost-consulting.com)
Fernando Cacciola (fernando_cacciola@ciudad.com.ar)
Fernando Luis Cacciola Carballal (fernando_cacciola@ciudad.com.ar)
Francois Faure (Francois.Faure -at- imag.fr) (See CVS log)
Gary Powell (powellg - at - amazon.com) (See Boost list message of 10 Feb 2004 14:22:46 -0800)
Gennadiy Rozental (rogeeff -at- mail.com) (Email to Andreas Huber, see change log)
Gottfried Ganssauge (Gottfried.Ganssauge -at- HAUFE.DE) (See Boost List message of Mon, 16 Aug 2004 10:09:19 +0200)
Gottfried Ganßauge (Gottfried.Ganssauge -at- HAUFE.DE) (Alternative spelling of Gottfried Ganssauge)
Greg Colvin (gregory.colvin -at- oracle.com) (See Boost list message of Sat, 14 Aug 2004 10:57:00 +0100)
Gregory Colvin (gregory.colvin -at- oracle.com) (See Boost list message of Sat, 14 Aug 2004 10:57:00 +0100)
Gunter Winkler (gunter.winkler -at- unibw-muenchen.de) (See Boost List message of Mon, 16 Aug 2004 10:24:17 +0200)
Hartmut Kaiser (hartmut.kaiser -at- gmail.com)
Herve Bronnimann (hbr -at- poly.edu)
Hervé Brönnimann (hbr -at- poly.edu)
Housemarque Oy (Ilari Kuittinen ilari.kuittinen -at- housemarque.fi)
Howard Hinnant (hinnant -at- twcny.rr.com) (See Boost list message of July 25, 2004 3:44:49 PM EST)
Hubert Holin (hubert_holin -at- users.sourceforge.net)
Indiana University ()
Itay Maman (imaman -at- users.sourceforge.net)
Jaakko Järvi (jajarvi -at- osl.iu.edu)
Jaap Suter (j.suter -at- student.utwente.nl) (See Boost list message of Thu, 16 Sep 2004 09:32:43 -0700)
Jeff Garland (jeff - at - crystalclearsoftware.com) (see Boost list post of July 25, 2004 19:31:09 -0700)
Jens Maurer (Jens.Maurer@gmx.net)
Jeremy G Siek (jsiek@osl.iu.edu)
Jeremy Siek (jsiek@osl.iu.edu)
Joel de Guzman (joel -at- boost-consulting.com) (See Boost list message of July 25, 2004 8:32:00 PM EST)
John Bandela (jbandela-at-ufl.edu)
John Maddock (john - at - johnmaddock.co.uk)
John R Bandela (jbandela-at-ufl.edu)
Jonathan Turkanis (turkanis -at- coderage dot com)
Juergen Hunold (hunold -at- ive.uni-hannover.de) (See Boost List Message of Fri, 13 Aug 2004 19:39:55 +0200)
Kevlin Henney (kevlin -at- curbralan.com) (See Boost list message of Wed, 15 Sep 2004 18:15:17 +0200)
Kresimir Fresl (fresl -at- master.grad.hr) (See Boost List message of August 16, 2004 8:23:35 AM EST)
Lars Gullik Bjønnes (larsbj -at- lyx.org) (See Boost list message of Tue, 17 Aug 2004 15:49:02 +0100)
Lie-Quan Lee (liequan - at - slac.stanford.edu, llee - at - cs.indiana.edu)
Maarten Keijzer (mkeijzer -at- cs.vu.nl) (See Boost list message of Wed, 18 Aug 2004 21:43:18 +0100)
Mac Murrett (mmurrett -at- mac.com)
Marc Wintermantel (wintermantel -at- imes.mavt.ethz.ch, wintermantel -at- even-ag.ch) (See CVS log)
Michael Glassford (glassfordm - at - hotmail.com)
Michael Stevens (Michael.Stevens - at - epost.de)
Multi Media Ltd. (pdimov@mmltd.net)
Nicolai M Josuttis (solutions -at- josuttis.com) (See Boost list message of Mon, 30 Aug 2004 10:52:00 +0100)
Nikolay Mladenov (nickm -at- sitius.com) (See Boost list message of Tue, 17 Aug 2004 15:45:33 +0100)
Paul Mensonides (pmenso57 -at- comcast.net) (See Boost list message of July 21, 2004 1:12:21 AM EST)
Pavol Droba (droba -at- topmail.sk)
Peter Dimov (pdimov@mmltd.net)
R W Grosse-Kunstleve (RWGrosse-Kunstleve@lbl.gov)
Ralf W. Grosse-Kunstleve (RWGrosse-Kunstleve@lbl.gov)
Rational Discovery LLC (Greg Landrum Landrum -at- RationalDiscovery.com) (See Boost list post of Tue, 17 Aug 2004 10:35:36 +0100)
Rene Rivera (grafik/redshift-software.com, rrivera/acm.org)
Robert Ramey (ramey@www.rrsd.com)
Roland Richter (roland -at- flll.jku.at) (See Boost list post of Mon, 16 Aug 2004 22:16:55 +0200)
Roland Schwarz (roland.schwarz -at- chello.at)
Ronald Garcia (garcia -at- cs.indiana.edu) (Email to Andreas Huber, see change log)
Samuel Krempp (krempp -at- crans.ens-cachan.fr) (See Boost list message of Mon, 27 Sep 2004 13:18:36 +0200)
Stefan Seefeld (seefeld -at- sympatico.ca)
Stephen Cleary (scleary -at- jerviswebb.com) (See Boost list message of Tue, 28 Sep 2004 13:11:46 +0100)
Steve Cleary (Variant of Stephen Cleary)
Sylvain Pion (Sylvain.Pion - at - sophia.inria.fr)
The Trustees of Indiana University ()
Thomas Witt (witt - at - ive.uni-hannover.de, witt - at - acm.org, witt - at - styleadvisor.com)
Thorsten Jørgen Ottosen (nesotto - at - cs.auc.dk)
Thorsten Ottosen (nesotto - at - cs.auc.dk)
Toon Knapen (toon dot knapen - at - fft.be)
Trustees of Indiana University ()
University of Notre Dame ()
Vladimir Prus (ghost@cs.msu.su)
William E. Kempf () (email to Beman Dawes, 9/14/2006 4:18 PM)
Joerg Walter (jhr.walter - at - t-online.de : email to ublas mailing list Mon, 17 Sep 2007 10:17:08 +0200)
Mathias Koch (mkoch - at - idesis.de 7 : email to boost-owner@lists.boost.org Sep 2007 13:20:09 +0200)
--- end ---

BIN
boost-dark-trans.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.2 KiB

BIN
boost_1_33_0.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 10 KiB

820
boost_soc_06_overview.html
View File

@ -1,820 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0.1 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>An overview of Boost participation in
Google Summer of Code&trade; 2006</title>
<link rel="stylesheet" href="../boost.css" type="text/css">
<style type="text/css">
<!--
table{
PADDING-RIGHT: 2pt;
BORDER-TOP: gray 1pt solid;
DISPLAY: block;
PADDING-LEFT: 2pt;
PADDING-BOTTOM: 2pt;
BORDER-LEFT: gray 1pt solid;
MARGIN-RIGHT: 32pt;
PADDING-TOP: 2pt;
background-color: #EEEEEE;
}
td{
BORDER-STYLE: solid;
BORDER-WIDTH: 1pt;
BORDER-LEFT: ;
BORDER-RIGHT: gray 1pt solid;
BORDER-TOP: ;
BORDER-BOTTOM: gray 1pt solid;
}
th{color: #ffffff; background-color: #000000;}
.odd_tr{background-color: #ffffff;}
-->
</style>
</head>
<body>
<img src="../boost.png" alt="boost.png (6308 bytes)" align="middle" width="277" height="86">
<h1>An overview of Boost participation in
Google Summer of Code&trade; 2006</h1>
<hr>
<p>
For the second consecutive year, Google has conducted its
<a href="http://code.google.com/soc/">Summer of Code&trade;</a> initiative,
a program by which student developers are sponsored for their contributions
within open source organizations willing to mentor the participants. The 2006
campaign has run between April and September, with active development work
taking place between May 23 and August 21.
</p>
<p>
Around mid April, when the program had just started, some Boost members began
considering the possibility to enter Summer of Code as a mentoring
organization. Despite the lack of time and the fact that most of us were
completely new to this initiative, Boost managed to successfully apply for
the program. As a result ten projects were selected and mentored, most of
which are expected to become full contributions to Boost in the near future.
</p>
<p>
We give here a summary report of this experience, along with a short analysis
of the main problems we found, so that we can work at solving them and do
better next year.
</p>
<h2>Contents</h2>
<ul>
<li><a href="#how_the_program_works">How the program works</a>
<ul>
<li><a href="#2006_figures">2006 figures</a></li>
</ul>
</li>
<li><a href="#boost_participation">Boost participation</a>
<ul>
<li><a href="#application_and_process_selection">Application and
process selection</a></li>
<li><a href="#accepted_projects">Accepted projects</a></li>
<li><a href="#development">Development</a></li>
<li><a href="#results">Results</a></li>
</ul>
</li>
<li><a href="#analysis">Analysis</a>
<ul>
<li><a href="#boost_appeal">Boost appeal</a></li>
<li><a href="#opportunities_lost">Opportunities lost?</a></li>
<li><a href="#projects_startup">Projects startup</a></li>
<li><a href="#ongoing_development">Ongoing development</a></li>
<li><a href="#public_communication_issues">Public communication
issues</a></li>
<li><a href="#scope_of_projects">Scope of projects</a></li>
</ul>
</li>
<li><a href="#suggestions_for_improvement">Suggestions for improvement</a>
<ul>
<li><a href="#preparation">Preparation</a></li>
<li><a href="#public_communication">Public communication</a></li>
<li><a href="#project_management">Project management</a></li>
</ul>
</li>
<li><a href="#conclusions">Conclusions</a></li>
<li><a href="#acknowledgements">Acknowledgements</a></li>
</ul>
<h2><a name="how_the_program_works">How the program works</a></h2>
<p>
There are three types of participants in Google Summer of Code:
<ul>
<li>Google itself acts as the funding partner and conducts the overall
program.</li>
<li>The open source organizations accepted into the program must designate
people inside the organization who will act as project mentors.</li>
<li>Students submit their project ideas and, if selected, work in
collaboration with one of the mentoring organizations; upon successful
completion of the project, students receive the full stipend for the
program.</li>
</ul>
The program goes through the following stages:
<ul>
<li>Organization selection: those open source organizations willing to
enter Summer of Code submit an expression of interest to Google, along
with information Google uses for qualifying purposes. Selected organizations
are publicly announced and each organization is expected to provide a pool
of project ideas.</li>
<li>Student selection: students willing to participate submit one or more
project proposals, typically expanding on some of the ideas previously
provided by the mentoring organizations. A student can apply several times
and for different organizations, but ultimately can only be chosen for just
one project. These proposals are routed by Google to the appropriate
organizations, which must analyze them, rank them, and assign mentors to the
most promising applications. Based on the information provided by mentoring
organizations, Google issues the final list of accepted projects.</li>
<li>Development: Students, guided by their assigned mentors, are expected to
complete the projects in a period of three months. Google asks mentors for a
mid-program review upon which continuation of the project depends.</li>
<li>Final review: Once the development period is over, mentors are requested
to inform Google on the results of the project, and determine whether students
qualify to receive the full stipend.</li>
</ul>
</p>
<h3><a name="2006_figures">2006 figures</a></h3>
<p>
The 2006 campaign of Google Summer of Code took place between April 14 and
September 25. A total of 102 mentoring organizations participated. Of the 6,338
applications submitted by 3,044 students around the globe, 630 were finally
selected and funded. Google has spent more than US$3 million in student stipends
and compensations to the mentoring organizations.
</p>
<h2><a name="#boost_participation">Boost participation</a></h2>
<h3><a name="#application_and_process_selection">Application and
process selection</a></h3>
<p>
On April 14, the same day Google Summer of Code started, Julio M. Merino Vidal
(later to become one of the selected students) sent a message encouraging Boost
members to participate in this program as a mentoring organization. This call
sparked the interest of the community; although time was already short for doing
all the preparation labors, Boost moderators put rapidly themselves to work and
conducted the preliminary registration steps. In the meantime, a Wiki page was
grown with project ideas provided by Boost members, totalling more than twenty
proposals.
</p>
<p>
By the beginning of May Boost was officially accepted into the program and Boost
moderators set out to form a group of mentors, selected on an invitation basis.
As student selection is a delicate process, involving the assessment of individuals
on their technical skills, all subsequent discussions were conducted by the
selected mentors on a private mail list established for their collaboration.
</p>
<p>
We were not prepared for the avalanche of student applications that followed. On
day two after the application period was open, we had received three proposals;
next day it was 14, and within a week the count exceeded 50. By the end of the
application period the total number of proposals received was 174, which forced
us to go through a very intensive ranking process and recruit additional mentors.
Two rules were followed so as rationalize the process of selection among dozens
of different proposals:
<ul>
<li>Where there were competing applications for the same project idea, only
one were to be ultimately selected; so, no two projects with the same or very
similar goals were accepted.</li>
<li>Some of the applications built on a given Boost library (for instance, the
Boost Graph Library is a frequent target for the addition of algorithms.) We
limited the applications to a maximum of two per Boost library.</li>
</ul>
These rules have the combined effect of greatly reducing the number of eligible
applications while at the same time distributing the accepted projects evenly
across the space of ideas. Moreover, students with unique proposals, i.e. project
ideas not coming from the pool originally presented by Boost, are at a
competitive advantage.
</p>
<p>
The different proposals were classified according to its related technological
area so that each cluster could be handled by an appointed mentor with the
required expertise on the subject. Mentors submitted then "focus reports"
summarizing the applications under their responsibility; these reports served as
a first filter to help reduce the number of final applications to be evaluated
jointly. Along the process, students with the most promising proposals were asked
to refine their ideas and provide further information.
</p>
<p>
Although not enforced by the official rules, we agreed upon a one-to-one ratio
of mentors to students, which ultimately marked a hard limit on the maximum number
of eligible projects.
</p>
<h3><a name="accepted_projects">Accepted projects</a></h3>
<p>
Google accepted and funded the ten top-ranked projects endorsed by Boost. Of
these, eight projects are libraries or library components targeted for future
inclusion into Boost, while the remaining two consist of utility programs
heavily relying on Boost.
</p>
<blockquote>
<b>C++ Coroutine Library</b>
<br>
Giovanni Piero Deretta, mentored by Eric Niebler.
<br>
Library for the management through a modern C++ interface of OS-provided
coroutine facilities.
</blockquote>
<blockquote>
<b>Concurrency Library</b>
<br>
Matthew Calabrese, mentored by David Abrahams.
<br>
STL-inspired generic framework for high-level specification and execution of
parallelizable algorithms.
</blockquote>
<blockquote>
<b>TR1 Math Special Functions</b>
<br>
Xiaogang Zhang, mentored by John Maddock.
<br>
Implementation of the 23 special mathematical functions specified in C++
standard library extension proposal TR1.
</blockquote>
<blockquote>
<b>The Boost.Process library</b>
<br>
Julio M. Merino Vidal, mentored by Jeff Garland.
<br>
Portable library for process launching and basic management.
</blockquote>
<blockquote>
<b>Out-of-Core Graphs and Graph Algorithms</b>
<br>
St&eacute;phane Zampelli, mentored by Jeremy Siek.
<br>
Extension of the Boost Graph Library to deal with out-of-core structures,
i.e. data sets too large to be kept in main memory at once.
</blockquote>
<blockquote>
<b>MISC (M)ulti (I)ndex (S)pecialized (C)ontainers</b>
<br>
Mat&iacute;as Capeletto, mentored by Joaqu&iacute;n M L&oacute;pez Mu&ntilde;oz.
<br>
Families of specialized containers internally based on Boost.MultiIndex.
</blockquote>
<blockquote>
<b>Generic Tree Container</b>
<br>
Bernhard Reiter, mentored by Ren&eacute; Rivera.
<br>
Design and implementation of a family of STL-compatible tree containers.
</blockquote>
<blockquote>
<b>Viewer utility for FSMs</b>
<br>
Ioana Tibuleac, mentored by Andreas Huber D&ouml;nni.
<br>
Utility program for the visualization of finite state machines (FSMs) specified
with Boost.Statechart.
</blockquote>
<blockquote>
<b>Modular C++ preprocessor, using Boost.Spirit</b>
<br>
Hermanpreet 'Lally' Singh, mentored by Joel de Guzman.
<br>
Implementation with Boost.Spirit and Boost.Wave of a front-end translator
from Modular C++ (as specified in a proposal to add modules to C++ by Daveed
Vandevoorde) to standard C++.
</blockquote>
<blockquote>
<b>Implementing a state of the art Mincut/Maxflow algorithm.</b>
<br>
Stephan Diederich, mentored by Douglas Gregor.
<br>
Implementation of a fast mincut/maxflow routine for the Boost Graph Library
based on a new algorithm devised by Vladimir Kolmogorov.
</blockquote>
<h3><a name="development">Development</a></h3>
<p>
Two main facilities were set up to assist students and mentors during the
development phase: a mailing list and a Trac/SVN project management system
with separate directories for each project. One of the students, Mat&iacute;as
Capeletto, out of personal initiative registered a Google Group aimed at giving
students with Boost a place for informal interaction and discussion of common
problems.
</p>
<p>
After the initial warm-up period, each student-mentor pair performed development
work mostly privately. The usage of the Boost mailing lists was scarce, and
only by the end of the program did some students publicly announced their results.
</p>
<h3><a name="results">Results</a></h3>
<p>
By the date the development period was officially closed, the status of the
different projects was as follows:
<ul>
<li>Seven projects were completed or nearly completed and the students are
expected to ask for a formal review within 2006 or early 2007. Four of these
projects necessitated a goal reorientation during development, basically
because the original plan was too ambitious for three months. Most of the
projects are still in active development during the months following the
Summer of Code program.</li>
<li>Two projects did not reach the planned goals, but nevertheless produced
useful material that could be expanded outside of the Summer of Code
program.</li>
<li>One project was abandoned shortly after the midterm review. The reasons
for the abandonment are unknown.</li>
</ul>
The results of all the projects can be consulted online at the dedicated
<a href="https://www.boost-consulting.com:8443/trac/soc/browser/boost/soc/2006">Trac
site</a>.
</p>
<h2><a name="analysis">Analysis</a></h2>
<p>
We examine the various stages of Boost participation in Summer of Code, with an
emphasis on discovering opportunities for improvement.
</p>
<h3><a name="boost_appeal">Boost appeal</a></h3>
<p>
In a mid project
<a href="http://code.google.com/soc/GSoC2006Statistics.pdf">presentation at OSCON
2006</a>, Chris DiBona from Google provided some data about the organizations
which received the most applications:
</p>
<p align="center">
<table cellspacing="0">
<tr>
<th align="left">Organization</th>
<th>No of applications</th>
</tr>
<tr>
<td>KDE</td>
<td align="center">244</td>
</tr>
<tr class="odd_tr">
<td>Ubuntu &amp; Bazaar</td>
<td align="center">236</td>
</tr>
<tr>
<td>Python Software Foundation</td>
<td align="center">212</td>
</tr>
<tr class="odd_tr">
<td>GNOME</td>
<td align="center">199</td>
</tr>
<tr>
<td>Apache Software Foundation</td>
<td align="center">190</td>
</tr>
<tr class="odd_tr">
<td><b>Boost</b></td>
<td align="center"><b>174</b></td>
</tr>
<tr>
<td>Gaim</td>
<td align="center">152</td>
</tr>
<tr class="odd_tr">
<td>The GNU Project</td>
<td align="center">148</td>
</tr>
<tr>
<td>Drupal</td>
<td align="center">146</td>
</tr>
</table>
</p>
<blockquote style="FONT-SIZE: 75%;">
The numbers shown here have been estimated from a chart included in the
presentation slides. This chart contains an additional column labeled "Google"
which actually accounts for the applications dismissed because of their low
quality.
</blockquote>
<p>
The fact that Boost is ranked the sixth most attractive organization out of a
total of 102 was entirely unexpected, especially considering the wide popularity
of the rest of top-rated organizations. There is a more or less implicit
consensus among Boost members that ours is a relatively niche project, known for
its quality standards by seasoned C++ practitioners, but with a limited penetration
among entry level programmers: maybe the figures above should make us reconsider
this assumption. A cursory examination of the applications submitted to Boost reveals
that most applicants were regular users of Boost: many cite the Boost status among
the C++ community as an appealing factor in order to apply.
</p>
<h3><a name="opportunities_lost">Opportunities lost?</a></h3>
<p>
If we look at the number of funded projects with respect to the applications received,
figures are not so favorable to Boost.</p>
<p align="center">
<table cellspacing="0">
<tr>
<th align="left">Organization</th>
<th>No of projects</th>
<th>Project/app ratio</th>
</tr>
<tr>
<td>KDE</td>
<td align="center">24</td>
<td align="center">9.8 %</td>
</tr>
<tr class="odd_tr">
<td>Ubuntu &amp; Bazaar</td>
<td align="center">22</td>
<td align="center">9.3 %</td>
</tr>
<tr>
<td>Python Software Foundation</td>
<td align="center">23</td>
<td align="center">10.8 %</td>
</tr>
<tr class="odd_tr">
<td>GNOME</td>
<td align="center">19</td>
<td align="center">9.5 %</td>
</tr>
<tr>
<td>Apache Software Foundation</td>
<td align="center">27</td>
<td align="center">14.2 %</td>
</tr>
<tr class="odd_tr">
<td><b>Boost</b></td>
<td align="center"><b>10</b></td>
<td align="center"><b>5.7 %</b></td>
</tr>
<tr>
<td>Gaim</td>
<td align="center">8</td>
<td align="center">5.3 %</td>
</tr>
<tr class="odd_tr">
<td>The GNU Project</td>
<td align="center">10</td>
<td align="center">6.8 %</td>
</tr>
<tr>
<td>Drupal</td>
<td align="center">14</td>
<td align="center">9.6 %</td>
</tr>
</table>
</p>
<p>
It turns out that the project/application ratio for almost any other organization
among the top nine is considerably higher than that of Boost. As it happens, Google
initially requested that organizations submitted the maximum number of projects they
felt they could cope with, and we got funding for exactly what we aimed for, so the
limiting factor lies entirely on Boost's side.
</p>
<h3><a name="projects_startup">Projects startup</a></h3>
<p>
Contributing to Boost relies on a fair number of guidelines and protocols for
coding, documentation, testing and maintenance. Many of the required tools are
exclusively used within Boost, and some of them are not trivial, like for instance
Boost.Build. Although the Boost web site contains information about all these tools
and procedures, this intelligence is scattered through unrelated pages and sometimes
is very hard to come by.
</p>
<p>
So, there is a good deal of expertise required to begin working at Boost. Some
students have reported on startup difficulties getting to know these details and
familiarizing themselves with the tools, most notably <code>bjam</code> and Quickbook. Each
student overcome the startup difficulties on their own or resorting to their
mentors (see the section on <a href="#public_communication_issues">public
communication issues</a>).
</p>
<h3><a name="ongoing_development">Ongoing development</a></h3>
<p>
Once students got past the startup stage, most projects advanced without serious
complications. In the majority of cases, it was realized at some point during
the development that there was no time to complete it. Some participants had to
redefine the goals in an effort to keep the project within schedule, while others
simply decided that they would continue working after the official deadline of
Summer of Code.
</p>
<p>
The information flow between each student and their mentor was usually reported
by both parties to be satisfactory. The projects suffering from lack of
communication have been precisely those yielding the poorest results. In general,
mentors have not felt overwhelmed by requests from their students, and even in a
couple of cases the projects were run practically unattendedly. This fact is
witness to the high competence of the students recruited into the program.
</p>
<p>
The degree of usage of the Trac/SVN system has varied. Some students did frequent
updates, while others have just used the repository to dump the final results for
the official submission to Google.
</p>
<h3><a name="public_communication_issues">Public communication
issues</a></h3>
<p>
Students and mentors had at their disposal three different forums for the public
interchange of information and support:
<ul>
<li>Boost public lists, especially the developers and users lists.</li>
<li>A dedicated mailing list reaching all students and mentors working at
Summer of Code in Boost.</li>
<li>A more casual Google Group, set up by one of the students, aimed at
providing the participants with a place for socializing and resolution of
common problems.</li>
</ul>
Despite this abundance of resources, there was an almost complete lack of group
communication among all the parties involved and between these and the larger
Boost community. Seemingly, students were satisfied to pursue their activities by
relying on support from their mentors alone. This circumstance has prevented
Boost members from enriching the initiative by offering their experience and
insight, and has possibly led students to the false impression that contributing
to Boost proceeds in a predictable linear path from requisites to completion of
the work. When asked about their not engaging in public communication, the students
gave vague justifications that can be classified into the following:
<ul>
<li>Doubts were deemed too technical or specific to be worth raising in
public.</li>
<li>A crave for perfectionism detracted students from asking or submitting work
in progress until they felt their material looked good enough.</li>
<li>Shyness: some students probably lacked previous experience communicating in
public, and most are not English native speakers, which could also be a
limiting factor.</li>
</ul>
Although students did not identify the following as a reason not to go public, it
is likely that many of them did not feel the need given the readily access to their
mentors they enjoyed. It is easy to grow used to such a dedicated source of support
and neglect resorting to other resources. Mentors should have encouraged their
students to pursue the public discussion of projects, which constitutes one of the
pillars of Boost renowned quality.
</p>
<h3><a name="scope_of_projects">Scope of projects</a></h3>
<p>
In hindsight, it has become apparent that most projects were too ambitious to be
completed within the three months of duration of the program, and even those that
were considered a success will need weeks or months of polishing up before the
material is ready for a formal review. In contrast with other organizations
participating in the Summer of Code program, Boost has as of this writing included
no results into its code base. No formal review for any project has been requested
yet, either.
</p>
<p>
These scope issues are very dependent on the particular type of project. We can
classify the Boost projects for Summer of Code as follows:
<ul>
<li>Full-fledged libraries,</li>
<li>additions to existing Boost libraries,</li>
<li>utilities and tool projects using Boost.</li>
</ul>
Of these, additions (like for instance the mincut/maxflow algorithm for BGL by
Stephan Diederich) are the most suitable for completion in a short period of time:
most of the preparation work is already done, and the student has clear guides as
to what coding and documentation standards to follow. Also, these projects need
not undergo a formal review, since it is the responsibility of the hosting library
author to review the code and include it within her discretion. Utility projects
seem also suitable for small timeframes, though most project proposals and requests
are naturally oriented to contributions of actual code to the Boost project.
</p>
<p>
As for those projects involving the design and realization of full-fledged
libraries, there is little hope that the goals and scope can be kept modest enough
for a three-month schedule. Boost candidate libraries developed by professional
authors usually take much longer than three months to be accepted; some libraries
have been evolving through several <i>years</i> before being included into Boost.
So, the best we can hope for if we are to support the realization of library projects
for Boost inside Summer of Code is that the results by the end of the program can
be evaluated to constitute a viable <i>potential</i> contribution to Boost. When this is
the case, it is crucial that the student commits to further working on the project
up to completion and formal review. Perhaps more important than getting libraries
coded is to engage new authors into a long-term relationship with the Boost project.
</p>
<h2><a name="suggestions_for_improvement">Suggestions for improvement</a></h2>
<p>
The following proposals aim to alleviate some of the problems we have identified
during the development of Summer of Code within Boost. These action points are
related only to the issues found in connection with Boost: we are not addressing
other areas of improvement associated to the Summer of Code program itself.
</p>
<h3><a name="preparation">Preparation</a></h3>
<p>
Much work can be done before the actual program begins. The following preparation
activities can already be launched:
</p>
<p>
<b>Create a pool of ideas for projects.</b> This action will provide valuable extra
time for evaluation and refining of ideas before the Summer of Code begins.
The experience has shown that those projects with more preparation work, especially
in the area of design, were ultimately more successful. The pool can also be used
to retain interesting ideas that arise at the mailing lists and very often are
not given proper attention and become abandoned.
</p>
<p>
<b>Create a student pool.</b> Prior involvement with Boost is clearly an advantage
both in the selection phase and later during project development. Those students
with a serious interest in participating in Summer of Code with Boost can enter
the pool and begin exploring ideas and interacting with the community well in
advance of the summer, so as to put themselves in a favorable position for the
selection. Advertisement for the student pool can be initiated in the beginning of
2007 through the usual channels (web site and mailing lists): additionally, Boost
members involved with the University can spread this information locally and help
raise the interest of students in their environment.
</p>
<p>
<b>Create a mentor pool.</b> Given the rush with which Boost entered the 2006
Summer of Code campaign, the invitation of mentors has to be done on an on-demand
basis as it became all too evident that the task was growing bigger and bigger.
It is important that the organization is better prepared next year so that a
number of people with the ability and will to participate as Boost mentors are
identified in advance.
</p>
<p>
<b>Prepare a startup package.</b> In order to facilitate the initial period of
getting familiarized with the various Boost guidelines, protocols and tools, it
would be extremely useful to prepare a compilation of startup material for
students. This package can consist of a single document gathering the currently
dispersed information, or go beyond this and provide some bundle of documentation
and pre-built tools, an approach that one of the students is currently working on.
</p>
<h3><a name="public_communication">Public communication</a></h3>
<p>
It is crucial that students get involved with the community as soon as possible
and grow to appreciate the advantages of public development with respect to
solitary coding.
</p>
<p>
<b>Mandate (bi)weekly reports.</b> These reports should be directed to the public
mailing lists so as to give all Boost members an opportunity to follow the work
in progress and contribute. Reporting has the extra benefit for students of
forcing them to reflect on their own work periodically and struggle with the
often difficult task of presenting their ideas to others.
</p>
<p>
<b>Conduct student-mentor exclusively through public channels.</b> This might be
too drastic a policy, as some matters need privacy, and depending on the amount
of information exchanged flooding problems may arise. Less severe variations
involve allowing for some private interchange at the mentors' discretion and
moving this kind of communication to a dedicated public mailing list different
from the general ones.
</p>
<h3><a name="project_management">Project management</a></h3>
<p>
The two most important issues to improve upon with respect to the management are:
<ul>
<li>Project scope must be kept under control,</li>
<li>The progress has to be publicly visible, so that problems of scope,
design and/or schedule can be more easily detected.</li>
</ul>
Some of the proposals in this section are not to be regarded as strict rules,
but rather as general guidelines to be kept in mind by students and encouraged
by mentors.
</p>
<p>
<b>Create a best practices document.</b> This document can serve as a guideline
for project management, an area in which Boost traditionally imposes no
requirements. Students might lack the expertise in this area that is usually
taken for granted in the traditional model where contributions to Boost are
made by professional programmers.
</p>
<p>
<b>Mandate a design phase.</b> Having a concrete design set up and clearly
described early in the project will help estimate the necessary effort for
completion of the work. This is also an opportunity for public discussion.
</p>
<p>
<b>Maintain code, docs and tests in parallel.</b> All too often, novice
programmers do the coding in one fell swoop and only then move to testing and
documenting their work. This is unacceptable by all current methodology
standards, and can result in serious underestimations of the time to
completion.
</p>
<p>
<b>Encourage the KISS principle.</b> It is much better to finish a simpler library
and then iteratively evolve it, once it has been exposed to public scrutiny and
usage.
</p>
<p>
<b>More Trac updates.</b> The repository should be viewed as an everyday work
tool, not only as the place into which to dump the final results. Updating often
leads to more visibility of the work by the mentor and the public in general.
</p>
<p>
<b>Informal reviews.</b> The typical Summer of Code Boost project will not be
completed by the official deadline, as have been discussed earlier. To somehow
officialize the work done within the Summer of Code proper, and also to allow
the students to reach some sort of psychological milestone, informal reviews can
be instituted where Boost members evaluate the work done at then end of Summer
of Code.
</p>
<p>
<b>Engage students.</b> This experience has shown that it is possible to guide
willing and bright students to the competence levels required for contributing
to Boost. The best possible outcome of Summer of Code campaigns are the
incorporation of new people into the circle of Boost active contributors. Strive
to make the students commit to Boost.
</p>
<h2><a name="conclusions">Conclusions</a></h2>
<p>
Despite the lack of previous experience in Boost, our participation in Google
Summer of Code has been extremely fruitful: much useful material has been produced,
and, perhaps more importantly, some of the students are likely to commit on a
long-term basis and grow to be regular Boost contributors. Traditionally, becoming
a productive Boost author has a very high entry barrier due to the extreme quality
standards, lack of public support and the very specific culture of the project.
The appeal of Summer of Code itself and the possibility of being gently mentored
into the world of Boost have most likely been key factors in lowering this entry
barrier.
</p>
<p>
The process has not been without some difficulties, either, as it was expected of
a newcomer organization as Boost. We have tried to identify in this paper the
areas of improvement and suggest specific actions so that the upcoming Google
Summer of Code 2007 can be an even more rewarding experience.
</p>
<h2><a name="acknowledgements">Acknowledgements</a></h2>
<p>
This paper couldn't have been written without the numerous reports and contributions
kindly provided by Boost students and mentors: Many thanks to all the participants
for sharing their experiences with me. Thank you also to the people at Google who
have promoted and conducted the Summer of Code initiative.
</p>
<hr>
<p>Revised October 17th 2006</p>
<p>&copy; Copyright 2006 Joaqu&iacute;n M L&oacute;pez Mu&ntilde;oz.
Distributed under the Boost Software
License, Version 1.0. (See accompanying file <a href="../LICENSE_1_0.txt">
LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

394
borland_cpp.html
View File

@ -1,394 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<title>Portability Hints: Borland C++ 5.5.1</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2" summary="">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt=
"boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial,Helvetica" color=
"#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color=
"#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial,Helvetica" color=
"#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial,Helvetica" color=
"#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial,Helvetica" color=
"#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Portability Hints: Borland C++ 5.5.1</h1>
<p>It is a general aim for boost libraries to be <a href=
"lib_guide.htm#Portability">portable</a>. The primary means for achieving
this goal is to adhere to ISO Standard C++. However, ISO C++ is a broad and
complex standard and most compilers are not fully conformant to ISO C++
yet. In order to achieve portability in the light of this restriction, it
seems advisable to get acquainted with those language features that some
compilers do not fully implement yet.</p>
<p>This page gives portability hints on some language features of the
Borland C++ version 5.5.1 compiler. Furthermore, the appendix presents
additional problems with Borland C++ version 5.5. Borland C++ 5.5.1 is a
freely available command-line compiler for Win32 available at <a href=
"http://www.borland.com/">http://www.borland.com/</a>.</p>
<p>Each entry in the following list describes a particular issue, complete
with sample source code to demonstrate the effect. Most sample code herein
has been verified to compile with gcc 2.95.2 and Comeau C++ 4.2.44.</p>
<h2>Preprocessor symbol</h2>
<p>The preprocessor symbol <code>__BORLANDC__</code> is defined for all
Borland C++ compilers. Its value is the version number of the compiler
interpreted as a hexadecimal number. The following table lists some known
values.</p>
<table border="1" summary="">
<tr>
<th>Compiler</th>
<th><code>__BORLANDC__</code> value</th>
</tr>
<tr>
<td>Borland C++ Builder 4</td>
<td>0x0540</td>
</tr>
<tr>
<td>Borland C++ Builder 5</td>
<td>0x0550</td>
</tr>
<tr>
<td>Borland C++ 5.5</td>
<td>0x0550</td>
</tr>
<tr>
<td>Borland C++ 5.5.1</td>
<td>0x0551</td>
</tr>
<tr>
<td>Borland C++ Builder 6</td>
<td>0x0560</td>
</tr>
</table>
<h2>Core Language</h2>
<h3>[using-directive] Mixing <code>using</code>-declarations and
<code>using</code>-directives</h3>
<p>Mixing <code>using</code>-directives (which refer to whole namespaces)
and namespace-level <code>using</code>-declarations (which refer to
individual identifiers within foreign namespaces) causes ambiguities where
there are none. The following code fragment illustrates this:</p>
<pre>
namespace N {
int x();
}
using N::x;
using namespace N;
int main()
{
&amp;x; // Ambiguous overload
}
</pre>
<h3>[using template] <code>using</code>-declarations for class
templates</h3>
<p>Identifiers for class templates can be used as arguments to
<code>using</code>-declarations as any other identifier. However, the
following code fails to compile with Borland C++:</p>
<pre>
template&lt;class T&gt;
class X { };
namespace N
{
// "cannot use template 'X&lt;T&gt;' without specifying specialization parameters"
using ::X;
};
</pre>
<h3>[template const arg] Deduction of constant arguments to function
templates</h3>
<p>Template function type deduction should omit top-level constness.
However, this code fragment instantiates "f&lt;const int&gt;(int)":</p>
<pre>
template&lt;class T&gt;
void f(T x)
{
x = 1; // works
(void) &amp;x;
T y = 17;
y = 20; // "Cannot modify a const object in function f&lt;const int&gt;(int)"
(void) &amp;y;
}
int main()
{
const int i = 17;
f(i);
}
</pre>
<h3>[function address] Resolving addresses of overloaded functions</h3>
<p>Addresses of overloaded functions are not in all contexts properly
resolved (std:13.4 [over.over]); here is a small example:</p>
<pre>
template&lt;class Arg&gt;
void f( void(*g)(Arg) );
void h(int);
void h(double);
template&lt;class T&gt;
void h2(T);
int main()
{
void (*p)(int) = h; // this works (std:13.4-1.1)
void (*p2)(unsigned char) = h2; // this works as well (std:13.4-1.1)
f&lt;int&gt;(h2); // this also works (std:13.4-1.3)
// "Cannot generate template specialization from h(int)",
// "Could not find a match for f&lt;Arg&gt;(void (*)(int))"
f&lt;double&gt;(h); // should work (std:13.4-1.3)
f( (void(*)(double))h); // C-style cast works (std:13.4-1.6 with 5.4)
// "Overloaded 'h' ambiguous in this context"
f(static_cast&lt;void(*)(double)&gt;(h)); // should work (std:13.4-1.6 with 5.2.9)
}
</pre>
<p><strong>Workaround:</strong> Always use C-style casts when determining
addresses of (potentially) overloaded functions.</p>
<h3>[string conversion] Converting <code>const char *</code> to
<code>std::string</code></h3>
<p>Implicitly converting <code>const char *</code> parameters to
<code>std::string</code> arguments fails if template functions are
explicitly instantiated (it works in the usual cases, though):</p>
<pre>
#include &lt;string&gt;
template&lt;class T&gt;
void f(const std::string &amp; s)
{}
int main()
{
f&lt;double&gt;("hello"); // "Could not find a match for f&lt;T&gt;(char *)"
}
</pre>
<p><strong>Workaround:</strong> Avoid explicit template function
instantiations (they have significant problems with Microsoft Visual C++)
and pass default-constructed unused dummy arguments with the appropriate
type. Alternatively, if you wish to keep to the explicit instantiation, you
could use an explicit conversion to <code>std::string</code> or declare the
template function as taking a <code>const char *</code> parameter.</p>
<h3>[template value defaults] Dependent default arguments for template
value parameters</h3>
<p>Template value parameters which default to an expression dependent on
previous template parameters don't work:</p>
<pre>
template&lt;class T&gt;
struct A
{
static const bool value = true;
};
// "Templates must be classes or functions", "Declaration syntax error"
template&lt;class T, bool v = A&lt;T&gt;::value&gt;
struct B {};
int main()
{
B&lt;int&gt; x;
}
</pre>
<p><strong>Workaround:</strong> If the relevant non-type template parameter
is an implementation detail, use inheritance and a fully qualified
identifier (for example, ::N::A&lt;T&gt;::value).</p>
<h3>[function partial ordering] Partial ordering of function templates</h3>
<p>Partial ordering of function templates, as described in std:14.5.5.2
[temp.func.order], does not work:</p>
<pre>
#include &lt;iostream&gt;
template&lt;class T&gt; struct A {};
template&lt;class T1&gt;
void f(const A&lt;T1&gt; &amp;)
{
std::cout &lt;&lt; "f(const A&lt;T1&gt;&amp;)\n";
}
template&lt;class T&gt;
void f(T)
{
std::cout &lt;&lt; "f(T)\n";
}
int main()
{
A&lt;double&gt; a;
f(a); // output: f(T) (wrong)
f(1); // output: f(T) (correct)
}
</pre>
<p><strong>Workaround:</strong> Declare all such functions uniformly as
either taking a value or a reference parameter.</p>
<h3>[instantiate memfun ptr] Instantiation with member function
pointer</h3>
<p>When directly instantiating a template with some member function
pointer, which is itself dependent on some template parameter, the compiler
cannot cope:</p>
<pre>
template&lt;class U&gt; class C { };
template&lt;class T&gt;
class A
{
static const int v = C&lt;void (T::*)()&gt;::value;
};
</pre>
<p><strong>Workaround:</strong> Use an intermediate
<code>typedef</code>:</p>
<pre>
template&lt;class U&gt; class C { };
template&lt;class T&gt;
class A
{
typedef void (T::*my_type)();
static const int v = C&lt;my_type&gt;::value;
};
</pre>
<p>(Extracted from e-mail exchange of David Abrahams, Fernando Cacciola,
and Peter Dimov; not actually tested.)</p>
<h2>Library</h2>
<h3>[cmath.abs] Function <code>double std::abs(double)</code> missing</h3>
<p>The function <code>double std::abs(double)</code> should be defined
(std:26.5-5 [lib.c.math]), but it is not:</p>
<pre>
#include &lt;cmath&gt;
int main()
{
double (*p)(double) = std::abs; // error
}
</pre>
<p>Note that <code>int std::abs(int)</code> will be used without warning if
you write <code>std::abs(5.1)</code>.</p>
<p>Similar remarks apply to seemingly all of the other standard math
functions, where Borland C++ fails to provide <code>float</code> and
<code>long double</code> overloads.</p>
<p><strong>Workaround:</strong> Use <code>std::fabs</code> instead if type
genericity is not required.</p>
<h2>Appendix: Additional issues with Borland C++ version 5.5</h2>
<p>These issues are documented mainly for historic reasons. If you are
still using Borland C++ version 5.5, you are strongly encouraged to obtain
an upgrade to version 5.5.1, which fixes the issues described in this
section.</p>
<h3>[inline friend] Inline friend functions in template classes</h3>
<p>If a friend function of some class has not been declared before the
friend function declaration, the function is declared at the namespace
scope surrounding the class definition. Together with class templates and
inline definitions of friend functions, the code in the following fragment
should declare (and define) a non-template function "bool N::f(int,int)",
which is a friend of class N::A&lt;int&gt;. However, Borland C++ v5.5
expects the function f to be declared beforehand:</p>
<pre>
namespace N {
template&lt;class T&gt;
class A
{
// "f is not a member of 'N' in function main()"
friend bool f(T x, T y) { return x &lt; y; }
};
}
int main()
{
N::A&lt;int&gt; a;
}
</pre>
<p>This technique is extensively used in boost/operators.hpp. Giving in to
the wish of the compiler doesn't work in this case, because then the
"instantiate one template, get lots of helper functions at namespace scope"
approach doesn't work anymore. Defining BOOST_NO_OPERATORS_IN_NAMESPACE (a
define BOOST_NO_INLINE_FRIENDS_IN_CLASS_TEMPLATES would match this case
better) works around this problem and leads to another one, see
[using-template].</p>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->03
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38512" --></p>
<p><i>Copyright &copy; 2000-2002 <a href="../people/jens_maurer.htm">Jens
Maurer</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

118
bugs.htm
View File

@ -1,118 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Bugs</title>
</head>
<body bgcolor="#ffffff" text="#000000">
<table border="1" bgcolor="#007f7f" cellpadding="2">
<tbody><tr>
<td bgcolor="#ffffff">
<img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color="#ffffff"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color="#ffffff"><big>
Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color="#ffffff"><big>
People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color="#ffffff"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color="#ffffff"><big>More</big></font></a></td>
</tr>
</tbody>
</table>
<h1>What to do about Boost bugs</h1>
<ol>
<li>Make sure the bug isn't already fixed in the latest sources. The most
recent version of everything on the Boost web site is available from
the <a href="http://www.boost.org/more/getting_started.html#CVS">boost public
CVS repository</a>.<br>
<br>
</li>
<li>If you are a Boost user, or a Boost developer that doesn't have a CVS
write access: <br>
<br>
<ol>
<li>Submit a bug report to either
<a href="http://www.boost.org/more/mailing_lists.htm#users">boost-users list</a>,
<a href="http://www.boost.org/more/mailing_lists.htm#main">boost mailing
list</a>, or our <a href="http://sourceforge.net/tracker/?group_id=7586">bug
tracking facility</a> at SourceForge; submitting it to either of the mailing
lists is a preferred way - because many of the Boost developers read the
lists on a daily basis, this way you are likely to get a quicker response,
and the discussions that often arise there from (possible) bug reports are
quite interesting and educational as well;<br>
<br>
</li>
<li>If you have a proposed patch to the code, post it along with your bug
report, preferably in the <em>unified diffs</em> format (<code>cvs diff -du</code>);
if you can, send a patch relative to the current CVS state. A canonical
example of creating a patch file follows (let's assume that you've found
a bug in the file <code>intentional_bug.hpp</code>:<br>
<br>
<ol>
<li>Download the latest version of <code>intentional_bug.hpp</code> from CVS.</li>
<li>Make sure that the bug is still present in the code.</li>
<li>Copy the file <code>intentional_bug.hpp</code> to a file called <code>intentional_bug.hpp.orig</code>.</li>
<li>Apply your changes to <code>intentional_bug.hpp</code>.</li>
<li>Run "<code>diff -du intentional_bug.hpp.orig intentional_bug.hpp &gt; intentional_bug.hpp.patch</code>" from the command prompt.</li>
<li>Submit the patch file together with an explanation of the bug
and the proposed fix; and don't forget to include the word <b>patch</b> or <b>bug</b>
in the subject if you're submitting to the <a href="http://www.boost.org/more/mailing_lists.htm#main">boost mailing list</a>.<br>
<br>
</li>
</ol>
</li>
</ol>
</li>
<li>If you are a Boost developer, and you have a CVS write access: <br>
<br>
<ol>
<li>If the bug is trivial (e.g. misspelled name, missed <code>typename</code>,
etc.), and you are willing to make a fix, either make your changes locally
and contact the library author(s)/maintainer(s) about it, or go ahead and
check the fix into CVS, but post a notification about it to the
<a href="http://www.boost.org/more/mailing_lists.htm#main">boost mailing
list</a> (if the author is not very active on the list, you also might want
to consider <code>cc</code>'ing him as well); <br>
<br>
</li>
<li>If the bug is non-trivial, and/or you don't have the time and resources to fix it,
submit a bug report (see p. 2 above); chances are that the maintainer(s)
will respond promptly and take care of the problem; <br>
<br>
</li>
<li>Otherwise, create a temporary branch in CVS, make your changes there, and
ask the library author(s)/maintainer(s) to review them; if they are ok with
the new code, either you or they can integrate the fixes into the main
trunk. </li>
</ol>
</li>
</ol>
<hr>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->18 January, 2002<!--webbot bot="Timestamp" i-checksum="38453" endspan -->
</p>
<p>© Copyright <a href="../people/aleksey_gurtovoy.htm">Aleksey Gurtovoy</a>
2002</p>
<p> Distributed under the Boost Software License, Version 1.0.
(See accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)
</p>
<br>
</body></html>

774
count_bdy.htm
View File

@ -1,774 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="GENERATOR" content="Microsoft FrontPage 6.0">
<meta name="Author" content="Kevlin Henney">
<meta name="KeyWords" content=
"C++, Reference Counting, Advanced Techniques, Smart Pointers, Patterns">
<title>Counted Body Techniques</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1 align="center"><i><font size="+4">Counted Body Techniques</font></i></h1>
<center>
<p><b><font size="+1"><a href="../people/kevlin_henney.htm">Kevlin Henney</a><br></font>
(<a href=
"mailto:kevlin@acm.org">kevlin@acm.org</a>, <a href=
"mailto:khenney@qatraining.com">khenney@qatraining.com</a>)</b></p>
</center>
<div style="margin-left: 2em">
<p>Reference counting techniques? Nothing new, you might think. Every good
C++ text that takes you to an intermediate or advanced level will
introduce the concept. It has been explored with such thoroughness in the
past that you might be forgiven for thinking that everything that can be
said has been said. Well, let's start from first principles and see if we
can unearth something new....</p>
</div>
<hr width="100%">
<h2>And then there were none...</h2>
<div style="margin-left: 2em">
<p>The principle behind reference counting is to keep a running usage
count of an object so that when it falls to zero we know the object is
unused. This is normally used to simplify the memory management for
dynamically allocated objects: keep a count of the number of references
held to that object and, on zero, delete the object.</p>
<p>How to keep a track of the number of users of an object? Well, normal
pointers are quite dumb, and so an extra level of indirection is required
to manage the count. This is essentially the P<font size="-1">ROXY</font>
pattern described in <i>Design Patterns</i> [Gamma, Helm, Johnson &amp;
Vlissides, Addison-Wesley, <font size="-1">ISBN</font> 0-201-63361-2]. The
intent is given as</p>
<div style="margin-left: 2em">
<p><i>Provide a surrogate or placeholder for another object to control
access to it.</i></p>
</div>
<p>Coplien [<i>Advanced C++ Programming Styles and Idioms</i>,
Addison-Wesley, <font size="-1">ISBN</font> 0-201-56365-7] defines a set
of idioms related to this essential separation of a handle and a body
part. The <i>Taligent Guide to Designing Programs</i> [Addison-Wesley,
<font size="-1">ISBN</font> 0-201-40888-0] identifies a number of specific
categories for proxies (aka surrogates). Broadly speaking they fall into
two general categories:</p>
<ul>
<li><i>Hidden</i>: The handle is the object of interest, hiding the body
itself. The functionality of the handle is obtained by delegation to the
body, and the user of the handle is unaware of the body. Reference
counted strings offer a transparent optimisation. The body is shared
between copies of a string until such a time as a change is needed, at
which point a copy is made. Such a C<font size=
"-1">OPY</font> <font size="-1">ON</font> W<font size="-1">RITE</font>
pattern (a specialisation of L<font size="-1">AZY</font> E<font size=
"-1">VALUATION</font>) requires the use of a hidden reference counted
body.</li>
<li><i>Explicit</i>: Here the body is of interest and the handle merely
provides intelligence for its access and housekeeping. In C++ this is
often implemented as the S<font size="-1">MART</font> P<font size=
"-1">OINTER</font> idiom. One such application is that of reference
counted smart pointers that collaborate to keep a count of an object,
deleting it when the count falls to zero.</li>
</ul>
</div>
<hr width="100%">
<h2>Attached vs detached</h2>
<div style="margin-left: 2em">
<p>For reference counted smart pointers there are two places the count can
exist, resulting in two different patterns, both outlined in
<i>Software Patterns</i> [Coplien, SIGS, <font size="-1">ISBN</font>
0-884842-50-X]:</p>
<ul>
<li>C<font size="-1">OUNTED</font> B<font size="-1">ODY</font> or A<font size="-1">TTACHED</font>
C<font size="-1">OUNTED</font>
H<font size="-1">ANDLE</font>/B<font size="-1">ODY</font> places the
count within the object being counted. The benefits are that
countability is a part of the object being counted, and that reference
counting does not require an additional object. The drawbacks are
clearly that this is intrusive, and that the space for the reference
count is wasted when the object is not heap based. Therefore the
reference counting ties you to a particular implementation and style of
use.</li>
<li>D<font size="-1">ETACHED</font> C<font size="-1">OUNTED</font>
H<font size="-1">ANDLE</font>/B<font size="-1">ODY</font> places the
count outside the object being counted, such that they are handled
together. The clear benefit of this is that this technique is completely
unintrusive, with all of the intelligence and support apparatus in the
smart pointer, and therefore can be used on classes created
independently of the reference counted pointer. The main disadvantage is
that frequent use of this can lead to a proliferation of small objects,
i.e. the counter, being created on the heap.</li>
</ul>
<p>Even with this simple analysis, it seems that the D<font size=
"-1">ETACHED</font> C<font size="-1">OUNTED</font> H<font size=
"-1">ANDLE</font>/B<font size="-1">ODY</font> approach is ahead. Indeed,
with the increasing use of templates this is often the favourite, and is
the principle behind the common - but not standard - <tt><font size=
"+1">counted_ptr</font></tt>. <i>[The Boost name is <a href=
"../libs/smart_ptr/shared_ptr.htm"><tt><font size=
"+1">shared_ptr</font></tt></a> rather than <tt><font size=
"+1">counted_ptr</font></tt>.]</i></p>
<p>A common implementation of C<font size="-1">OUNTED</font> B<font size=
"-1">ODY</font> is to provide the counting mechanism in a base class that
the counted type is derived from. Either that, or the reference counting
mechanism is provided anew for each class that needs it. Both of these
approaches are unsatisfactory because they are quite closed, coupling a
class into a particular framework. Added to this the non-cohesiveness of
having the count lying dormant in a non-counted object, and you get the
feeling that excepting its use in widespread object models such as COM and
CORBA the C<font size="-1">OUNTED</font> B<font size="-1">ODY</font>
approach is perhaps only of use in specialised situations.</p>
</div>
<hr width="100%">
<h2>A requirements based approach</h2>
<div style="margin-left: 2em">
<p>It is the question of openness that convinced me to revisit the
problems with the C<font size="-1">OUNTED</font> B<font size=
"-1">ODY</font> idiom. Yes, there is a certain degree of intrusion
expected when using this idiom, but is there anyway to minimise this and
decouple the choice of counting mechanism from the smart pointer type
used?</p>
<p>In recent years the most instructive body of code and specification for
constructing open general purpose components has been the Stepanov and
Lee's STL (Standard Template Library), now part of the C++ standard
library. The STL approach makes extensive use of compile time polymorphism
based on well defined operational requirements for types. For instance,
each container, contained and iterator type is defined by the operations
that should be performable on an object of that type, often with
annotations describing additional constraints. Compile time polymorphism,
as its name suggests, resolves functions at compile time based on function
name and argument usage, i.e. overloading. This is less intrusive,
although less easily diagnosed if incorrect, than runtime poymorphism that
is based on types, names and function signatures.</p>
<p>This requirements based approach can be applied to reference counting.
The operations we need for a type to be <i>Countable</i> are loosely:</p>
<ul>
<li>An <tt><font size="+1">acquire</font></tt> operation that registers
interest in a <i>Countable</i> object.</li>
<li>A <tt><font size="+1">release</font></tt> operation unregisters
interest in a <i>Countable</i> object.</li>
<li>An <tt><font size="+1">acquired</font></tt> query that returns
whether or not a <i>Countable</i> object is currently acquired.</li>
<li>A <tt><font size="+1">dispose</font></tt> operation that is
responsible for disposing of an object that is no longer acquired.</li>
</ul>
<p>Note that the count is deduced as a part of the abstract state of this
type, and is not mentioned or defined in any other way. The openness of
this approach derives in part from the use of global functions, meaning
that no particular member functions are implied; a perfect way to wrap up
an existing counted body class without modifying the class itself. The
other aspect to the openness comes from a more precise specification of
the operations.</p>
<p>For a type to be <i>Countable</i> it must satisfy the following
requirements, where <tt><font size="+1">ptr</font></tt> is a non-null
pointer to a single object (i.e. not an array) of the type, and
<i><tt><font size="+1">#function</font></tt></i> indicates number of calls
to <tt><font size="+1"><i>function(</i>ptr<i>)</i></font></tt>:</p>
<center>
<table border="1" cellspacing="2" cellpadding="2" summary="">
<tr>
<td><i>Expression</i></td>
<td><i>Return type</i></td>
<td><i>Semantics and notes</i></td>
</tr>
<tr>
<td><tt><font size="+1">acquire(ptr)</font></tt></td>
<td>no requirement</td>
<td><i>post</i>: <tt><font size="+1">acquired(ptr)</font></tt></td>
</tr>
<tr>
<td><tt><font size="+1">release(ptr)</font></tt></td>
<td>no requirement</td>
<td><i>pre</i>: <tt><font size="+1">acquired(ptr)<br></font></tt>
<i>post</i>: <tt><font size="+1">acquired(ptr) == #acquire -
#release</font></tt></td>
</tr>
<tr>
<td><tt><font size="+1">acquired(ptr)</font></tt></td>
<td>convertible to <tt><font size="+1">bool</font></tt></td>
<td><i>return</i>: <tt><font size="+1">#acquire &gt; #release</font></tt></td>
</tr>
<tr>
<td><tt><font size="+1">dispose(ptr, ptr)</font></tt></td>
<td>no requirement</td>
<td><i>pre</i>: <tt><font size="+1">!acquired(ptr)<br></font></tt>
<i>post</i>: <tt><font size="+1">*ptr</font></tt> no longer usable</td>
</tr>
</table>
</center>
<p>Note that the two arguments to <tt><font size="+1">dispose</font></tt>
are to support selection of the appropriate type safe version of the
function to be called. In the general case the intent is that the first
argument determines the type to be deleted, and would typically be
templated, while the second selects which template to use, e.g. by
conforming to a specific base class.</p>
<p>In addition the following requirements must also be satisfied, where
<tt><font size="+1">null</font></tt> is a null pointer to the
<i>Countable</i> type:</p>
<center>
<table border="1" summary="">
<tr>
<td><i>Expression</i></td>
<td><i>Return type</i></td>
<td><i>Semantics and notes</i></td>
</tr>
<tr>
<td><tt><font size="+1">acquire(null)</font></tt></td>
<td>no requirement</td>
<td><i>action</i>: none</td>
</tr>
<tr>
<td><tt><font size="+1">release(null)</font></tt></td>
<td>no requirement</td>
<td><i>action</i>: none</td>
</tr>
<tr>
<td><tt><font size="+1">acquired(null)</font></tt></td>
<td>convertible to <tt><font size="+1">bool</font></tt></td>
<td><i>return</i>: <tt><font size="+1">false</font></tt></td>
</tr>
<tr>
<td><tt><font size="+1">dispose(null, null)</font></tt></td>
<td>no requirement</td>
<td><i>action</i>: none</td>
</tr>
</table>
</center>
<p>Note that there are no requirements on these functions in terms of
exceptions thrown or not thrown, except that if exceptions are thrown the
functions themselves should be exception safe.</p>
</div>
<hr width="100%">
<h2>Getting smart</h2>
<div style="margin-left: 2em">
<p>Given the <i>Countable</i> requirements for a type, it is possible to
define a generic smart pointer type that uses them for reference counting:</p>
<div style="margin-left: 2em">
<pre>
<tt>template&lt;typename countable_type&gt;
class countable_ptr
{
public: // construction and destruction
explicit countable_ptr(countable_type *);
countable_ptr(const countable_ptr &amp;);
~countable_ptr();
public: // access
countable_type *operator-&gt;() const;
countable_type &amp;operator*() const;
countable_type *get() const;
public: // modification
countable_ptr &amp;clear();
countable_ptr &amp;assign(countable_type *);
countable_ptr &amp;assign(const countable_ptr &amp;);
countable_ptr &amp;operator=(const countable_ptr &amp;);
private: // representation
countable_type *body;
};
</tt>
</pre>
</div>
<p>The interface to this class has been kept intentionally simple, e.g.
member templates and <tt><font size="+1">throw</font></tt> specs have been
omitted, for exposition. The majority of the functions are quite simple in
implementation, relying very much on the <tt><font size=
"+1">assign</font></tt> member as a keystone function:</p>
<div style="margin-left: 2em">
<pre>
<tt>template&lt;typename countable_type&gt;
countable_ptr&lt;countable_type&gt;::countable_ptr(countable_type *initial)
: body(initial)
{
acquire(body);
}
template&lt;typename countable_type&gt;
countable_ptr&lt;countable_type&gt;::countable_ptr(const countable_ptr &amp;other)
: body(other.body)
{
acquire(body);
}
template&lt;typename countable_type&gt;
countable_ptr&lt;countable_type&gt;::~countable_ptr()
{
clear();
}
template&lt;typename countable_type&gt;
countable_type *countable_ptr&lt;countable_type&gt;::operator-&gt;() const
{
return body;
}
template&lt;typename countable_type&gt;
countable_type &amp;countable_ptr&lt;countable_type&gt;::operator*() const
{
return *body;
}
template&lt;typename countable_type&gt;
countable_type *countable_ptr&lt;countable_type&gt;::get() const
{
return body;
}
template&lt;typename countable_type&gt;
countable_ptr&lt;countable_type&gt; &amp;countable_ptr&lt;countable_type&gt;::clear()
{
return assign(0);
}
template&lt;typename countable_type&gt;
countable_ptr&lt;countable_type&gt; &amp;countable_ptr&lt;countable_type&gt;::assign(countable_type *rhs)
{
// set to rhs (uses Copy Before Release idiom which is self assignment safe)
acquire(rhs);
countable_type *old_body = body;
body = rhs;
// tidy up
release(old_body);
if(!acquired(old_body))
{
dispose(old_body, old_body);
}
return *this;
}
template&lt;typename countable_type&gt;
countable_ptr&lt;countable_type&gt; &amp;countable_ptr&lt;countable_type&gt;::assign(const countable_ptr &amp;rhs)
{
return assign(rhs.body);
}
template&lt;typename countable_type&gt;
countable_ptr&lt;countable_type&gt; &amp;countable_ptr&lt;countable_type&gt;::operator=(const countable_ptr &amp;rhs)
{
return assign(rhs);
}
</tt>
</pre>
</div>
</div>
<hr width="100%">
<h2>Public accountability</h2>
<div style="margin-left: 2em">
<p>Conformance to the requirements means that a type can be used with
<tt><font size="+1">countable_ptr</font></tt>. Here is an implementation
mix-in class (<i>mix-imp</i>) that confers countability on its derived
classes through member functions. This class can be used as a class
adaptor:</p>
<div style="margin-left: 2em">
<pre>
<tt>class countability
{
public: // manipulation
void acquire() const;
void release() const;
size_t acquired() const;
protected: // construction and destruction
countability();
~countability();
private: // representation
mutable size_t count;
private: // prevention
countability(const countability &amp;);
countability &amp;operator=(const countability &amp;);
};
</tt>
</pre>
</div>
<p>Notice that the manipulation functions are <tt><font size=
"+1">const</font></tt> and that the <tt><font size="+1">count</font></tt>
member itself is <tt><font size="+1">mutable</font></tt>. This is because
countability is not a part of an object's abstract state: memory
management does not depend on the <tt><font size=
"+1">const</font></tt>-ness or otherwise of an object. I won't include the
definitions of the member functions here as you can probably guess them:
increment, decrement and return the current count, respectively for the
manipulation functions. In a multithreaded environment you should ensure
that such read and write operations are atomic.</p>
<p>So how do we make this class <i>Countable</i>? A simple set of
forwarding functions does the job:</p>
<div style="margin-left: 2em">
<pre>
<tt>void acquire(const countability *ptr)
{
if(ptr)
{
ptr-&gt;acquire();
}
}
void release(const countability *ptr)
{
if(ptr)
{
ptr-&gt;release();
}
}
size_t acquired(const countability *ptr)
{
return ptr ? ptr-&gt;acquired() : 0;
}
template&lt;class countability_derived&gt;
void dispose(const countability_derived *ptr, const countability *)
{
delete ptr;
}
</tt>
</pre>
</div>
<p>Any type that now derives from <tt><font size=
"+1">countability</font></tt> may now be used with <tt><font size=
"+1">countable_ptr</font></tt>:</p>
<div style="margin-left: 2em">
<pre>
<tt>class example : public countability
{
...
};
void simple()
{
countable_ptr&lt;example&gt; ptr(new example);
countable_ptr&lt;example&gt; qtr(ptr);
ptr.clear(); // set ptr to point to null
} // allocated object deleted when qtr destructs
</tt>
</pre>
</div>
</div>
<hr width="100%">
<h2>Runtime mixin</h2>
<div style="margin-left: 2em">
<p>The challenge is to apply C<font size="-1">OUNTED</font> B<font size=
"-1">ODY</font> in a non-intrusive fashion, such that there is no overhead
when an object is not counted. What we would like to do is confer this
capability on a per object rather than on a per class basis. Effectively
we are after <i>Countability</i> on any object, i.e. anything pointed to
by a <tt><font size="+1">void *</font></tt>! It goes without saying that <tt><font size="+1">
void</font></tt> is perhaps the least committed of any type.</p>
<p>The forces to resolve on this are quite interesting, to say the least.
Interesting, but not insurmountable. Given that the class of a runtime
object cannot change dynamically in any well defined manner, and the
layout of the object must be fixed, we have to find a new place and time
to add the counting state. The fact that this must be added only on heap
creation suggests the following solution:</p>
<div style="margin-left: 2em">
<pre>
<tt>struct countable_new;
extern const countable_new countable;
void *operator new(size_t, const countable_new &amp;);
void operator delete(void *, const countable_new &amp;);</tt>
</pre>
</div>
<p>We have overloaded <tt><font size="+1">operator new</font></tt> with a
dummy argument to distinguish it from the regular global <tt><font size=
"+1">operator new</font></tt>. This is comparable to the use of the
<tt><font size="+1">std::nothrow_t</font></tt> type and <tt><font size=
"+1">std::nothrow</font></tt> object in the standard library. The
placement <tt><font size="+1">operator delete</font></tt> is there to
perform any tidy up in the event of failed construction. Note that this is
not yet supported on all that many compilers.</p>
<p>The result of a <tt><font size="+1">new</font></tt> expression using
<tt><font size="+1">countable</font></tt> is an object allocated on the
heap that has a header block that holds the count, i.e. we have extended
the object by prefixing it. We can provide a couple of features in an
anonymous namespace (not shown) in the implementation file for for
supporting the count and its access from a raw pointer:</p>
<div style="margin-left: 2em">
<pre>
<tt>struct count
{
size_t value;
};
count *header(const void *ptr)
{
return const_cast&lt;count *&gt;(static_cast&lt;const count *&gt;(ptr) - 1);
}
</tt>
</pre>
</div>
<p>An important constraint to observe here is the alignment of
<tt><font size="+1">count</font></tt> should be such that it is suitably
aligned for any type. For the definition shown this will be the case on
almost all platforms. However, you may need to add a padding member for
those that don't, e.g. using an anonymous <tt><font size=
"+1">union</font></tt> to coalign <tt><font size="+1">count</font></tt>
and the most aligned type. Unfortunately, there is no portable way of
specifying this such that the minimum alignment is also observed - this is
a common problem when specifying your own allocators that do not directly
use the results of either <tt><font size="+1">new</font></tt> or
<tt><font size="+1">malloc</font></tt>.</p>
<p>Again, note that the count is not considered to be a part of the
logical state of the object, and hence the conversion from
<tt><font size="+1">const</font></tt> to non-<tt><font size=
"+1">const</font></tt> - <tt><font size="+1">count</font></tt> is in
effect a <tt><font size="+1">mutable</font></tt> type.</p>
<p>The allocator functions themselves are fairly straightforward:</p>
<div style="margin-left: 2em">
<pre>
<tt>void *operator new(size_t size, const countable_new &amp;)
{
count *allocated = static_cast&lt;count *&gt;(::operator new(sizeof(count) + size));
*allocated = count(); // initialise the header
return allocated + 1; // adjust result to point to the body
}
void operator delete(void *ptr, const countable_new &amp;)
{
::operator delete(header(ptr));
}
</tt>
</pre>
</div>
<p>Given a correctly allocated header, we now need the <i>Countable</i>
functions to operate on <tt><font size="+1">const void *</font></tt> to
complete the picture:</p>
<div style="margin-left: 2em">
<pre>
<tt>void acquire(const void *ptr)
{
if(ptr)
{
++header(ptr)-&gt;value;
}
}
void release(const void *ptr)
{
if(ptr)
{
--header(ptr)-&gt;value;
}
}
size_t acquired(const void *ptr)
{
return ptr ? header(ptr)-&gt;value : 0;
}
template&lt;typename countable_type&gt;
void dispose(const countable_type *ptr, const void *)
{
ptr-&gt;~countable_type();
operator delete(const_cast&lt;countable_type *&gt;(ptr), countable);
}
</tt>
</pre>
</div>
<p>The most complex of these is the <tt><font size=
"+1">dispose</font></tt> function that must ensure that the correct type
is destructed and also that the memory is collected from the correct
offset. It uses the value and type of first argument to perform this
correctly, and the second argument merely acts as a strategy selector,
i.e. the use of <tt><font size="+1">const void *</font></tt>
distinguishes it from the earlier dispose shown for <tt><font size=
"+1">const countability *</font></tt>.</p>
</div>
<hr width="100%">
<h2>Getting smarter</h2>
<div style="margin-left: 2em">
<p>Now that we have a way of adding countability at creation for objects
of any type, what extra is needed to make this work with the
<tt><font size="+1">countable_ptr</font></tt> we defined earlier? Good
news: nothing!</p>
<div style="margin-left: 2em">
<pre>
<tt>class example
{
...
};
void simple()
{
countable_ptr&lt;example&gt; ptr(new(countable) example);
countable_ptr&lt;example&gt; qtr(ptr);
ptr.clear(); // set ptr to point to null
} // allocated object deleted when qtr destructs
</tt>
</pre>
</div>
<p>The <tt><font size="+1">new(countable)</font></tt> expression defines a
different policy for allocation and deallocation and, in common with other
allocators, any attempt to mix your allocation policies, e.g. call
<tt><font size="+1">delete</font></tt> on an object allocated with
<tt><font size="+1">new(countable)</font></tt>, results in undefined
behaviour. This is similar to what happens when you mix <tt><font size=
"+1">new[]</font></tt> with <tt><font size="+1">delete</font></tt> or
<tt><font size="+1">malloc</font></tt> with <tt><font size=
"+1">delete</font></tt>. The whole point of <i>Countable</i> conformance
is that <i>Countable</i> objects are used with <tt><font size=
"+1">countable_ptr</font></tt>, and this ensures the correct use.</p>
<p>However, accidents will happen, and inevitably you may forget to
allocate using <tt><font size="+1">new(countable)</font></tt> and instead
use <tt><font size="+1">new</font></tt>. This error and others can be
detected in most cases by extending the code shown here to add a check
member to the <tt><font size="+1">count</font></tt>, validating the check
on every access. A benefit of ensuring clear separation between header and
implementation source files means that you can introduce a checking
version of this allocator without having to recompile your code.</p>
</div>
<hr width="100%">
<h2>Conclusion</h2>
<div style="margin-left: 2em">
<p>There are two key concepts that this article has introduced:</p>
<ul>
<li>The use of a generic requirements based approach to simplify and
adapt the use of the C<font size="-1">OUNTED</font> B<font size=
"-1">ODY</font> pattern.</li>
<li>The ability, through control of allocation, to dynamically and
non-intrusively add capabilities to fixed types using the R<font size=
"-1">UNTIME</font> M<font size="-1">IXIN</font> pattern.</li>
</ul>
<p>The application of the two together gives rise to a new variant of the
essential C<font size="-1">OUNTED</font> B<font size="-1">ODY</font>
pattern, U<font size="-1">NINTRUSIVE</font> C<font size=
"-1">OUNTED</font> B<font size="-1">ODY</font>. You can take this theme
even further and contrive a simple garbage collection system for C++.</p>
<p>The complete code for <tt><font size="+1">countable_ptr</font></tt>,
<tt><font size="+1">countability</font></tt>, and the <tt><font size=
"+1">countable new</font></tt> is also available.</p>
</div>
<div align="right">
<hr width="100%">
<font size="-1"><i>First published in</i> <a href=
"http://www.accu.org/c++sig/public/Overload.html">Overload</a> <i>25,
April 1998, ISSN 1354-3172</i></font>
</div>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 1998-1999 Kevlin Henney</i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

125
cpp_committee_meetings.html
View File

@ -1,125 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>C++ Committee Meetings</title>
</head>
<body bgcolor="#FFFFFF">
<h1>C++ Committee Meeting FAQ for Boost Members</h1>
<p><b>Who can attend C++ Committee meetings?</b> Members of
J16 (the INCITS/ANSI committee) or of a WG21 (ISO) member country committee
(&quot;national body&quot; in
ISO-speak). <a href="http://www.ncits.org/">
INCITS</a> has broadened&nbsp; J16 membership requirements so anyone can
join, regardless of nationality or employer.</p>
<p>In addition, a small number of &quot;technical experts&quot; who are not committee
members can also attend meetings. The &quot;technical expert&quot; umbrella is broad enough to cover
the
Boost members who attend meetings.</p>
<p><b>When and where is the next meeting?</b> There are two meetings a year. The
Fall meeting is usually in North America, and the Spring meeting is usually
outside North America. See a general
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/meetings">list of meeting locations and
dates</a>. Detailed information about a particular meeting, including hotel
information, is usually provided in a paper appearing in one of
<a href="#Mailing">mailings</a> for the prior meeting. If there isn't a link to
it on the <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/meetings">
Meetings</a> web page, you will have to go to
the committee's <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/">
Papers</a> page and search a bit.</p>
<p><b>Is there a fee for attending meetings?</b> No, but there can be a lot of
incidental expenses like travel, lodging, and meals, and there is a $US 800 a
year INCITS fee to become a voting member.</p>
<p><b>What is the schedule?</b>&nbsp; The meetings start at 9:00AM on
Monday, and 8:30AM other days, unless otherwise announced. It is best to arrive
a half-hour early to grab a good seat, some coffee, tea, or donuts, and to say
hello to people. (There is also a Sunday evening a WG21 administrative meeting,
which is closed except to delegates from national bodies.)</p>
<p>The meetings generally end on Friday, although there is discussion of
extending them one extra day until the next standard ships. The last day the meeting&nbsp; is generally over by 11:00AM. Because
the last day's meeting is for formal votes only, it is primarily of interest only to
actual committee
members.</p>
<p>Sometimes there are evening technical sessions; the details aren't
usually available until the Monday morning meeting.&nbsp; There may be a
reception one evening, and, yes, significant others are
invited. Again, details usually&nbsp;become available Monday morning.</p>
<p><b>What actually happens at the meetings?</b> Monday morning an hour or two
is spent in full committee on administrivia, and then the committee breaks up
into working groups (Core, Library, and Enhancements). The full committee also
gets together later in the week to hear working group progress reports.</p>
<p>The working groups are where most technical activities take place.&nbsp; Each
active issue that appears on an issues list is discussed, as are papers from the
mailing. Most issues are non-controversial and disposed of in a few minutes.
Technical discussions are often led by long-term committee members, often
referring to past decisions or longstanding working group practice. Sometimes a
controversy erupts. It takes first-time attendees awhile to understand the
discussions and how decisions are actually made. The working group chairperson
moderates.</p>
<p>Sometimes straw polls are taken. In a straw poll anyone attending can vote,
in contrast to the formal votes taken by the full committee, where only voting
members can vote.</p>
<p>Lunch break is an hour and a half.&nbsp; Informal subgroups often lunch
together; a lot of technical problems are discussed or actually solved at lunch,
or later at dinner. In many ways these discussions involving only a few people
are the most interesting. Sometimes during the regular meetings, a working group
chair will break off a sub-group to tackle a difficult problem. </p>
<p><b>Do I have to stay at the main hotel?</b> No, and committee members on
tight budgets often stay at other, cheaper, hotels. (The main hotels are usually
chosen because they have large meeting rooms available, and thus tend to be pricey.)
The advantage of staying at the main hotel is that it is then easier to
participate in the off-line discussions which can be at least as interesting
as what actually happens in the scheduled meetings.</p>
<p><b>What do people wear at meetings?</b>&nbsp; Programmer casual. No neckties
to be seen. </p>
<p><b>What should I bring to a meeting?</b> It is almost essential to have a
laptop computer along. There is a committee LAN with a wiki and Internet connectivity.
Wireless connectivity has become the norm, although there is usually a wired hub
or two for those needed wired access.</p>
<p><b>What should I do to prepare for a meeting?</b> It is helpful to have
downloaded the mailing or individual papers for the
meeting, and read any papers you are interested in. Familiarize yourself with
the issues lists if you haven't done so already. Decide which of the working
groups you want to attend.</p>
<p><b>What is a &quot;<a name="Paper">Paper</a>&quot;?</b> An electronic document containing issues,
proposals, or anything else the committee is interested in. Very little gets
discussed at a meeting, much less acted upon, unless it is presented in a paper.&nbsp;
<a href="http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/">Papers are available</a>
to anyone. Papers don't just appear randomly; they become available four (lately
six) times a
year, before and after each meeting. Committee members often refer to a paper by
saying what mailing it was in: &quot;See the pre-Redmond mailing.&quot;</p>
<p><b>What is a &quot;<a name="Mailing">Mailing</a>&quot;?</b> A mailing is the
set of papers prepared four to six times a year before and after each meeting,
or between meetings.&nbsp; It
is physically just a
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/mailings/">.zip or .gz</a>
archive of
all the papers for a meeting. Although the mailing's archive file itself is only available to committee members and technical
experts, the contents (except copies of the standard) are available to the
general public as individual papers. The ways of ISO are
inscrutable.</p>
<p><b>What is a &quot;Reflector&quot;?</b> The committee's mailing lists are
called &quot;reflectors&quot;. There are a number of them; &quot;all&quot;, &quot;core&quot;, &quot;lib&quot;, and &quot;ext&quot;
are the main ones. As a courtesy, Boost technical experts can be added to
committee reflectors at the request of a committee member. </p>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%B %d, %Y" startspan -->April 17, 2005<!--webbot bot="Timestamp" endspan i-checksum="17669" --></p>
<p>© Copyright Beman Dawes, 2002</p>
<p>
Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

BIN
css_0/boost_bullet.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 820 B

241
css_0/common.css
View File

@ -1,241 +0,0 @@
/*
Copyright 2004-2005 Redshift Software, Inc.
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
*/
/* The base font size. The first one is for IE, the second for everyone else. */
body {
font-size: smaller;
}
* > body {
font-size: 10pt;
}
/* Global defaults. */
* {
margin: 0;
padding: 0;
font-weight: normal;
font-size: 100%;
text-decoration: none;
}
body {
font-family: sans-serif;
color: #000000;
background-color: #CCCCCC;
}
/* Links, black with sharp slate blue underline in all states. */
a {
text-decoration: none;
color: #000000;
border-bottom: 1px solid #8AB4CA;
}
a:hover {
border-bottom: 1px solid #005090;
}
/* A generic class to clear this element. */
.clear {
clear: both;
width: 100%;
height: 1px;
overflow: hidden;
}
/* Enforce a minimum width. */
/* - For IE we can't really control this so we only make
sure the container doesn't look strange at small sizes by
making the body have enough whitespace. */
/* #content h1, #content h2, #content h3 {
white-space: nowrap;
} */
/* - New browsers have the easy way to set this. */
.body-0 {
min-width: 55em;
}
/* The shadow arrangement. */
.body-0 {
padding-left: 50px;
background: url(shadow-light-dark.png) repeat-y left;
}
.body-1 {
padding-right: 50px;
background: url(shadow-dark-light.png) repeat-y right;
}
.body-2 {
background-color: #FFFFFF;
}
/* */
#content {
padding: 1em;
}
/* Heading, title and logo. */
#heading {
background: #005080 url(heading-background.jpg) repeat bottom left;
border: 2px solid #FFFFFF;
position: relative;
}
#heading * {
color: #FFFFFF;
}
#heading h1 {
padding: 2em 0.25em 0.25em 0.75em;
float: left;
position: relative;
white-space: nowrap;
}
#heading h1 img {
border: none;
}
#heading #boost {
font-size: 250%;
font-weight: 900;
font-family: Impact, sans-serif;
}
#heading #cpplibraries {
font-size: 100%;
font-weight: 900;
padding-left: 0.75em;
}
#heading-quote {
white-space: nowrap;
margin: 0.75em 0.75em 0em -7em;
float: right;
clear: right;
position: relative;
text-align: right;
}
#heading-quote .quote {
font-size: 80%;
display: block;
}
#heading-quote .attribution {
font-size: 75%;
display: block;
}
#heading-quote a {
border-bottom: 1px solid #0080C0;
}
#heading-quote a:hover {
border-bottom: 1px solid #c8dae3;
}
/* Content sections, inside the top content section. */
.section {
padding-left: 28px;
margin-bottom: 3em;
}
.section-body p {
margin: 0em 0em 0.75em 0em;
}
.section-body h2 {
margin: 0em 0em 0.5em 0em;
padding: 0em 0em 0em 0em;
font-size: 140%;
clear: both;
}
.section-body h3 {
margin: 0em;
padding: 0em;
font-size: 120%;
clear: both;
}
.section-body h4 {
margin: 0.5em 0em 0.5em 0em;
font-size: 110%;
clear: both;
}
.section-body ul {
margin: 0em 0em 0.75em 0em;
padding: 0em 0em 0em 2em;
}
.section-body ul li {
margin: 0.75em 0em 0em 0em;
text-indent: -1.75em;
padding: 0em;
list-style-type: none;
}
.section-body ul li ul {
margin: 0.75em 0em 0em 0em;
padding: 0em;
}
.section-body ul li ul li {
display: block;
margin: 0em;
padding: 0em 0em 0em 1em;
list-style-type: none;
background: url(boost_bullet.gif) no-repeat 0em 0.5em;
text-indent: 0em;
}
.section-body blockquote {
margin: 0.5em 1em 0em 2em;
border-right: 1px dashed #CCCCCC;
border-left: 1px dashed #CCCCCC;
text-align: justify;
padding-right: 0.5em;
padding-left: 0.5em;
}
.section-body .left-inset {
float: left;
margin: 0em 1em 1em 0em;
}
.section-body .library {
display: block;
margin: 0em 0em 0.5em 0em;
}
.section-body .faq {
margin: 0em 0em 1em 0em;
}
.section-body .faq .faq-question {
color: #005080;
font-weight: bold;
}
.section-body .faq .faq-answer {
}
.section-body .note {
margin: 0em 0em 1em 0em;
}
.section-body .note .note-label {
color: #005080;
font-weight: bold;
}
.section-body .note .note-body {
}
.section-body table {
width: 90%;
margin-left: auto;
margin-right: auto;
border-spacing: 0.5em;
border: none;
}
.section-body table caption {
margin-left: auto;
margin-right: auto;
border-bottom: 1pt solid #000000;
padding: 0em 0em 0.2em 0em;
}
.section-body table tr th {
border: none;
border-bottom: 1pt solid #000000;
text-align: left;
vertical-align: bottom;
font-weight: bold;
padding: 0em 0em 0.2em 0em;
}
.section-body table tr td {
border: none;
text-align: left;
vertical-align: top;
padding: 0em 0em 0.2em 0em;
}
/* Section headings, all use the same stream op indicator style. */
#content h1, #content h2 {
padding-left: 24px;
background: url(section_head.png) no-repeat left center;
text-indent: 4px;
vertical-align: middle;
font-size: 140%;
position: relative;
left: -28px;
}
/* Uniformly color everything that's a heading */
#content h1, #content h2, #content h3, #content h4 {
color: #005080;
font-weight: bold;
}

91
css_0/csshover.htc
View File

@ -1,91 +0,0 @@
<attach event="ondocumentready" handler="parseStylesheets" />
<script language="JScript">
/**
* Pseudos - V1.30.050121 - hover & active
* ---------------------------------------------
* Peterned - http://www.xs4all.nl/~peterned/
* (c) 2005 - Peter Nederlof
*
* Credits - Arnoud Berendsen
* - Martin Reurings
* - Robert Hanson
*
* howto: body { behavior:url("csshover.htc"); }
* ---------------------------------------------
*/
var currentSheet, doc = window.document, activators = {
onhover:{on:'onmouseover', off:'onmouseout'},
onactive:{on:'onmousedown', off:'onmouseup'}
}
function parseStylesheets() {
var sheets = doc.styleSheets, l = sheets.length;
for(var i=0; i<l; i++)
parseStylesheet(sheets[i]);
}
function parseStylesheet(sheet) {
if(sheet.imports) {
try {
var imports = sheet.imports, l = imports.length;
for(var i=0; i<l; i++) parseStylesheet(sheet.imports[i]);
} catch(securityException){}
}
try {
var rules = (currentSheet = sheet).rules, l = rules.length;
for(var j=0; j<l; j++) parseCSSRule(rules[j]);
} catch(securityException){}
}
function parseCSSRule(rule) {
var select = rule.selectorText, style = rule.style.cssText;
if(!(/(^|\s)(([^a]([^ ]+)?)|(a([^#.][^ ]+)+)):(hover|active)/i).test(select) || !style) return;
var pseudo = select.replace(/[^:]+:([a-z-]+).*/i, 'on$1');
var newSelect = select.replace(/(\.([a-z0-9_-]+):[a-z]+)|(:[a-z]+)/gi, '.$2' + pseudo);
var className = (/\.([a-z0-9_-]*on(hover|active))/i).exec(newSelect)[1];
var affected = select.replace(/:hover.*$/, '');
var elements = getElementsBySelect(affected);
currentSheet.addRule(newSelect, style);
for(var i=0; i<elements.length; i++)
new HoverElement(elements[i], className, activators[pseudo]);
}
function HoverElement(node, className, events) {
if(!node.hovers) node.hovers = {};
if(node.hovers[className]) return;
node.hovers[className] = true;
node.attachEvent(events.on,
function() { node.className += ' ' + className; });
node.attachEvent(events.off,
function() { node.className =
node.className.replace(new RegExp('\\s+'+className, 'g'),''); });
}
function getElementsBySelect(rule) {
var parts, nodes = [doc];
parts = rule.split(' ');
for(var i=0; i<parts.length; i++) {
nodes = getSelectedNodes(parts[i], nodes);
}
return nodes;
}
function getSelectedNodes(select, elements) {
var result, node, nodes = [];
var classname = (/\.([a-z0-9_-]+)/i).exec(select);
var identify = (/\#([a-z0-9_-]+)/i).exec(select);
var tagName = select.replace(/(\.|\#|\:)[a-z0-9_-]+/i, '');
for(var i=0; i<elements.length; i++) {
result = tagName? elements[i].all.tags(tagName):elements[i].all;
for(var j=0; j<result.length; j++) {
node = result[j];
if((identify && node.id != identify[1]) || (classname && !(new RegExp('\\b' +
classname[1] + '\\b').exec(node.className)))) continue;
nodes[nodes.length] = node;
}
}
return nodes;
}
</script>

206
css_0/front.css
View File

@ -1,206 +0,0 @@
/*
Copyright 2004-2005 Redshift Software, Inc.
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
*/
@import url(common.css);
/* */
#news {
margin-bottom: 0em;
}
#content table {
border-spacing: 0em;
}
#sidebars-top {
vertical-align: top;
}
#sidebars-bottom {
vertical-align: bottom;
}
.sidebar {
width: 22em;
margin: 0em 0em 1em 1em
}
#content h1, #content h2 {
margin: 0em 0em 0.5em 0em;
}
/* The shadow and inner layout of the sidebars. */
.sidebar {
background: url(sidebar-shadow-bottom.png) no-repeat left bottom;
}
.sidebar-0 {
background: url(sidebar-shadow-right.png) no-repeat right top;
}
.sidebar-1 {
padding: 0px 8px 8px 0px;
background: url(sidebar-shadow-bottom-right.png) no-repeat right bottom;
}
.sidebar-2 {
border: 1px solid #c8dae3;
}
.sidebar-3 {
padding: 0em 0.5em 0.5em 0em;
}
/* Arrangement of the various side cells. */
#libraries, #search, #tests,
#groups, #contribute, #support,
#other, #official, #unofficial, #footer {
float: left;
}
#search,
#official,
#footer {
clear: left;
}
/* */
.sidecell {
width: 50%;
}
.sidecell-0 {
padding: 0.5em 0em 0em 0.5em;
font-size: 85%;
}
.sidecell h4 {
display: block; margin: 0em; padding: 0em;
border-bottom: 1px solid #8AB4CA;
}
.sidecell:hover h4 {
border-bottom-color: #005090;
}
.sidecell form {
display: block; margin: 0em; padding: 0em;
}
.sidecell ul {
display: block; margin: 0em; padding: 0em;
}
/* Lists in sidecells are menus. */
.sidecell ul a {
border: none;
padding-left: 14px;
}
.sidecell ul a:hover {
border: none;
background: url(menu_link_indicator.png) no-repeat left center;
}
.sidecell ul {
list-style-type: none;
}
.sidecell ul li {
margin: 0em; padding: 0em;
}
/* Search box */
#search {
width: 98.5%;
}
/* - The three parts of the search widget. */
#search #search-text {
display: block;
height: 1.8em;
margin: 0.25em 0em 0em 0em;
padding: 0em 48% 0em 0em;
}
#search #search-choice {
display: block;
height: 1.8em;
margin: -1.8em 0em 0em 55%;
padding: 0em 30px 0em 0em;
}
#search #go {
display: block;
height: 1.8em;
margin: -1.8em 0em 0em 55%;
text-align: right;
}
#search #search-text #q {
width: 100%;
margin: 0em; padding: 1px;
border: 1px solid #003399;
color: #000000;
background-color: #FFFFFF;
}
#search #search-choice #hq {
width: 100%;
margin: 0em; padding: 0em;
border: 1px solid #003399;
color: #000000;
background-color: #FFFFFF;
}
#search #go #search-button {
width: 26px; height: 20px;
margin: 0em; padding: 0em;
background-image: url(search-button.png);
}
/* - The custom Google banner and link. */
#search #google {
display: block;
clear: both;
margin: 0em 0em 0em 0em;
border: none;
text-align: center;
}
#search #google a {
font-size: 10px;
}
#search #google img {
width: 75px; height: 32px;
margin: 0em -20px 0em 0em;
border: none;
}
/* Footer with copyright and license. */
#footer-sidebar,
#footer-sidebar .sidebar-0, #footer-sidebar .sidebar-1,
#footer-sidebar .sidebar-2, #footer-sidebar .sidebar-3 {
background: #FFFFFF;
border: none;
}
#footer-sidebar {
padding: 3em 0em 0em 0em;
}
#footer {
width: 100%;
}
#footer p {
margin: 0em; padding: 0em;
text-align: left;
}
#footer #revised {
display: block;
border-bottom: 1px solid #8AB4CA;
}
#footer:hover #revised {
border-bottom-color: #005090;
}
#footer #revised p {
}
#footer #copyright {
display: block;
margin: 0.25em 0em 1em 14px;
}
#footer #copyright p {
margin: 0em;
padding: 0em 0em 0em 1.5em;
text-indent: -1.5em;
}
#footer #license {
display: block;
margin: 0.25em 0em 1em 14px;
}
#footer #license p {
margin: 0em;
padding: 0em 0em 0em 1.5em;
text-indent: -1.5em;
}
#footer #banners {
display: block;
margin: 0.25em 0em 0em 0em;
text-align: center;
}
#footer #banners p {
display: inline;
}
#footer #banners img {
border: none;
}
#footer #banners a {
border: none;
}

BIN
css_0/heading-background.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 20 KiB

70
css_0/inner.css
View File

@ -1,70 +0,0 @@
/*
Copyright 2004-2005 Redshift Software, Inc.
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
*/
@import url(common.css);
/* Heading quick pick menu. */
#heading ul {
float: right;
clear: right;
margin: 0.5em 1em 0em 0em;
padding: 0.25em 0em 0.25em 0em;
position: relative;
list-style-type: none;
white-space: nowrap;
}
#heading ul li {
display: inline;
margin: 0em; padding: 0em;
}
#heading ul li a {
margin: 0em;
padding: 0em 0.25em 0em 0.25em;
background-color: #005080;
border: 1px solid #0080C0;
}
#heading ul li a:hover {
border: 1px solid #c8dae3;
}
#heading h1 a {
color: #FFFFFF;
border: none;
}
#heading h1 a:hover {
border: none;
}
/* */
#history {
margin: 0em;
padding: 0em;
padding-left: 28px;
}
#content h1, #content h2 {
left: 0;
}
.section-body h3 {
margin: 1.5em 0em 0.5em 0em;
}
/* Footer with copyright and license. */
#footer {
background-color: #c8dae3;
border: 2px solid #FFFFFF;
color: #000000;
padding: 0.5em;
}
#footer p {
margin: 0em;
padding: 0em;
font-size: 80%;
margin: 0em;
padding: 0em 0.5em 0em 0.5em;
text-align: center;
}
#footer a {
color: #000000;
border-bottom: 1px solid #A0B0C0;
}
#footer a:hover {
border-bottom: 1px solid #0080C0;
}

BIN
css_0/menu_link_indicator.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 334 B

BIN
css_0/search-button.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.0 KiB

BIN
css_0/section_head.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 609 B

BIN
css_0/shadow-dark-light.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 160 B

BIN
css_0/shadow-light-dark.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 162 B

BIN
css_0/sidebar-shadow-bottom-right.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 208 B

BIN
css_0/sidebar-shadow-bottom.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 249 B

BIN
css_0/sidebar-shadow-right.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 261 B

112
cvs.html
View File

@ -1,112 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Boost CVS Repository</title>
<meta content="HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org"
name="generator">
<meta content="Microsoft FrontPage 5.0" name="generator">
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<link href="../boost.css" type="text/css" rel="stylesheet">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<table cellspacing="0" cellpadding="0" width="100%" summary="" border="0">
<tr valign="top">
<td valign="top" align="left"><img height="86" alt=
"boost.png (6897 bytes)" src="../boost.png" width="277"></td>
<td valign="top" align="right">
<table cellspacing="0" cellpadding="2" summary="" border="1">
<tr>
<td>
<table cellspacing="0" cellpadding="2" summary="" border="0">
<tr>
<td bgcolor="#DDDDDD">
<p>.&nbsp;<a href="../index.htm">Home</a><br>
.&nbsp;<a href="../libs/libraries.htm">Libraries</a><br>
.&nbsp;<a href="../people/people.htm">People</a><br>
.&nbsp;<a href="faq.htm">FAQ</a><br>
.&nbsp;<a href="index.htm">More</a></p>
</td>
</tr>
</table>
</td>
</tr>
</table>
</td>
</tr>
</table>
<h1><a id="CVS" name="CVS">Boost's CVS Repository</a></h1>
<p>All Boost files, including the entire distribution tree including web
site HTML is maintained in a CVS repository. Command line, GUI, or browser
access is available.</p>
<h2>Boost CVS access via command line or graphical clients</h2>For those
who have CVS clients installed, the libraries are also available from the
public <a href="http://sourceforge.net/cvs/?group_id=7586">Boost CVS
repository</a>. Free command line clients (often already installed on
Linux/Unix systems) are available for many systems, and free GUI clients
are available for Windows, Mac, and other systems.
<p>See the much improved <a href=
"http://sourceforge.net/docman/?group_id=1">CVS documentation</a> (Section
F) from SourceForge, which includes links to the home pages for various GUI
and command line clients.</p>
<p>The general procedure for command-line clients is something like
this:</p>
<blockquote>
<code>cvs -d:pserver:anonymous@boost.cvs.sourceforge.net:/cvsroot/boost
login</code><br>
[Hit &lt;return&gt; when it asks for a password]<br>
<code>cvs -z3 -d:pserver:anonymous@boost.cvs.sourceforge.net:/cvsroot/boost
checkout boost</code><br>
<code>cvs -d:pserver:anonymous@boost.cvs.sourceforge.net:/cvsroot/boost
logout</code>
</blockquote>Read the manual for your CVS client for further information.
<p>This access is read-only; if you are a library author and wish to have
CVS write access, please contact one of the <a href=
"moderators.html">moderators</a>.</p>
<h2>Boost CVS access via web <a id="Browser" name=
"Browser">Browser</a></h2>For access to the CVS archive from any modern web
browser, you can also use the <a href=
"http://boost.cvs.sourceforge.net/boost/boost/">web
browser&nbsp; interface</a>.&nbsp; Try one of the color diffs to see how a
file has changed over time. <b>Note:</b> this interface is only suitable
for viewing individual files and their revision histories.
<h2><a id="generated" name="generated">Documentation</a> generated from
BoostBook in CVS</h2>
<p>Some of the Boost documentation is generated from <a href=
"../doc/html/boostbook.html">BoostBook XML</a> source stored in the CVS
repository, and will not appear directly in the CVS tree as readable HTML.
View a nightly build of the generated HTML on the <a href=
"http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/libraries.html">
Nightly Generated Documentation</a> page. Where generated HTML is missing
from the CVS tree, an attempt has been made to include redirection to this
nightly build, but if you are away from an internet connection you may want
to download the generated documentation archive from the aforementioned
page so you can browse those documents offline.</p>
<hr>
<p>Revised $Date$</p>
<p>Copyright &copy; Rene Rivera 2003.<br>
Copyright &copy; Jens Maurer 2001.<br>
Copyright &copy; John Maddock 2004.</p>
<p><small>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</small></p>
</body>
</html>

370
discussion_policy.htm
View File

@ -1,370 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Microsoft FrontPage 6.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Boost Discussion Policy</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2" summary="">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt=
"boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color=
"#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color=
"#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color=
"#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color=
"#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color=
"#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Boost Discussion Policy</h1>
<p>Email discussion is the tie that binds boost members together into a
community. If the discussion is stimulating and effective, the community
thrives. If the discussion degenerates into name calling and ill will, the
community withers and dies.</p>
<h2>Contents</h2>
<dl>
<dt><a href="#acceptable">Acceptable Topics</a></dt>
<dt><a href="#unacceptable">Unacceptable Topics</a></dt>
<dt><a href="#effective">Effective Posting</a></dt>
<dt><a href="#behavior">Prohibited Behavior</a></dt>
<dt><a href="#culture">Culture</a></dt>
<dt><a href="#lib_names">Library Names</a></dt>
</dl>
<h2><a name="acceptable" id="acceptable"></a>Acceptable topics</h2>
<ul>
<li>Queries to determine interest in a possible library submission.</li>
<li>Technical discussions about a proposed or existing library, including
bug reports and requests for help.</li>
<li>Formal Reviews of proposed libraries.</li>
<li>Reports of user experiences with Boost libraries.</li>
<li>Boost administration or policies.</li>
<li>Compiler specific workarounds as applied to Boost libraries.</li>
</ul>
<p>Other topics related to boost development may be acceptable, at the
discretion of moderators. If unsure, go ahead and post. The moderators will
let you know.</p>
<h2><a name="unacceptable" id="unacceptable"></a>Unacceptable Topics</h2>
<ul>
<li>Advertisements for commercial products.</li>
<li>Requests for help getting non-boost code to compile with your
compiler. Try the comp.lang.c++.moderated newsgroup instead.</li>
<li>Requests for help interpreting the C++ standard. Try the comp.std.c++
newsgroup instead.</li>
<li>Job offers.</li>
<li>Requests for solutions to homework assignments.</li>
</ul>
<h2><a name="effective" id="effective"></a>Effective Posting</h2>
<p>Most Boost mailing lists host a great deal of traffic, so your post is
usually competing for attention with many other communications. This
section describes how to make sure it has the desired impact.</p>
<h3>Well-Crafted Posting is Worth the Effort</h3>
<p>Don't forget, you're a single writer but there are many readers, and you
want them to stay interested in what you're saying. Saving your readers a
little time and effort is usually worth the extra time you spend when
writing a message. Also, boost discussions are saved for posterity, as
rationales and history of the work we do. A post's usefulness in the future
is determined by its readability.</p>
<h3>Put the Library Name in the Subject Line</h3>
<p>When your post is related to a particular Boost library, it's helpful to
put the library name in square brackets at the beginning of the subject
line, e.g.</p>
<blockquote>
Subject: [Regex] Why doesn't this pattern match?
</blockquote>The Boost developers' list is a high-volume mailing list, and
most maintainers don't have time to read every message. A tag on the
subject line will help ensure the right people see your post.
<p><a name="tabs" id="tabs"></a></p>
<h3>Don't Use Tabs</h3>If you use tabs to indent your source code, convert
them to spaces before inserting the code in a posting. Something in the
processing chain usually strips all the indentation and leaves a mess
behind.
<p><a name="longlines" id="longlines"></a></p>
<h3>Limit Line Length</h3>If you put source code in your postings and your
mailer wraps long lines automatically, either keep the code narrow or
insert the code as an (inline, if possible) attachment. That will help
ensure others can read what you've posted.
<p><a name="quoting" id="quoting"></a></p>
<h3>Don't Overquote</h3>Please <b>prune extraneous quoted text</b> from
replies so that only the relevant parts are included. Some people have to
pay for, or wait for, each byte that they download from the list. More
importantly, it will save time and make your post more valuable when
readers do not have to find out which exact part of a previous message you
are responding to.
<h3>Use a Readable Quotation Style</h3>
<p>A common and very useful approach is to cite the small fractions of the
message you are actually responding to and to put your response directly
beneath each citation, with a blank line separating them for
readability:</p>
<blockquote>
<pre>
<i>Person-you're-replying-to</i> wrote:
&gt; Some part of a paragraph that you wish to reply to goes
&gt; here; there may be several lines.
Your response to that part of the message goes here. There may,
of course, be several lines.
&gt; The second part of the paragraph that is relevant to your
&gt; reply goes here; agiain there may be several lines.
Your response to the second part of the message goes here.
...
</pre>
</blockquote>For more information about effective use of quotation in
posts, see <a href="http://www.netmeister.org/news/learn2quote.html">this
helpful guide</a>.
<h3>Keep the Formatting of Quotations Consistent</h3>
<p>Some email and news clients use poor word wrapping algorithms that leave
successive lines from the same quotation with differing numbers of leading
"<tt>&gt;</tt>" characters. <b>Microsoft Outlook</b> and <b>Outlook
Express</b>, and some web clients, are especially bad about this. If your
client offends in this way, please take the effort to clean up the mess it
makes in quoted text. Remember, even if you didn't write the original text,
it's <i>your</i> posting; whether you get your point across depends on its
readability.</p>
<p>The Microsoft clients also create an unusually verbose header at the
beginning of the original message text and leave the cursor at the
beginning of the message, which encourages users to write their replies
before all of the quoted text rather than putting the reply in context.
Fortunately, Dominic Jain has written a utility that fixes all of these
problems automatically: <a href=
"http://home.in.tum.de/~jain/software/outlook-quotefix/">Outlook
Quotefix</a> for Outlook Users and <a href=
"http://home.in.tum.de/~jain/software/oe-quotefix/">OE QuoteFix</a> for
users of Outlook Express.</p>
<h3>Summarizing and Referring to Earlier Messages</h3>
<p>A summary of the foregoing thread is only needed after a long
discussion, especially when the topic is drifting or a result has been
achieved in a discussion. The mail system will do the tracking that is
needed to enable mail readers to display message threads (and every decent
mail reader supports that).</p>
<p>If you ever have to refer to single message earlier in a thread or in a
different thread then you can use a URL to the <a href=
"mailing_lists.htm#archive">message archives</a>. To help to keep those
URLs short, you can use <a href="http://www.tinyurl.com">tinyurl.com</a>.
Citing the relevant portion of a message you link to is often helpful (if
the citation is small).</p>
<h3>Maintain the Integrity of Discussion Threads</h3>
<p><b>When starting a new topic, always send a fresh message</b>, rather
than beginning a reply to some other message and replacing the subject and
body. Many mailers are able to detect the thread you started with and will
show the new message as part of the original thread, which probably isn't
what you intended. Follow this guideline for your own sake as well as for
others'. Often, people scanning for relevant messages will decide they're
done with a topic and hide or kill the entire thread: your message will be
missed, and you won't get the response you're looking for.</p>
<p>By the same token, <b>When replying to an existing message, use your
mailer's "Reply" function</b>, so that the reply shows up as part of the
same discussion thread.</p>
<p><b>Do not reply to digests</b> if you are a digest delivery subscriber.
Your reply will not be properly threaded and will probably have the wrong
subject line. Instead, you can reply through the <a href=
"http://news.gmane.org/gmane.comp.lib.boost.devel">GMane web
interface</a>.</p>
<h3>Keep The Size of Your Posting Manageable</h3>
<p>The mailing list software automatically limits message and attachment
size to a reasonable amount, typically 75K, which is adjusted from
time-to-time by the moderators. This limit is a courtesy to those who rely
on dial-up Internet access.</p>
<h2><a name="behavior" id="behavior"></a>Prohibited Behavior</h2>
<p>Prohibited behavior will not be tolerated. The moderators will ban
postings by abusers.</p>
<h3>Flame wars</h3>
<p>Personal insults, argument for the sake of argument, and all the other
behaviors which fall into the "flame war" category are prohibited.
Discussions should focus on technical arguments, not the personality traits
or motives of participants.</p>
<h3>Third-party attacks</h3>
<p>Attacks on third parties such as software vendors, hardware vendors, or
any other organizations, are prohibited. Boost exists to unite and serve
the entire C++ community, not to disparage the work of others.</p>
<p>Does this mean that we ban the occasional complaint or wry remark about
a troublesome compiler? No, but be wary of overdoing it.</p>
<h3>Off-topic posts</h3>
<p>Discussions which stray from the acceptable topics are strongly
discouraged. While off-topic posts are often well meaning and not as
individually corrosive as other abuses, cumulatively the distraction
damages the effectiveness of discussion.</p>
<h2><a name="culture" id="culture"></a>Culture</h2>
<p>In addition to technical skills, Boost members value collaboration,
acknowledgement of the help of others, and a certain level of politeness.
Boost membership is very international, and ranges widely in age and other
characteristics. Think of discussion as occurring among colleagues in a
widely read forum, rather than among a few close friends.</p>
<p>Always remember that the cumulative effort spent by people reading your
contribution scales with the (already large) number of boost members. Thus,
do invest time and effort to make your message as readable as possible.
Adhere to English syntax and grammar rules such as proper capitalization.
Avoid copious informalism, colloquial language, or abbreviations, they may
not be understood by all readers. Re-read your message before submitting
it.</p>
<h2>Guidelines for Effective Discussions</h2>
<p>Apply social engineering to prevent heated technical discussion from
degenerating into a shouting match, and to actively encourage the
cooperation upon which Boost depends.</p>
<ul>
<li>Questions help. If someone suggests something that you don't think
will work, then replying with a question like "will that compile?" or
"won't that fail to compile, or am I missing something?" is a lot
smoother than "That's really stupid - it won't compile."&nbsp; Saying
"that fails to compile for me, and seems to violate section n.n.n of the
standard" would be yet another way to be firm without being
abrasive.</li>
<li>If most of the discussion has been code-free generalities, posting a
bit of sample code can focus people on the practical issues.</li>
<li>If most of the discussion has been in terms of specific code, try to
talk a bit about hidden assumptions and generalities that may be
preventing discussion closure.</li>
<li>Taking a time-out is often effective. Just say: "Let me think about
that for a day or two. Let's take a time-out to digest the discussion so
far."</li>
</ul>
<p>Avoid <i><b>Parkinson's Bicycle Shed</b></i>. Parkinson described a
committee formed to oversee design of an early nuclear power plant. There
were three agenda items - when to have tea, where to put the bicycle shed,
and how to ensure nuclear safety. Tea was disposed of quickly as
trivial.&nbsp;Nuclear safety was discussed for only an hour - it was so
complex, scary, and technical that even among experts few felt comfortable
with the issues. Endless days were then spent discussing construction of
the bicycle shed (the parking lot would be the modern equivalent) because
everyone though they understood the issues and felt comfortable discussing
them.&nbsp;</p>
<h2><a name="lib_names" id="lib_names"></a>Library Names</h2>
<p>In order to ensure a uniform presentation in books and articles, we have
adopted a convention for referring to Boost libraries. Library names can
either be written in a compact form with a dot, as "Boost.<i>Name</i>", or
in a long form as "the Boost <i>Name</i> library." For example:</p>
<blockquote>
<b>Boost.Python</b> serves a very different purpose from <b>the Boost
Graph library</b>.
</blockquote>Note that the word "library" is not part of the name, and as
such isn't capitalized.
<p>Please take care to avoid confusion in discussions between libraries
that have been accepted into Boost and those that have not. Acceptance as a
Boost library indicates that the code and design have passed through our
peer-review process; failing to make the distinction devalues the hard work
of library authors who've gone through that process. Here are some
suggested ways to describe potential Boost libraries:</p>
<ul>
<li>the proposed Boost <i>Name</i> library</li>
<li>the Boost.<i>Name</i> candidate</li>
<li>the <i>Name</i> library (probably the best choice where
applicable)</li>
</ul>
<p>Note that this policy only applies to discussions, not to the
documentation, directory structure, or even identifiers in the code of
potential Boost libraries.</p>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->04 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2000-2005 Beman Dawes, Rob Stewart, and David Abrahams</i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

240
error_handling.html
View File

@ -1,240 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<meta name="generator" content=
"HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org">
<meta http-equiv="Content-Type" content=
"text/html; charset=windows-1252">
<title>Error and Exception Handling</title>
</head>
<body>
<h1>Error and Exception Handling</h1>
<h2>References</h2>
<p>The following paper is a good introduction to some of the issues of
writing robust generic components:</p>
<blockquote>
<a href="generic_exception_safety.html">D. Abrahams: ``Exception Safety
in Generic Components''</a>, originally published in <a href=
"http://www.springer.de/cgi-bin/search_book.pl?isbn=3-540-41090-2">M.
Jazayeri, R. Loos, D. Musser (eds.): Generic Programming, Proc. of a
Dagstuhl Seminar, Lecture Notes on Computer Science. Volume. 1766</a>
</blockquote>
<h2>Guidelines</h2>
<h3>When should I use exceptions?</h3>
<p>The simple answer is: ``whenever the semantic and performance
characteristics of exceptions are appropriate.''</p>
<p>An oft-cited guideline is to ask yourself the question ``is this an
exceptional (or unexpected) situation?'' This guideline has an attractive
ring to it, but is usually a mistake. The problem is that one person's
``exceptional'' is another's ``expected'': when you really look at the
terms carefully, the distinction evaporates and you're left with no
guideline. After all, if you check for an error condition, then in some
sense you expect it to happen, or the check is wasted code.</p>
<p>A more appropriate question to ask is: ``do we want stack
unwinding here?'' Because actually handling an exception is likely
to be significantly slower than executing mainline code, you
should also ask: ``Can I afford stack unwinding here?'' For
example, a desktop application performing a long computation might
periodically check to see whether the user had pressed a cancel
button. Throwing an exception could allow the operation to be
cancelled gracefully. On the other hand, it would probably be
inappropriate to throw and <i>handle</i> exceptions in the inner
loop of this computation because that could have a significant
performance impact. The guideline mentioned above has a grain of
truth in it: in time critical code, throwing an exception
should <em>be</em> the exception, not the rule.</p>
<h3>How should I design my exception classes?</h3>
<ol>
<li><b>Derive your exception class
from <code>std::exception</code></b>. Except in *very* rare
circumstances where you can't afford the cost of a virtual
table,
<code>std::exception</code> makes a reasonable exception base class,
and when used universally, allows programmers to catch "everything"
without resorting to <code>catch(...)</code>. For more about
<code>catch(...)</code>, see below.
<li><b>Use <i>virtual</i> inheritance.</b> This insight is due
to Andrew Koenig. Using virtual inheritance from your
exception's base class(es) prevents ambiguity problems at the
catch-site in case someone throws an exception derived from
multiple bases which have a base class in common:
<pre>
#include &lt;iostream&gt;
struct my_exc1 : std::exception { char const* what() const throw(); };
struct my_exc2 : std::exception { char const* what() const throw(); };
struct your_exc3 : my_exc1, my_exc2 {};
int main()
{
try { throw your_exc3(); }
catch(std::exception const&amp; e) {}
catch(...) { std::cout &lt;&lt; &quot;whoops!&quot; &lt;&lt; std::endl; }
}
</pre>
The program above prints <code>&quot;whoops&quot;</code> because the
C++ runtime can't resolve which <code>exception</code> instance to
match in the first catch clause.
</li>
<li>
<b><i>Don't</i> embed a std::string object</b> or any other data
member or base class whose copy constructor could throw an exception.
That could lead directly to std::terminate() at the throw point.
Similarly, it's a bad idea to use a base or member whose ordinary
constructor(s) might throw, because, though not necessarily fatal to
your program, you may report a different exception than intended from
a <i>throw-expression</i> that includes construction such as:
<blockquote>
<pre>
throw some_exception();
</pre>
</blockquote>
<p>There are various ways to avoid copying string objects when
exceptions are copied, including embedding a fixed-length buffer in
the exception object, or managing strings via reference-counting.
However, consider the next point before pursuing either of these
approaches.</p>
</li>
<li><b>Format the <code>what()</code> message on demand</b>, if you
feel you really must format the message. Formatting an exception error
message is typically a memory-intensive operation that could
potentially throw an exception. This is an operation best delayed until
after stack unwinding has occurred, and presumably, released some
resources. It's a good idea in this case to protect your
<code>what()</code> function with a <code>catch(...)</code> block so
that you have a fallback in case the formatting code throws</li>
<li><b>Don't worry <i>too</i> much about the <code>what()</code>
message</b>. It's nice to have a message that a programmer stands a
chance of figuring out, but you're very unlikely to be able to compose
a relevant and <i>user</i>-comprehensible error message at the point an
exception is thrown. Certainly, internationalization is beyond the
scope of the exception class author. <a href=
"../people/peter_dimov.htm">Peter Dimov</a> makes an excellent argument
that the proper use of a <code>what()</code> string is to serve as a
key into a table of error message formatters. Now if only we could get
standardized <code>what()</code> strings for exceptions thrown by the
standard library...</li>
<li><b>Expose relevant information about the cause of the error</b> in
your exception class' public interface. A fixation on the
<code>what()</code> message is likely to mean that you neglect to
expose information someone might need in order to make a coherent
message for users. For example, if your exception reports a numeric
range error, it's important to have the actual numbers involved
available <i>as numbers</i> in the exception class' public interface
where error reporting code can do something intelligent with them. If
you only expose a textual representation of those numbers in the
<code>what()</code> string, you will make life very difficult for
programmers who need to do something more (e.g. subtraction) with them
than dumb output.</li>
<li><b>Make your exception class immune to double-destruction</b> if
possible. Unfortunately, several popular compilers occasionally cause
exception objects to be destroyed twice. If you can arrange for that to
be harmless (e.g. by zeroing deleted pointers) your code will be more
robust.</li>
</ol>
<h3>What About Programmer Errors?</h3>
<p>As a developer, if I have violated a precondition of a library I'm
using, I don't want stack unwinding. What I want is a core dump or the
equivalent - a way to inspect the state of the program at the exact point
where the problem was detected. That usually means <tt>assert()</tt> or
something like it.</p>
<p>Sometimes it is necessary to have resilient APIs which can stand up to
nearly any kind of client abuse, but there is usually a significant cost
to this approach. For example, it usually requires that each object used
by a client be tracked so that it can be checked for validity. If you
need that sort of protection, it can usually be provided as a layer on
top of a simpler API. Beware half-measures, though. An API which promises
resilience against some, but not all abuse is an invitation to disaster.
Clients will begin to rely on the protection and their expectations will
grow to cover unprotected parts of the interface.</p>
<p><b>Note for Windows developers</b>: unfortunately, the native
exception-handling used by most Windows compilers actually throws an
exception when you use <tt>assert()</tt>. Actually, this is true of other
programmer errors such as segmentation faults and divide-by-zero errors.
One problem with this is that if you use JIT (Just In Time) debugging,
there will be collateral exception-unwinding before the debugger comes up
because <code>catch(...)</code> will catch these not-really-C++
exceptions. Fortunately, there is a simple but little-known workaround,
which is to use the following incantation:</p>
<blockquote>
<pre>
extern "C" void straight_to_debugger(unsigned int, EXCEPTION_POINTERS*)
{
throw;
}
extern "C" void (*old_translator)(unsigned, EXCEPTION_POINTERS*)
= _set_se_translator(straight_to_debugger);
</pre>
</blockquote>
This technique doesn't work if the SEH is raised from within a catch
block (or a function called from within a catch block), but it still
eliminates the vast majority of JIT-masking problems.
<h3>How should I handle exceptions?</h3>
<p>Often the best way to deal with exceptions is to not handle them at
all. If you can let them pass through your code and allow destructors to
handle cleanup, your code will be cleaner.</p>
<h4>Avoid <code>catch(...)</code> when possible</h4>
Unfortunately, operating systems other than Windows also wind non-C++
"exceptions" (such as thread cancellation) into the C++ EH machinery, and
there is sometimes no workaround corresponding to the
<code>_set_se_translator</code> hack described above. The result is that
<code>catch(...)</code> can have the effect of making some unexpected
system notification at a point where recovery is impossible look just
like a C++ exception thrown from a reasonable place, invalidating the
usual safe assumptions that destructors and catch blocks have taken valid
steps to ensure program invariants during unwinding.
<p>I reluctantly concede this point to Hillel Y. Sims, after many
long debates in the newsgroups: until all OSes are "fixed", if
every exception were derived from <code>std::exception</code> and
everyone substituted
<code>catch(std::exception&amp;)</code> for <code>catch(...)</code>, the
world would be a better place.</p>
<p>Sometimes, <code>catch(...)</code>, is still the most appropriate
pattern, in spite of bad interactions with OS/platform design choices. If
you have no idea what kind of exception might be thrown and you really
<i>must</i> stop unwinding it's probably still your best bet. One obvious
place where this occurs is at language boundaries.</p>
<hr>
<p>&copy; Copyright David Abrahams 2001-2003. All rights reserved.</p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->
21 August, 2003<!--webbot bot="Timestamp" endspan i-checksum="34359" -->
</p>
</body>
</html>

178
faq.htm
View File

@ -1,178 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Boost FAQ</title>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF">
<img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home </big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries </big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People </big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ </big></font></a></td>
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More </big></font></a></td>
</tr>
</table>
<h1>Boost Frequently Asked Questions</h1>
<p><strong>How do I download the libraries?</strong>
&nbsp; See <a href="getting_started.html#Download">Download</a> instructions.</p>
<p><b>What support is available for the libraries?</b>&nbsp; The
<a href="mailing_lists.htm#users">Boost-Users mailing list</a> is a good start.</p>
<p><b>What do the Boost version numbers mean?&nbsp; </b>The scheme is x.y.z, where x is incremented only for massive changes, such as a reorganization of many libraries, y is incremented whenever a new library is added, and z is incremented for maintenance releases. y and z are reset to 0 if
the value to the left changes.&nbsp;<br>
<br>
<b>Is there any assurance libraries actually work as claimed?</b> No. The review
process will hopefully eliminate the most seriously flawed libraries, but a well
constructed library with hidden defects is likely to slip through. Encouraging ordinary
users to report their experience with a library is intended to address such concerns.&nbsp;
See the <a href="../status/compiler_status.html">Status</a> page for an
indication of how well a library works on specific platforms. </p>
<p>
<b>How can the Boost libraries be used successfully for important projects?&nbsp;
</b>Many of the Boost libraries are actively maintained and improved, so backward compatibility with prior version isn't always possible. Deal with this by freezing the version of the Boost libraries used by your project. Only upgrade at points in your project's life cycle where a bit of change will not cause problems. Individual bug fixes can always be obtained from the CVS repository. </p>
<p><b>How is a library accepted for posting on the site?</b>
See <a href="submission_process.htm">Library Submission Process</a></p>
<p><b>How does someone submit a Formal Review comment?</b>&nbsp; Send email to <a
href="mailto:boost@lists.boost.org">boost@lists.boost.org</a>.&nbsp; See the <a href="formal_review_process.htm">Formal
Review</a> page for more information. </p>
<p><strong>How does someone submit a library?</strong> See <a href="lib_guide.htm">Library
Guidelines</a></p>
<p><b>Are commercial libraries requiring a fee acceptable?</b> No. However, a library that
a commercial enterprise makes available without fee is acceptable. If the description of
the library makes a low-key plug for the supplier, that is acceptable as long as the
library delivers real value and isn't just a Trojan horse for the plug.</p>
<p><b>Are shareware libraries acceptable?</b> No. Only free libraries
will be accepted.</p>
<p><strong>Are open source license libraries acceptable?</strong>&nbsp; Some
are, many are not.
Open source licenses often require redistribution or availability of source code,
inclusion of license document with machine-executable redistribution, give the initial
developer rights to licensee modifications, or need a lawyer to understand.&nbsp; These
would be immediate disqualifications for many business, commercial, and consumer
applications. Boost aims to avoid subjecting users to hard-to-comply-with license
terms. See <a href="lib_guide.htm#License">License requirements</a>.<br>
<br>
This is subject to review for a particularly important piece of software, or as the
industry changes.</p>
<p><b>Must full source code be provided?</b> Yes, these are source code libraries.</p>
<p><b>What about documentation?</b> A very simple library might be accepted with only a
well commented header file. For more substantial libraries, some form of documentation is
certainly going to be expected.&nbsp; HTML is the preferred form.</p>
<p><b>Are platform specific libraries acceptable?</b> There is a preference for portable
libraries. Libraries will be accepted that have portable interfaces but require platform
specific implementations, as long as the author supplies implementations for a couple of
disparate major operating systems.</p>
<p><b>Must a library do useful work? </b>No. A library meant as a teaching example or
demonstration might not actually do any work.</p>
<p><b>Can an existing library be accepted by Boost?</b> Yes, although it would
have to be &quot;Boostified&quot; to meet the requirements.&nbsp; The Boost
Graph and Regex libraries are examples of libraries which began life elsewhere.</p>
<p><b>Who owns the libraries?</b> Presumably many authors will copyright their libraries.
Others authors may wish to place their libraries in the public domain. The Boost.org
policy is to only accept libraries with a clear copyright notice and meeting the
<a href="lib_guide.htm#License">License requirements</a>..&nbsp; It is up to
potential users to decide if the terms acceptable, and not to use
libraries with unacceptable copyrights or licenses.</p>
<p><b>Is there a formal relationship between Boost.org and the C++ Standards Committee?</b>
&nbsp;No, although there is a strong informal relationship in that many members
of the committee participate in Boost, and the people who started Boost were all
committee members.</p>
<p><b>Will the Boost.org libraries become part of the next C++ Standard?</b>&nbsp; Some
might, someday, but that is up to the standards committee.&nbsp; Committee
members who also participate in Boost will definitely be proposing at least some
Boost libraries for standardization.</p>
<p>Libraries which are &quot;existing practice&quot; are most likely to be
accepted by the C++ committee for future standardization. Having a library
accepted by Boost is
one way to establish existing practice.</p>
<p><b>Where does the name &quot;Boost&quot; come from?</b> Boost began with
Robert Klarer and I fantasizing about a new library effort over dinner at a C++
committee meeting in Sofia Antipolis, France, in 1998. Robert mentioned that Herb Sutter
was working on a spoof proposal for a new language named Booze, which was
supposed to be better than Java. Somehow that kicked off the idea of
&quot;Boost&quot; as a name. We'd probably had a couple of glasses of good
French wine at that point. It was just a working name, but no one ever came up
with a replacement. (Beman Dawes)</p>
<p><b>Is the web site a commercial business?</b> No. It is just some people getting together
as a kind of cyberspace civic association. If it ever needs to incorporate, it would be as
a
non-profit organization.</p>
<p><b>Is there any charge for submitting libraries or reviews to Boost.org?</b> No. Unlike
the standards committees, you don't have to pay to volunteer!</p>
<p><b>Will the site include material beyond libraries?</b> The main focus is on libraries,
but if people contribute occasional articles or other material to make the site more
interesting, that could be a nice fit.</p>
<p><b>Why isn't there a separate boost mailing list for my favorite
library?&nbsp;</b> One of the reasons for boost's success has been the cross-pollination of ideas between diverse library
projects and the occasional look into other threads by otherwise uninterested parties. The more people participate, the less they tend to be annoyed by
"noise".</p>
<p><b>How can I cope with the large volume of boost mailing list messages?</b>&nbsp;
One approach is to use the &quot;digest&quot; option; that cuts the email blizzard
down to several (long) messages per day, so you can glance over the subjects
summary at the top and quickly read what you think is important.&nbsp;The&nbsp; &quot;no
mail&quot; option turns off list email entirely.</p>
<p>Another approach is to follow the list traffic via an NTTP newsgroup reader.
See <a href="mailing_lists.htm#newsgroup">Mailing List</a> newsgroup
information.</p>
<p><b>Why do Boost headers have a .hpp suffix rather than .h or none at all?</b>
File extensions communicate the &quot;type&quot; of the file, both to humans and
to computer programs. The '.h' extension is used for C header files, and
therefore communicates the wrong thing about C++ header files. Using no
extension communicates nothing and forces inspection of file contents to
determine type. Using '.hpp' unambiguously identifies it as C++ header file, and
works well in actual practice. (Rainer Deyke)</p>
<p><b>What should I do if I spot a bug in the Boost code or documentation?</b>
See the suggestions on the <a href="bugs.htm">Bugs page</a>.</p>
<p><b>How can I request a new feature in a Boost Library? </b>See the
<a href="requesting_new_features.htm">Requesting New Features</a> page.</p>
<hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->23 June, 2005<!--webbot bot="Timestamp" i-checksum="19916" endspan --></p>
<p>© Copyright Beman Dawes 2001</p>
<p>
Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

BIN
favicon.ico
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 22 KiB

112
feature_model_diagrams.htm
View File

@ -1,112 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Feature Model Diagrams</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<p><img border="0" src="../boost.png" alt="Boost logo" width="277" height="86"></p>
<h1>Feature Model Diagrams in text and HTML</h1>
<p>By <a href="../people/beman_dawes.html">Beman Dawes</a></p>
<h2>Introduction</h2>
<p>In their seminal book, Generative Programming, Czarnecki and Eisenecker (<a href="#Generative%20Programming">C&amp;E</a>))
describe how to build feature models [C&amp;E 4.4] consisting of a feature
diagram plus semantic, rationale, and other attributes.&nbsp; Feature models are
then used to drive design cycles which eventually lead to manual or automatic
assembly of configurations.</p>
<p>Feature models provide a language to describe the library variability that is
often such an issue in boost.org discussions. The Whorf hypothesis that
&quot;Language shapes the way we think, and determines what we can think
about&quot; seems to apply.&nbsp; In discussion of library variability issues,
we have been crippled by lack of a good language. With feature models we now
have a language to carry on the dialog.</p>
<p>The graphical feature diagrams presented by C&amp;E are not in a suitable
form for the email discussions boost.org depends upon. The hierarchical nature
of feature diagrams can be represented by a simple text-based feature diagram
language.&nbsp; A feature model can also take advantage of the hyperlinks
inherent in HTML.</p>
<h2><a name="Grammar">Grammar</a></h2>
<p>The grammar for the feature diagram language is expressed in Extended
Bakus-Naur Form; ::= represents productions, [...] represents options, {...}
represents zero or more instances, and represents | alternatives.</p>
<blockquote>
<pre>feature-model ::= concept-name details { feature }</pre>
<pre>feature ::= feature-name [details]</pre>
<pre>details ::= &quot;(&quot; feature-list &quot;)&quot; // required features
| &quot;[&quot; feature-list &quot;]&quot; // optional features</pre>
<pre>feature-list ::= element { &quot;|&quot; element } // one only
| element { &quot;+&quot; element } // one or more
| element { &quot;,&quot; element } // all
// [a+b] equivalent to [a,b]</pre>
<pre>element ::= feature
| details</pre>
<pre>concept-name ::= name</pre>
<pre>feature-name ::= name</pre>
</blockquote>
<p>The usual lexical conventions apply. Names are case-insensitive and consist
of a leading letter, followed by letters, digits, underscores or hyphens, with
no spaces allowed.</p>
<p>At least one instance of each name should be hyperlinked to the corresponding
<a href="#FeatureDescriptions">Feature Description</a>.</p>
<p>While the grammar is intended for written communication between people, it
may also be trivially machine parsed for use by automatic tools.</p>
<h2><a id="FeatureDescriptions" name="FeatureDescriptions"></a></h2>
<p>Descriptive information is associated with each concept or feature. According
to [C&amp;E 4.4.2] this includes:</p>
<ul>
<li>Semantic descriptions.</li>
<li>Rationale.</li>
<li>Stakeholders and client programs.</li>
<li>Exemplar systems.</li>
<li>Constraints and default dependency rules.</li>
<li>Availability sites, binding sites, and binding mode.</li>
<li>Open/Closed attribute.</li>
</ul>
<h2>What is a Feature?</h2>
<p>A feature [C&amp;E 4.9.1] is &quot;anything users or client programs might
want to control about a concept.&nbsp; Thus, during feature modeling, we
document no only functional features ... but also implementation features, ...,
various optimizations, alternative implementation techniques, and so on.&quot;</p>
<h2>Example</h2>
<blockquote>
<pre>special-container ( organization,
performance,
interface ) // all required</pre>
<pre>organization [ ordered + indexed ] // zero or more (4 configurations)</pre>
<pre>indexed [ hash-function ] // zero or one (2 configurations)</pre>
<pre>performance ( fast | small | balanced ) // exactly one (3 configurations)</pre>
<pre>interface ( STL-style + cursor-style ) // one or more (3 configurations)</pre>
</blockquote>
<p>There should be feature descriptions for <code>some-container, organization,
ordered, indexed, hash-function, performance, fast, small, balanced, interface,
STL-style, and cursor-style</code>.</p>
<p>The number of possible configurations is&nbsp; (2 + 2*2) * 3 * 3 = 54,
assuming no constraints.</p>
<p>There are equivalent representations. For example:</p>
<blockquote>
<pre>special-container ( organization[ ordered+indexed[ hash-function ]],
performance( fast|small|balanced ),
interface( STL-style+cursor-style ) )</pre>
</blockquote>
<h2>References</h2>
<p>Krzysztof Czarnecki and Ulrich W. Eisenecker, <a href="http://www.generative-programming.org">Generative
Programming</a>, Addison-Wesley, 2000, ISBN 0-201-30977-7</p>
<hr>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->26 August 2004<!--webbot bot="Timestamp" endspan i-checksum="32277" --></p>
<p>© Copyright Beman Dawes, 2000</p>
<p>
Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

311
formal_review_process.htm
View File

@ -1,311 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta name="generator" content=
"Microsoft FrontPage 5.0">
<meta http-equiv="Content-Type" content=
"text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Boost Formal Review Process</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt=
"boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color=
"#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color=
"#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color=
"#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color=
"#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color=
"#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Boost Formal Review Process</h1>
<p><a href="#Introduction">Introduction</a><br>
<a href="#Comments">What to include in Review Comments</a><br>
<a href="#Results">Results</a><br>
<a href="#Review_Manager">Notes for Review Managers</a><br>
<a href="#Submitters">Notes for Library Submitters</a><br>
<a href="#Wizard">Review Wizard</a><br>
<a href="#Fast-Track">Fast Track Reviews</a></p>
<h2><a name="Introduction">Introduction</a></h2>
<p>Proposed libraries are accepted into Boost only after undergoing a
formal review, where Boost mailing list members comment on their
evaluation of the library.</p>
<p>The final "accept" or "reject" decision is made by the <a href=
"#Review_Manager">Review Manager</a>, based on the review comments
received from boost mailing list members.</p>
<p>Boost mailing list members are encouraged to submit Formal Review
comments:</p>
<blockquote>
<ul>
<li>Publicly on the mailing list.</li>
<li>Privately to the Review Manager.</li>
</ul>
</blockquote>
<p>Private comments to a library submitter may be helpful to her or him,
but won't help the Review Manager reach a decision, so the other forms
are preferred.</p>
<h2>What to include in Review <a name="Comments">Comments</a></h2>
<p>Your comments may be brief or lengthy, but basically the Review
Manager needs your evaluation of the library.&nbsp; If you identify
problems along the way, please note if they are minor, serious, or
showstoppers.</p>
<p>The goal of a Boost library review is to improve the library through
constructive criticism, and at the end a decision must be made: is the
library good enough at this point to accept into Boost? If not, we hope to
have provided enough constructive criticism for it to be improved and
accepted at a later time. The Serialization library is a good example of how
constructive criticism resulted in revisions resulting in an excellent
library that was accepted in its second review.</p>
<p>Here are some questions you might want to answer in your review:</p>
<ul>
<li>What is your evaluation of the design?<br>
</li>
<li>What is your evaluation of the implementation?<br>
</li>
<li>What is your evaluation of the documentation?<br>
</li>
<li>What is your evaluation of the potential usefulness of the
library?<br>
</li>
<li>Did you try to use the library?&nbsp; With what compiler?&nbsp; Did
you have any problems?<br>
</li>
<li>How much effort did you put into your evaluation? A glance? A quick
reading? In-depth study?<br>
</li>
<li>Are you knowledgeable about the problem domain?</li>
</ul>
<p>And finally, every review should answer this question:<br>
</p>
<ul>
<li>Do you think the library should be accepted as a Boost
library?&nbsp; Be sure to say this explicitly so that your other
comments don't obscure your overall opinion.</li>
</ul>
<p>Many reviews include questions for library authors. Authors are
interested in defending their library against your criticisms; otherwise
they would not have brought their library up for review. If you don't get a
response to your question quickly, be patient; if it takes too long or you
don't get an answer you feel is sufficient, ask again or try to rephrase the
question. Do remember that English is not the native language for many
Boosters, and that can cause misunderstandings.<br>
<br>
E-mail is a poor communication medium, and even if messages rarely get lost
in transmission, they often get drowned in the deluge of other messages.
Don't assume that an unanswered message means you're being ignored. Given
constructively, criticism will be taken better and have more positive
effects, and you'll get the answers you want.</p>
<h2><a name="Results">Results</a></h2>
<p>At the conclusion of the comment period, the Review Manager will post
a message to the mailing list saying if the library has been accepted or
rejected.&nbsp; A rationale is also helpful, but its extent is up to the
Review Manager. If there are suggestions, or conditions that must be met
before final inclusion, they should be stated.</p>
<h2>Notes for <a name="Review_Manager">Review Manager</a>s</h2>
<p>Before a library can be scheduled for formal review, an active boost
member not connected with the library submission must volunteer to be the
"Review Manager" for the library.</p>
<p>The Review Manager:</p>
<ul>
<li>Checks the submission to make sure it really is complete enough to
warrant formal review.&nbsp; See the <a href="lib_guide.htm">Boost
Library Requirements and Guidelines</a>.&nbsp; If necessary, work with
the submitter to verify the code compiles and runs correctly on several
compilers and platforms.</li>
<li>Finalizes the schedule with the <a href="#Wizard">Review Wizard</a>
and the submitter .</li>
<li>
Posts a notice of the review schedule on the
regular <b><a href= "mailto:boost@lists.boost.org">boost</a></b>
mailing list,
the <b><a href="mailto:boost-users@lists.boost.org">boost-users</a></b>
mailing list, and the
<b><a href="mailto:boost-announce@lists.boost.org">boost-announce</a></b>
mailing list.
<ul>
<li>The notice should include a brief description of the library
and what it does, to let readers know if the library is one they
are interested in reviewing.</li>
<li>If the library is known to fail with certain compilers, please
mention them in the review notice so reviewers with those compilers
won't waste time diagnosing known problems.</li>
</ul>
</li>
<li>Inspects the Boost <a href="../libs/libraries.htm">library
catalogue</a> for libraries which may interact with the new submission.
These potential interactions should be pointed out in the review
announcement, and the author(s) of these libraries should be privately
notified and urged to participate in the review.</li>
<li>Urges people to do reviews if they aren't forthcoming.</li>
<li>Follows review discussions regarding the library, moderating or
answering questions as needed.</li>
<li>Asks the <a href="#Wizard">review wizard</a> for permission
to extend the review schedule if it appears that too few reviews will
be submitted during the review period.</li>
<li>Decides if there is consensus to accept the library, and if there
are any conditions attached.</li>
<li>
Posts a notice of the <a href="#Results">review results</a> on the
regular <b><a href= "mailto:boost@lists.boost.org">boost</a></b>
mailing list,
the <b><a href="mailto:boost-users@lists.boost.org">boost-users</a></b>
mailing list, and the
<b><a href="mailto:boost-announce@lists.boost.org">boost-announce</a></b>
mailing list.
</ul>
<p>In other words, it is the Review Manager's responsibility to make sure
the review process works smoothly.</p>
<h2>Notes for Library <a name="Submitters">Submitters</a></h2>
<p>See <a href="submission_process.htm">Submission Process</a> for a
description of the steps a library developer goes through to get a
library accepted by Boost.</p>
<p>A proposed library should remain stable during the review period; it
will just confuse and irritate reviewers if there are numerous
changes.&nbsp; It is, however, useful to upload fixes for serious bugs
right away, particularly those which prevent reviewers from fully
evaluating the library.&nbsp; Post a notice of such fixes on the mailing
list.</p>
<p>Library improvements suggested by reviewers should normally be held
until after the completion of review period.&nbsp; If the suggested
changes might affect reviewer's judgments,&nbsp;post a notice of the
pending change on the mailing list.</p>
<h2>Review <a name="Wizard">Wizard</a></h2>
<p>The Review Wizard coordinates the formal review schedule:</p>
<ul>
<li>Maintains a list of review manager volunteers, in the form of a
queue, so that volunteers who least recently managed reviews become the
prime candidates for upcoming reviews.</li>
<li>When a formal review is requested for a library:</li>
<li style="list-style: none">
&nbsp;<ul>
<li>Assign a review manager and suggests a schedule, after checking
(via private email) availability of the volunteers at the top of
review manager queue.</li>
<li>Finalize the schedule, once the review manager verifies the
library is actually ready for review.</li>
<li>Resolve schedule slips or other issues with review managers and
submitters.</li>
</ul>
</li>
<li>Maintains a schedule of both past and pending reviews, in the form
of the <a href="formal_review_schedule.html">Review Schedule</a> web
page.</li>
<li>Resolves questions from review managers and library submitters, who
sometimes want a third opinion on questions such as "Should we extend
the review period because ...?"</li>
<li>Monitors the general review process, and makes minor adjustments as
needed, or queries the list about possible major adjustments.</li>
</ul>
The role of Boost Review Wizard is currently played by John
Phillips (phillips at mps dot ohio-state dot edu) and Ronald
Garcia (garcia at cs dot indiana dot edu).
<h2><a name="Fast-Track">Fast Track Reviews</a></h2>
<p>To qualify for fast track review:</p>
<ul>
<li>The component must be small.</li>
<li>The technique must be already in use in Boost libraries and the new
component provides a common implementation.</li>
<li>A full Boost-conformant implementation is available in the sandbox.</li>
<li>The Review Wizard determines that the proposal qualifies for fast
track review.</li>
</ul>
<p>Procedure:</p>
<ul>
<li>The Boost Review Wizard posts a review announcement to the main Boost
developer's list. The review period will normally last for 5 days. No two
fast track reviews will run in parallel. Fast track reviews may run during
full reviews, though generally this is to be avoided.</li>
<li>After the review period ends, the submitter will post a review summary
containing proposed changes to the reviewed implementation.</li>
<li>The Review Wizard will accept or reject the proposed library and
proposed changes.</li>
<li>After applying the proposed changes, the component is checked into CVS
like any other library.<br>
&nbsp;</li>
</ul>
<hr>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->10 October, 2006<!--webbot bot="Timestamp" endspan i-checksum="38930" --></p>
<p>© Copyright Beman Dawes 2000</p>
<p>
Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

865
formal_review_schedule.html
View File

@ -1,865 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<title>Formal Review Schedule</title>
</head>
<body>
<table border="1" bgcolor="#007F7F" cellpadding="2" summary="Links">
<tr>
<td bgcolor="#FFFFFF">
<img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>
Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>
People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Formal Review Schedule</h1>
<p>Reviews are usually scheduled on a first-come-first-served basis, and
normally last ten days.&nbsp; See <a href="formal_review_process.htm">Formal
Review Process</a> for more information.</p>
<p>In addition to
upcoming reviews, the schedule includes recent reviews already completed; that helps
track review manager assignments and libraries reviewed but not yet posted on
the web site. There is often a lag between acceptance and site posting as
authors address issues raised in the formal review.</p>
<h2><a name="Schedule">Schedule</a></h2>
<table border="1" cellpadding="5" cellspacing="0" summary="Review Queue">
<tr>
<td valign="top"><b>Submission</b></td>
<td valign="top"><b>Submitter</b></td>
<td valign="top"><b>Link</b></td>
<td valign="top"><b>Review<br>
Manager</b></td>
<td valign="top"><b>Review<br>
Dates</b></td>
</tr>
<tr>
<td>Finite State Machines</td>
<td>Andrey Semashev</td>
<td><a href="http://tinyurl.com/yjozfn">
Boost Sandbox Vault</a></td>
<td>Martin Vuille</td>
<td>October 21, 2007 - October 30, 2007</td>
</tr>
<tr>
<td>Floating Point Utilities</td>
<td>Johan R&aring;de</td>
<td><a href="http://boost-consulting.com/vault/index.php?directory=Math%20-%20Numerics">
Boost Sandbox Vault</a></td>
<td>Needed</td>
<td>-</td>
</tr>
<tr>
<td>Switch</td>
<td>Steven Watanabe</td>
<td><a href="http://boost-consulting.com/vault/index.php?action=downloadfile&filename=mcs_units_v0.7.1.zip&directory=Units">
Boost Sandbox Vault</a> </td>
<td>Needed</td>
<td>-</td>
</tr>
<tr>
<td>Property Map (fast-track)</td>
<td>Andrew Sutton</td>
<td><a href="http://svn.boost.org/svn/boost/sandbox/graph-v2">
Boost Sandbox</a></td>
<td>Jeremy Siek</td>
<td>October 8, 2007 - October 12, 2007</td>
</tr>
<tr>
<td>Graph (fast-track)</td>
<td>Andrew Sutton</td>
<td><a href="http://svn.boost.org/svn/boost/sandbox/graph-v2">
Boost Sandbox</a></td>
<td>Jeremy Siek</td>
<td>October 15, 2007 - October 19, 2007</td>
</tr>
<tr>
<td>Forward (fast-track)</td>
<td>Tobias Schwinger</td>
<td><a href="http://boost-consulting.com/vault/index.php?&amp;direction=0&order=&directory=X-Files">
Boost Sandbox Vault</a></td>
<td>Needed</td>
<td>-</td>
</tr>
<tr>
<td>Singleton (fast-track)</td>
<td>Tobias Schwinger</td>
<td><a href="http://boost-consulting.com/vault/index.php?&amp;direction=0&order=&directory=X-Files">
Boost Sandbox Vault</a></td>
<td>Needed</td>
<td>-</td>
</tr>
<tr>
<td>Factory (fast-track)</td>
<td>Tobias Schwinger</td>
<td><a href="http://boost-consulting.com/vault/index.php?&amp;direction=0&order=&directory=X-Files">
Boost Sandbox Vault</a></td>
<td>Needed</td>
<td>-</td>
</tr>
<tr>
<td>Lexer</td>
<td>Ben Hanson</td>
<td><a href="http://boost-consulting.com/vault/index.php?action=downloadfile&filename=boost.lexer.zip&directory=Strings%20-%20Text%20Processing&">
Boost Sandbox Vault</a></td>
<td>Needed</td>
<td>-</td>
</tr>
<tr>
<td>Thread-Safe Signals</td>
<td>Frank Hess</td>
<td><a href="http://www.boost-consulting.com/vault/index.php?&direction=0&order=&directory=thread_safe_signals">
Boost Sandbox Vault</a></td>
<td>Needed</td>
<td>-</td>
</tr>
</table>
<h2>Past Review Results and Milestones</h2>
<table border="1" cellpadding="5" cellspacing="0"summary="Review Results">
<tr>
<td valign="top"><b>Submission</b></td>
<td valign="top"><b>Submitter</b></td>
<td valign="top"><b>Review<br>
Manager</b></td>
<td valign="top"><b>Review<br>
Dates</b></td>
<td valign="top"><b>Result</b></td>
</tr>
<tr>
<td>Exception</td>
<td>Emil Dotchevski</td>
<td>Tobias Schwinger</td>
<td>September 27, 2007 - October 7, 2007</td>
<td><a href="http://lists.boost.org/boost-announce/2007/09/0146.php">
Ongoing</a></td>
</tr>
<tr>
<td>Review Wizard Status Report</td>
<td></td>
<td>Ronald Garcia</td>
<td>2007 September 14</td>
<td><a href="report-sep-2007.html">Report</a></td>
</tr>
<tr>
<td>Scope Exit</td>
<td>Alexander Nasonov</td>
<td>Jody Hagins</td>
<td>August 13, 2007 - August 22, 2007-</td>
<td><a href="http://lists.boost.org/boost-announce/2007/08/0139.php">
Pending</a></td>
</tr>
<tr>
<td>Time Series</td>
<td>Eric Niebler</td>
<td>John R. Phillips</td>
<td>July 30, 2007 - August 13, 2007</td>
<td><a href="http://lists.boost.org/boost-announce/2007/08/0142.php">
Accepted</a></td>
</tr>
<tr>
<td>Boost 1.34.1 Released</td>
<td></td>
<td>Thomas Witt</td>
<td>July 24, 2007</td>
<td><a href="http://lists.boost.org/boost-announce/2007/07/0135.php">
Notes</a></td>
</tr>
<tr>
<td>Boost 1.34.0 Released</td>
<td></td>
<td>Thomas Witt</td>
<td>May 12, 2007</td>
<td><a href="http://lists.boost.org/boost-announce/2007/05/0131.php">
Notes</a></td>
</tr>
<tr>
<td>Globally Unique Identifier</td>
<td>Andy Tompkins</td>
<td>Hartmut Kaiser</td>
<td>April 30, 2007 - May 10, 2007</td>
<td><a href="http://lists.boost.org/boost-announce/2007/05/0134.php">
Accepted Provisionally</a></td>
</tr>
<tr>
<td>Math Toolkit</td>
<td>John Maddock</td>
<td>Matthias Schabel</td>
<td>April 11, 2007 - April 27, 2007</td>
<td><a href="http://lists.boost.org/boost-announce/2007/05/0129.php">
Accepted</a></td>
</tr>
<tr>
<td>Quantitative Units</td>
<td>Matthias Schabel</td>
<td>John R. Phillips</td>
<td>March 26, 2007 - April 4, 2007</td>
<td><a href="http://lists.boost.org/boost-announce/2007/04/0126.php">
Accepted</a></td>
</tr>
<tr>
<td>Intrusive Containers</td>
<td>Ion Gazta&ntilde;aga</td>
<td>Joaqu&iacute;n M&ordf; L&oacute;pez Mu&ntilde;oz</td>
<td>March 12, 2007 - March 21, 2007</td>
<td><a href="http://lists.boost.org/boost-announce/2007/04/0122.php">
Accepted -- Added to CVS</a></td>
</tr>
<tr>
<td>Bimap</td>
<td>Matias Capeletto</td>
<td>Ion Gazta&ntilde;aga</td>
<td>February 15 2007- March 2, 2007</td>
<td><a href="http://lists.boost.org/Archives/boost/2007/03/117351.php">
Accepted -- Added to CVS</a></td>
</tr>
<tr>
<td>Accumulators</td>
<td>Eric Niebler</td>
<td>John R. Phillips</td>
<td>January 29, 2007 - February 7, 2007</td>
<td><a href="http://lists.boost.org/boost-announce/2007/02/0114.php">
Accepted</a></td>
</tr>
<tr>
<td>Function Types (Re-review)</td>
<td>Tobias Schwinger</td>
<td>Tom Brinkman</td>
<td>2006 November 6 - 2006 November 17</td>
<td><a href="http://lists.boost.org/boost-announce/2006/11/0106.php">
Accepted -- Added to CVS</a></td>
</tr>
<tr>
<td>Generic Image Library</td>
<td>Lubomir Bourdev</td>
<td>Tom Brinkman</td>
<td>2006 October 5 - 2006 October 25</td>
<td><a href="http://lists.boost.org/Archives/boost/2006/11/112896.php">
Accepted -- Added to CVS</a></td>
</tr>
<tr>
<td>Message Passing</td>
<td>Doug Gregor</td>
<td>Jeremy Siek</td>
<td>2006 September 6 - 2006 September 15</td>
<td><a href="http://lists.boost.org/boost-announce/2006/09/0099.php">
Accepted -- Added to CVS</a></td>
</tr>
<tr>
<td>Physical Quantities System</td>
<td>Andy Little</td>
<td>Fred Bertsch</td>
<td>2006 May 31 - 2006 June 9</td>
<td><a href="http://lists.boost.org/boost-announce/2006/06/0096.php">
Rejected</a></td>
</tr>
<tr>
<td>Pimpl Pointer</td>
<td>Asger Mangaard</td>
<td>Rene Rivera</td>
<td>2006 May 15 - 2006 May 24</td>
<td><a href="http://lists.boost.org/boost-announce/2006/10/0104.php">
Rejected</a></td>
</tr>
<tr>
<td>Fusion</td>
<td>Joel de Guzman</td>
<td>Ronald Garcia</td>
<td>2006 May 1 - 2006 May 10</td>
<td><a href="http://lists.boost.org/boost-announce/2006/06/0094.php">
Accepted -- Added to CVS</a></td>
</tr>
<tr>
<td>Property Tree</td>
<td>Marcin Kalicinski</td>
<td>Thorsten Ottosen</td>
<td>2006 April 18 - 2006 April 30</td>
<td><a href="http://lists.boost.org/boost-announce/2006/05/0092.php">
Accepted -- Added to CVS</a></td>
</tr>
<tr>
<td>Promotion Traits (fast-track)</td>
<td>Alexander Nasonov</td>
<td>Tobias Schwinger</td>
<td>2006 April 1 - 2006 April 9</td>
<td><a href="http://lists.boost.org/boost-announce/2006/04/0086.php">
Accepted -- Added to CVS</a></td>
</tr>
<tr>
<td>Review Wizard Status Report</td>
<td></td>
<td>Tom Brinkman</td>
<td>2006 March 30</td>
<td><a href="report-apr-2006.html">Report</a></td>
</tr>
<tr>
<td>Shmem (now Interprocess)</td>
<td>Ion Gazta&ntilde;aga</td>
<td>Fred Bertsch</td>
<td>2006 February 6 - 2006 February 15</td>
<td><a
href="http://lists.boost.org/boost-announce/2006/02/0083.php">
Accepted -- Added to CVS</a></td>
</tr>
<tr>
<td>Fixed Strings</td>
<td>Reece Dunn</td>
<td>Harmut Kaiser</td>
<td>2006 January 19 - 2006 February 5</td>
<td><a href="http://lists.boost.org/boost-announce/2006/02/0081.php">
Rejected</a></td>
</tr>
<tr>
<td>Review Wizard Status Report</td>
<td></td>
<td>Ronald Garcia</td>
<td>2006 January 19</td>
<td><a href="report-jan-2006.html">Report</a></td>
</tr>
<tr>
<td>asio</td>
<td>Christopher Kohlhoff</td>
<td>Jeff Garland</td>
<td>2005 December 10 - <br>2005 December 30</td>
<td><a href="http://lists.boost.org/Archives/boost/2006/03/102287.php">
Accepted -- Added to CVS</a></td>
</tr>
<tr>
<td>Boost 1.33.1 Released</td>
<td></td>
<td>Doug Gregor</td>
<td>2005 December 5</td>
<td><a href="http://lists.boost.org/boost-announce/2005/12/0077.php">
Notes</a></td>
</tr>
<tr>
<td>Review Wizard Status Report</td>
<td></td>
<td>Ronald Garcia</td>
<td>2005 December 1</td>
<td><a href="http://lists.boost.org/boost-announce/2005/12/0076.php">
Report</a></td>
</tr>
<tr>
<td>Logging Library</td>
<td>John Torjo</td>
<td>Hartmut Kaiser</td>
<td>2005 November 7 - 2005 November 16th</td>
<td><a href="http://lists.boost.org/boost-announce/2005/11/0075.php">
Rejected</a></td>
</tr>
<tr>
<td>Boost 1.33.1 Beta Released</td>
<td></td>
<td>Doug Gregor</td>
<td>2005 November 9</td>
<td><a href="http://lists.boost.org/boost-announce/2005/11/0073.php">
Notes</a></td>
</tr>
<tr>
<td>binary_int</td>
<td>Scott Schurr and Matt Calabrese</td>
<td>Pavel Vozenilek</td>
<td>2005 October 13 - 2005 October 20</td>
<td><a href="http://lists.boost.org/boost-announce/2006/01/0078.php">
Accepted -- not yet added.</a></td>
</tr>
<tr>
<td>TR1</td>
<td>John Maddock</td>
<td>Beman Dawes</td>
<td>2005 September 24 - 2005 October 5</td>
<td>Accepted -- Added in 1.34</td>
</tr>
<tr>
<td>Xpressive</td>
<td>Eric Niebler</td>
<td>Thomas Witt</td>
<td> 2005 September 8 - 2005 September 18</td>
<td>Accepted -- Added in 1.34</td>
</tr>
<tr>
<td>Boost 1.33.0 Released</td>
<td></td>
<td>Doug Gregor</td>
<td>17 August 2005</td>
<td><a href="http://lists.boost.org/boost-announce/2005/08/0067.php">
Notes</a></td>
</tr>
<tr>
<td>Function Types</td>
<td>Tobias Schwinger</td>
<td>John Maddock</td>
<td>2005-Jun-6 to 2005-June-16</td>
<td><a href="http://lists.boost.org/boost-announce/2005/06/0066.php">
Accepted Provisionally</a></td>
</tr>
<tr>
<td>Typeof</td>
<td>Arkadiy Vertleyb and Peder Holt</td>
<td>Andy Little</td>
<td>2005 May 20 - 2005 May 30</td>
<td>Accepted -- Added in 1.34</td>
</tr>
<tr>
<td>Singleton</td>
<td>Jason Hise</td>
<td>Pavel Vozenilek</td>
<td>2005 May 5 - 2005 May 15</td>
<td><a href="http://lists.boost.org/boost-announce/2005/05/0062.php">
Rejected</a></td>
</tr>
<tr>
<td>FOREACH Macro</td>
<td>Eric Niebler</td>
<td>Gennadiy Rozental</td>
<td>2005 April 25 - 2005 May 1</td>
<td>Accepted -- Added in 1.34</td>
</tr>
<tr>
<td>Hash</td>
<td>Daniel James</td>
<td>Thorsten Ottosen</td>
<td>2005 Mar 21 - 2005 March 12</td>
<td>Accepted -- Added in 1.33</td>
</tr>
<tr>
<td>State Chart</td>
<td>Andreas Huber</td>
<td>Pavel Vozenilek</td>
<td>2005 Feb 23 - 2005 March 9</td>
<td>Accepted -- Added in 1.34</td>
</tr>
<tr>
<td>Wave</td>
<td>Hartmut Kaiser</td>
<td>Tom Brinkman</td>
<td>2005 Feb 7 - 2005 Feb 20</td>
<td>Accepted -- Added in 1.33</td>
</tr>
<tr>
<td>Pointer Containers</td>
<td>Thorsten Ottosen</td>
<td>Pavol Droba</td>
<td>2004 Sept 26 - Oct 5</td>
<td>Accepted -- Added in 1.33</td>
</tr>
<tr>
<td>Named Params</td>
<td>David Abrahams &amp; Daniel Wallin</td>
<td>Doug Gregor</td>
<td>2004 Nov 1 - 2004 Nov 20</td>
<td>Accepted -- Added in 1.33</td>
</tr>
<tr>
<td>Output Formatters</td>
<td>Reece Dunn</td>
<td>John Torjo</td>
<td>2004 Sept 11 - Sept 25</td>
<td><a href="http://lists.boost.org/Archives/boost/2004/10/74535.php">
Rejected</a></td>
</tr>
<tr>
<td>Iostreams</td>
<td>Jonathan Turkanis</td>
<td>Jeff Garland</td>
<td>2004 Aug 28 - Sep 11</td>
<td>Accepted -- Added in 1.33</td>
</tr>
<tr>
<td>More IO</td>
<td>Daryle Walker</td>
<td>Tom Brinkman</td>
<td>2004 Aug 21 - 28</td>
<td>Rejected</td>
</tr>
<tr>
<td>Tribool</td>
<td>Douglas Gregor</td>
<td>Thomas Witt</td>
<td>2004 May 19-29</td>
<td>Accepted -- Added in 1.32</td>
</tr>
<tr>
<td>Assignment</td>
<td>Thorsten Ottosen</td>
<td>Tom Brinkman</td>
<td>2004 Apr 1 - 11</td>
<td>Accepted -- Added in 1.32</td>
</tr>
<tr>
<td>Serialization (re-review)</td>
<td>Robert Ramey</td>
<td>Jeff Garland</td>
<td>2004 Apr 13 - 26</td>
<td>Accepted -- Added in 1.32</td>
</tr>
<tr>
<td>Container Traits (now Range)</td>
<td>Thorsten Ottosen</td>
<td>Hartmut Kaiser</td>
<td>2004 Apr 28 - May 7</td>
<td>Accepted -- Added in 1.32</td>
</tr>
<tr>
<td>Indexed Set (now MultiIndex)</td>
<td>Joaqu&iacute;n M&ordf; L&oacute;pez Mu&ntilde;oz</td>
<td>Pavel Vozenilek</td>
<td>2004 Mar 20 - 30</td>
<td><a href="http://lists.boost.org/Archives/boost/2004/04/63582.php">
Accepted -- Added in 1.32</a></td>
</tr>
<tr>
<td>Circular Buffer</td>
<td>Jan Gaspar</td>
<td>Pavel Vozenilek</td>
<td>2004 Mar 5 - 15</td>
<td>Accepted -- Added to CVS</td>
</tr>
<tr>
<td>enable_if</td>
<td>Jaakko J&auml;rvi &amp; Jeremiah Willcock &amp; Andrew Lumsdaine</td>
<td>(fasttrack)</td>
<td>Dec 2003</td>
<td>Accepted -- added in 1.31</td>
</tr>
<tr>
<td>FC++</td>
<td>Brian McNamara &amp; Yannis Smaragdakis</td>
<td>Mat Marcus</td>
<td>2004 Feb 14 - Mar 1</td>
<td>Rejected</td>
</tr>
<tr>
<td>Numeric Conversions Library</td>
<td>Fernando Cacciola</td>
<td>Thorsten Ottosen</td>
<td>8 - 22 Dec 2003</td>
<td>Accepted -- added in 1.32</td>
</tr>
<tr>
<td>String Algorithm Library</td>
<td>Pavol Droba</td>
<td>Thorsten Ottosen</td>
<td>17 - 30 Oct 2003</td>
<td>Accepted -- added in 1.32</td>
</tr>
<tr>
<td>Shifted Pointer</td>
<td>Philippe A. Bouchard</td>
<td>Doug Gregor</td>
<td>24 - 30 Sep 2003</td>
<td>Rejected</td>
</tr>
<tr>
<td>Fixed-Point Decimal</td>
<td>Bill Seymour</td>
<td>Jens Maurer</td>
<td>11 - 21 Jul 2003</td>
<td>Rejected</td>
</tr>
<tr>
<td>Math Constants</td>
<td>Paul A. Bristow</td>
<td>Jaap Suter</td>
<td>06 - 15 Jun 2003</td>
<td>Rejected</td>
</tr>
<tr>
<td>Command Line &amp; Config</td>
<td>Vladimir Prus</td>
<td>Aleksey Gurtovoy</td>
<td>21 May - 03 Jun 2003</td>
<td>Accepted -- added in 1.32</td>
</tr>
<tr>
<td>I/O Manipulators and Adaptors</td>
<td>Daryle Walker</td>
<td>Ed Brey</td>
<td>27 Feb - 11 Mar 2003</td>
<td>-</td>
</tr>
<tr>
<td>Variant</td>
<td>Eric Friedman &amp; Itay Maman</td>
<td>Jeff Garland</td>
<td>16 - 25 Feb 2003</td>
<td>Accepted -- added in 1.31</td>
</tr>
<tr>
<td>Optional</td>
<td>Fernando Cacciola</td>
<td>Douglas Gregor</td>
<td>09 - 18 Dec 2002</td>
<td>Accepted -- added in 1.30</td>
</tr>
<tr>
<td>Serialization</td>
<td>Robert Ramey</td>
<td>Dave Abrahams</td>
<td>02 - 11 Nov 2002</td>
<td>Rejected</td>
</tr>
<tr>
<td>Spirit</td>
<td>Joel de Guzman</td>
<td>John Maddock</td>
<td>11 - 20 Oct 2002</td>
<td>Accepted -- added in 1.30</td>
</tr>
<tr>
<td>Minmax</td>
<td>Herv&eacute; Bronnimann</td>
<td>Thomas Witt</td>
<td>28 Sep - 07 Oct 2002</td>
<td>Accepted -- added in 1.32</td>
</tr>
<tr>
<td>Filesystem</td>
<td>Beman Dawes</td>
<td>William Kempf</td>
<td>14 - 23 Sep 2002</td>
<td>Accepted -- added in 1.30</td>
</tr>
<tr>
<td>Interval Arithmetic Library</td>
<td>Herv&eacute; Bronnimann &amp; Guillaume Melquiond &amp; Sylvain Pion</td>
<td>Beman Dawes</td>
<td>31 Aug - 09 Sep 2002</td>
<td>Accepted -- added in 1.30</td>
</tr>
<tr>
<td>Template Meta Programming Library MPL</td>
<td>Aleksey Gurtovoy</td>
<td>Douglas Gregor</td>
<td>15 - 29 Jul 2002</td>
<td>Accepted -- added in 1.30</td>
</tr>
<tr>
<td>uBLAS</td>
<td>Joerg Walter &amp; Mathias Koch</td>
<td>Ed Brey</td>
<td>21 Jun - 01 Jul 2002</td>
<td>Accepted -- added in 1.29</td>
</tr>
<tr>
<td>Dynamic Bitset</td>
<td>Chuck Alison &amp; Jeremy Siek</td>
<td>Mat Marcus</td>
<td>08 - 17 Jun 2002</td>
<td>Accepted -- added in 1.29</td>
</tr>
<tr>
<td>Date / Time</td>
<td>Jeff Garland</td>
<td>Darin Adler</td>
<td>15 - 24 Apr 2002</td>
<td>Accepted -- added in 1.29</td>
</tr>
<tr>
<td>Lambda</td>
<td>Jaakko J&auml;rvi &amp; Gary Powell</td>
<td>Aleksey Gurtovoy</td>
<td>08 - 20 Mar 2002</td>
<td>Accepted and added</td>
</tr>
<tr>
<td>Signals</td>
<td>Douglas Gregor</td>
<td>William Kempf</td>
<td>18 - 27 Feb 2002</td>
<td>Accepted -- added in 1.29</td>
</tr>
<tr>
<td>I/O State Saver</td>
<td>Daryle Walker</td>
<td>Beman Dawes</td>
<td>06 - 16 Feb 2002</td>
<td>Accepted and added</td>
</tr>
<tr>
<td>printf-like formatting for iostreams</td>
<td>Samuel Krempp</td>
<td>Jens Maurer</td>
<td>13 - 23 Jan 2002</td>
<td>Accepted -- added in 1.29</td>
</tr>
<tr>
<td>Multi-array</td>
<td>Ron Garcia</td>
<td>John Maddock</td>
<td>02 - 12 Jan 2002</td>
<td>Accepted -- added in 1.29</td>
</tr>
<tr>
<td>Unit Test Library</td>
<td>Gennadiy Rozental</td>
<td>Jeremy Siek</td>
<td>01 - 13 Dec 2001</td>
<td>Accepted and added</td>
</tr>
<tr>
<td>GCD Library plus integer additions</td>
<td>Daryle Walker</td>
<td>Dave Abrahams</td>
<td>17 - 26 Sep 2001</td>
<td>-</td>
</tr>
<tr>
<td>Thread Library</td>
<td>Bill Kempf</td>
<td>Ed Brey</td>
<td>Aug 30 - Sep 8</td>
<td>Accepted and added</td>
</tr>
<tr>
<td>Config System</td>
<td>John Maddock</td>
<td>Doug Gregor</td>
<td>Aug 20 - 29&nbsp;</td>
<td>Accepted and added</td>
</tr>
<tr>
<td>Bind Library</td>
<td>Peter Dimov</td>
<td>Darin Adler</td>
<td>Aug 10 - 19</td>
<td>Accepted and added</td>
</tr>
<tr>
<td>Base from Member Library</td>
<td>Daryle Walker</td>
<td>Beman Dawes</td>
<td>Jul 30 - Aug 9</td>
<td>-</td>
</tr>
<tr>
<td>Coding Guidelines</td>
<td>Dave Abrahams</td>
<td>Aleksey Gurtovoy</td>
<td>Jul 20 - 29</td>
<td>-</td>
</tr>
<tr>
<td>Preprocessor Library</td>
<td>Vesa Karvonen</td>
<td>Jeremy Siek</td>
<td>Jun 28 - Jul 9</td>
<td>Accepted and added</td>
</tr>
<tr>
<td>Tuples Library</td>
<td>Jaakko J&auml;rvi</td>
<td>Beman Dawes</td>
<td>Jun 17 - 26</td>
<td>Accepted and added</td>
</tr>
<tr>
<td>Function Library</td>
<td>Doug Gregor</td>
<td>John Maddock</td>
<td>Jun 6 - 16</td>
<td>Accepted and added</td>
</tr>
<tr>
<td>Tokenizer</td>
<td>John Bandela</td>
<td>Doug Gregor</td>
<td>May 28 - Jun 6</td>
<td>Accepted and added</td>
</tr>
<tr>
<td>Special Functions</td>
<td>Hubert Holin</td>
<td>Jens Maurer</td>
<td>May 18 - 27</td>
<td>Accepted and added</td>
</tr>
</table>
<h2>Review <a name="Managers">Managers</a></h2>
<p>We try to rotate the task of Review Manager between many experienced Boost
members, both to ensure fairness, and to spread the workload.&nbsp; If you would
like to volunteer to become a review manager, please contact
John Phillips (phillips at mps dot ohio-state dot edu) or Ronald
Garcia (garcia at cs dot indiana dot edu).
</p>
<hr>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->15 Apr 2005<!--webbot bot="Timestamp" endspan i-checksum="15045" -->
</p>
<p>Copyright Beman Dawes, Tom Brinkman, Jeff Garland 2001 - 2005</p>
<p>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href
="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

683
generic_exception_safety.html
View File

@ -1,683 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0052)http://people.ne.mediaone.net/abrahams/abrahams.html -->
<meta name="generator" content="Microsoft FrontPage 5.0">
<title>Exception-Safety in Generic Components</title>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta content="MSHTML 5.50.4522.1800" name="GENERATOR">
<h1 align="center">Exception-Safety in Generic Components</h1>
<p align="center"><i><b>Lessons Learned from Specifying Exception-Safety
for the C++ Standard Library</b></i>
<h3 align="center">David Abrahams</h3>
<h3 align="center"><a href="mailto:david.abrahams@rcn.com">
david.abrahams@rcn.com</a></h3>
<p><b>Abstract.</b> This paper represents the knowledge accumulated in
response to a real-world need: that the C++ Standard Template Library
exhibit useful and well-defined interactions with exceptions, the
error-handling mechanism built-in to the core C++ language. It explores the
meaning of exception-safety, reveals surprising myths about exceptions and
genericity, describes valuable tools for reasoning about program
correctness, and outlines an automated testing procedure for verifying
exception-safety.
<p><b>Keywords:</b> exception-safety, exceptions, STL, C++
<h2>1 What is exception-safety?</h2>
<p>Informally, exception-safety in a component means that it exhibits
reasonable behavior when an exception is thrown during its execution. For
most people, the term ``reasonable'' includes all the usual
expectations for error-handling: that resources should not be leaked, and
that the program should remain in a well-defined state so that execution
can continue. For most components, it also includes the expectation that
when an error is encountered, it is reported to the caller.
<p>More formally, we can describe a component as minimally exception-safe
if, when exceptions are thrown from within that component, its invariants
are intact. Later on we'll see that at least three different levels of
exception-safety can be usefully distinguished. These distinctions can help
us to describe and reason about the behavior of large systems.
<p>In a generic component, we usually have an additional expectation of
<i>exception-neutrality</i>, which means that exceptions thrown by a
component's type parameters should be propagated, unchanged, to the
component's caller.
<h2>2 Myths and Superstitions</h2>
<p>Exception-safety seems straightforward so far: it doesn't constitute
anything more than we'd expect from code using more traditional
error-handling techniques. It might be worthwhile, however, to examine the
term from a psychological viewpoint. Nobody ever spoke of
``error-safety'' before C++ had exceptions.
<p>It's almost as though exceptions are viewed as a <i>mysterious
attack</i> on otherwise correct code, from which we must protect ourselves.
Needless to say, this doesn't lead to a healthy relationship with error
handling! During standardization, a democratic process which requires broad
support for changes, I encountered many widely-held superstitions. In order
to even begin the discussion of exception-safety in generic components, it
may be worthwhile confronting a few of them.
<p><i>``Interactions between templates and exceptions are not
well-understood.''</i> This myth, often heard from those who consider
these both new language features, is easily disposed of: there simply are
no interactions. A template, once instantiated, works in all respects like
an ordinary class or function. A simple way to reason about the behavior of
a template with exceptions is to think of how a specific instantiation of
that template works. Finally, the genericity of templates should not cause
special concern. Although the component's client supplies part of the
operation (which may, unless otherwise specified, throw arbitrary
exceptions), the same is true of operations using familiar virtual
functions or simple function pointers.
<p><i>``It is well known to be impossible to write an exception-safe
generic container.''</i> This claim is often heard with reference to
an article by Tom Cargill <a title=
"Tom Cargill, ``Exception Handling: A False Sense of Security'', C++ Report, Nov-Dec 1994"
href=
"#reference4"><sup>[4]</sup></a>
in which he explores the problem of exception-safety for a generic stack
template. In his article, Cargill raises many useful questions, but
unfortunately fails to present a solution to his problem.<a title=
"Probably the greatest impediment to a solution in Cargill's case was an unfortunate combination of choices on his part: the interface he chose for his container was incompatible with his particular demands for safety. By changing either one he might have solved the problem."
href=
"#footnote1"><sup>1</sup></a>
He concludes by suggesting that a solution may not be possible.
Unfortunately, his article was read by many as ``proof'' of that
speculation. Since it was published there have been many examples of
exception-safe generic components, among them the C++ standard library
containers.
<p><i>``Dealing with exceptions will slow code down, and templates are
used specifically to get the best possible performance.''</i> A good
implementation of C++ will not devote a single instruction cycle to dealing
with exceptions until one is thrown, and then it can be handled at a speed
comparable with that of calling a function <a title=
"D. R. Musser, ``Introspective Sorting and Selection Algorithms'', Software-Practice and Experience 27(8):983-993, 1997."
href=
"#reference7"><sup>[7]</sup></a>.
That alone gives programs using exceptions performance equivalent to that
of a program which ignores the possibility of errors. Using exceptions can
actually result in faster programs than ``traditional'' error
handling methods for other reasons. First, a catch block clearly indicates
to the compiler which code is devoted to error-handling; it can then be
separated from the usual execution path, improving locality of reference.
Second, code using ``traditional'' error handling must typically
test a return value for errors after every single function call; using
exceptions completely eliminates that overhead.
<p><i>``Exceptions make it more difficult to reason about a program's
behavior.''</i> Usually cited in support of this myth is the way
``hidden'' execution paths are followed during stack-unwinding.
Hidden execution paths are nothing new to any C++ programmer who expects
local variables to be destroyed upon returning from a function:
<blockquote>
<pre>ErrorCode f( int&amp; result ) // 1
{ // 2
X x; // 3
ErrorCode err = x.g( result ); // 4
if ( err != kNoError ) // 5
return err; // 6
// ...More code here...
return kNoError; // 7
}
</pre>
</blockquote>
<p>In the example above, there is a ``hidden'' call to
<code>X::~X()</code> in lines 6 and 7. Granted, using exceptions, there is
no code devoted to error handling visible:
<blockquote>
<pre>int f() // 1
{ // 2
X x; // 3
int result = x.g(); // 4
// ...More code here...
return result; // 5
}
</pre>
</blockquote>
<p>For many programmers more familiar with exceptions, the second example
is actually more readable and understandable than the first. The
``hidden'' code paths include the same calls to destructors of
local variables. In addition, they follow a simple pattern which acts
<i>exactly</i> as though there were a potential return statement after each
function call in case of an exception. Readability is enhanced because the
normal path of execution is unobscured by error-handling, and return values
are freed up to be used in a natural way.
<p>There is an even more important way in which exceptions can enhance
correctness: by allowing simple class invariants. In the first example, if
<code>x</code>'s constructor should need to allocate resources, it has no
way to report a failure: in C++, constructors have no return values. The
usual result when exceptions are avoided is that classes requiring
resources must include a separate initializer function which finishes the
job of construction. The programmer can therefore never be sure, when an
object of class <code>X</code> is used, whether he is handling a
full-fledged <code>X</code> or some abortive attempt to construct one (or
worse: someone simply forgot to call the initializer!)
<h2>3 A contractual basis for exception-safety</h2>
<p>A non-generic component can be described as exception-safe in isolation,
but because of its configurability by client code, exception-safety in a
generic component usually depends on a contract between the component and
its clients. For example, the designer of a generic component might require
that an operation which is used in the component's destructor not throw any
exceptions.<a title=
" It is usually inadvisable to throw an exception from a destructor in C++, since the destructor may itself be called during the stack-unwinding caused by another exception. If the second exception is allowed to propagate beyond the destructor, the program is immediately terminated."
href=
"#footnote2"><sup>2</sup></a>
The generic component might, in return, provide one of the following
guarantees:
<ul>
<li>The <i>basic</i> guarantee: that the invariants of the component are
preserved, and no resources are leaked.
<li>The <i>strong</i> guarantee: that the operation has either completed
successfully or thrown an exception, leaving the program state exactly as
it was before the operation started.
<li>The <i>no-throw</i> guarantee: that the operation will not throw an
exception.
</ul>
<p>The basic guarantee is a simple minimum standard for exception-safety to
which we can hold all components. It says simply that after an exception,
the component can still be used as before. Importantly, the preservation of
invariants allows the component to be destroyed, potentially as part of
stack-unwinding. This guarantee is actually less useful than it might at
first appear. If a component has many valid states, after an exception we
have no idea what state the component is in|only that the state is valid.
The options for recovery in this case are limited: either destruction or
resetting the component to some known state before further use. Consider
the following example:
<blockquote>
<pre>template &lt;class X&gt;
void print_random_sequence()
{
std::vector&lt;X&gt; v(10); // A vector of 10 items
try {
// Provides only the <i>basic</i> guarantee
v.insert( v.begin(), X() );
}
catch(...) {} // ignore any exceptions above
// print the vector's contents
std::cout "(" &lt;&lt; v.size() &lt;&lt; ") ";
std::copy( v.begin(), v.end(),
std::ostream_iterator&lt;X&gt;( std::cout, " " ) );
}
</pre>
</blockquote>
<p>Since all we know about v after an exception is that it is valid, the
function is allowed to print any random sequence of <code>X</code>s.<a
title=
"In practice of course, this function would make an extremely poor random sequence generator!"
href=
"#footnote3"><sup>3</sup></a>
It is ``safe'' in the sense that it is not allowed to crash, but
its output may be unpredictable.
<p>The <i>strong</i> guarantee provides full
``commit-or-rollback'' semantics. In the case of C++ standard
containers, this means, for example, that if an exception is thrown all
iterators remain valid. We also know that the container has exactly the
same elements as before the exception was thrown. A transaction that has no
effects if it fails has obvious benefits: the program state is simple and
predictable in case of an exception. In the C++ standard library, nearly
all of the operations on the node-based containers list, set, multiset,
map, and multimap provide the <i>strong</i> guarantee.<a title=
"It is worth noting that mutating algorithms usually cannot provide the strong guarantee: to roll back a modified element of a range, it must be set back to its previous value using operator=, which itself might throw. In the C++ standard library, there are a few exceptions to this rule, whose rollback behavior consists only of destruction: uninitialized_copy, uninitialized_fill, and uninitialized_fill_n."
href=
"#footnote4"><sup>4</sup></a>).
<p>The <i>no-throw</i> guarantee is the strongest of all, and it says that
an operation is guaranteed not to throw an exception: it always completes
successfully. This guarantee is necessary for most destructors, and indeed
the destructors of C++ standard library components are all guaranteed not
to throw exceptions. The <i>no-throw</i> guarantee turns out to be
important for other reasons, as we shall see.<a title=
"All type parameters supplied by clients of the C++ standard library are required not to throw from their destructors. In return, all components of the C++ standard library provide at least the basic guarantee."
href=
"#footnote5"><sup>5</sup></a>
<h2>4 Legal Wrangling</h2>
<p>Inevitably, the contract can get more complicated: a quid pro quo
arrangement is possible. Some components in the C++ Standard Library give
one guarantee for arbitrary type parameters, but give a stronger guarantee
in exchange for additional promises from the client type that no exceptions
will be thrown. For example, the standard container operation
<code>vector&lt;T&gt;::erase</code> gives the <i>basic</i> guarantee for
any <code>T</code>, but for types whose copy constructor and copy
assignment operator do not throw, it gives the <i>no-throw</i> guarantee.<a
title=
"Similar arrangements might have been made in the C++ standard for many of the mutating algorithms, but were never considered due to time constraints on the standardization process."
href=
"#footnote6"><sup>6</sup></a>
<h2>5 What level of exception-safety should a component specify?</h2>
<p>From a client's point-of-view, the strongest possible level of safety
would be ideal. Of course, the <i>no-throw</i> guarantee is simply
impossible for many operations, but what about the <i>strong</i> guarantee?
For example, suppose we wanted atomic behavior for
<code>vector&lt;T&gt;::insert</code>. Insertion into the middle of a vector
requires copying elements after the insertion point into later positions,
to make room for the new element. If copying an element can fail, rolling
back the operation would require ``undoing'' the previous
copies...which depends on copying again. If copying back should fail (as it
likely would), we have failed to meet our guarantee.
<p>One possible alternative would be to redefine <code>insert</code> to
build the new array contents in a fresh piece of memory each time, and only
destroy the old contents when that has succeeded. Unfortunately, there is a
non-trivial cost if this approach is followed: insertions near the end of a
vector which might have previously caused only a few copies would now cause
every element to be copied. The <i>basic</i> guarantee is a
``natural'' level of safety for this operation, which it can
provide without violating its performance guarantees. In fact all of the
operations in the library appear to have such a ``natural'' level
of safety.
<p>Because performance requirements were already a well-established part of
the draft standard and because performance is a primary goal of the STL,
there was no attempt to specify more safety than could be provided within
those requirements. Although not all of the library gives the <i>strong</i>
guarantee, almost any operation on a standard container which gives the
<i>basic</i> guarantee can be made <i>strong</i> using the ``make a
new copy'' strategy described above:
<blockquote>
<pre>template &lt;class Container, class BasicOp&gt;
void MakeOperationStrong( Container&amp; c, const BasicOp&amp; op )
{
Container tmp(c); // Copy c
op(tmp); // Work on the copy
c.swap(tmp); // Cannot fail<a title=
"Associative containers whose Compare object might throw an exception when copied cannot use this technique, since the swap function might fail."
href=
"#footnote7"><sup>7</sup></a>
}
</pre>
</blockquote>
<p>This technique can be folded into a wrapper class to make a similar
container which provides stronger guarantees (and different performance
characteristics).<a title=
"This suggests another potential use for the oft-wished-for but as yet unseen container traits&lt;&gt; template: automated container selection to meet exceptionsafety constraints."
href=
"#footnote8"><sup>8</sup></a>
<h2>6 Should we take everything we can get?</h2>
<p>By considering a particular implementation, we can hope to discern a
natural level of safety. The danger in using this to establish requirements
for a component is that the implementation might be restricted. If someone
should come up with a more-efficient implementation which we'd like to use,
we may find that it's incompatible with our exception-safety requirements.
One might expect this to be of no concern in the well-explored domains of
data structures and algorithms covered by the STL, but even there, advances
are being made. A good example is the recent <i>introsort</i> algorithm <a
title=
"D. R. Musser, ``Introspective Sorting and Selection Algorithms'', Software-Practice and Experience 27(8):983-993, 1997."
href=
"#reference6"><sup>[6]</sup></a>,
which represents a substantial improvement in worst-case complexity over
the well-established <i>quicksort</i>.
<p>To determine exactly how much to demand of the standard components, I
looked at a typical real-world scenario. The chosen test case was a
``composite container.'' Such a container, built of two or more
standard container components, is not only commonly needed, but serves as a
simple representative case for maintaining invariants in larger systems:
<blockquote>
<pre>// SearchableStack - A stack which can be efficiently searched
// for any value.
template &lt;class T&gt;
class SearchableStack
{
public:
void push(const T&amp; t); // O(log n)
void pop(); // O(log n)
bool contains(const T&amp; t) const; // O(log n)
const T&amp; top() const; // O(1)
private:
std::set&lt;T&gt; set_impl;
std::list&lt;std::set&lt;T&gt;::iterator&gt; list_impl;
};
</pre>
</blockquote>
<p>The idea is that the list acts as a stack of set iterators: every
element goes into the set first, and the resulting position is pushed onto
the list. The invariant is straightforward: the set and the list should
always have the same number of elements, and every element of the set
should be referenced by an element of the list. The following
implementation of the push function is designed to give the <i>strong</i>
guarantee within the natural levels of safety provided by set and list:
<blockquote>
<pre>template &lt;class T&gt; // 1
void SearchableStack&lt;T&gt;::push(const T&amp; t) // 2
{ // 3
set&lt;T&gt;::iterator i = set_impl.insert(t); // 4
try // 5
{ // 6
list_impl.push_back(i); // 7
} // 8
catch(...) // 9
{ // 10
set_impl.erase(i); // 11
throw; // 12
} // 13
} // 14
</pre>
</blockquote>
<p>What does our code actually require of the library? We need to examine
the lines where non-const operations occur:
<ul>
<li>Line 4: if the insertion fails but <code>set_impl</code> is modified
in the process, our invariant is violated. We need to be able to rely on
the <i>strong</i> guarantee from <code>set&lt;T&gt;::insert</code>.
<li>Line 7: likewise, if <code>push_back</code> fails, but
<code>list_impl</code> is modified in the process, our invariant is
violated, so we need to be able to rely on the <i>strong</i> guarantee
from list&lt;T&gt;::insert.
<li>Line 11: here we are ``rolling back'' the insertion on line
4. If this operation should fail, we will be unable to restore our
invariant. We absolutely depend on the <i>no-throw</i> guarantee from
<code>set&lt;T&gt;::erase</code>.<a title=
"One might be tempted to surround the erase operation with a try/catch block to reduce the requirements on set&lt;T&gt; and the problems that arise in case of an exception, but in the end that just begs the question. First, erase just failed and in this case there are no viable alternative ways to produce the necessary result. Second and more generally, because of the variability of its type parameters a generic component can seldom be assured that any alternatives will succeed."
href=
"#footnote9"><sup>9</sup></a>
<li>Line 11: for the same reasons, we also depend on being able to pass
the <code>i</code> to the <code>erase</code> function: we need the
<i>no-throw</i> guarantee from the copy constructor of
<code>set&lt;T&gt;::iterator</code>.
</ul>
<p>I learned a great deal by approaching the question this way during
standardization. First, the guarantee specified for the composite container
actually depends on stronger guarantees from its components (the
<i>no-throw</i> guarantees in line 11). Also, I took advantage of all of
the natural level of safety to implement this simple example. Finally, the
analysis revealed a requirement on iterators which I had previously
overlooked when operations were considered on their own. The conclusion was
that we should provide as much of the natural level of safety as possible.
Faster but less-safe implementations could always be provided as extensions
to the standard components. <sup><a title=
"The prevalent philosophy in the design of STL was that functionality that wasn't essential to all uses should be left out in favor of efficiency, as long as that functionality could be obtained when needed by adapting the base components. This departs from that philosophy, but it would be difficult or impossible to obtain even the basic guarantee by adapting a base component that doesn't already have it."
name="#footnote10">10</a></sup>
<h2>7 Automated testing for exception-safety</h2>
<p>As part of the standardization process, I produced an exception-safe
reference implementation of the STL. Error-handling code is seldom
rigorously tested in real life, in part because it is difficult to cause
error conditions to occur. It is very common to see error-handling code
which crashes the first time it is executed ...in a shipping product! To
bolster confidence that the implementation actually worked as advertised, I
designed an automated test suite, based on an exhaustive technique due to
my colleague Matt Arnold.
<p>The test program started with the basics: reinforcement and
instrumentation, especially of the global operators <code>new</code> and
<code>delete</code>.<sup><a title=
"An excellent discussion on how to fortify memory subsystems can be found in: Steve Maguire, Writing Solid Code, Microsoft Press, Redmond, WA, 1993, ISBN 1-55615- 551-4."
name="#footnote11">11</a></sup>Instances of the components (containers and
algorithms) were created, with type parameters chosen to reveal as many
potential problems as possible. For example, all type parameters were given
a pointer to heap-allocated memory, so that leaking a contained object
would be detected as a memory leak.
<p>Finally, a scheme was designed that could cause an operation to throw an
exception at each possible point of failure. At the beginning of every
client-supplied operation which is allowed to throw an exception, a call to
<code>ThisCanThrow</code> was added. A call to <code>ThisCanThrow</code>
also had to be added everywhere that the generic operation being tested
might throw an exception, for example in the global operator
<code>new</code>, for which an instrumented replacement was supplied.
<blockquote>
<pre>// Use this as a type parameter, e.g. vector&lt;TestClass&gt;
struct TestClass
{
TestClass( int v = 0 )
: p( ThisCanThrow(), new int( v ) ) {}
TestClass( const TestClass&amp; rhs )
: p( ThisCanThrow(), new int( *rhs.p ) ) {}
const TestClass&amp; operator=( const TestClass&amp; rhs )
{ ThisCanThrow(); *p = *rhs.p; }
bool operator==( const TestClass&amp; rhs ) const
{ ThisCanThrow(); return *p == *rhs.p; }
...etc...
~TestClass() { delete p; }
};
</pre>
</blockquote>
<p><code>ThisCanThrow</code> simply decrements a ``throw
counter'' and, if it has reached zero, throws an exception. Each test
takes a form which begins the counter at successively higher values in an
outer loop and repeatedly attempts to complete the operation being tested.
The result is that the operation throws an exception at each successive
step along its execution path that can possibly fail. For example, here is
a simplified version of the function used to test the <i>strong</i>
guarantee: <a title=
"Note that this technique requires that the operation being tested be exception-neutral. If the operation ever tries to recover from an exception and proceed, the throw counter will be negative, and subsequent operations that might fail will not be tested for exception-safety."
href=
"#footnote12"><sup>12</sup></a>
<blockquote>
<pre>extern int gThrowCounter; // The throw counter
void ThisCanThrow()
{
if (gThrowCounter-- == 0)
throw 0;
}
template &lt;class Value, class Operation&gt;
void StrongCheck(const Value&amp; v, const Operation&amp; op)
{
bool succeeded = false;
for (long nextThrowCount = 0; !succeeded; ++nextThrowCount)
{
Value duplicate = v;
try
{
gThrowCounter = nextThrowCount;
op( duplicate ); // Try the operation
succeeded = true;
}
catch(...) // Catch all exceptions
{
bool unchanged = duplicate == v; // Test <i>strong</i> guarantee
assert( unchanged );
}
// Specialize as desired for each container type, to check
// integrity. For example, size() == distance(begin(),end())
CheckInvariant(v); // Check any invariant
}
}
</pre>
</blockquote>
<p>Notably, this kind of testing is much easier and less intrusive with a
generic component than with non-generics, because testing-specific type
parameters can be used without modifying the source code of the component
being tested. Also, generic functions like <code>StrongCheck</code> above
were instrumental in performing the tests on a wide range of values and
operations.
<h2>8 Further Reading</h2>
To my knowledge, there are currently only two descriptions of STL
exception-safety available. The original specification <a title=
"D. Abrahams, Exception Safety in STLport" href=
"#reference2"><sup>[2]</sup></a>
for the reference exception-safe implementation of the STL is an informal
specification, simple and self-explanatory (also verbose), and uses the
<i>basic-</i> and <i>strong-</i>guarantee distinctions outlined in this
article. It explicitly forbids leaks, and differs substantively from the
final C++ standard in the guarantees it makes, though they are largely
identical. I hope to produce an updated version of this document soon.
<p>The description of exception-safety in the C++ Standard <a title=
"International Standard ISO/IEC 14882, Information Technology-Programming Languages-C++, Document Number ISO/IEC 14882-1998"
href=
"#reference1"><sup>[1]</sup></a>
is only slightly more formal, but relies on hard-to-read
``standardese'' and an occasionally subtle web of implication.<a
title=
"The changes to the draft standard which introduced exception-safety were made late in the process, when amendments were likely to be rejected solely on the basis of the number of altered words. Unfortunately, the result compromises clarity somewhat in favor of brevity. Greg Colvin was responsible for the clever language-lawyering needed to minimize the extent of these changes."
href=
"#footnote13"><sup>13</sup></a>
In particular, leaks are not treated directly at all. It does have the
advantage that it <i>is</i> the standard.
<p>The original reference implementation <a title=
"B. Fomitchev, Adapted SGI STL Version 1.0, with exception handling code by D. Abrahams"
href=
"#reference5"><sup>[5]</sup></a>
of the exception-safe STL is an adaptation of an old version of the SGI
STL, designed for C++ compilers with limited features. Although it is not a
complete STL implementation, the code may be easier to read, and it
illustrates a useful base-class technique for eliminating
exception-handling code in constructors. The full test suite <a title=
"D. Abrahams and B. Fomitchev, Exception Handling Test Suite" href=
"#reference3"><sup>[3]</sup></a>
used to validate the reference implementation has been used successfully to
validate all recent versions of the SGI STL, and has been adapted to test
one other vendor's implementation (which failed). As noted on the
documentation page, it also seems to have the power to reveal hidden
compiler bugs, particularly where optimizers interact with
exception-handling code.
<h2>References</h2>
<ol>
<li><a name="reference1">International</a> Standard ISO/IEC 14882,
<i>Information Technology-Programming Languages-C++</i>, Document Number
ISO/IEC 14882-1998, available from <a href=
"http://webstore.ansi.org/ansidocstore/default.asp">http://webstore.ansi.org/ansidocstore/default.asp</a>.
<li><a name="reference2">D.</a> Abrahams, <i>Exception Safety in
STLport</i>, available at <a href=
"http://www.stlport.org/doc/exception_safety.html">http://www.stlport.org/doc/exception_safety.html</a>.
<li><a name="reference3">D.</a> Abrahams and B. Fomitchev, <i>Exception
Handling Test Suite</i>, available at <a href=
"http://www.stlport.org/doc/eh_testsuite.html">http://www.stlport.org/doc/eh_testsuite.html</a>.
<li><a name="reference4">Tom</a> Cargill, ``Exception Handling:
A False Sense of Security,'' C++ Report, Nov-Dec 1994, also
available at <a href=
"http://www.awprofessional.com/content/images/020163371x/supplements/Exception_Handling_Article.html">http://www.awprofessional.com/content/images/020163371x/supplements/Exception_Handling_Article.html</a>.
<li><a name="reference5">B.</a> Fomitchev, <i>Adapted SGI STL Version
1.0</i>, with exception handling code by D. Abrahams, available at <a
href="http://www.stlport.org">http://www.stlport.org</a>.
<li><a name="reference6">D.</a> R. Musser, ``Introspective Sorting
and Selection Algorithms,'' <i>Software-Practice and Experience</i>
27(8):983-993, 1997.
<li><a name="reference7">Bjarne</a> Stroustrup, <i>The Design And
Evolution of C++</i>. Addison Wesley, Reading, MA, 1995, ISBN
0-201-54330-3, Section 16.9.1.
</ol>
<h2>Footnotes</h2>
<p><a name="footnote1">1</a> Probably the greatest impediment to a solution
in Cargill's case was an unfortunate combination of choices on his part:
the interface he chose for his container was incompatible with his
particular demands for safety. By changing either one he might have solved
the problem.
<p><a name="footnote2">2</a> It is usually inadvisable to throw an
exception from a destructor in C++, since the destructor may itself be
called during the stack-unwinding caused by another exception. If the
second exception is allowed to propagate beyond the destructor, the program
is immediately terminated.
<p><a name="footnote3">3</a> In practice of course, this function would
make an extremely poor random sequence generator!
<p><a name="footnote4">4</a> It is worth noting that mutating algorithms
usually cannot provide the <i>strong</i> guarantee: to roll back a modified
element of a range, it must be set back to its previous value using
<code>operator=</code>, which itself might throw. In the C++ standard
library, there are a few exceptions to this rule, whose rollback behavior
consists only of destruction: <code>uninitialized_copy</code>,
<code>uninitialized_fill</code>, and <code>uninitialized_fill_n</code>.
<p><a name="footnote5">5</a> All type parameters supplied by clients of the
C++ standard library are required not to throw from their destructors. In
return, all components of the C++ standard library provide at least the
<i>basic</i> guarantee.
<p><a name="footnote6">6</a> Similar arrangements might have been made in
the C++ standard for many of the mutating algorithms, but were never
considered due to time constraints on the standardization process.
<p><a name="footnote7">7</a> Associative containers whose
<code>Compare</code> object might throw an exception when copied cannot use
this technique, since the swap function might fail.
<p><a name="footnote8">8</a> This suggests another potential use for the
oft-wished-for but as yet unseen <code>container_traits&lt;&gt;</code>
template: automated container selection to meet exception-safety
constraints.
<p><a name="footnote9">9</a> One might be tempted to surround the erase
operation with a <code>try</code>/<code>catch</code> block to reduce the
requirements on <code>set&lt;T&gt;</code> and the problems that arise in
case of an exception, but in the end that just begs the question. First,
erase just failed and in this case there are no viable alternative ways to
produce the necessary result. Second and more generally, because of the
variability of its type parameters a generic component can seldom be
assured that any alternatives will succeed.
<p><a name="footnote10">10</a> The prevalent philosophy in the design of
STL was that functionality that wasn't essential to all uses should be left
out in favor of efficiency, as long as that functionality could be obtained
when needed by adapting the base components. This departs from that
philosophy, but it would be difficult or impossible to obtain even the
<i>basic</i> guarantee by adapting a base component that doesn't already
have it.
<p><a name="footnote11">11</a> An excellent discussion on how to fortify
memory subsystems can be found in: Steve Maguire, Writing Solid Code,
Microsoft Press, Redmond, WA, 1993, ISBN 1-55615- 551-4.
<p><a name="footnote12">12</a> Note that this technique requires that the
operation being tested be exception-neutral. If the operation ever tries to
recover from an exception and proceed, the throw counter will be negative,
and subsequent operations that might fail will not be tested for
exception-safety.
<p><a name="footnote13">13</a> The changes to the draft standard which
introduced exception-safety were made late in the process, when amendments
were likely to be rejected solely on the basis of the number of altered
words. Unfortunately, the result compromises clarity somewhat in favor of
brevity. Greg Colvin was responsible for the clever language-lawyering
needed to minimize the extent of these changes.

474
generic_programming.html
View File

@ -1,474 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<meta name="generator" content=
"HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org">
<meta http-equiv="Content-Type" content=
"text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Generic Programming Techniques</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<img src="../boost.png" alt="boost.png (6897 bytes)" align="center"
width="277" height="86">
<h1>Generic Programming Techniques</h1>
<p>This is an incomplete survey of some of the generic programming
techniques used in the <a href="../index.htm">boost</a> libraries.</p>
<h2>Table of Contents</h2>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#concept">The Anatomy of a Concept</a></li>
<li><a href="#traits">Traits</a></li>
<li><a href="#tag_dispatching">Tag Dispatching</a></li>
<li><a href="#adaptors">Adaptors</a></li>
<li><a href="#type_generator">Type Generators</a></li>
<li><a href="#object_generator">Object Generators</a></li>
<li><a href="#policy">Policy Classes</a></li>
</ul>
<h2><a name="introduction">Introduction</a></h2>
<p>Generic programming is about generalizing software components so that
they can be easily reused in a wide variety of situations. In C++, class
and function templates are particularly effective mechanisms for generic
programming because they make the generalization possible without
sacrificing efficiency.</p>
<p>As a simple example of generic programming, we will look at how one
might generalize the <tt>memcpy()</tt> function of the C standard
library. An implementation of <tt>memcpy()</tt> might look like the
following:<br>
<br>
</p>
<blockquote>
<pre>
void* memcpy(void* region1, const void* region2, size_t n)
{
const char* first = (const char*)region2;
const char* last = ((const char*)region2) + n;
char* result = (char*)region1;
while (first != last)
*result++ = *first++;
return result;
}
</pre>
</blockquote>
The <tt>memcpy()</tt> function is already generalized to some extent by
the use of <tt>void*</tt> so that the function can be used to copy arrays
of different kinds of data. But what if the data we would like to copy is
not in an array? Perhaps it is in a linked list. Can we generalize the
notion of copy to any sequence of elements? Looking at the body of
<tt>memcpy()</tt>, the function's <b><i>minimal requirements</i></b> are
that it needs to <i>traverse</i> through the sequence using some sort
of pointer, <i>access</i> elements pointed to, <i>write</i> the elements
to the destination, and <i>compare</i> pointers to know when to stop. The
C++ standard library groups requirements such as these into
<b><i>concepts</i></b>, in this case the <a href=
"http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>
concept (for <tt>region2</tt>) and the <a href=
"http://www.sgi.com/tech/stl/OutputIterator.html">Output Iterator</a>
concept (for <tt>region1</tt>).
<p>If we rewrite the <tt>memcpy()</tt> as a function template, and use
the <a href="http://www.sgi.com/tech/stl/InputIterator.html">Input
Iterator</a> and <a href=
"http://www.sgi.com/tech/stl/OutputIterator.html">Output Iterator</a>
concepts to describe the requirements on the template parameters, we can
implement a highly reusable <tt>copy()</tt> function in the following
way:<br>
<br>
</p>
<blockquote>
<pre>
template &lt;typename InputIterator, typename OutputIterator&gt;
OutputIterator
copy(InputIterator first, InputIterator last, OutputIterator result)
{
while (first != last)
*result++ = *first++;
return result;
}
</pre>
</blockquote>
<p>Using the generic <tt>copy()</tt> function, we can now copy elements
from any kind of sequence, including a linked list that exports iterators
such as <tt>std::<a href=
"http://www.sgi.com/tech/stl/List.html">list</a></tt>.<br>
<br>
</p>
<blockquote>
<pre>
#include &lt;list&gt;
#include &lt;vector&gt;
#include &lt;iostream&gt;
int main()
{
const int N = 3;
std::vector&lt;int&gt; region1(N);
std::list&lt;int&gt; region2;
region2.push_back(1);
region2.push_back(0);
region2.push_back(3);
std::copy(region2.begin(), region2.end(), region1.begin());
for (int i = 0; i &lt; N; ++i)
std::cout &lt;&lt; region1[i] &lt;&lt; " ";
std::cout &lt;&lt; std::endl;
}
</pre>
</blockquote>
<h2><a name="concept">Anatomy of a Concept</a></h2>
A <b><i>concept</i></b> is a set of requirements
consisting of valid expressions, associated types, invariants, and
complexity guarantees. A type that satisfies the requirements is
said to <b><i>model</i></b> the concept. A concept can extend the
requirements of another concept, which is called
<b><i>refinement</i></b>.
<ul>
<li><a name="valid_expression"><b>Valid Expressions</b></a> are C++
expressions which must compile successfully for the objects involved in
the expression to be considered <i>models</i> of the concept.</li>
<li><a name="associated_type"><b>Associated Types</b></a> are types
that are related to the modeling type in that they participate in one
or more of the valid expressions. Typically associated types can be
accessed either through typedefs nested within a class definition for
the modeling type, or they are accessed through a <a href=
"#traits">traits class</a>.</li>
<li><b>Invariants</b> are run-time characteristics of the objects that
must always be true, that is, the functions involving the objects must
preserve these characteristics. The invariants often take the form of
pre-conditions and post-conditions.</li>
<li><b>Complexity Guarantees</b> are maximum limits on how long the
execution of one of the valid expressions will take, or how much of
various resources its computation will use.</li>
</ul>
<p>The concepts used in the C++ Standard Library are documented at the <a
href="http://www.sgi.com/tech/stl/table_of_contents.html">SGI STL
site</a>.</p>
<h2><a name="traits">Traits</a></h2>
<p>A traits class provides a way of associating information with a
compile-time entity (a type, integral constant, or address). For example,
the class template <tt><a href=
"http://www.sgi.com/tech/stl/iterator_traits.html">std::iterator_traits&lt;T&gt;</a></tt>
looks something like this:</p>
<blockquote>
<pre>
template &lt;class Iterator&gt;
struct iterator_traits {
typedef ... iterator_category;
typedef ... value_type;
typedef ... difference_type;
typedef ... pointer;
typedef ... reference;
};
</pre>
</blockquote>
The traits' <tt>value_type</tt> gives generic code the type which the
iterator is "pointing at", while the <tt>iterator_category</tt> can be
used to select more efficient algorithms depending on the iterator's
capabilities.
<p>A key feature of traits templates is that they're
<i>non-intrusive</i>: they allow us to associate information with
arbitrary types, including built-in types and types defined in
third-party libraries, Normally, traits are specified for a particular
type by (partially) specializing the traits template.</p>
<p>For an in-depth description of <tt>std::iterator_traits</tt>, see <a
href="http://www.sgi.com/tech/stl/iterator_traits.html">this page</a>
provided by SGI. Another very different expression of the traits idiom in
the standard is <tt>std::numeric_limits&lt;T&gt;</tt> which provides
constants describing the range and capabilities of numeric types.</p>
<h2><a name="tag_dispatching">Tag Dispatching</a></h2>
<p>Tag dispatching is a way of using function overloading to
dispatch based on properties of a type, and is often used hand in
hand with traits classes. A good example of this synergy is the
implementation of the <a href=
"http://www.sgi.com/tech/stl/advance.html"><tt>std::advance()</tt></a>
function in the C++ Standard Library, which increments an iterator
<tt>n</tt> times. Depending on the kind of iterator, there are different
optimizations that can be applied in the implementation. If the iterator
is <a href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">random
access</a> (can jump forward and backward arbitrary distances), then the
<tt>advance()</tt> function can simply be implemented with <tt>i +=
n</tt>, and is very efficient: constant time. Other iterators must be
<tt>advance</tt>d in steps, making the operation linear in n. If the
iterator is <a href=
"http://www.sgi.com/tech/stl/BidirectionalIterator.html">bidirectional</a>,
then it makes sense for <tt>n</tt> to be negative, so we must decide
whether to increment or decrement the iterator.</p>
<p>The relation between tag dispatching and traits classes is that the
property used for dispatching (in this case the
<tt>iterator_category</tt>) is often accessed through a traits class. The
main <tt>advance()</tt> function uses the <a href=
"http://www.sgi.com/tech/stl/iterator_traits.html"><tt>iterator_traits</tt></a>
class to get the <tt>iterator_category</tt>. It then makes a call the the
overloaded <tt>advance_dispatch()</tt> function. The appropriate
<tt>advance_dispatch()</tt> is selected by the compiler based on whatever
type the <tt>iterator_category</tt> resolves to, either <a href=
"http://www.sgi.com/tech/stl/input_iterator_tag.html"><tt>input_iterator_tag</tt></a>,
<a href=
"http://www.sgi.com/tech/stl/bidirectional_iterator_tag.html"><tt>bidirectional_iterator_tag</tt></a>,
or <a href=
"http://www.sgi.com/tech/stl/random_access_iterator_tag.html"><tt>random_access_iterator_tag</tt></a>.
A <b><i>tag</i></b> is simply a class whose only purpose is to convey
some property for use in tag dispatching and similar techniques. Refer to
<a href="http://www.sgi.com/tech/stl/iterator_tags.html">this page</a>
for a more detailed description of iterator tags.</p>
<blockquote>
<pre>
namespace std {
struct input_iterator_tag { };
struct bidirectional_iterator_tag { };
struct random_access_iterator_tag { };
namespace detail {
template &lt;class InputIterator, class Distance&gt;
void advance_dispatch(InputIterator&amp; i, Distance n, <b>input_iterator_tag</b>) {
while (n--) ++i;
}
template &lt;class BidirectionalIterator, class Distance&gt;
void advance_dispatch(BidirectionalIterator&amp; i, Distance n,
<b>bidirectional_iterator_tag</b>) {
if (n &gt;= 0)
while (n--) ++i;
else
while (n++) --i;
}
template &lt;class RandomAccessIterator, class Distance&gt;
void advance_dispatch(RandomAccessIterator&amp; i, Distance n,
<b>random_access_iterator_tag</b>) {
i += n;
}
}
template &lt;class InputIterator, class Distance&gt;
void advance(InputIterator&amp; i, Distance n) {
typename <b>iterator_traits&lt;InputIterator&gt;::iterator_category</b> category;
detail::advance_dispatch(i, n, <b>category</b>);
}
}
</pre>
</blockquote>
<h2><a name="adaptors">Adaptors</a></h2>
<p>An <i>adaptor</i> is a class template which builds on another type or
types to provide a new interface or behavioral variant. Examples of
standard adaptors are <a href=
"http://www.sgi.com/tech/stl/ReverseIterator.html">std::reverse_iterator</a>,
which adapts an iterator type by reversing its motion upon
increment/decrement, and <a href=
"http://www.sgi.com/tech/stl/stack.html">std::stack</a>, which adapts a
container to provide a simple stack interface.</p>
<p>A more comprehensive review of the adaptors in the standard can be
found <a href="http://portal.acm.org/citation.cfm?id=249118.249120">
here</a>.</p>
<h2><a name="type_generator">Type Generators</a></h2>
<p><b>Note:</b> The <i>type generator</i> concept has largely been
superseded by the more refined notion of a <a href=
"../libs/mpl/doc/refmanual/metafunction.html"><i>metafunction</i></a>. See
<i><a href="http://www.boost-consulting.com/mplbook">C++ Template
Metaprogramming</a></i> for an in-depth discussion of metafunctions.</p>
<p>A <i>type generator</i> is a template whose only purpose is to
synthesize a new type or types based on its template argument(s)<a href=
"#1">[1]</a>. The generated type is usually expressed as a nested typedef
named, appropriately <tt>type</tt>. A type generator is usually used to
consolidate a complicated type expression into a simple one. This example
uses an old version of <tt><a href=
"../libs/iterator/doc/iterator_adaptor.html">iterator_adaptor</a></tt>
whose design didn't allow derived iterator types. As a result, every
adapted iterator had to be a specialization of <tt>iterator_adaptor</tt>
itself and generators were a convenient way to produce those types.</p>
<blockquote>
<pre>
template &lt;class Predicate, class Iterator,
class Value = <i>complicated default</i>,
class Reference = <i>complicated default</i>,
class Pointer = <i>complicated default</i>,
class Category = <i>complicated default</i>,
class Distance = <i>complicated default</i>
&gt;
struct filter_iterator_generator {
typedef iterator_adaptor&lt;
Iterator,filter_iterator_policies&lt;Predicate,Iterator&gt;,
Value,Reference,Pointer,Category,Distance&gt; <b>type</b>;
};
</pre>
</blockquote>
<p>Now, that's complicated, but producing an adapted filter iterator
using the generator is much easier. You can usually just write:</p>
<blockquote>
<pre>
boost::filter_iterator_generator&lt;my_predicate,my_base_iterator&gt;::type
</pre>
</blockquote>
<h2><a name="object_generator">Object Generators</a></h2>
<p>An <i>object generator</i> is a function template whose only purpose
is to construct a new object out of its arguments. Think of it as a kind
of generic constructor. An object generator may be more useful than a
plain constructor when the exact type to be generated is difficult or
impossible to express and the result of the generator can be passed
directly to a function rather than stored in a variable. Most Boost
object generators are named with the prefix "<tt>make_</tt>", after
<tt>std::<a href=
"http://www.sgi.com/tech/stl/pair.html">make_pair</a>(const&nbsp;T&amp;,&nbsp;const&nbsp;U&amp;)</tt>.</p>
<p>For example, given:</p>
<blockquote>
<pre>
struct widget {
void tweak(int);
};
std::vector&lt;widget *&gt; widget_ptrs;
</pre>
</blockquote>
By chaining two standard object generators, <tt>std::<a href=
"http://www.dinkumware.com/htm_cpl/functio2.html#bind2nd">bind2nd</a>()</tt>
and <tt>std::<a href=
"http://www.dinkumware.com/htm_cpl/functio2.html#mem_fun">mem_fun</a>()</tt>,
we can easily tweak all widgets:
<blockquote>
<pre>
void tweak_all_widgets1(int arg)
{
for_each(widget_ptrs.begin(), widget_ptrs.end(),
<b>bind2nd</b>(std::<b>mem_fun</b>(&amp;widget::tweak), arg));
}
</pre>
</blockquote>
<p>Without using object generators the example above would look like
this:</p>
<blockquote>
<pre>
void tweak_all_widgets2(int arg)
{
for_each(struct_ptrs.begin(), struct_ptrs.end(),
<b>std::binder2nd&lt;std::mem_fun1_t&lt;void, widget, int&gt; &gt;</b>(
std::<b>mem_fun1_t&lt;void, widget, int&gt;</b>(&amp;widget::tweak), arg));
}
</pre>
</blockquote>
<p>As expressions get more complicated the need to reduce the verbosity
of type specification gets more compelling.</p>
<h2><a name="policy">Policy Classes</a></h2>
<p>A policy class is a template parameter used to transmit behavior. An
example from the standard library is <tt>std::<a href=
"http://www.dinkumware.com/htm_cpl/memory.html#allocator">allocator</a></tt>,
which supplies memory management behaviors to standard <a href=
"http://www.sgi.com/tech/stl/Container.html">containers</a>.</p>
<p>Policy classes have been explored in detail by <a href=
"http://www.moderncppdesign.com/">Andrei Alexandrescu</a> in <a href=
"http://www.informit.com/articles/article.asp?p=167842">this chapter</a>
of his book, <i>Modern C++ Design</i>. He writes:</p>
<blockquote>
<p>In brief, policy-based class design fosters assembling a class with
complex behavior out of many little classes (called policies), each of
which takes care of only one behavioral or structural aspect. As the
name suggests, a policy establishes an interface pertaining to a
specific issue. You can implement policies in various ways as long as
you respect the policy interface.</p>
<p>Because you can mix and match policies, you can achieve a
combinatorial set of behaviors by using a small core of elementary
components.</p>
</blockquote>
<p>Andrei's description of policy classes suggests that their power is
derived from granularity and orthogonality. Less-granular policy
interfaces have been shown to work well in practice, though. <a href=
"http://cvs.sourceforge.net/viewcvs.py/*checkout*/boost/boost/libs/utility/Attic/iterator_adaptors.pdf">
This paper</a> describes an old version of <tt><a href=
"../libs/iterator/doc/iterator_adaptor.html">iterator_adaptor</a></tt>
that used non-orthogonal policies. There is also precedent in the
standard library: <tt><a href=
"http://www.dinkumware.com/htm_cpl/string2.html#char_traits">std::char_traits</a></tt>,
despite its name, acts as a policies class that determines the behaviors
of <a href=
"http://www.dinkumware.com/htm_cpl/string2.html#basic_string">std::basic_string</a>.</p>
<h2>Notes</h2>
<a name="1">[1]</a> Type generators are sometimes viewed as a workaround
for the lack of ``templated typedefs'' in C++.
<hr>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->18
August 2004<!--webbot bot="Timestamp" endspan i-checksum="14885" -->
</p>
<p>&copy; Copyright David Abrahams 2001. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided "as is" without
express or implied warranty, and with no claim as to its suitability for
any purpose.
<!-- LocalWords: HTML html charset gif alt htm struct SGI namespace std libs
-->
<!-- LocalWords: InputIterator BidirectionalIterator RandomAccessIterator pdf
-->
<!-- LocalWords: typename Alexandrescu templated Andrei's Abrahams memcpy int
-->
<!-- LocalWords: const OutputIterator iostream pre cpl
-->
</p>
</body>
</html>

12
getting_started.html
View File

@ -1,12 +0,0 @@
<html>
<head>
<meta http-equiv="refresh" content="0; URL=getting_started/index.html">
</head>
<body>
Automatically loading index page... if nothing happens, please go to
<a href="getting_started/index.html">getting_started/index.html</a>.
</body>
</html>
<!-- Copyright David Abrahams 2006. 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) -->

23
getting_started/Jamfile.v2
View File

@ -1,23 +0,0 @@
# Copyright David Abrahams 2006. 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)
import docutils ;
import path ;
sources = [ path.glob . : *.rst ] ;
bases = $(sources:S=) ;
# This is a path relative to the html/ subdirectory where the
# generated output will eventually be moved.
stylesheet = "--stylesheet=../../rst.css" ;
for local b in $(bases)
{
html $(b) : $(b).rst :
<docutils-html>"--link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet)
;
}
alias htmls : $(bases) ;
stage . : $(bases) ;

10
getting_started/detail/binary-head.rst
View File

@ -1,10 +0,0 @@
.. Copyright David Abrahams 2006. 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)
Prepare to Use a Boost Library Binary
=====================================
If you want to use any of the separately-compiled Boost libraries,
you'll need to acquire library binaries.

123
getting_started/detail/build-from-source-head.rst
View File

@ -1,123 +0,0 @@
.. Copyright David Abrahams 2006. 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)
Boost.Build_ is a text-based system for developing, testing, and
installing software. To use it, you'll need an executable called
``bjam``.
.. |precompiled-bjam| replace:: pre-compiled ``bjam`` executables
.. _precompiled-bjam: http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=72941
.. .. _Boost.Jam documentation: Boost.Jam_
.. _Boost.Build: ../../tools/build/index.html
.. _Boost.Jam: ../../tools/jam/index.html
.. _Boost.Build documentation: Boost.Build_
Get ``bjam``
............
``bjam`` is the |command-line tool| that drives the Boost Build
system. To build Boost binaries, you'll invoke ``bjam`` from the
Boost root.
Boost provides |precompiled-bjam|_ for a variety of platforms.
Alternatively, you can build ``bjam`` yourself using `these
instructions`__.
__ ../../doc/html/jam/building.html
.. _toolset:
.. _toolset-name:
Identify Your Toolset
.....................
First, find the toolset corresponding to your compiler in the
following table.
+-----------+--------------------+-----------------------------+
|Toolset |Vendor |Notes |
|Name | | |
+===========+====================+=============================+
|``acc`` |Hewlett Packard |Only very recent versions are|
| | |known to work well with Boost|
+-----------+--------------------+-----------------------------+
|``borland``|Borland | |
+-----------+--------------------+-----------------------------+
|``como`` |Comeau Computing |Using this toolset may |
| | |require configuring__ another|
| | |toolset to act as its backend|
+-----------+--------------------+-----------------------------+
|``cw`` |Metrowerks/FreeScale|The CodeWarrior compiler. We|
| | |have not tested versions of |
| | |this compiler produced since |
| | |it was sold to FreeScale. |
+-----------+--------------------+-----------------------------+
|``dmc`` |Digital Mars |As of this Boost release, no |
| | |version of dmc is known to |
| | |handle Boost well. |
+-----------+--------------------+-----------------------------+
|``darwin`` |Apple Computer |Apple's version of the GCC |
| | |toolchain with support for |
| | |Darwin and MacOS X features |
| | |such as frameworks. |
+-----------+--------------------+-----------------------------+
|``gcc`` |The Gnu Project |Includes support for Cygwin |
| | |and MinGW compilers. |
+-----------+--------------------+-----------------------------+
|``hp_cxx`` |Hewlett Packard |Targeted at the Tru64 |
| | |operating system. |
+-----------+--------------------+-----------------------------+
|``intel`` |Intel | |
+-----------+--------------------+-----------------------------+
|``kylix`` |Borland | |
+-----------+--------------------+-----------------------------+
|``msvc`` |Microsoft | |
+-----------+--------------------+-----------------------------+
|``qcc`` |QNX Software Systems| |
+-----------+--------------------+-----------------------------+
|``sun`` |Sun |Only very recent versions are|
| | |known to work well with |
| | |Boost. |
+-----------+--------------------+-----------------------------+
|``vacpp`` |IBM |The VisualAge C++ compiler. |
+-----------+--------------------+-----------------------------+
__ Boost.Build_
If you have multiple versions of a particular compiler installed,
you can append the version number to the toolset name, preceded by a
hyphen, e.g. ``msvc-7.1`` or ``gcc-3.4``.
.. Note:: if you built ``bjam`` yourself, you may
have selected a toolset name for that purpose, but that does not
affect this step in any way; you still need to select a Boost.Build
toolset from the table.
.. _build directory:
.. _build-directory:
Select a Build Directory
........................
Boost.Build_ will place all intermediate files it generates while
building into the **build directory**. If your Boost root
directory is writable, this step isn't strictly necessary: by
default Boost.Build will create a ``bin.v2/`` subdirectory for that
purpose in your current working directory.
Invoke ``bjam``
...............
.. |build-directory| replace:: *build-directory*
.. |toolset-name| replace:: *toolset-name*
Change your current directory to the Boost root directory and
invoke ``bjam`` as follows:
.. parsed-literal::
bjam **--build-dir=**\ |build-directory|_ **--toolset=**\ |toolset-name|_ stage

66
getting_started/detail/build-from-source-tail.rst
View File

@ -1,66 +0,0 @@
.. Copyright David Abrahams 2006. 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)
Boost.Build will place the Boost binaries in the ``stage``\ |/|
subdirectory of your `build directory`_.
.. Note:: ``bjam`` is case-sensitive; it is important that all the
parts shown in **bold** type above be entirely lower-case.
For a description of other options you can pass when invoking
``bjam``, type::
bjam --help
In particular, to limit the amount of time spent building, you may
be interested in:
* reviewing the list of library names with ``--show-libraries``
* limiting which libraries get built with the ``--with-``\
*library-name* or ``--without-``\ *library-name* options
* choosing a specific build variant by adding ``release`` or
``debug`` to the command line.
Expected Build Output
---------------------
During the process of building Boost libraries, you can expect to
see some messages printed on the console. These may include
* Notices about Boost library configuration—for example, the Regex
library outputs a message about ICU when built without Unicode
support, and the Python library may be skipped without error (but
with a notice) if you don't have Python installed.
* Messages from the build tool that report the number of targets
that were built or skipped. Don't be surprised if those numbers
don't make any sense to you; there are many targets per library.
* Build action messages describing what the tool is doing, which
look something like:
.. parsed-literal::
*toolset-name*.c++ *long*\ /\ *path*\ /\ *to*\ /\ *file*\ /\ *being*\ /\ *built*
* Compiler warnings.
In Case of Build Errors
-----------------------
The only error messages you see when building Boost—if any—should
be related to the IOStreams library's support of zip and bzip2
formats as described here__. Install the relevant development
packages for libz and libbz2 if you need those features. Other
errors when building Boost libraries are cause for concern.
__ ../../libs/iostreams/doc/installation.html
If it seems like the build system can't find your compiler and/or
linker, consider setting up a ``user-config.jam`` file as described
in the `Boost.Build documentation`_. If that isn't your problem or
the ``user-config.jam`` file doesn't work for you, please address
questions about configuring Boost for your compiler to the
`Boost.Build mailing list`_.

28
getting_started/detail/build-simple-head.rst
View File

@ -1,28 +0,0 @@
.. Copyright David Abrahams 2006. 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)
Build a Simple Program Using Boost
==================================
To keep things simple, let's start by using a header-only library.
The following program reads a sequence of integers from standard
input, uses Boost.Lambda to multiply each number by three, and
writes them to standard output::
#include <boost/lambda/lambda.hpp>
#include <iostream>
#include <iterator>
#include <algorithm>
int main()
{
using namespace boost::lambda;
typedef std::istream_iterator<int> in;
std::for_each(
in(std::cin), in(), std::cout << (_1 * 3) << " " );
}
Copy the text of this program into a file called ``example.cpp``.

26
getting_started/detail/common-footnotes.rst
View File

@ -1,26 +0,0 @@
.. Copyright David Abrahams 2006. 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)
.. [#warnings] Remember that warnings are specific to each compiler
implementation. The developer of a given Boost library might
not have access to your compiler. Also, some warnings are
extremely difficult to eliminate in generic code, to the point
where it's not worth the trouble. Finally, some compilers don't
have any source code mechanism for suppressing warnings.
.. [#distinct] This convention distinguishes the static version of
a Boost library from the import library for an
identically-configured Boost DLL, which would otherwise have the
same name.
.. [#debug-abi] These libraries were compiled without optimization
or inlining, with full debug symbols enabled, and without
``NDEBUG`` ``#define``\ d. Although it's true that sometimes
these choices don't affect binary compatibility with other
compiled code, you can't count on that with Boost libraries.
.. [#native] This feature of STLPort is deprecated because it's
impossible to make it work transparently to the user; we don't
recommend it.

21
getting_started/detail/common-unix.rst
View File

@ -1,21 +0,0 @@
.. Copyright David Abrahams 2006. 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)
.. |//| replace:: **/**
.. |/| replace:: ``/``
.. |default-root| replace:: ``/usr/local/``\ |boost_ver|
.. |default-root-bold| replace:: **/usr/local/**\ |boost_ver-bold|
.. |root| replace:: *path/to/*\ |boost_ver|
.. |forward-slashes| replace:: `` ``
.. |precompiled-dir| replace:: `` ``
.. |include-paths| replace:: `` ``
.. |command-line tool| replace:: command-line tool
.. include:: common.rst

29
getting_started/detail/common-windows.rst
View File

@ -1,29 +0,0 @@
.. Copyright David Abrahams 2006. 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)
.. |//| replace:: **\\**
.. |/| replace:: ``\``
.. |default-root| replace:: ``C:\Program Files\boost\``\ |boost_ver|
.. |default-root-bold| replace:: **C:\\Program Files\\boost\\**\ |boost_ver-bold|
.. |root| replace:: *path\\to\\*\ |boost_ver|
.. |include-paths| replace:: Specific steps for setting up ``#include``
paths in Microsoft Visual Studio follow later in this document;
if you use another IDE, please consult your product's
documentation for instructions.
.. |forward-slashes| replace:: Even Windows users can (and, for
portability reasons, probably should) use forward slashes in
``#include`` directives; your compiler doesn't care.
.. |precompiled-dir| replace::
**lib**\ |//| .....................\ *precompiled library binaries*
.. |command-line tool| replace:: `command-line tool`_
.. include:: common.rst

5
getting_started/detail/common.rst
View File

@ -1,5 +0,0 @@
.. Copyright David Abrahams 2006. 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)
.. |next| replace:: *skip to the next step*

39
getting_started/detail/conclusion.rst
View File

@ -1,39 +0,0 @@
.. Copyright David Abrahams 2006. 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)
Conclusion and Further Resources
================================
This concludes your introduction to Boost and to integrating it
with your programs. As you start using Boost in earnest, there are
surely a few additional points you'll wish we had covered. One day
we may have a “Book 2 in the Getting Started series” that addresses
them. Until then, we suggest you pursue the following resources.
If you can't find what you need, or there's anything we can do to
make this document clearer, please post it to the `Boost Users'
mailing list`_.
* `Boost.Build reference manual`_
* `Boost.Jam reference manual`_
* `Boost Users' mailing list`_
* `Boost.Build mailing list`_
* `Boost.Build Wiki`_
* `Index of all Boost library documentation`_
.. _Index of all Boost library documentation: ../../libs/index.html
.. Admonition:: Onward
.. epigraph::
Good luck, and have fun!
-- the Boost Developers
.. _Boost.Build reference manual: ../../tools/build/v2
.. _Boost.Jam reference manual: `Boost.Jam`_
.. _Boost Users' mailing list: ../../more/mailing_lists.htm#users
.. _Boost.Build Wiki: http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build_V2
.. _Boost.Build mailing list: ../../more/mailing_lists.htm#jamboost

88
getting_started/detail/distro.rst
View File

@ -1,88 +0,0 @@
.. Copyright David Abrahams 2006. 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)
The Boost Distribution
======================
This is a sketch of the resulting directory structure:
.. parsed-literal::
|boost_ver-bold|\ |//| .................\ *The “boost root directory”*
**index.htm** .........\ *A copy of www.boost.org starts here*
**boost**\ |//| .........................\ *All Boost Header files*
|precompiled-dir|
**libs**\ |//| ............\ *Tests, .cpp*\ s\ *, docs, etc., by library*
**index.html** ........\ *Library documentation starts here*
**algorithm**\ |//|
**any**\ |//|
**array**\ |//|
*…more libraries…*
**status**\ |//| .........................\ *Boost-wide test suite*
**tools**\ |//| ...........\ *Utilities, e.g. bjam, quickbook, bcp*
**more**\ |//| ..........................\ *Policy documents, etc.*
**doc**\ |//| ...............\ *A subset of all Boost library docs*
.. sidebar:: Header Organization
.. class:: pre-wrap
The organization of Boost library headers isn't entirely uniform,
but most libraries follow a few patterns:
* Some older libraries and most very small libraries place all
public headers directly into ``boost``\ |/|.
* Most libraries' public headers live in a subdirectory of
``boost``\ |/|, named after the library. For example, you'll find
the Python library's ``def.hpp`` header in
.. parsed-literal::
``boost``\ |/|\ ``python``\ |/|\ ``def.hpp``.
* Some libraries have an “aggregate header” in ``boost``\ |/| that
``#include``\ s all of the library's other headers. For
example, Boost.Python_'s aggregate header is
.. parsed-literal::
``boost``\ |/|\ ``python.hpp``.
* Most libraries place private headers in a subdirectory called
``detail``\ |/|, or ``aux_``\ |/|. Don't expect to find
anything you can use in these directories.
It's important to note the following:
.. _Boost root directory:
1. The path to the **boost root directory** (often |default-root|) is
sometimes referred to as ``$BOOST_ROOT`` in documentation and
mailing lists .
2. To compile anything in Boost, you need a directory containing
the ``boost``\ |/| subdirectory in your ``#include`` path. |include-paths|
3. Since all of Boost's header files have the ``.hpp`` extension,
and live in the ``boost``\ |/| subdirectory of the boost root, your
Boost ``#include`` directives will look like:
.. parsed-literal::
#include <boost/\ *whatever*\ .hpp>
or
.. parsed-literal::
#include "boost/\ *whatever*\ .hpp"
depending on your preference regarding the use of angle bracket
includes. |forward-slashes|
4. Don't be distracted by the ``doc``\ |/| subdirectory; it only
contains a subset of the Boost documentation. Start with
``libs``\ |/|\ ``index.html`` if you're looking for the whole enchilada.

16
getting_started/detail/errors-and-warnings.rst
View File

@ -1,16 +0,0 @@
.. Copyright David Abrahams 2006. 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)
Errors and Warnings
-------------------
Don't be alarmed if you see compiler warnings originating in Boost
headers. We try to eliminate them, but doing so isn't always
practical. [#warnings]_ **Errors are another matter**. If you're
seeing compilation errors at this point in the tutorial, check to
be sure you've copied the `example program`__ correctly and that you've
correctly identified the `Boost root directory`_.
__ `Build a Simple Program Using Boost`_

48
getting_started/detail/header-only.rst
View File

@ -1,48 +0,0 @@
.. Copyright David Abrahams 2006. 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)
Header-Only Libraries
=====================
The first thing many people want to know is, “how do I build
Boost?” The good news is that often, there's nothing to build.
.. admonition:: Nothing to Build?
Most Boost libraries are **header-only**: they consist *entirely
of header files* containing templates and inline functions, and
require no separately-compiled library binaries or special
treatment when linking.
.. .. _separate:
The only Boost libraries that *must* be built separately are:
* Boost.Filesystem_
* Boost.IOStreams_
* Boost.ProgramOptions_
* Boost.Python_ (see the `Boost.Python build documentation`__
before building and installing it)
* Boost.Regex_
* Boost.Serialization_
* Boost.Signals_
* Boost.Thread_
* Boost.Wave_
__ ../../libs/python/doc/building.html
A few libraries have optional separately-compiled binaries:
* Boost.DateTime_ has a binary component that is only needed if
you're using its ``to_string``\ /\ ``from_string`` or serialization
features, or if you're targeting Visual C++ 6.x or Borland.
* Boost.Graph_ also has a binary component that is only needed if
you intend to `parse GraphViz files`__.
* Boost.Test_ can be used in “header-only” or “separately compiled”
mode, although **separate compilation is recommended for serious
use**.
__ ../../libs/graph/doc/read_graphviz.html

80
getting_started/detail/library-naming.rst
View File

@ -1,80 +0,0 @@
.. Copyright David Abrahams 2006. 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)
In order to choose the right binary for your build configuration
you need to know how Boost binaries are named. Each library
filename is composed of a common sequence of elements that describe
how it was built. For example,
``libboost_regex-vc71-mt-d-1_34.lib`` can be broken down into the
following elements:
``lib``
*Prefix*: except on Microsoft Windows, every Boost library
name begins with this string. On Windows, only ordinary static
libraries use the ``lib`` prefix; import libraries and DLLs do
not. [#distinct]_
``boost_regex``
*Library name*: all boost library filenames begin with ``boost_``.
``-vc71``
*Toolset tag*: identifies the toolset_ and version used to build
the binary.
``-mt``
*Threading tag*: indicates that the library was
built with multithreading support enabled. Libraries built
without multithreading support can be identified by the absence
of ``-mt``.
``-d``
*ABI tag*: encodes details that affect the library's
interoperability with other compiled code. For each such
feature, a single letter is added to the tag:
+-----+------------------------------------------------------------------------------+
|Key |Use this library when: |
+=====+==============================================================================+
|``s``|linking statically to the C++ standard library and compiler runtime support |
| |libraries. |
+-----+------------------------------------------------------------------------------+
|``g``|using debug versions of the standard and runtime support libraries. |
+-----+------------------------------------------------------------------------------+
|``y``|using a special `debug build of Python`__. |
+-----+------------------------------------------------------------------------------+
|``d``|building a debug version of your code. [#debug-abi]_ |
+-----+------------------------------------------------------------------------------+
|``p``|using the STLPort standard library rather than the default one supplied with |
| |your compiler. |
+-----+------------------------------------------------------------------------------+
|``n``|using STLPort's deprecated “native iostreams” feature. [#native]_ |
+-----+------------------------------------------------------------------------------+
For example, if you build a debug version of your code for use
with debug versions of the static runtime library and the
STLPort standard library in “native iostreams” mode,
the tag would be: ``-sgdpn``. If none of the above apply, the
ABI tag is ommitted.
``-1_34``
*Version tag*: the full Boost release number, with periods
replaced by underscores. For example, version 1.31.1 would be
tagged as "-1_31_1".
``.lib``
*Extension*: determined according to the operating system's usual
convention. On most unix-style platforms the extensions are
``.a`` and ``.so`` for static libraries (archives) and shared
libraries, respectively. On Windows, ``.dll`` indicates a shared
library and (except for static libraries built by the ``gcc``
toolset_, whose names always end in ``.a``) ``.lib`` indicates a
static or import library. Where supported by toolsets on unix
variants, a full version extension is added (e.g. ".so.1.34") and
a symbolic link to the library file, named without the trailing
version number, will also be created.
.. .. _Boost.Build toolset names: toolset-name_
__ ../../libs/python/doc/building.html#variants

39
getting_started/detail/link-head.rst
View File

@ -1,39 +0,0 @@
.. Copyright David Abrahams 2006. 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)
Link Your Program to a Boost Library
====================================
To demonstrate linking with a Boost binary library, we'll use the
following simple program that extracts the subject lines from
emails. It uses the Boost.Regex_ library, which has a
separately-compiled binary component. ::
#include <boost/regex.hpp>
#include <iostream>
#include <string>
int main()
{
std::string line;
boost::regex pat( "^Subject: (Re: |Aw: )*(.*)" );
while (std::cin)
{
std::getline(std::cin, line);
boost::smatch matches;
if (boost::regex_match(line, matches, pat))
std::cout << matches[2] << std::endl;
}
}
There are two main challenges associated with linking:
1. Tool configuration, e.g. choosing command-line options or IDE
build settings.
2. Identifying the library binary, among all the build variants,
whose compile configuration is compatible with the rest of your
project.

16
getting_started/detail/links.rst
View File

@ -1,16 +0,0 @@
.. Copyright David Abrahams 2006. 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)
.. _Boost.DateTime: ../../libs/date_time/index.html
.. _Boost.Filesystem: ../../libs/filesystem/index.html
.. _Boost.Graph: ../../libs/graph/index.html
.. _Boost.IOStreams: ../../libs/iostreams/index.html
.. _Boost.ProgramOptions: ../../libs/program_options/index.html
.. _Boost.Python: ../../libs/python/doc/building.html
.. _Boost.Regex: ../../libs/regex/index.html
.. _Boost.Serialization: ../../libs/serialization/index.html
.. _Boost.Signals: ../../libs/signals/index.html
.. _Boost.Test: ../../libs/test/index.html
.. _Boost.Thread: ../../doc/html/thread/build.html#thread.build
.. _Boost.Wave: ../../libs/wave/index.html

12
getting_started/detail/release-variables.rst
View File

@ -1,12 +0,0 @@
.. Copyright David Abrahams 2006. 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)
.. This file contains all the definitions that need to be updated
.. for each new release of Boost.
.. |boost-version-number| replace:: 1.34.0
.. |boost_ver| replace:: ``boost_1_34_0``
.. |boost_ver-bold| replace:: **boost_1_34_0**
.. _sf-download: http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041

16
getting_started/detail/test-head.rst
View File

@ -1,16 +0,0 @@
.. Copyright David Abrahams 2006. 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)
Test Your Program
-----------------
To test our subject extraction, we'll filter the following text
file. Copy it out of your browser and save it as ``jayne.txt``::
To: George Shmidlap
From: Rita Marlowe
Subject: Will Success Spoil Rock Hunter?
---
See subject.

58
getting_started/index.html
View File

@ -1,58 +0,0 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Boost Getting Started</title>
<link rel="stylesheet" href="../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="logo-getting-started">
<h1 class="title"><a class="reference external" href="../../index.htm"><img alt="Boost" class="boost-logo" src="../../boost.png" /></a> Getting Started</h1>
<!-- Copyright David Abrahams 2006. 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) -->
<div class="section" id="welcome">
<h1>Welcome</h1>
<p>Welcome to the Boost libraries! By the time you've completed this
tutorial, you'll be at least somewhat comfortable with the contents
of a Boost distribution and how to go about using it.</p>
</div>
<div class="section" id="what-s-here">
<h1>What's Here</h1>
<p>This document is designed to be an <em>extremely</em> gentle introduction,
so we included a fair amount of material that may already be very
familiar to you. To keep things simple, we also left out some
information intermediate and advanced users will probably want. At
the end of this document, we'll refer you on to resources that can
help you pursue these topics further.</p>
</div>
<div class="section" id="preliminaries">
<h1>Preliminaries</h1>
<p>We use one typographic convention that might not be immediately
obvious: <em>italic</em> text in examples is meant as a descriptive
placeholder for something else, usually information that you'll
provide. For example:</p>
<pre class="literal-block">
<strong>$</strong> echo &quot;My name is <em>your name</em>&quot;
</pre>
<p>Here you're expected to imagine replacing the text “your name” with
your actual name.</p>
</div>
<div class="section" id="ready">
<h1>Ready?</h1>
<p>Let's go!</p>
</div>
</div>
<div class="footer">
<hr class="footer" />
<div class="nextpage line-block">
<div class="line"><strong>Next:</strong> <a class="reference external" href="windows.html">Getting Started on Microsoft Windows</a></div>
<div class="line"><strong>or:</strong> <a class="reference external" href="unix-variants.html">Getting Started on Unix variants (e.g. Linux, MacOS)</a></div>
</div>
</div>
</body>
</html>

60
getting_started/index.rst
View File

@ -1,60 +0,0 @@
.. Copyright David Abrahams 2006. 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)
============================
|(logo)|__ Getting Started
============================
.. |(logo)| image:: ../../boost.png
:alt: Boost
:class: boost-logo
__ ../../index.htm
Welcome
-------
Welcome to the Boost libraries! By the time you've completed this
tutorial, you'll be at least somewhat comfortable with the contents
of a Boost distribution and how to go about using it.
What's Here
-----------
This document is designed to be an *extremely* gentle introduction,
so we included a fair amount of material that may already be very
familiar to you. To keep things simple, we also left out some
information intermediate and advanced users will probably want. At
the end of this document, we'll refer you on to resources that can
help you pursue these topics further.
Preliminaries
-------------
We use one typographic convention that might not be immediately
obvious: *italic* text in examples is meant as a descriptive
placeholder for something else, usually information that you'll
provide. For example:
.. parsed-literal::
**$** echo "My name is *your name*\ "
Here you're expected to imagine replacing the text “your name” with
your actual name.
Ready?
------
Let's go!
.. footer::
.. class:: nextpage
| **Next:** `Getting Started on Microsoft Windows`__
| **or:** `Getting Started on Unix variants (e.g. Linux, MacOS)`__
__ windows.html
__ unix-variants.html

790
getting_started/unix-variants.html
View File

@ -1,790 +0,0 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Boost Getting Started on Unix Variants</title>
<meta content="Getting Started with Boost on Unix Variants (including Linux and MacOS)" name="description" />
<link rel="stylesheet" href="../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="logo-getting-started-on-unix-variants">
<h1 class="title"><a class="reference external" href="../../index.htm"><img alt="Boost" class="boost-logo" src="../../boost.png" /></a> Getting Started on Unix Variants</h1>
<!-- Copyright David Abrahams 2006. 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) -->
<!-- maybe we don't need this
.. Admonition:: A note to Cygwin_ and MinGW_ users
If you plan to build from the Cygwin_ bash shell, you're in the
right place. If you plan to use your tools from the Windows
command prompt, you should follow the instructions for `getting
started on Windows`_. Other command shells, such as MinGW_\ 's
MSYS, are not supported—they may or may not work.
.. _`Getting Started on Windows`: windows.html
.. _Cygwin: http://www.cygwin.com
.. _MinGW: http://mingw.org -->
<div class="contents topic" id="index">
<p class="topic-title first">Index</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#get-boost" id="id18">1&nbsp;&nbsp;&nbsp;Get Boost</a></li>
<li><a class="reference internal" href="#the-boost-distribution" id="id19">2&nbsp;&nbsp;&nbsp;The Boost Distribution</a></li>
<li><a class="reference internal" href="#header-only-libraries" id="id20">3&nbsp;&nbsp;&nbsp;Header-Only Libraries</a></li>
<li><a class="reference internal" href="#build-a-simple-program-using-boost" id="id21">4&nbsp;&nbsp;&nbsp;Build a Simple Program Using Boost</a><ul class="auto-toc">
<li><a class="reference internal" href="#errors-and-warnings" id="id22">4.1&nbsp;&nbsp;&nbsp;Errors and Warnings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#prepare-to-use-a-boost-library-binary" id="id23">5&nbsp;&nbsp;&nbsp;Prepare to Use a Boost Library Binary</a><ul class="auto-toc">
<li><a class="reference internal" href="#easy-build-and-install" id="id24">5.1&nbsp;&nbsp;&nbsp;Easy Build and Install</a></li>
<li><a class="reference internal" href="#or-custom-build-and-install" id="id25">5.2&nbsp;&nbsp;&nbsp;Or, Custom Build and Install</a><ul class="auto-toc">
<li><a class="reference internal" href="#get-bjam" id="id26">5.2.1&nbsp;&nbsp;&nbsp;Get <tt class="docutils literal"><span class="pre">bjam</span></tt></a></li>
<li><a class="reference internal" href="#identify-your-toolset" id="id27">5.2.2&nbsp;&nbsp;&nbsp;Identify Your Toolset</a></li>
<li><a class="reference internal" href="#select-a-build-directory" id="id28">5.2.3&nbsp;&nbsp;&nbsp;Select a Build Directory</a></li>
<li><a class="reference internal" href="#invoke-bjam" id="id29">5.2.4&nbsp;&nbsp;&nbsp;Invoke <tt class="docutils literal"><span class="pre">bjam</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#expected-build-output" id="id30">5.3&nbsp;&nbsp;&nbsp;Expected Build Output</a></li>
<li><a class="reference internal" href="#in-case-of-build-errors" id="id31">5.4&nbsp;&nbsp;&nbsp;In Case of Build Errors</a></li>
</ul>
</li>
<li><a class="reference internal" href="#link-your-program-to-a-boost-library" id="id32">6&nbsp;&nbsp;&nbsp;Link Your Program to a Boost Library</a><ul class="auto-toc">
<li><a class="reference internal" href="#library-naming" id="id33">6.1&nbsp;&nbsp;&nbsp;Library Naming</a></li>
<li><a class="reference internal" href="#test-your-program" id="id34">6.2&nbsp;&nbsp;&nbsp;Test Your Program</a></li>
</ul>
</li>
<li><a class="reference internal" href="#conclusion-and-further-resources" id="id35">7&nbsp;&nbsp;&nbsp;Conclusion and Further Resources</a></li>
</ul>
</div>
<div class="section" id="get-boost">
<h1><a class="toc-backref" href="#id18">1&nbsp;&nbsp;&nbsp;Get Boost</a></h1>
<p>The most reliable way to get a copy of Boost is to download a
distribution from <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041">SourceForge</a>:</p>
<ol class="arabic">
<li><p class="first">Download <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041"><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt><tt class="docutils literal"><span class="pre">.tar.bz2</span></tt></a>.</p>
</li>
<li><p class="first">In the directory where you want to put the Boost installation,
execute</p>
<pre class="literal-block">
tar --bzip2 -xf <em>/path/to/</em><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>.tar.bz2
</pre>
</li>
</ol>
<div class="admonition-other-packages admonition">
<p class="first admonition-title">Other Packages</p>
<p class="last">RedHat, Debian, and other distribution packagers supply Boost
library packages, however you may need to adapt these
instructions if you use third-party packages, because their
creators usually choose to break Boost up into several packages,
reorganize the directory structure of the Boost distribution,
and/or rename the library binaries.<a class="footnote-reference" href="#packagers" id="id2"><sup>1</sup></a> If you have
any trouble, we suggest using an official Boost distribution
from <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041">SourceForge</a>.</p>
</div>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
<div class="section" id="the-boost-distribution">
<h1><a class="toc-backref" href="#id19">2&nbsp;&nbsp;&nbsp;The Boost Distribution</a></h1>
<p>This is a sketch of the resulting directory structure:</p>
<pre class="literal-block">
<strong>boost_1_34_0</strong><strong>/</strong> .................<em>The “boost root directory”</em>
<strong>index.htm</strong> .........<em>A copy of www.boost.org starts here</em>
<strong>boost</strong><strong>/</strong> .........................<em>All Boost Header files</em>
<tt class="docutils literal"> </tt>
<strong>libs</strong><strong>/</strong> ............<em>Tests, .cpp</em>s<em>, docs, etc., by library</em>
<strong>index.html</strong> ........<em>Library documentation starts here</em>
<strong>algorithm</strong><strong>/</strong>
<strong>any</strong><strong>/</strong>
<strong>array</strong><strong>/</strong>
<em>…more libraries…</em>
<strong>status</strong><strong>/</strong> .........................<em>Boost-wide test suite</em>
<strong>tools</strong><strong>/</strong> ...........<em>Utilities, e.g. bjam, quickbook, bcp</em>
<strong>more</strong><strong>/</strong> ..........................<em>Policy documents, etc.</em>
<strong>doc</strong><strong>/</strong> ...............<em>A subset of all Boost library docs</em>
</pre>
<div class="sidebar">
<p class="first sidebar-title">Header Organization</p>
<p class="pre-wrap">The organization of Boost library headers isn't entirely uniform,
but most libraries follow a few patterns:</p>
<ul class="pre-wrap last">
<li><p class="first">Some older libraries and most very small libraries place all
public headers directly into <tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">/</span></tt>.</p>
</li>
<li><p class="first">Most libraries' public headers live in a subdirectory of
<tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">/</span></tt>, named after the library. For example, you'll find
the Python library's <tt class="docutils literal"><span class="pre">def.hpp</span></tt> header in</p>
<pre class="literal-block">
<tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">/</span></tt><tt class="docutils literal"><span class="pre">python</span></tt><tt class="docutils literal"><span class="pre">/</span></tt><tt class="docutils literal"><span class="pre">def.hpp</span></tt>.
</pre>
</li>
<li><p class="first">Some libraries have an “aggregate header” in <tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">/</span></tt> that
<tt class="docutils literal"><span class="pre">#include</span></tt>s all of the library's other headers. For
example, <a class="reference external" href="../../libs/python/doc/building.html">Boost.Python</a>'s aggregate header is</p>
<pre class="literal-block">
<tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">/</span></tt><tt class="docutils literal"><span class="pre">python.hpp</span></tt>.
</pre>
</li>
<li><p class="first">Most libraries place private headers in a subdirectory called
<tt class="docutils literal"><span class="pre">detail</span></tt><tt class="docutils literal"><span class="pre">/</span></tt>, or <tt class="docutils literal"><span class="pre">aux_</span></tt><tt class="docutils literal"><span class="pre">/</span></tt>. Don't expect to find
anything you can use in these directories.</p>
</li>
</ul>
</div>
<p>It's important to note the following:</p>
<ol class="arabic" id="boost-root-directory">
<li><p class="first">The path to the <strong>boost root directory</strong> (often <tt class="docutils literal"><span class="pre">/usr/local/</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>) is
sometimes referred to as <tt class="docutils literal"><span class="pre">$BOOST_ROOT</span></tt> in documentation and
mailing lists .</p>
</li>
<li><p class="first">To compile anything in Boost, you need a directory containing
the <tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">/</span></tt> subdirectory in your <tt class="docutils literal"><span class="pre">#include</span></tt> path. <tt class="docutils literal"> </tt></p>
</li>
<li><p class="first">Since all of Boost's header files have the <tt class="docutils literal"><span class="pre">.hpp</span></tt> extension,
and live in the <tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">/</span></tt> subdirectory of the boost root, your
Boost <tt class="docutils literal"><span class="pre">#include</span></tt> directives will look like:</p>
<pre class="literal-block">
#include &lt;boost/<em>whatever</em>.hpp&gt;
</pre>
<p>or</p>
<pre class="literal-block">
#include &quot;boost/<em>whatever</em>.hpp&quot;
</pre>
<p>depending on your preference regarding the use of angle bracket
includes. <tt class="docutils literal"> </tt></p>
</li>
<li><p class="first">Don't be distracted by the <tt class="docutils literal"><span class="pre">doc</span></tt><tt class="docutils literal"><span class="pre">/</span></tt> subdirectory; it only
contains a subset of the Boost documentation. Start with
<tt class="docutils literal"><span class="pre">libs</span></tt><tt class="docutils literal"><span class="pre">/</span></tt><tt class="docutils literal"><span class="pre">index.html</span></tt> if you're looking for the whole enchilada.</p>
</li>
</ol>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
<div class="section" id="header-only-libraries">
<h1><a class="toc-backref" href="#id20">3&nbsp;&nbsp;&nbsp;Header-Only Libraries</a></h1>
<p>The first thing many people want to know is, “how do I build
Boost?” The good news is that often, there's nothing to build.</p>
<div class="admonition-nothing-to-build admonition">
<p class="first admonition-title">Nothing to Build?</p>
<p class="last">Most Boost libraries are <strong>header-only</strong>: they consist <em>entirely
of header files</em> containing templates and inline functions, and
require no separately-compiled library binaries or special
treatment when linking.</p>
</div>
<!-- .. _separate: -->
<p>The only Boost libraries that <em>must</em> be built separately are:</p>
<ul class="simple">
<li><a class="reference external" href="../../libs/filesystem/index.html">Boost.Filesystem</a></li>
<li><a class="reference external" href="../../libs/iostreams/index.html">Boost.IOStreams</a></li>
<li><a class="reference external" href="../../libs/program_options/index.html">Boost.ProgramOptions</a></li>
<li><a class="reference external" href="../../libs/python/doc/building.html">Boost.Python</a> (see the <a class="reference external" href="../../libs/python/doc/building.html">Boost.Python build documentation</a>
before building and installing it)</li>
<li><a class="reference external" href="../../libs/regex/index.html">Boost.Regex</a></li>
<li><a class="reference external" href="../../libs/serialization/index.html">Boost.Serialization</a></li>
<li><a class="reference external" href="../../libs/signals/index.html">Boost.Signals</a></li>
<li><a class="reference external" href="../../doc/html/thread/build.html#thread.build">Boost.Thread</a></li>
<li><a class="reference external" href="../../libs/wave/index.html">Boost.Wave</a></li>
</ul>
<p>A few libraries have optional separately-compiled binaries:</p>
<ul class="simple">
<li><a class="reference external" href="../../libs/date_time/index.html">Boost.DateTime</a> has a binary component that is only needed if
you're using its <tt class="docutils literal"><span class="pre">to_string</span></tt>/<tt class="docutils literal"><span class="pre">from_string</span></tt> or serialization
features, or if you're targeting Visual C++ 6.x or Borland.</li>
<li><a class="reference external" href="../../libs/graph/index.html">Boost.Graph</a> also has a binary component that is only needed if
you intend to <a class="reference external" href="../../libs/graph/doc/read_graphviz.html">parse GraphViz files</a>.</li>
<li><a class="reference external" href="../../libs/test/index.html">Boost.Test</a> can be used in “header-only” or “separately compiled”
mode, although <strong>separate compilation is recommended for serious
use</strong>.</li>
</ul>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
<div class="section" id="build-a-simple-program-using-boost">
<h1><a class="toc-backref" href="#id21">4&nbsp;&nbsp;&nbsp;Build a Simple Program Using Boost</a></h1>
<p>To keep things simple, let's start by using a header-only library.
The following program reads a sequence of integers from standard
input, uses Boost.Lambda to multiply each number by three, and
writes them to standard output:</p>
<pre class="literal-block">
#include &lt;boost/lambda/lambda.hpp&gt;
#include &lt;iostream&gt;
#include &lt;iterator&gt;
#include &lt;algorithm&gt;
int main()
{
using namespace boost::lambda;
typedef std::istream_iterator&lt;int&gt; in;
std::for_each(
in(std::cin), in(), std::cout &lt;&lt; (_1 * 3) &lt;&lt; &quot; &quot; );
}
</pre>
<p>Copy the text of this program into a file called <tt class="docutils literal"><span class="pre">example.cpp</span></tt>.</p>
<p>Now, in the directory where you saved <tt class="docutils literal"><span class="pre">example.cpp</span></tt>, issue the
following command:</p>
<pre class="literal-block">
c++ -I <em>path/to/</em><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt> example.cpp -o example
</pre>
<p>To test the result, type:</p>
<pre class="literal-block">
echo 1 2 3 | ./example
</pre>
<!-- Copyright David Abrahams 2006. 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) -->
<div class="section" id="errors-and-warnings">
<h2><a class="toc-backref" href="#id22">4.1&nbsp;&nbsp;&nbsp;Errors and Warnings</a></h2>
<p>Don't be alarmed if you see compiler warnings originating in Boost
headers. We try to eliminate them, but doing so isn't always
practical.<a class="footnote-reference" href="#warnings" id="id5"><sup>3</sup></a> <strong>Errors are another matter</strong>. If you're
seeing compilation errors at this point in the tutorial, check to
be sure you've copied the <a class="reference internal" href="#build-a-simple-program-using-boost">example program</a> correctly and that you've
correctly identified the <a class="reference internal" href="#boost-root-directory">Boost root directory</a>.</p>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
</div>
<div class="section" id="prepare-to-use-a-boost-library-binary">
<h1><a class="toc-backref" href="#id23">5&nbsp;&nbsp;&nbsp;Prepare to Use a Boost Library Binary</a></h1>
<p>If you want to use any of the separately-compiled Boost libraries,
you'll need to acquire library binaries.</p>
<div class="section" id="easy-build-and-install">
<h2><a class="toc-backref" href="#id24">5.1&nbsp;&nbsp;&nbsp;Easy Build and Install</a></h2>
<p>Issue the following commands in the shell (don't type <tt class="docutils literal"><span class="pre">$</span></tt>; that
represents the shell's prompt):</p>
<pre class="literal-block">
<strong>$</strong> cd <em>path/to/</em><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>
<strong>$</strong> ./configure --help
</pre>
<p>Select your configuration options and invoke <tt class="docutils literal"><span class="pre">./configure</span></tt> again
without the <tt class="docutils literal"><span class="pre">--help</span></tt> option. Unless you have write permission in
your system's <tt class="docutils literal"><span class="pre">/usr/local/</span></tt> directory, you'll probably want to at
least use</p>
<pre class="literal-block">
<strong>$</strong> ./configure <strong>--prefix=</strong><em>path</em>/<em>to</em>/<em>installation</em>/<em>prefix</em>
</pre>
<p>to install somewhere else. Also, consider using the
<tt class="docutils literal"><span class="pre">--show-libraries</span></tt> and <tt class="docutils literal"><span class="pre">--with-libraries=</span></tt> options to limit the
long wait you'll experience if you build everything. Finally,</p>
<pre class="literal-block">
<strong>$</strong> make install
</pre>
<p>will leave Boost binaries in the <tt class="docutils literal"><span class="pre">lib/</span></tt> subdirectory of your
installation prefix. You will also find a copy of the Boost
headers in the <tt class="docutils literal"><span class="pre">include/</span></tt> subdirectory of the installation
prefix, so you can henceforth use that directory as an <tt class="docutils literal"><span class="pre">#include</span></tt>
path in place of the Boost root directory.</p>
<p><a class="reference internal" href="#link-your-program-to-a-boost-library"><em>skip to the next step</em></a></p>
</div>
<div class="section" id="or-custom-build-and-install">
<h2><a class="toc-backref" href="#id25">5.2&nbsp;&nbsp;&nbsp;Or, Custom Build and Install</a></h2>
<p>If you're using a compiler other than your system's default, you'll
need to use <a class="reference external" href="../../tools/build/index.html">Boost.Build</a> to create binaries. You'll also
use this method if you need a nonstandard build variant (see the
<a class="reference external" href="../../tools/build/index.html">Boost.Build documentation</a> for more details).</p>
<!-- Copyright David Abrahams 2006. 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) -->
<p><a class="reference external" href="../../tools/build/index.html">Boost.Build</a> is a text-based system for developing, testing, and
installing software. To use it, you'll need an executable called
<tt class="docutils literal"><span class="pre">bjam</span></tt>.</p>
<!-- .. _Boost.Jam documentation: Boost.Jam_ -->
<div class="section" id="get-bjam">
<h3><a class="toc-backref" href="#id26">5.2.1&nbsp;&nbsp;&nbsp;Get <tt class="docutils literal"><span class="pre">bjam</span></tt></a></h3>
<p><tt class="docutils literal"><span class="pre">bjam</span></tt> is the command-line tool that drives the Boost Build
system. To build Boost binaries, you'll invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> from the
Boost root.</p>
<p>Boost provides <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=72941">pre-compiled <tt class="docutils literal"><span class="pre">bjam</span></tt> executables</a> for a variety of platforms.
Alternatively, you can build <tt class="docutils literal"><span class="pre">bjam</span></tt> yourself using <a class="reference external" href="../../doc/html/jam/building.html">these
instructions</a>.</p>
</div>
<div class="section" id="identify-your-toolset">
<span id="toolset-name"></span><span id="toolset"></span><h3><a class="toc-backref" href="#id27">5.2.2&nbsp;&nbsp;&nbsp;Identify Your Toolset</a></h3>
<p>First, find the toolset corresponding to your compiler in the
following table.</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="33%" />
<col width="48%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Toolset
Name</th>
<th class="head">Vendor</th>
<th class="head">Notes</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">acc</span></tt></td>
<td>Hewlett Packard</td>
<td>Only very recent versions are
known to work well with Boost</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">borland</span></tt></td>
<td>Borland</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">como</span></tt></td>
<td>Comeau Computing</td>
<td>Using this toolset may
require <a class="reference external" href="../../tools/build/index.html">configuring</a> another
toolset to act as its backend</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">cw</span></tt></td>
<td>Metrowerks/FreeScale</td>
<td>The CodeWarrior compiler. We
have not tested versions of
this compiler produced since
it was sold to FreeScale.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">dmc</span></tt></td>
<td>Digital Mars</td>
<td>As of this Boost release, no
version of dmc is known to
handle Boost well.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">darwin</span></tt></td>
<td>Apple Computer</td>
<td>Apple's version of the GCC
toolchain with support for
Darwin and MacOS X features
such as frameworks.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">gcc</span></tt></td>
<td>The Gnu Project</td>
<td>Includes support for Cygwin
and MinGW compilers.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">hp_cxx</span></tt></td>
<td>Hewlett Packard</td>
<td>Targeted at the Tru64
operating system.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">intel</span></tt></td>
<td>Intel</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">kylix</span></tt></td>
<td>Borland</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">msvc</span></tt></td>
<td>Microsoft</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">qcc</span></tt></td>
<td>QNX Software Systems</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">sun</span></tt></td>
<td>Sun</td>
<td>Only very recent versions are
known to work well with
Boost.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">vacpp</span></tt></td>
<td>IBM</td>
<td>The VisualAge C++ compiler.</td>
</tr>
</tbody>
</table>
<p>If you have multiple versions of a particular compiler installed,
you can append the version number to the toolset name, preceded by a
hyphen, e.g. <tt class="docutils literal"><span class="pre">msvc-7.1</span></tt> or <tt class="docutils literal"><span class="pre">gcc-3.4</span></tt>.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">if you built <tt class="docutils literal"><span class="pre">bjam</span></tt> yourself, you may
have selected a toolset name for that purpose, but that does not
affect this step in any way; you still need to select a Boost.Build
toolset from the table.</p>
</div>
</div>
<div class="section" id="select-a-build-directory">
<span id="id10"></span><span id="build-directory"></span><h3><a class="toc-backref" href="#id28">5.2.3&nbsp;&nbsp;&nbsp;Select a Build Directory</a></h3>
<p><a class="reference external" href="../../tools/build/index.html">Boost.Build</a> will place all intermediate files it generates while
building into the <strong>build directory</strong>. If your Boost root
directory is writable, this step isn't strictly necessary: by
default Boost.Build will create a <tt class="docutils literal"><span class="pre">bin.v2/</span></tt> subdirectory for that
purpose in your current working directory.</p>
</div>
<div class="section" id="invoke-bjam">
<h3><a class="toc-backref" href="#id29">5.2.4&nbsp;&nbsp;&nbsp;Invoke <tt class="docutils literal"><span class="pre">bjam</span></tt></a></h3>
<p>Change your current directory to the Boost root directory and
invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> as follows:</p>
<pre class="literal-block">
bjam <strong>--build-dir=</strong><a class="reference internal" href="#id10"><em>build-directory</em></a> <strong>--toolset=</strong><a class="reference internal" href="#toolset-name"><em>toolset-name</em></a> stage
</pre>
<p>For example, your session might look like this:</p>
<pre class="literal-block">
$ cd ~/<tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>
$ bjam <strong>--build-dir=</strong>/tmp/build-boost <strong>--toolset=</strong>gcc
</pre>
<!-- Copyright David Abrahams 2006. 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) -->
<p>Boost.Build will place the Boost binaries in the <tt class="docutils literal"><span class="pre">stage</span></tt><tt class="docutils literal"><span class="pre">/</span></tt>
subdirectory of your <a class="reference internal" href="#build-directory">build directory</a>.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last"><tt class="docutils literal"><span class="pre">bjam</span></tt> is case-sensitive; it is important that all the
parts shown in <strong>bold</strong> type above be entirely lower-case.</p>
</div>
<p>For a description of other options you can pass when invoking
<tt class="docutils literal"><span class="pre">bjam</span></tt>, type:</p>
<pre class="literal-block">
bjam --help
</pre>
<p>In particular, to limit the amount of time spent building, you may
be interested in:</p>
<ul class="simple">
<li>reviewing the list of library names with <tt class="docutils literal"><span class="pre">--show-libraries</span></tt></li>
<li>limiting which libraries get built with the <tt class="docutils literal"><span class="pre">--with-</span></tt><em>library-name</em> or <tt class="docutils literal"><span class="pre">--without-</span></tt><em>library-name</em> options</li>
<li>choosing a specific build variant by adding <tt class="docutils literal"><span class="pre">release</span></tt> or
<tt class="docutils literal"><span class="pre">debug</span></tt> to the command line.</li>
</ul>
</div>
</div>
<div class="section" id="expected-build-output">
<h2><a class="toc-backref" href="#id30">5.3&nbsp;&nbsp;&nbsp;Expected Build Output</a></h2>
<p>During the process of building Boost libraries, you can expect to
see some messages printed on the console. These may include</p>
<ul>
<li><p class="first">Notices about Boost library configuration—for example, the Regex
library outputs a message about ICU when built without Unicode
support, and the Python library may be skipped without error (but
with a notice) if you don't have Python installed.</p>
</li>
<li><p class="first">Messages from the build tool that report the number of targets
that were built or skipped. Don't be surprised if those numbers
don't make any sense to you; there are many targets per library.</p>
</li>
<li><p class="first">Build action messages describing what the tool is doing, which
look something like:</p>
<pre class="literal-block">
<em>toolset-name</em>.c++ <em>long</em>/<em>path</em>/<em>to</em>/<em>file</em>/<em>being</em>/<em>built</em>
</pre>
</li>
<li><p class="first">Compiler warnings.</p>
</li>
</ul>
</div>
<div class="section" id="in-case-of-build-errors">
<h2><a class="toc-backref" href="#id31">5.4&nbsp;&nbsp;&nbsp;In Case of Build Errors</a></h2>
<p>The only error messages you see when building Boost—if any—should
be related to the IOStreams library's support of zip and bzip2
formats as described <a class="reference external" href="../../libs/iostreams/doc/installation.html">here</a>. Install the relevant development
packages for libz and libbz2 if you need those features. Other
errors when building Boost libraries are cause for concern.</p>
<p>If it seems like the build system can't find your compiler and/or
linker, consider setting up a <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file as described
in the <a class="reference external" href="../../tools/build/index.html">Boost.Build documentation</a>. If that isn't your problem or
the <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file doesn't work for you, please address
questions about configuring Boost for your compiler to the
<a class="reference external" href="../../more/mailing_lists.htm#jamboost">Boost.Build mailing list</a>.</p>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
</div>
<div class="section" id="link-your-program-to-a-boost-library">
<h1><a class="toc-backref" href="#id32">6&nbsp;&nbsp;&nbsp;Link Your Program to a Boost Library</a></h1>
<p>To demonstrate linking with a Boost binary library, we'll use the
following simple program that extracts the subject lines from
emails. It uses the <a class="reference external" href="../../libs/regex/index.html">Boost.Regex</a> library, which has a
separately-compiled binary component.</p>
<pre class="literal-block">
#include &lt;boost/regex.hpp&gt;
#include &lt;iostream&gt;
#include &lt;string&gt;
int main()
{
std::string line;
boost::regex pat( &quot;^Subject: (Re: |Aw: )*(.*)&quot; );
while (std::cin)
{
std::getline(std::cin, line);
boost::smatch matches;
if (boost::regex_match(line, matches, pat))
std::cout &lt;&lt; matches[2] &lt;&lt; std::endl;
}
}
</pre>
<p>There are two main challenges associated with linking:</p>
<ol class="arabic simple">
<li>Tool configuration, e.g. choosing command-line options or IDE
build settings.</li>
<li>Identifying the library binary, among all the build variants,
whose compile configuration is compatible with the rest of your
project.</li>
</ol>
<p>There are two main ways to link to libraries:</p>
<ol class="upperalpha">
<li><p class="first">You can specify the full path to each library:</p>
<pre class="literal-block">
$ c++ -I <em>path/to/</em><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt> example.cpp -o example <strong>\</strong>
<strong>~/boost/lib/libboost_regex-gcc-3.4-mt-d-1_34.a</strong>
</pre>
</li>
<li><p class="first">You can separately specify a directory to search (with <tt class="docutils literal"><span class="pre">-L</span></tt><em>directory</em>) and a library name to search for (with <tt class="docutils literal"><span class="pre">-l</span></tt><em>library</em>,<a class="footnote-reference" href="#lowercase-l" id="id12"><sup>2</sup></a> dropping the filename's leading <tt class="docutils literal"><span class="pre">lib</span></tt> and trailing
suffix (<tt class="docutils literal"><span class="pre">.a</span></tt> in this case):</p>
<pre class="literal-block">
$ c++ -I <em>path/to/</em><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt> example.cpp -o example <strong>\</strong>
<strong>-L~/boost/lib/ -lboost_regex-gcc-3.4-mt-d-1_34</strong>
</pre>
<p>As you can see, this method is just as terse as method A for one
library; it <em>really</em> pays off when you're using multiple
libraries from the same directory. Note, however, that if you
use this method with a library that has both static (<tt class="docutils literal"><span class="pre">.a</span></tt>) and
dynamic (<tt class="docutils literal"><span class="pre">.so</span></tt>) builds, the system may choose one
automatically for you unless you pass a special option such as
<tt class="docutils literal"><span class="pre">-static</span></tt> on the command line.</p>
</li>
</ol>
<p>In both cases above, the bold text is what you'd add to <a class="reference internal" href="#build-a-simple-program-using-boost">the
command lines we explored earlier</a>.</p>
<div class="section" id="library-naming">
<h2><a class="toc-backref" href="#id33">6.1&nbsp;&nbsp;&nbsp;Library Naming</a></h2>
<!-- Copyright David Abrahams 2006. 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) -->
<p>In order to choose the right binary for your build configuration
you need to know how Boost binaries are named. Each library
filename is composed of a common sequence of elements that describe
how it was built. For example,
<tt class="docutils literal"><span class="pre">libboost_regex-vc71-mt-d-1_34.lib</span></tt> can be broken down into the
following elements:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">lib</span></tt></dt>
<dd><em>Prefix</em>: except on Microsoft Windows, every Boost library
name begins with this string. On Windows, only ordinary static
libraries use the <tt class="docutils literal"><span class="pre">lib</span></tt> prefix; import libraries and DLLs do
not.<a class="footnote-reference" href="#distinct" id="id14"><sup>4</sup></a></dd>
<dt><tt class="docutils literal"><span class="pre">boost_regex</span></tt></dt>
<dd><em>Library name</em>: all boost library filenames begin with <tt class="docutils literal"><span class="pre">boost_</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">-vc71</span></tt></dt>
<dd><em>Toolset tag</em>: identifies the <a class="reference internal" href="#toolset">toolset</a> and version used to build
the binary.</dd>
<dt><tt class="docutils literal"><span class="pre">-mt</span></tt></dt>
<dd><em>Threading tag</em>: indicates that the library was
built with multithreading support enabled. Libraries built
without multithreading support can be identified by the absence
of <tt class="docutils literal"><span class="pre">-mt</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">-d</span></tt></dt>
<dd><p class="first"><em>ABI tag</em>: encodes details that affect the library's
interoperability with other compiled code. For each such
feature, a single letter is added to the tag:</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="6%" />
<col width="94%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Key</th>
<th class="head">Use this library when:</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">s</span></tt></td>
<td>linking statically to the C++ standard library and compiler runtime support
libraries.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">g</span></tt></td>
<td>using debug versions of the standard and runtime support libraries.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">y</span></tt></td>
<td>using a special <a class="reference external" href="../../libs/python/doc/building.html#variants">debug build of Python</a>.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">d</span></tt></td>
<td>building a debug version of your code.<a class="footnote-reference" href="#debug-abi" id="id15"><sup>5</sup></a></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">p</span></tt></td>
<td>using the STLPort standard library rather than the default one supplied with
your compiler.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">n</span></tt></td>
<td>using STLPort's deprecated “native iostreams” feature.<a class="footnote-reference" href="#native" id="id16"><sup>6</sup></a></td>
</tr>
</tbody>
</table>
</blockquote>
<p class="last">For example, if you build a debug version of your code for use
with debug versions of the static runtime library and the
STLPort standard library in “native iostreams” mode,
the tag would be: <tt class="docutils literal"><span class="pre">-sgdpn</span></tt>. If none of the above apply, the
ABI tag is ommitted.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">-1_34</span></tt></dt>
<dd><em>Version tag</em>: the full Boost release number, with periods
replaced by underscores. For example, version 1.31.1 would be
tagged as &quot;-1_31_1&quot;.</dd>
<dt><tt class="docutils literal"><span class="pre">.lib</span></tt></dt>
<dd><em>Extension</em>: determined according to the operating system's usual
convention. On most unix-style platforms the extensions are
<tt class="docutils literal"><span class="pre">.a</span></tt> and <tt class="docutils literal"><span class="pre">.so</span></tt> for static libraries (archives) and shared
libraries, respectively. On Windows, <tt class="docutils literal"><span class="pre">.dll</span></tt> indicates a shared
library and (except for static libraries built by the <tt class="docutils literal"><span class="pre">gcc</span></tt>
<a class="reference internal" href="#toolset">toolset</a>, whose names always end in <tt class="docutils literal"><span class="pre">.a</span></tt>) <tt class="docutils literal"><span class="pre">.lib</span></tt> indicates a
static or import library. Where supported by toolsets on unix
variants, a full version extension is added (e.g. &quot;.so.1.34&quot;) and
a symbolic link to the library file, named without the trailing
version number, will also be created.</dd>
</dl>
<!-- .. _Boost.Build toolset names: toolset-name_ -->
<!-- Copyright David Abrahams 2006. 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) -->
</div>
<div class="section" id="test-your-program">
<h2><a class="toc-backref" href="#id34">6.2&nbsp;&nbsp;&nbsp;Test Your Program</a></h2>
<p>To test our subject extraction, we'll filter the following text
file. Copy it out of your browser and save it as <tt class="docutils literal"><span class="pre">jayne.txt</span></tt>:</p>
<pre class="literal-block">
To: George Shmidlap
From: Rita Marlowe
Subject: Will Success Spoil Rock Hunter?
---
See subject.
</pre>
<p>If you linked to a shared library, you may need to prepare some
platform-specific settings so that the system will be able to find
and load it when your program is run. Most platforms have an
environment variable to which you can add the directory containing
the library. On many platforms (Linux, FreeBSD) that variable is
<tt class="docutils literal"><span class="pre">LD_LIBRARY_PATH</span></tt>, but on MacOS it's <tt class="docutils literal"><span class="pre">DYLD_LIBRARY_PATH</span></tt>, and
on Cygwin it's simply <tt class="docutils literal"><span class="pre">PATH</span></tt>. In most shells other than <tt class="docutils literal"><span class="pre">csh</span></tt>
and <tt class="docutils literal"><span class="pre">tcsh</span></tt>, you can adjust the variable as follows (again, don't
type the <tt class="docutils literal"><span class="pre">$</span></tt>—that represents the shell prompt):</p>
<pre class="literal-block">
<strong>$</strong> <em>VARIABLE_NAME</em>=<em>path/to/lib/directory</em>:${<em>VARIABLE_NAME</em>}
<strong>$</strong> export <em>VARIABLE_NAME</em>
</pre>
<p>On <tt class="docutils literal"><span class="pre">csh</span></tt> and <tt class="docutils literal"><span class="pre">tcsh</span></tt>, it's</p>
<pre class="literal-block">
<strong>$</strong> setenv <em>VARIABLE_NAME</em> <em>path/to/lib/directory</em>:${<em>VARIABLE_NAME</em>}
</pre>
<p>Once the necessary variable (if any) is set, you can run your
program as follows:</p>
<pre class="literal-block">
<strong>$</strong> <em>path</em>/<em>to</em>/<em>compiled</em>/example &lt; <em>path</em>/<em>to</em>/jayne.txt
</pre>
<p>The program should respond with the email subject, “Will Success
Spoil Rock Hunter?”</p>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
</div>
<div class="section" id="conclusion-and-further-resources">
<h1><a class="toc-backref" href="#id35">7&nbsp;&nbsp;&nbsp;Conclusion and Further Resources</a></h1>
<p>This concludes your introduction to Boost and to integrating it
with your programs. As you start using Boost in earnest, there are
surely a few additional points you'll wish we had covered. One day
we may have a “Book 2 in the Getting Started series” that addresses
them. Until then, we suggest you pursue the following resources.
If you can't find what you need, or there's anything we can do to
make this document clearer, please post it to the <a class="reference external" href="../../more/mailing_lists.htm#users">Boost Users'
mailing list</a>.</p>
<ul class="simple">
<li><a class="reference external" href="../../tools/build/v2">Boost.Build reference manual</a></li>
<li><a class="reference external" href="../../tools/jam/index.html">Boost.Jam reference manual</a></li>
<li><a class="reference external" href="../../more/mailing_lists.htm#users">Boost Users' mailing list</a></li>
<li><a class="reference external" href="../../more/mailing_lists.htm#jamboost">Boost.Build mailing list</a></li>
<li><a class="reference external" href="http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build_V2">Boost.Build Wiki</a></li>
<li><a class="reference external" href="../../libs/index.html">Index of all Boost library documentation</a></li>
</ul>
<div class="admonition-onward admonition">
<p class="first admonition-title">Onward</p>
<blockquote class="epigraph last">
<p>Good luck, and have fun!</p>
<p class="attribution">&mdash;the Boost Developers</p>
</blockquote>
</div>
<hr class="docutils" />
<table class="docutils footnote" frame="void" id="packagers" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td><p class="first">If developers of Boost packages would like to work
with us to make sure these instructions can be used with their
packages, we'd be glad to help. Please make your interest known
to the <a class="reference external" href="../../more/mailing_lists.htm#main">Boost developers' list</a>.</p>
</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="lowercase-l" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id12">[2]</a></td><td>That option is a dash followed by a lowercase “L”
character, which looks very much like a numeral 1 in some fonts.</td></tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. 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) -->
<table class="docutils footnote" frame="void" id="warnings" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[3]</a></td><td>Remember that warnings are specific to each compiler
implementation. The developer of a given Boost library might
not have access to your compiler. Also, some warnings are
extremely difficult to eliminate in generic code, to the point
where it's not worth the trouble. Finally, some compilers don't
have any source code mechanism for suppressing warnings.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="distinct" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id14">[4]</a></td><td>This convention distinguishes the static version of
a Boost library from the import library for an
identically-configured Boost DLL, which would otherwise have the
same name.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="debug-abi" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id15">[5]</a></td><td>These libraries were compiled without optimization
or inlining, with full debug symbols enabled, and without
<tt class="docutils literal"><span class="pre">NDEBUG</span></tt> <tt class="docutils literal"><span class="pre">#define</span></tt>d. Although it's true that sometimes
these choices don't affect binary compatibility with other
compiled code, you can't count on that with Boost libraries.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="native" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id16">[6]</a></td><td>This feature of STLPort is deprecated because it's
impossible to make it work transparently to the user; we don't
recommend it.</td></tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. 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) -->
<!-- This file contains all the definitions that need to be updated -->
<!-- for each new release of Boost. -->
<!-- Copyright David Abrahams 2006. 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) -->
<!-- Copyright David Abrahams 2006. 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) -->
<!-- Copyright David Abrahams 2006. 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) -->
</div>
</div>
</body>
</html>

236
getting_started/unix-variants.rst
View File

@ -1,236 +0,0 @@
.. Copyright David Abrahams 2006. 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)
=============================================
|(logo)|__ Getting Started on Unix Variants
=============================================
.. meta::
:description: Getting Started with Boost on Unix Variants (including Linux and MacOS)
.. |(logo)| image:: ../../boost.png
:alt: Boost
:class: boost-logo
__ ../../index.htm
.. section-numbering::
.. maybe we don't need this
.. Admonition:: A note to Cygwin_ and MinGW_ users
If you plan to build from the Cygwin_ bash shell, you're in the
right place. If you plan to use your tools from the Windows
command prompt, you should follow the instructions for `getting
started on Windows`_. Other command shells, such as MinGW_\ 's
MSYS, are not supported—they may or may not work.
.. _`Getting Started on Windows`: windows.html
.. _Cygwin: http://www.cygwin.com
.. _MinGW: http://mingw.org
.. Contents:: Index
Get Boost
=========
The most reliable way to get a copy of Boost is to download a
distribution from SourceForge_:
.. _SourceForge: `sf-download`_
1. Download |boost.tar.bz2|_.
2. In the directory where you want to put the Boost installation,
execute
.. parsed-literal::
tar --bzip2 -xf */path/to/*\ |boost_ver|\ .tar.bz2
.. |boost.tar.bz2| replace:: |boost_ver|\ ``.tar.bz2``
.. _`boost.tar.bz2`: `sf-download`_
.. Admonition:: Other Packages
RedHat, Debian, and other distribution packagers supply Boost
library packages, however you may need to adapt these
instructions if you use third-party packages, because their
creators usually choose to break Boost up into several packages,
reorganize the directory structure of the Boost distribution,
and/or rename the library binaries. [#packagers]_ If you have
any trouble, we suggest using an official Boost distribution
from SourceForge_.
.. include:: detail/distro.rst
.. include:: detail/header-only.rst
.. include:: detail/build-simple-head.rst
Now, in the directory where you saved ``example.cpp``, issue the
following command:
.. parsed-literal::
c++ -I |root| example.cpp -o example
To test the result, type:
.. parsed-literal::
echo 1 2 3 | ./example
.. include:: detail/errors-and-warnings.rst
.. include:: detail/binary-head.rst
Easy Build and Install
----------------------
Issue the following commands in the shell (don't type ``$``; that
represents the shell's prompt):
.. parsed-literal::
**$** cd |root|
**$** ./configure --help
Select your configuration options and invoke ``./configure`` again
without the ``--help`` option. Unless you have write permission in
your system's ``/usr/local/`` directory, you'll probably want to at
least use
.. parsed-literal::
**$** ./configure **--prefix=**\ *path*\ /\ *to*\ /\ *installation*\ /\ *prefix*
to install somewhere else. Also, consider using the
``--show-libraries`` and ``--with-libraries=`` options to limit the
long wait you'll experience if you build everything. Finally,
.. parsed-literal::
**$** make install
will leave Boost binaries in the ``lib/`` subdirectory of your
installation prefix. You will also find a copy of the Boost
headers in the ``include/`` subdirectory of the installation
prefix, so you can henceforth use that directory as an ``#include``
path in place of the Boost root directory.
|next|__
__ `Link Your Program to a Boost Library`_
Or, Custom Build and Install
----------------------------
If you're using a compiler other than your system's default, you'll
need to use Boost.Build_ to create binaries. You'll also
use this method if you need a nonstandard build variant (see the
`Boost.Build documentation`_ for more details).
.. include:: detail/build-from-source-head.rst
For example, your session might look like this:
.. parsed-literal::
$ cd ~/|boost_ver|
$ bjam **--build-dir=**\ /tmp/build-boost **--toolset=**\ gcc
.. include:: detail/build-from-source-tail.rst
.. include:: detail/link-head.rst
There are two main ways to link to libraries:
A. You can specify the full path to each library:
.. parsed-literal::
$ c++ -I |root| example.cpp -o example **\\**
**~/boost/lib/libboost_regex-gcc-3.4-mt-d-1_34.a**
B. You can separately specify a directory to search (with ``-L``\
*directory*) and a library name to search for (with ``-l``\
*library*, [#lowercase-l]_ dropping the filename's leading ``lib`` and trailing
suffix (``.a`` in this case):
.. parsed-literal::
$ c++ -I |root| example.cpp -o example **\\**
**-L~/boost/lib/ -lboost_regex-gcc-3.4-mt-d-1_34**
As you can see, this method is just as terse as method A for one
library; it *really* pays off when you're using multiple
libraries from the same directory. Note, however, that if you
use this method with a library that has both static (``.a``) and
dynamic (``.so``) builds, the system may choose one
automatically for you unless you pass a special option such as
``-static`` on the command line.
In both cases above, the bold text is what you'd add to `the
command lines we explored earlier`__.
__ `build a simple program using boost`_
Library Naming
--------------
.. include:: detail/library-naming.rst
.. include:: detail/test-head.rst
If you linked to a shared library, you may need to prepare some
platform-specific settings so that the system will be able to find
and load it when your program is run. Most platforms have an
environment variable to which you can add the directory containing
the library. On many platforms (Linux, FreeBSD) that variable is
``LD_LIBRARY_PATH``, but on MacOS it's ``DYLD_LIBRARY_PATH``, and
on Cygwin it's simply ``PATH``. In most shells other than ``csh``
and ``tcsh``, you can adjust the variable as follows (again, don't
type the ``$``\ —that represents the shell prompt):
.. parsed-literal::
**$** *VARIABLE_NAME*\ =\ *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ }
**$** export *VARIABLE_NAME*
On ``csh`` and ``tcsh``, it's
.. parsed-literal::
**$** setenv *VARIABLE_NAME* *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ }
Once the necessary variable (if any) is set, you can run your
program as follows:
.. parsed-literal::
**$** *path*\ /\ *to*\ /\ *compiled*\ /\ example < *path*\ /\ *to*\ /\ jayne.txt
The program should respond with the email subject, “Will Success
Spoil Rock Hunter?”
.. include:: detail/conclusion.rst
------------------------------
.. [#packagers] If developers of Boost packages would like to work
with us to make sure these instructions can be used with their
packages, we'd be glad to help. Please make your interest known
to the `Boost developers' list`_.
.. _Boost developers' list: ../../more/mailing_lists.htm#main
.. [#lowercase-l] That option is a dash followed by a lowercase “L”
character, which looks very much like a numeral 1 in some fonts.
.. include:: detail/common-footnotes.rst
.. include:: detail/release-variables.rst
.. include:: detail/common-unix.rst
.. include:: detail/links.rst

874
getting_started/windows.html
View File

@ -1,874 +0,0 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Boost Getting Started on Windows</title>
<link rel="stylesheet" href="../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="logo-getting-started-on-windows">
<h1 class="title"><a class="reference external" href="../../index.htm"><img alt="Boost" class="boost-logo" src="../../boost.png" /></a> Getting Started on Windows</h1>
<!-- Copyright David Abrahams 2006. 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) -->
<div class="admonition-a-note-to-cygwin-and-mingw-users admonition">
<p class="first admonition-title">A note to <a class="reference external" href="http://www.cygwin.com">Cygwin</a> and <a class="reference external" href="http://mingw.org">MinGW</a> users</p>
<p class="last">If you plan to use your tools from the Windows command prompt,
you're in the right place. If you plan to build from the <a class="reference external" href="http://www.cygwin.com">Cygwin</a>
bash shell, you're actually running on a POSIX platform and
should follow the instructions for <a class="reference external" href="unix-variants.html">getting started on Unix
variants</a>. Other command shells, such as <a class="reference external" href="http://mingw.org">MinGW</a>'s MSYS, are
not supported—they may or may not work.</p>
</div>
<div class="contents topic" id="index">
<p class="topic-title first">Index</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#get-boost" id="id22">1&nbsp;&nbsp;&nbsp;Get Boost</a></li>
<li><a class="reference internal" href="#the-boost-distribution" id="id23">2&nbsp;&nbsp;&nbsp;The Boost Distribution</a></li>
<li><a class="reference internal" href="#header-only-libraries" id="id24">3&nbsp;&nbsp;&nbsp;Header-Only Libraries</a></li>
<li><a class="reference internal" href="#build-a-simple-program-using-boost" id="id25">4&nbsp;&nbsp;&nbsp;Build a Simple Program Using Boost</a><ul class="auto-toc">
<li><a class="reference internal" href="#build-from-the-visual-studio-ide" id="id26">4.1&nbsp;&nbsp;&nbsp;Build From the Visual Studio IDE</a></li>
<li><a class="reference internal" href="#or-build-from-the-command-prompt" id="id27">4.2&nbsp;&nbsp;&nbsp;Or, Build From the Command Prompt</a></li>
<li><a class="reference internal" href="#errors-and-warnings" id="id28">4.3&nbsp;&nbsp;&nbsp;Errors and Warnings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#prepare-to-use-a-boost-library-binary" id="id29">5&nbsp;&nbsp;&nbsp;Prepare to Use a Boost Library Binary</a><ul class="auto-toc">
<li><a class="reference internal" href="#install-visual-studio-2005-or-net-2003-binaries" id="id30">5.1&nbsp;&nbsp;&nbsp;Install Visual Studio (2005 or .NET 2003) Binaries</a></li>
<li><a class="reference internal" href="#or-build-and-install-binaries-from-source" id="id31">5.2&nbsp;&nbsp;&nbsp;Or, Build and Install Binaries From Source</a><ul class="auto-toc">
<li><a class="reference internal" href="#get-bjam" id="id32">5.2.1&nbsp;&nbsp;&nbsp;Get <tt class="docutils literal"><span class="pre">bjam</span></tt></a></li>
<li><a class="reference internal" href="#identify-your-toolset" id="id33">5.2.2&nbsp;&nbsp;&nbsp;Identify Your Toolset</a></li>
<li><a class="reference internal" href="#select-a-build-directory" id="id34">5.2.3&nbsp;&nbsp;&nbsp;Select a Build Directory</a></li>
<li><a class="reference internal" href="#invoke-bjam" id="id35">5.2.4&nbsp;&nbsp;&nbsp;Invoke <tt class="docutils literal"><span class="pre">bjam</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#expected-build-output" id="id36">5.3&nbsp;&nbsp;&nbsp;Expected Build Output</a></li>
<li><a class="reference internal" href="#in-case-of-build-errors" id="id37">5.4&nbsp;&nbsp;&nbsp;In Case of Build Errors</a></li>
</ul>
</li>
<li><a class="reference internal" href="#link-your-program-to-a-boost-library" id="id38">6&nbsp;&nbsp;&nbsp;Link Your Program to a Boost Library</a><ul class="auto-toc">
<li><a class="reference internal" href="#link-from-within-the-visual-studio-ide" id="id39">6.1&nbsp;&nbsp;&nbsp;Link From Within the Visual Studio IDE</a></li>
<li><a class="reference internal" href="#or-link-from-the-command-prompt" id="id40">6.2&nbsp;&nbsp;&nbsp;Or, Link From the Command Prompt</a></li>
<li><a class="reference internal" href="#library-naming" id="id41">6.3&nbsp;&nbsp;&nbsp;Library Naming</a></li>
<li><a class="reference internal" href="#test-your-program" id="id42">6.4&nbsp;&nbsp;&nbsp;Test Your Program</a></li>
</ul>
</li>
<li><a class="reference internal" href="#conclusion-and-further-resources" id="id43">7&nbsp;&nbsp;&nbsp;Conclusion and Further Resources</a></li>
</ul>
</div>
<div class="section" id="get-boost">
<h1><a class="toc-backref" href="#id22">1&nbsp;&nbsp;&nbsp;Get Boost</a></h1>
<p>The easiest way to get a copy of Boost is to use the <a class="reference external" href="http://www.boost-consulting.com/download/windows">installer</a>
provided by <a class="reference external" href="http://www.boost-consulting.com">Boost Consulting</a>. We especially recommend this
method if you use Microsoft Visual Studio .NET 2003 or Microsoft
Visual Studio 2005, because the installer can download and install
precompiled library binaries, saving you the trouble of building
them yourself. To complete this tutorial, you'll need to at least
install the <a class="reference external" href="../../libs/regex/index.html">Boost.Regex</a> binaries when given the option.</p>
<p>If you're using an earlier version of Visual Studio or some other
compiler, or if you prefer to build everything yourself, you can
download <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041"><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt><tt class="docutils literal"><span class="pre">.exe</span></tt></a> and run it to install a complete Boost
distribution.<a class="footnote-reference" href="#zip" id="id2"><sup>1</sup></a></p>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
<div class="section" id="the-boost-distribution">
<h1><a class="toc-backref" href="#id23">2&nbsp;&nbsp;&nbsp;The Boost Distribution</a></h1>
<p>This is a sketch of the resulting directory structure:</p>
<pre class="literal-block">
<strong>boost_1_34_0</strong><strong>\</strong> .................<em>The “boost root directory”</em>
<strong>index.htm</strong> .........<em>A copy of www.boost.org starts here</em>
<strong>boost</strong><strong>\</strong> .........................<em>All Boost Header files</em>
<strong>lib</strong><strong>\</strong> .....................<em>precompiled library binaries</em>
<strong>libs</strong><strong>\</strong> ............<em>Tests, .cpp</em>s<em>, docs, etc., by library</em>
<strong>index.html</strong> ........<em>Library documentation starts here</em>
<strong>algorithm</strong><strong>\</strong>
<strong>any</strong><strong>\</strong>
<strong>array</strong><strong>\</strong>
<em>…more libraries…</em>
<strong>status</strong><strong>\</strong> .........................<em>Boost-wide test suite</em>
<strong>tools</strong><strong>\</strong> ...........<em>Utilities, e.g. bjam, quickbook, bcp</em>
<strong>more</strong><strong>\</strong> ..........................<em>Policy documents, etc.</em>
<strong>doc</strong><strong>\</strong> ...............<em>A subset of all Boost library docs</em>
</pre>
<div class="sidebar">
<p class="first sidebar-title">Header Organization</p>
<p class="pre-wrap">The organization of Boost library headers isn't entirely uniform,
but most libraries follow a few patterns:</p>
<ul class="pre-wrap last">
<li><p class="first">Some older libraries and most very small libraries place all
public headers directly into <tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">\</span></tt>.</p>
</li>
<li><p class="first">Most libraries' public headers live in a subdirectory of
<tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">\</span></tt>, named after the library. For example, you'll find
the Python library's <tt class="docutils literal"><span class="pre">def.hpp</span></tt> header in</p>
<pre class="literal-block">
<tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">\</span></tt><tt class="docutils literal"><span class="pre">python</span></tt><tt class="docutils literal"><span class="pre">\</span></tt><tt class="docutils literal"><span class="pre">def.hpp</span></tt>.
</pre>
</li>
<li><p class="first">Some libraries have an “aggregate header” in <tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">\</span></tt> that
<tt class="docutils literal"><span class="pre">#include</span></tt>s all of the library's other headers. For
example, <a class="reference external" href="../../libs/python/doc/building.html">Boost.Python</a>'s aggregate header is</p>
<pre class="literal-block">
<tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">\</span></tt><tt class="docutils literal"><span class="pre">python.hpp</span></tt>.
</pre>
</li>
<li><p class="first">Most libraries place private headers in a subdirectory called
<tt class="docutils literal"><span class="pre">detail</span></tt><tt class="docutils literal"><span class="pre">\</span></tt>, or <tt class="docutils literal"><span class="pre">aux_</span></tt><tt class="docutils literal"><span class="pre">\</span></tt>. Don't expect to find
anything you can use in these directories.</p>
</li>
</ul>
</div>
<p>It's important to note the following:</p>
<ol class="arabic" id="boost-root-directory">
<li><p class="first">The path to the <strong>boost root directory</strong> (often <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>) is
sometimes referred to as <tt class="docutils literal"><span class="pre">$BOOST_ROOT</span></tt> in documentation and
mailing lists .</p>
</li>
<li><p class="first">To compile anything in Boost, you need a directory containing
the <tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">\</span></tt> subdirectory in your <tt class="docutils literal"><span class="pre">#include</span></tt> path. Specific steps for setting up <tt class="docutils literal"><span class="pre">#include</span></tt>
paths in Microsoft Visual Studio follow later in this document;
if you use another IDE, please consult your product's
documentation for instructions.</p>
</li>
<li><p class="first">Since all of Boost's header files have the <tt class="docutils literal"><span class="pre">.hpp</span></tt> extension,
and live in the <tt class="docutils literal"><span class="pre">boost</span></tt><tt class="docutils literal"><span class="pre">\</span></tt> subdirectory of the boost root, your
Boost <tt class="docutils literal"><span class="pre">#include</span></tt> directives will look like:</p>
<pre class="literal-block">
#include &lt;boost/<em>whatever</em>.hpp&gt;
</pre>
<p>or</p>
<pre class="literal-block">
#include &quot;boost/<em>whatever</em>.hpp&quot;
</pre>
<p>depending on your preference regarding the use of angle bracket
includes. Even Windows users can (and, for
portability reasons, probably should) use forward slashes in
<tt class="docutils literal"><span class="pre">#include</span></tt> directives; your compiler doesn't care.</p>
</li>
<li><p class="first">Don't be distracted by the <tt class="docutils literal"><span class="pre">doc</span></tt><tt class="docutils literal"><span class="pre">\</span></tt> subdirectory; it only
contains a subset of the Boost documentation. Start with
<tt class="docutils literal"><span class="pre">libs</span></tt><tt class="docutils literal"><span class="pre">\</span></tt><tt class="docutils literal"><span class="pre">index.html</span></tt> if you're looking for the whole enchilada.</p>
</li>
</ol>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
<div class="section" id="header-only-libraries">
<h1><a class="toc-backref" href="#id24">3&nbsp;&nbsp;&nbsp;Header-Only Libraries</a></h1>
<p>The first thing many people want to know is, “how do I build
Boost?” The good news is that often, there's nothing to build.</p>
<div class="admonition-nothing-to-build admonition">
<p class="first admonition-title">Nothing to Build?</p>
<p class="last">Most Boost libraries are <strong>header-only</strong>: they consist <em>entirely
of header files</em> containing templates and inline functions, and
require no separately-compiled library binaries or special
treatment when linking.</p>
</div>
<!-- .. _separate: -->
<p>The only Boost libraries that <em>must</em> be built separately are:</p>
<ul class="simple">
<li><a class="reference external" href="../../libs/filesystem/index.html">Boost.Filesystem</a></li>
<li><a class="reference external" href="../../libs/iostreams/index.html">Boost.IOStreams</a></li>
<li><a class="reference external" href="../../libs/program_options/index.html">Boost.ProgramOptions</a></li>
<li><a class="reference external" href="../../libs/python/doc/building.html">Boost.Python</a> (see the <a class="reference external" href="../../libs/python/doc/building.html">Boost.Python build documentation</a>
before building and installing it)</li>
<li><a class="reference external" href="../../libs/regex/index.html">Boost.Regex</a></li>
<li><a class="reference external" href="../../libs/serialization/index.html">Boost.Serialization</a></li>
<li><a class="reference external" href="../../libs/signals/index.html">Boost.Signals</a></li>
<li><a class="reference external" href="../../doc/html/thread/build.html#thread.build">Boost.Thread</a></li>
<li><a class="reference external" href="../../libs/wave/index.html">Boost.Wave</a></li>
</ul>
<p>A few libraries have optional separately-compiled binaries:</p>
<ul class="simple">
<li><a class="reference external" href="../../libs/date_time/index.html">Boost.DateTime</a> has a binary component that is only needed if
you're using its <tt class="docutils literal"><span class="pre">to_string</span></tt>/<tt class="docutils literal"><span class="pre">from_string</span></tt> or serialization
features, or if you're targeting Visual C++ 6.x or Borland.</li>
<li><a class="reference external" href="../../libs/graph/index.html">Boost.Graph</a> also has a binary component that is only needed if
you intend to <a class="reference external" href="../../libs/graph/doc/read_graphviz.html">parse GraphViz files</a>.</li>
<li><a class="reference external" href="../../libs/test/index.html">Boost.Test</a> can be used in “header-only” or “separately compiled”
mode, although <strong>separate compilation is recommended for serious
use</strong>.</li>
</ul>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
<div class="section" id="build-a-simple-program-using-boost">
<h1><a class="toc-backref" href="#id25">4&nbsp;&nbsp;&nbsp;Build a Simple Program Using Boost</a></h1>
<p>To keep things simple, let's start by using a header-only library.
The following program reads a sequence of integers from standard
input, uses Boost.Lambda to multiply each number by three, and
writes them to standard output:</p>
<pre class="literal-block">
#include &lt;boost/lambda/lambda.hpp&gt;
#include &lt;iostream&gt;
#include &lt;iterator&gt;
#include &lt;algorithm&gt;
int main()
{
using namespace boost::lambda;
typedef std::istream_iterator&lt;int&gt; in;
std::for_each(
in(std::cin), in(), std::cout &lt;&lt; (_1 * 3) &lt;&lt; &quot; &quot; );
}
</pre>
<p>Copy the text of this program into a file called <tt class="docutils literal"><span class="pre">example.cpp</span></tt>.</p>
<div class="note" id="command-line-tool">
<span id="command-prompt"></span><p class="first admonition-title">Note</p>
<p class="last">To build the examples in this guide, you can use an
Integrated Development Environment (IDE) like Visual Studio, or
you can issue commands from the <a class="reference internal" href="#command-prompt">command prompt</a>. Since every
IDE and compiler has different options and Microsoft's are by
far the dominant compilers on Windows, we only give specific
directions here for Visual Studio 2005 and .NET 2003 IDEs and
their respective command prompt compilers (using the command
prompt is a bit simpler). If you are using another compiler or
IDE, it should be relatively easy to adapt these instructions to
your environment.</p>
</div>
<div class="small sidebar">
<p class="first sidebar-title">Command Prompt Basics</p>
<p>In Windows, a command-line tool is invoked by typing its name,
optionally followed by arguments, into a <em>Command Prompt</em> window
and pressing the Return (or Enter) key.</p>
<p>To open a generic <em>Command Prompt</em>, click the <em>Start</em> menu
button, click <em>Run</em>, type “cmd”, and then click <em>OK</em>.</p>
<p id="current-directory">All commands are executed within the context of a <strong>current
directory</strong> in the filesystem. To set the current directory,
type:</p>
<pre class="literal-block">
cd <em>path</em>\<em>to</em>\<em>some</em>\<em>directory</em>
</pre>
<p>followed by Return. For example,</p>
<pre class="literal-block">
cd <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>
</pre>
<p class="last">Long commands can be continued across several lines by typing a
caret (<tt class="docutils literal"><span class="pre">^</span></tt>) at the end of all but the last line. Some examples
on this page use that technique to save horizontal space.</p>
</div>
<div class="section" id="build-from-the-visual-studio-ide">
<span id="vs-header-only"></span><h2><a class="toc-backref" href="#id26">4.1&nbsp;&nbsp;&nbsp;Build From the Visual Studio IDE</a></h2>
<ul>
<li><p class="first">From Visual Studio's <em>File</em> menu, select <em>New</em> &gt; <em>Project…</em></p>
</li>
<li><p class="first">In the left-hand pane of the resulting <em>New Project</em> dialog,
select <em>Visual C++</em> &gt; <em>Win32</em>.</p>
</li>
<li><p class="first">In the right-hand pane, select <em>Win32 Console Application</em>
(VS8.0) or <em>Win32 Console Project</em> (VS7.1).</p>
</li>
<li><p class="first">In the <em>name</em> field, enter “example”</p>
</li>
<li><p class="first">Right-click <strong>example</strong> in the <em>Solution Explorer</em> pane and
select <em>Properties</em> from the resulting pop-up menu</p>
</li>
<li><p class="first">In <em>Configuration Properties</em> &gt; <em>C/C++</em> &gt; <em>General</em> &gt; <em>Additional Include
Directories</em>, enter the path to the Boost root directory, for example</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt></p>
</blockquote>
</li>
<li><p class="first">In <em>Configuration Properties</em> &gt; <em>C/C++</em> &gt; <em>Precompiled Headers</em>, change
<em>Use Precompiled Header (/Yu)</em> to <em>Not Using Precompiled
Headers</em>.<a class="footnote-reference" href="#pch" id="id5"><sup>3</sup></a></p>
</li>
<li><p class="first">Replace the contents of the <tt class="docutils literal"><span class="pre">example.cpp</span></tt> generated by the IDE
with the example code above.</p>
</li>
<li><p class="first">From the <em>Build</em> menu, select <em>Build Solution</em>.</p>
</li>
</ul>
<p>To test your application, hit the F5 key and type the following
into the resulting window, followed by the Return key:</p>
<pre class="literal-block">
1 2 3
</pre>
<p>Then hold down the control key and press &quot;Z&quot;, followed by the
Return key.</p>
<p><a class="reference internal" href="#errors-and-warnings"><em>skip to the next step</em></a></p>
</div>
<div class="section" id="or-build-from-the-command-prompt">
<h2><a class="toc-backref" href="#id27">4.2&nbsp;&nbsp;&nbsp;Or, Build From the Command Prompt</a></h2>
<p>From your computer's <em>Start</em> menu, if you are a Visual
Studio 2005 user, select</p>
<blockquote>
<em>All Programs</em> &gt; <em>Microsoft Visual Studio 2005</em>
&gt; <em>Visual Studio Tools</em> &gt; <em>Visual Studio 2005 Command Prompt</em></blockquote>
<p>or, if you're a Visual Studio .NET 2003 user, select</p>
<blockquote>
<em>All Programs</em> &gt; <em>Microsoft Visual Studio .NET 2003</em>
&gt; <em>Visual Studio .NET Tools</em> &gt; <em>Visual Studio .NET 2003 Command Prompt</em></blockquote>
<p>to bring up a special <a class="reference internal" href="#command-prompt">command prompt</a> window set up for the
Visual Studio compiler. In that window, set the <a class="reference internal" href="#current-directory">current
directory</a> to a suitable location for creating some temporary
files and type the following command followed by the Return key:</p>
<pre class="literal-block">
cl /EHsc /I <em>path\to\</em><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt> <em>path</em>\<em>to</em>\example.cpp
</pre>
<p>To test the result, type:</p>
<pre class="literal-block">
echo 1 2 3 | example
</pre>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
<div class="section" id="errors-and-warnings">
<h2><a class="toc-backref" href="#id28">4.3&nbsp;&nbsp;&nbsp;Errors and Warnings</a></h2>
<p>Don't be alarmed if you see compiler warnings originating in Boost
headers. We try to eliminate them, but doing so isn't always
practical.<a class="footnote-reference" href="#warnings" id="id7"><sup>5</sup></a> <strong>Errors are another matter</strong>. If you're
seeing compilation errors at this point in the tutorial, check to
be sure you've copied the <a class="reference internal" href="#build-a-simple-program-using-boost">example program</a> correctly and that you've
correctly identified the <a class="reference internal" href="#boost-root-directory">Boost root directory</a>.</p>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
</div>
<div class="section" id="prepare-to-use-a-boost-library-binary">
<h1><a class="toc-backref" href="#id29">5&nbsp;&nbsp;&nbsp;Prepare to Use a Boost Library Binary</a></h1>
<p>If you want to use any of the separately-compiled Boost libraries,
you'll need to acquire library binaries.</p>
<div class="section" id="install-visual-studio-2005-or-net-2003-binaries">
<h2><a class="toc-backref" href="#id30">5.1&nbsp;&nbsp;&nbsp;Install Visual Studio (2005 or .NET 2003) Binaries</a></h2>
<p>The <a class="reference external" href="http://www.boost-consulting.com/download/windows">installer</a> supplied by Boost Consulting will download and
install pre-compiled binaries into the <tt class="docutils literal"><span class="pre">lib\</span></tt> subdirectory of the
boost root, typically <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt><tt class="docutils literal"><span class="pre">\lib\</span></tt>. If you installed
all variants of the <a class="reference external" href="../../libs/regex/index.html">Boost.Regex</a> binary, you're done with this
step. Otherwise, please run the installer again and install them
now.</p>
<p><a class="reference internal" href="#link-your-program-to-a-boost-library"><em>skip to the next step</em></a></p>
</div>
<div class="section" id="or-build-and-install-binaries-from-source">
<h2><a class="toc-backref" href="#id31">5.2&nbsp;&nbsp;&nbsp;Or, Build and Install Binaries From Source</a></h2>
<p>If you're using an earlier version of Visual C++, or a compiler
from another vendor, you'll need to use <a class="reference external" href="../../tools/build/index.html">Boost.Build</a> to create your
own binaries.</p>
<!-- Copyright David Abrahams 2006. 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) -->
<p><a class="reference external" href="../../tools/build/index.html">Boost.Build</a> is a text-based system for developing, testing, and
installing software. To use it, you'll need an executable called
<tt class="docutils literal"><span class="pre">bjam</span></tt>.</p>
<!-- .. _Boost.Jam documentation: Boost.Jam_ -->
<div class="section" id="get-bjam">
<h3><a class="toc-backref" href="#id32">5.2.1&nbsp;&nbsp;&nbsp;Get <tt class="docutils literal"><span class="pre">bjam</span></tt></a></h3>
<p><tt class="docutils literal"><span class="pre">bjam</span></tt> is the <a class="reference internal" href="#command-line-tool">command-line tool</a> that drives the Boost Build
system. To build Boost binaries, you'll invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> from the
Boost root.</p>
<p>Boost provides <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=72941">pre-compiled <tt class="docutils literal"><span class="pre">bjam</span></tt> executables</a> for a variety of platforms.
Alternatively, you can build <tt class="docutils literal"><span class="pre">bjam</span></tt> yourself using <a class="reference external" href="../../doc/html/jam/building.html">these
instructions</a>.</p>
</div>
<div class="section" id="identify-your-toolset">
<span id="toolset-name"></span><span id="toolset"></span><h3><a class="toc-backref" href="#id33">5.2.2&nbsp;&nbsp;&nbsp;Identify Your Toolset</a></h3>
<p>First, find the toolset corresponding to your compiler in the
following table.</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="33%" />
<col width="48%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Toolset
Name</th>
<th class="head">Vendor</th>
<th class="head">Notes</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">acc</span></tt></td>
<td>Hewlett Packard</td>
<td>Only very recent versions are
known to work well with Boost</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">borland</span></tt></td>
<td>Borland</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">como</span></tt></td>
<td>Comeau Computing</td>
<td>Using this toolset may
require <a class="reference external" href="../../tools/build/index.html">configuring</a> another
toolset to act as its backend</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">cw</span></tt></td>
<td>Metrowerks/FreeScale</td>
<td>The CodeWarrior compiler. We
have not tested versions of
this compiler produced since
it was sold to FreeScale.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">dmc</span></tt></td>
<td>Digital Mars</td>
<td>As of this Boost release, no
version of dmc is known to
handle Boost well.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">darwin</span></tt></td>
<td>Apple Computer</td>
<td>Apple's version of the GCC
toolchain with support for
Darwin and MacOS X features
such as frameworks.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">gcc</span></tt></td>
<td>The Gnu Project</td>
<td>Includes support for Cygwin
and MinGW compilers.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">hp_cxx</span></tt></td>
<td>Hewlett Packard</td>
<td>Targeted at the Tru64
operating system.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">intel</span></tt></td>
<td>Intel</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">kylix</span></tt></td>
<td>Borland</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">msvc</span></tt></td>
<td>Microsoft</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">qcc</span></tt></td>
<td>QNX Software Systems</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">sun</span></tt></td>
<td>Sun</td>
<td>Only very recent versions are
known to work well with
Boost.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">vacpp</span></tt></td>
<td>IBM</td>
<td>The VisualAge C++ compiler.</td>
</tr>
</tbody>
</table>
<p>If you have multiple versions of a particular compiler installed,
you can append the version number to the toolset name, preceded by a
hyphen, e.g. <tt class="docutils literal"><span class="pre">msvc-7.1</span></tt> or <tt class="docutils literal"><span class="pre">gcc-3.4</span></tt>.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">if you built <tt class="docutils literal"><span class="pre">bjam</span></tt> yourself, you may
have selected a toolset name for that purpose, but that does not
affect this step in any way; you still need to select a Boost.Build
toolset from the table.</p>
</div>
</div>
<div class="section" id="select-a-build-directory">
<span id="id12"></span><span id="build-directory"></span><h3><a class="toc-backref" href="#id34">5.2.3&nbsp;&nbsp;&nbsp;Select a Build Directory</a></h3>
<p><a class="reference external" href="../../tools/build/index.html">Boost.Build</a> will place all intermediate files it generates while
building into the <strong>build directory</strong>. If your Boost root
directory is writable, this step isn't strictly necessary: by
default Boost.Build will create a <tt class="docutils literal"><span class="pre">bin.v2/</span></tt> subdirectory for that
purpose in your current working directory.</p>
</div>
<div class="section" id="invoke-bjam">
<h3><a class="toc-backref" href="#id35">5.2.4&nbsp;&nbsp;&nbsp;Invoke <tt class="docutils literal"><span class="pre">bjam</span></tt></a></h3>
<p>Change your current directory to the Boost root directory and
invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> as follows:</p>
<pre class="literal-block">
bjam <strong>--build-dir=</strong><a class="reference internal" href="#id12"><em>build-directory</em></a> <strong>--toolset=</strong><a class="reference internal" href="#toolset-name"><em>toolset-name</em></a> stage
</pre>
<p>For example, your session might look like this:<a class="footnote-reference" href="#continuation" id="id13"><sup>4</sup></a></p>
<pre class="literal-block">
C:WINDOWS&gt; cd <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>
<tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>&gt; bjam <strong>^</strong>
More? <strong>--build-dir=</strong>%TEMP%\build-boost <strong>^</strong>
More? <strong>--toolset=</strong>msvc stage
</pre>
<!-- Copyright David Abrahams 2006. 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) -->
<p>Boost.Build will place the Boost binaries in the <tt class="docutils literal"><span class="pre">stage</span></tt><tt class="docutils literal"><span class="pre">\</span></tt>
subdirectory of your <a class="reference internal" href="#build-directory">build directory</a>.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last"><tt class="docutils literal"><span class="pre">bjam</span></tt> is case-sensitive; it is important that all the
parts shown in <strong>bold</strong> type above be entirely lower-case.</p>
</div>
<p>For a description of other options you can pass when invoking
<tt class="docutils literal"><span class="pre">bjam</span></tt>, type:</p>
<pre class="literal-block">
bjam --help
</pre>
<p>In particular, to limit the amount of time spent building, you may
be interested in:</p>
<ul class="simple">
<li>reviewing the list of library names with <tt class="docutils literal"><span class="pre">--show-libraries</span></tt></li>
<li>limiting which libraries get built with the <tt class="docutils literal"><span class="pre">--with-</span></tt><em>library-name</em> or <tt class="docutils literal"><span class="pre">--without-</span></tt><em>library-name</em> options</li>
<li>choosing a specific build variant by adding <tt class="docutils literal"><span class="pre">release</span></tt> or
<tt class="docutils literal"><span class="pre">debug</span></tt> to the command line.</li>
</ul>
</div>
</div>
<div class="section" id="expected-build-output">
<h2><a class="toc-backref" href="#id36">5.3&nbsp;&nbsp;&nbsp;Expected Build Output</a></h2>
<p>During the process of building Boost libraries, you can expect to
see some messages printed on the console. These may include</p>
<ul>
<li><p class="first">Notices about Boost library configuration—for example, the Regex
library outputs a message about ICU when built without Unicode
support, and the Python library may be skipped without error (but
with a notice) if you don't have Python installed.</p>
</li>
<li><p class="first">Messages from the build tool that report the number of targets
that were built or skipped. Don't be surprised if those numbers
don't make any sense to you; there are many targets per library.</p>
</li>
<li><p class="first">Build action messages describing what the tool is doing, which
look something like:</p>
<pre class="literal-block">
<em>toolset-name</em>.c++ <em>long</em>/<em>path</em>/<em>to</em>/<em>file</em>/<em>being</em>/<em>built</em>
</pre>
</li>
<li><p class="first">Compiler warnings.</p>
</li>
</ul>
</div>
<div class="section" id="in-case-of-build-errors">
<h2><a class="toc-backref" href="#id37">5.4&nbsp;&nbsp;&nbsp;In Case of Build Errors</a></h2>
<p>The only error messages you see when building Boost—if any—should
be related to the IOStreams library's support of zip and bzip2
formats as described <a class="reference external" href="../../libs/iostreams/doc/installation.html">here</a>. Install the relevant development
packages for libz and libbz2 if you need those features. Other
errors when building Boost libraries are cause for concern.</p>
<p>If it seems like the build system can't find your compiler and/or
linker, consider setting up a <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file as described
in the <a class="reference external" href="../../tools/build/index.html">Boost.Build documentation</a>. If that isn't your problem or
the <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file doesn't work for you, please address
questions about configuring Boost for your compiler to the
<a class="reference external" href="../../more/mailing_lists.htm#jamboost">Boost.Build mailing list</a>.</p>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
</div>
<div class="section" id="link-your-program-to-a-boost-library">
<h1><a class="toc-backref" href="#id38">6&nbsp;&nbsp;&nbsp;Link Your Program to a Boost Library</a></h1>
<p>To demonstrate linking with a Boost binary library, we'll use the
following simple program that extracts the subject lines from
emails. It uses the <a class="reference external" href="../../libs/regex/index.html">Boost.Regex</a> library, which has a
separately-compiled binary component.</p>
<pre class="literal-block">
#include &lt;boost/regex.hpp&gt;
#include &lt;iostream&gt;
#include &lt;string&gt;
int main()
{
std::string line;
boost::regex pat( &quot;^Subject: (Re: |Aw: )*(.*)&quot; );
while (std::cin)
{
std::getline(std::cin, line);
boost::smatch matches;
if (boost::regex_match(line, matches, pat))
std::cout &lt;&lt; matches[2] &lt;&lt; std::endl;
}
}
</pre>
<p>There are two main challenges associated with linking:</p>
<ol class="arabic simple">
<li>Tool configuration, e.g. choosing command-line options or IDE
build settings.</li>
<li>Identifying the library binary, among all the build variants,
whose compile configuration is compatible with the rest of your
project.</li>
</ol>
<div class="admonition-auto-linking admonition">
<p class="first admonition-title">Auto-Linking</p>
<p class="last">Most Windows compilers and linkers have so-called “auto-linking
support,” which eliminates the second challenge. Special code in
Boost header files detects your compiler options and uses that
information to encode the name of the correct library into your
object files; the linker selects the library with that name from
the directories you've told it to search.</p>
</div>
<div class="section" id="link-from-within-the-visual-studio-ide">
<h2><a class="toc-backref" href="#id39">6.1&nbsp;&nbsp;&nbsp;Link From Within the Visual Studio IDE</a></h2>
<p>Starting with the <a class="reference internal" href="#vs-header-only">header-only example project</a> we created
earlier:</p>
<ol class="arabic simple">
<li>Right-click <strong>example</strong> in the <em>Solution Explorer</em> pane and
select <em>Properties</em> from the resulting pop-up menu</li>
<li>In <em>Configuration Properties</em> &gt; <em>Linker</em> &gt; <em>Additional Library
Directories</em>, enter the path to the Boost binaries,
e.g. <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt><tt class="docutils literal"><span class="pre">\lib\</span></tt>.</li>
<li>From the <em>Build</em> menu, select <em>Build Solution</em>.</li>
</ol>
<p><a class="reference internal" href="#test-your-program"><em>skip to the next step</em></a></p>
</div>
<div class="section" id="or-link-from-the-command-prompt">
<h2><a class="toc-backref" href="#id40">6.2&nbsp;&nbsp;&nbsp;Or, Link From the Command Prompt</a></h2>
<p>For example, we can compile and link the above program from the
Visual C++ command-line by simply adding the <strong>bold</strong> text below to
the command line we used earlier, assuming your Boost binaries are
in <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt><tt class="docutils literal"><span class="pre">\lib</span></tt>:</p>
<pre class="literal-block">
cl /EHsc /I <em>path\to\</em><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt> example.cpp <strong>^</strong>
<strong>/link /LIBPATH:</strong> <strong>C:\Program Files\boost\</strong><strong>boost_1_34_0</strong><strong>\lib</strong>
</pre>
</div>
<div class="section" id="library-naming">
<h2><a class="toc-backref" href="#id41">6.3&nbsp;&nbsp;&nbsp;Library Naming</a></h2>
<div class="note">
<p class="first admonition-title">Note</p>
<p>If, like Visual C++, your compiler supports auto-linking,
you can probably <a class="reference internal" href="#test-your-program"><em>skip to the next step</em></a>.</p>
<blockquote class="last">
</blockquote>
</div>
<!-- Copyright David Abrahams 2006. 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) -->
<p>In order to choose the right binary for your build configuration
you need to know how Boost binaries are named. Each library
filename is composed of a common sequence of elements that describe
how it was built. For example,
<tt class="docutils literal"><span class="pre">libboost_regex-vc71-mt-d-1_34.lib</span></tt> can be broken down into the
following elements:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">lib</span></tt></dt>
<dd><em>Prefix</em>: except on Microsoft Windows, every Boost library
name begins with this string. On Windows, only ordinary static
libraries use the <tt class="docutils literal"><span class="pre">lib</span></tt> prefix; import libraries and DLLs do
not.<a class="footnote-reference" href="#distinct" id="id18"><sup>6</sup></a></dd>
<dt><tt class="docutils literal"><span class="pre">boost_regex</span></tt></dt>
<dd><em>Library name</em>: all boost library filenames begin with <tt class="docutils literal"><span class="pre">boost_</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">-vc71</span></tt></dt>
<dd><em>Toolset tag</em>: identifies the <a class="reference internal" href="#toolset">toolset</a> and version used to build
the binary.</dd>
<dt><tt class="docutils literal"><span class="pre">-mt</span></tt></dt>
<dd><em>Threading tag</em>: indicates that the library was
built with multithreading support enabled. Libraries built
without multithreading support can be identified by the absence
of <tt class="docutils literal"><span class="pre">-mt</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">-d</span></tt></dt>
<dd><p class="first"><em>ABI tag</em>: encodes details that affect the library's
interoperability with other compiled code. For each such
feature, a single letter is added to the tag:</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="6%" />
<col width="94%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Key</th>
<th class="head">Use this library when:</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">s</span></tt></td>
<td>linking statically to the C++ standard library and compiler runtime support
libraries.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">g</span></tt></td>
<td>using debug versions of the standard and runtime support libraries.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">y</span></tt></td>
<td>using a special <a class="reference external" href="../../libs/python/doc/building.html#variants">debug build of Python</a>.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">d</span></tt></td>
<td>building a debug version of your code.<a class="footnote-reference" href="#debug-abi" id="id19"><sup>7</sup></a></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">p</span></tt></td>
<td>using the STLPort standard library rather than the default one supplied with
your compiler.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">n</span></tt></td>
<td>using STLPort's deprecated “native iostreams” feature.<a class="footnote-reference" href="#native" id="id20"><sup>8</sup></a></td>
</tr>
</tbody>
</table>
</blockquote>
<p class="last">For example, if you build a debug version of your code for use
with debug versions of the static runtime library and the
STLPort standard library in “native iostreams” mode,
the tag would be: <tt class="docutils literal"><span class="pre">-sgdpn</span></tt>. If none of the above apply, the
ABI tag is ommitted.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">-1_34</span></tt></dt>
<dd><em>Version tag</em>: the full Boost release number, with periods
replaced by underscores. For example, version 1.31.1 would be
tagged as &quot;-1_31_1&quot;.</dd>
<dt><tt class="docutils literal"><span class="pre">.lib</span></tt></dt>
<dd><em>Extension</em>: determined according to the operating system's usual
convention. On most unix-style platforms the extensions are
<tt class="docutils literal"><span class="pre">.a</span></tt> and <tt class="docutils literal"><span class="pre">.so</span></tt> for static libraries (archives) and shared
libraries, respectively. On Windows, <tt class="docutils literal"><span class="pre">.dll</span></tt> indicates a shared
library and (except for static libraries built by the <tt class="docutils literal"><span class="pre">gcc</span></tt>
<a class="reference internal" href="#toolset">toolset</a>, whose names always end in <tt class="docutils literal"><span class="pre">.a</span></tt>) <tt class="docutils literal"><span class="pre">.lib</span></tt> indicates a
static or import library. Where supported by toolsets on unix
variants, a full version extension is added (e.g. &quot;.so.1.34&quot;) and
a symbolic link to the library file, named without the trailing
version number, will also be created.</dd>
</dl>
<!-- .. _Boost.Build toolset names: toolset-name_ -->
<!-- Copyright David Abrahams 2006. 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) -->
</div>
<div class="section" id="test-your-program">
<h2><a class="toc-backref" href="#id42">6.4&nbsp;&nbsp;&nbsp;Test Your Program</a></h2>
<p>To test our subject extraction, we'll filter the following text
file. Copy it out of your browser and save it as <tt class="docutils literal"><span class="pre">jayne.txt</span></tt>:</p>
<pre class="literal-block">
To: George Shmidlap
From: Rita Marlowe
Subject: Will Success Spoil Rock Hunter?
---
See subject.
</pre>
<p>Now, in a <a class="reference internal" href="#command-prompt">command prompt</a> window, type:</p>
<pre class="literal-block">
<em>path</em>\<em>to</em>\<em>compiled</em>\example &lt; <em>path</em>\<em>to</em>\jayne.txt
</pre>
<p>The program should respond with the email subject, “Will Success
Spoil Rock Hunter?”</p>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
</div>
<div class="section" id="conclusion-and-further-resources">
<h1><a class="toc-backref" href="#id43">7&nbsp;&nbsp;&nbsp;Conclusion and Further Resources</a></h1>
<p>This concludes your introduction to Boost and to integrating it
with your programs. As you start using Boost in earnest, there are
surely a few additional points you'll wish we had covered. One day
we may have a “Book 2 in the Getting Started series” that addresses
them. Until then, we suggest you pursue the following resources.
If you can't find what you need, or there's anything we can do to
make this document clearer, please post it to the <a class="reference external" href="../../more/mailing_lists.htm#users">Boost Users'
mailing list</a>.</p>
<ul class="simple">
<li><a class="reference external" href="../../tools/build/v2">Boost.Build reference manual</a></li>
<li><a class="reference external" href="../../tools/jam/index.html">Boost.Jam reference manual</a></li>
<li><a class="reference external" href="../../more/mailing_lists.htm#users">Boost Users' mailing list</a></li>
<li><a class="reference external" href="../../more/mailing_lists.htm#jamboost">Boost.Build mailing list</a></li>
<li><a class="reference external" href="http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build_V2">Boost.Build Wiki</a></li>
<li><a class="reference external" href="../../libs/index.html">Index of all Boost library documentation</a></li>
</ul>
<div class="admonition-onward admonition">
<p class="first admonition-title">Onward</p>
<blockquote class="epigraph last">
<p>Good luck, and have fun!</p>
<p class="attribution">&mdash;the Boost Developers</p>
</blockquote>
</div>
<hr class="docutils" />
<table class="docutils footnote" frame="void" id="zip" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>If you prefer not to download executable programs,
download <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041"><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt><tt class="docutils literal"><span class="pre">.zip</span></tt></a> and use an external tool to decompress
it. We don't recommend using Windows' built-in decompression as
it can be painfully slow for large archives.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="installer-src" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[2]</td><td>If you used the <a class="reference external" href="http://www.boost-consulting.com/download/windows">installer</a> from Boost
Consulting and deselected “Source and Documentation” (it's
selected by default), you won't see the <tt class="docutils literal"><span class="pre">libs/</span></tt> subdirectory.
That won't affect your ability to use precompiled binaries, but
you won't be able to rebuild libraries from scratch.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="pch" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[3]</a></td><td>There's no problem using Boost with precompiled headers;
these instructions merely avoid precompiled headers because it
would require Visual Studio-specific changes to the source code
used in the examples.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="continuation" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id13">[4]</a></td><td>In this example, the caret character <tt class="docutils literal"><span class="pre">^</span></tt> is a
way of continuing the command on multiple lines. The command
prompt responds with <tt class="docutils literal"><span class="pre">More?</span></tt> to prompt for more input. Feel
free to omit the carets and subsequent newlines; we used them so
the example would fit on a page of reasonable width.</td></tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. 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) -->
<table class="docutils footnote" frame="void" id="warnings" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id7">[5]</a></td><td>Remember that warnings are specific to each compiler
implementation. The developer of a given Boost library might
not have access to your compiler. Also, some warnings are
extremely difficult to eliminate in generic code, to the point
where it's not worth the trouble. Finally, some compilers don't
have any source code mechanism for suppressing warnings.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="distinct" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id18">[6]</a></td><td>This convention distinguishes the static version of
a Boost library from the import library for an
identically-configured Boost DLL, which would otherwise have the
same name.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="debug-abi" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id19">[7]</a></td><td>These libraries were compiled without optimization
or inlining, with full debug symbols enabled, and without
<tt class="docutils literal"><span class="pre">NDEBUG</span></tt> <tt class="docutils literal"><span class="pre">#define</span></tt>d. Although it's true that sometimes
these choices don't affect binary compatibility with other
compiled code, you can't count on that with Boost libraries.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="native" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id20">[8]</a></td><td>This feature of STLPort is deprecated because it's
impossible to make it work transparently to the user; we don't
recommend it.</td></tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. 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) -->
<!-- This file contains all the definitions that need to be updated -->
<!-- for each new release of Boost. -->
<!-- Copyright David Abrahams 2006. 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) -->
<!-- Copyright David Abrahams 2006. 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) -->
<!-- Copyright David Abrahams 2006. 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) -->
</div>
</div>
</body>
</html>

307
getting_started/windows.rst
View File

@ -1,307 +0,0 @@
.. Copyright David Abrahams 2006. 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)
=======================================
|(logo)|__ Getting Started on Windows
=======================================
.. |(logo)| image:: ../../boost.png
:alt: Boost
:class: boost-logo
__ ../../index.htm
.. section-numbering::
.. Admonition:: A note to Cygwin_ and MinGW_ users
If you plan to use your tools from the Windows command prompt,
you're in the right place. If you plan to build from the Cygwin_
bash shell, you're actually running on a POSIX platform and
should follow the instructions for `getting started on Unix
variants`_. Other command shells, such as MinGW_\ 's MSYS, are
not supported—they may or may not work.
.. _`Getting Started on Unix Variants`: unix-variants.html
.. _Cygwin: http://www.cygwin.com
.. _MinGW: http://mingw.org
.. Contents:: Index
Get Boost
=========
The easiest way to get a copy of Boost is to use the `installer`_
provided by `Boost Consulting`_. We especially recommend this
method if you use Microsoft Visual Studio .NET 2003 or Microsoft
Visual Studio 2005, because the installer can download and install
precompiled library binaries, saving you the trouble of building
them yourself. To complete this tutorial, you'll need to at least
install the Boost.Regex_ binaries when given the option.
.. _installer: http://www.boost-consulting.com/download/windows
.. _Boost Consulting: http://www.boost-consulting.com
If you're using an earlier version of Visual Studio or some other
compiler, or if you prefer to build everything yourself, you can
download |boost.exe|_ and run it to install a complete Boost
distribution. [#zip]_
.. |boost.exe| replace:: |boost_ver|\ ``.exe``
.. _`boost.exe`: `sf-download`_
.. include:: detail/distro.rst
.. include:: detail/header-only.rst
.. include:: detail/build-simple-head.rst
.. _`command prompt`:
.. _`command-line tool`:
.. Note:: To build the examples in this guide, you can use an
Integrated Development Environment (IDE) like Visual Studio, or
you can issue commands from the `command prompt`_. Since every
IDE and compiler has different options and Microsoft's are by
far the dominant compilers on Windows, we only give specific
directions here for Visual Studio 2005 and .NET 2003 IDEs and
their respective command prompt compilers (using the command
prompt is a bit simpler). If you are using another compiler or
IDE, it should be relatively easy to adapt these instructions to
your environment.
.. sidebar:: Command Prompt Basics
:class: small
In Windows, a command-line tool is invoked by typing its name,
optionally followed by arguments, into a *Command Prompt* window
and pressing the Return (or Enter) key.
To open a generic *Command Prompt*, click the *Start* menu
button, click *Run*, type “cmd”, and then click *OK*.
.. _current directory:
All commands are executed within the context of a **current
directory** in the filesystem. To set the current directory,
type:
.. parsed-literal::
cd *path*\ \\\ *to*\ \\\ *some*\ \\\ *directory*
followed by Return. For example,
.. parsed-literal::
cd |default-root|
Long commands can be continued across several lines by typing a
caret (``^``) at the end of all but the last line. Some examples
on this page use that technique to save horizontal space.
.. _vs-header-only:
Build From the Visual Studio IDE
--------------------------------
* From Visual Studio's *File* menu, select *New* > *Project…*
* In the left-hand pane of the resulting *New Project* dialog,
select *Visual C++* > *Win32*.
* In the right-hand pane, select *Win32 Console Application*
(VS8.0) or *Win32 Console Project* (VS7.1).
* In the *name* field, enter “example”
* Right-click **example** in the *Solution Explorer* pane and
select *Properties* from the resulting pop-up menu
* In *Configuration Properties* > *C/C++* > *General* > *Additional Include
Directories*, enter the path to the Boost root directory, for example
|default-root|
* In *Configuration Properties* > *C/C++* > *Precompiled Headers*, change
*Use Precompiled Header (/Yu)* to *Not Using Precompiled
Headers*. [#pch]_
* Replace the contents of the ``example.cpp`` generated by the IDE
with the example code above.
* From the *Build* menu, select *Build Solution*.
To test your application, hit the F5 key and type the following
into the resulting window, followed by the Return key::
1 2 3
Then hold down the control key and press "Z", followed by the
Return key.
|next|__
__ `Errors and Warnings`_
Or, Build From the Command Prompt
---------------------------------
From your computer's *Start* menu, if you are a Visual
Studio 2005 user, select
*All Programs* > *Microsoft Visual Studio 2005*
> *Visual Studio Tools* > *Visual Studio 2005 Command Prompt*
or, if you're a Visual Studio .NET 2003 user, select
*All Programs* > *Microsoft Visual Studio .NET 2003*
> *Visual Studio .NET Tools* > *Visual Studio .NET 2003 Command Prompt*
to bring up a special `command prompt`_ window set up for the
Visual Studio compiler. In that window, set the `current
directory`_ to a suitable location for creating some temporary
files and type the following command followed by the Return key:
.. parsed-literal::
cl /EHsc /I |root| *path*\ \\\ *to*\ \\example.cpp
To test the result, type:
.. parsed-literal::
echo 1 2 3 | example
.. include:: detail/errors-and-warnings.rst
.. include:: detail/binary-head.rst
Install Visual Studio (2005 or .NET 2003) Binaries
--------------------------------------------------
The installer_ supplied by Boost Consulting will download and
install pre-compiled binaries into the ``lib\`` subdirectory of the
boost root, typically |default-root|\ ``\lib\``. If you installed
all variants of the Boost.Regex_ binary, you're done with this
step. Otherwise, please run the installer again and install them
now.
|next|__
__ `Link Your Program to a Boost Library`_
Or, Build and Install Binaries From Source
------------------------------------------
If you're using an earlier version of Visual C++, or a compiler
from another vendor, you'll need to use Boost.Build_ to create your
own binaries.
.. include:: detail/build-from-source-head.rst
For example, your session might look like this: [#continuation]_
.. parsed-literal::
C:\WINDOWS> cd |default-root|
|default-root|> bjam **^**
More? **--build-dir=**\ %TEMP%\\build-boost **^**
More? **--toolset=**\ msvc stage
.. include:: detail/build-from-source-tail.rst
.. include:: detail/link-head.rst
.. Admonition:: Auto-Linking
Most Windows compilers and linkers have so-called “auto-linking
support,” which eliminates the second challenge. Special code in
Boost header files detects your compiler options and uses that
information to encode the name of the correct library into your
object files; the linker selects the library with that name from
the directories you've told it to search.
Link From Within the Visual Studio IDE
--------------------------------------
Starting with the `header-only example project`__ we created
earlier:
__ vs-header-only_
1. Right-click **example** in the *Solution Explorer* pane and
select *Properties* from the resulting pop-up menu
2. In *Configuration Properties* > *Linker* > *Additional Library
Directories*, enter the path to the Boost binaries,
e.g. |default-root|\ ``\lib\``.
3. From the *Build* menu, select *Build Solution*.
|next|__
__ `Test Your Program`_
Or, Link From the Command Prompt
--------------------------------
For example, we can compile and link the above program from the
Visual C++ command-line by simply adding the **bold** text below to
the command line we used earlier, assuming your Boost binaries are
in |default-root|\ ``\lib``:
.. parsed-literal::
cl /EHsc /I |root| example.cpp **^**
**/link /LIBPATH:** |default-root-bold|\ **\\lib**
Library Naming
--------------
.. Note:: If, like Visual C++, your compiler supports auto-linking,
you can probably |next|__.
__ `Test Your Program`_
.. include:: detail/library-naming.rst
.. include:: detail/test-head.rst
Now, in a `command prompt`_ window, type:
.. parsed-literal::
*path*\ \\\ *to*\ \\\ *compiled*\ \\example < *path*\ \\\ *to*\ \\\ jayne.txt
The program should respond with the email subject, “Will Success
Spoil Rock Hunter?”
.. include:: detail/conclusion.rst
------------------------------
.. [#zip] If you prefer not to download executable programs,
download |boost.zip|_ and use an external tool to decompress
it. We don't recommend using Windows' built-in decompression as
it can be painfully slow for large archives.
.. [#installer-src] If you used the installer_ from Boost
Consulting and deselected “Source and Documentation” (it's
selected by default), you won't see the ``libs/`` subdirectory.
That won't affect your ability to use precompiled binaries, but
you won't be able to rebuild libraries from scratch.
.. [#pch] There's no problem using Boost with precompiled headers;
these instructions merely avoid precompiled headers because it
would require Visual Studio-specific changes to the source code
used in the examples.
.. [#continuation] In this example, the caret character ``^`` is a
way of continuing the command on multiple lines. The command
prompt responds with ``More?`` to prompt for more input. Feel
free to omit the carets and subsequent newlines; we used them so
the example would fit on a page of reasonable width.
.. |boost.zip| replace:: |boost_ver|\ ``.zip``
.. _`boost.zip`: `sf-download`_
.. include:: detail/common-footnotes.rst
.. include:: detail/release-variables.rst
.. include:: detail/common-windows.rst
.. include:: detail/links.rst

BIN
google_logo_25wht.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.6 KiB

103
header.htm
View File

@ -1,103 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Boost Header policy</title>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta name="Microsoft Border" content="none, default">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table summary="Navigational header"
border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Boost Header Policy</h1>
<p>Header files are the place where a library comes into contact with user code
and other libraries.&nbsp; To co-exist peacefully and productively, headers must
be &quot;good neighbors&quot;.</p>
<p>Here are the standards for boost headers.&nbsp;&nbsp;&nbsp; Many of
these are also reasonable guidelines for general use.
<ul>
<li>Header filenames should have a .hpp (lowercase) extension.&nbsp;</li>
<li>Unless multiple inclusion is intended, wrap the header in #ifndef guards.
Use a naming convention that minimizes the chance of clashes
with macro names from other's code.&nbsp; The <a href="#SampleHeader">sample
header</a> uses the Boost convention of all uppercase letters, with the
header name prefixed by the namespace name, and suffixed with HPP, separated
by underscores.</li>
<li>Wrap the header contents in a namespace to prevent global namespace
pollution. The namespace approach to pollution control is strongly preferred
to older approaches such as adding funny prefixes to global names.&nbsp;
Libraries which are designed to work well with other Boost libraries should
be placed in namespace <tt>boost</tt>.</li>
<li>Make sure that a translation unit consisting of just the
contents of the header file will compile successfully.</li>
<li>Place the header file in a sub-directory to prevent conflict with
identically named header files in other libraries.&nbsp; The parent
directory is added to the compiler's include search path.&nbsp; Then both
your code and user code specifies the sub-directory in <tt>#include</tt>
directives.&nbsp; Thus the header <a href="#SampleHeader">sample header</a>&nbsp;
would be included by <tt>#include &lt;boost/furball.hpp&gt;</tt></li>
<li>The preferred ordering for class definitions is public members, protected
members, and finally private members.</li>
<li>Include the boost/config.hpp <a href="../libs/config/config.htm">configuration
header</a> if there is a need to deal with compiler or platform
configuration issues.</li>
</ul>
<h2><a name="SampleHeader"></a>Sample Header</h2>
<pre><tt>//&nbsp; Boost general library furball.hpp header file ---------------------------//
&lt;<i> Copyright and license notice</i>, as indicated in the <a href="license_info.html">license page</a> &gt;
//&nbsp; See http://www.boost.org/ for latest version.
#ifndef BOOST_FURBALL_HPP
#define BOOST_FURBALL_HPP
namespace boost {
//&nbsp; Furball class declaration&nbsp; -----------------------------------------------//
&nbsp; class furball
{
public:
&nbsp; void throw_up();
private:
int whatever;
&nbsp;&nbsp;};&nbsp; // furball
} // namespace
#endif&nbsp; // include guard</tt></pre>
<h2>Coding Style</h2>
<p>The alert reader will have noticed that the <a href="#SampleHeader">sample
header</a> employs a certain coding style for indentation, positioning braces,
commenting ending braces, and similar formatting issues.&nbsp; These stylistic
issues are viewed as personal preferences and are not part of the Boost Header
Policy.</p>
<hr>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->02 October, 2003<!--webbot bot="Timestamp" endspan i-checksum="38549" --></p>
<p>&copy; Copyright Beman Dawes 1998</p>
<p>
Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

211
imp_vars.htm
View File

@ -1,211 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Boost Implementation Variations</title>
</head>
<body link="#0000ff" vlink="#800080" bgcolor="#FFFFFF" text="#000000">
<table summary="Navigational header"
border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Boost Implementation Variations</h1>
<h2>Separation of interface and implementation</h2>
<p>The interface specifications for boost.org library components (as well as for
quality software in general) are conceptually separate from implementations of
those interfaces. This may not be obvious, particularly when a component is
implemented entirely within a header, but this separation of interface and
implementation is always assumed. From the perspective of those concerned with
software design, portability, and standardization, the interface is what is
important, while the implementation is just a detail.</p>
<p>Dietmar Kühl, one of the original boost.org contributors, comments &quot;The
main contribution is the interface, which is augmented with an implementation,
proving that it is possible to implement the corresponding class and providing a
free implementation.&quot;</p>
<h2>Implementation variations</h2>
<p>There may be a need for multiple implementations of an interface, to
accommodate either platform dependencies or performance tradeoffs. Examples of
platform dependencies include compiler shortcomings, file systems, thread
mechanisms, and graphical user interfaces. The classic example of a performance
tradeoff is a fast implementation which uses a lot of memory versus a slower
implementation which uses less memory.</p>
<p>Boost libraries generally use a <a href="../libs/config/config.htm">configuration
header</a>, boost/config.hpp, to capture compiler and platform
dependencies.&nbsp; Although the use of boost/config.hpp is not required, it is
the preferred approach for simple configuration problems.&nbsp;&nbsp;</p>
<h2>Boost policy</h2>
<p>The Boost policy is to avoid platform dependent variations in interface
specifications, but supply implementations which are usable over a wide range of
platforms and applications.&nbsp; That means boost libraries will use the
techniques below described as appropriate for dealing with platform
dependencies.</p>
<p>The Boost policy toward implementation variations designed to enhance
performance is to avoid them unless the benefits greatly exceed the full
costs.&nbsp; The term &quot;full costs&quot; is intended to include both
tangible costs like extra maintenance, and intangible cost like increased
difficulty in user understanding.</p>
<h2>Techniques for providing implementation variations</h2>
<p>Several techniques may be used to provide implementation variations. Each is
appropriate in some situations, and not appropriate in other situations.</p>
<h3>Single general purpose implementation</h3>
<p>The first technique is to simply not provide implementation variation at
all.&nbsp; Instead, provide a single general purpose implementation, and forgo
the increased complexity implied by all other techniques.</p>
<p><b>Appropriate:</b>&nbsp; When it is possible to write a single portable
implementation which has reasonable performance across a wide range of
platforms. Particularly appropriate when alternative implementations differ only
in esoteric ways.</p>
<p><b>Not appropriate:</b> When implementation requires platform specific
features, or when there are multiple implementation possible with widely
differing performance characteristics.</p>
<p>Beman Dawes comments &quot;In design discussions some implementation is often
alleged to be much faster than another, yet&nbsp; a timing test discovers no
significant difference. The lesson is that while algorithmic differences may
affect speed dramatically, coding differences such as changing a class from
virtual to non-virtual members or removing a level of indirection are unlikely
to make any measurable difference unless deep in an inner loop. And even in an
inner loop, modern CPUs often execute such competing code sequences in the
same number of clock cycles!&nbsp; A single general purpose implementation is
often just fine.&quot;</p>
<p>Or as Donald Knuth said, &quot;Premature optimization is the root of all
evil.&quot; (Computing Surveys, vol 6, #4, p 268).</p>
<h3>Macros</h3>
<p>While the evils of macros are well known, there remain a few cases where
macros are the preferred solution:</p>
<blockquote>
<ul>
<li>&nbsp;Preventing multiple inclusion of headers via #include guards.</li>
<li>&nbsp;Passing minor configuration information from a configuration
header to other files.</li>
</ul>
</blockquote>
<p><b>Appropriate:</b>&nbsp; For small compile-time variations which would
otherwise be costly or confusing to install, use, or maintain. More appropriate
to communicate within and between library components than to communicate with
library users.</p>
<p><b>Not appropriate:&nbsp;</b> If other techniques will do.</p>
<p>To minimize the negative aspects of macros:</p>
<blockquote>
<ul>
<li>Only use macros when they are clearly superior to other
techniques.&nbsp; They should be viewed as a last resort.</li>
<li>Names should be all uppercase, and begin with the namespace name. This
will minimize the chance of name collisions. For example, the #include
guard for a boost header called foobar.h might be named BOOST_FOOBAR_H.</li>
</ul>
</blockquote>
<h3>Separate files</h3>
<p>A library component can have multiple variations, each contained in its own
separate file or files.&nbsp; The files for the most appropriate variation are
copied to the appropriate include or implementation directories at installation
time.</p>
<p>The way to provide this approach in boost libraries is to include specialized
implementations as separate files in separate sub-directories in the .ZIP
distribution file. For example, the structure within the .ZIP distribution file
for a library named foobar which has both default and specialized variations
might look something like:</p>
<blockquote>
<pre>foobar.h // The default header file
foobar.cpp // The default implementation file
readme.txt // Readme explains when to use which files
self_contained/foobar.h // A variation with everything in the header
linux/foobar.cpp // Implementation file to replace the default
win32/foobar.h // Header file to replace the default
win32/foobar.cpp // Implementation file to replace the default</pre>
</blockquote>
<p><b>Appropriate:</b>&nbsp; When different platforms require different
implementations, or when there are major performance differences between
possible implementations.&nbsp;</p>
<p><b>Not appropriate:</b>&nbsp; When it makes sense to use more that one of the
variations in the same installation.</p>
<h3>Separate components</h3>
<p>Rather than have several implementation variations of a single component,
supply several separate components. For example, the Boost library currently
supplies <code>scoped_ptr</code> and <code>shared_ptr</code> classes rather than
a single <code>smart_ptr</code> class parameterized to distinguish between the
two cases.&nbsp; There are several ways to make the component choice:</p>
<blockquote>
<ul>
<li>Hardwired by the programmer during coding.</li>
<li>Chosen by programmer written runtime logic (trading off some extra
space, time, and program complexity for the ability to select the
implementation at run-time.)</li>
</ul>
</blockquote>
<p><b>Appropriate: </b>When the interfaces for the variations diverge, and when
it is reasonably to use more than one of the variations. When run-time selection
of implementation is called for.</p>
<p><b>Not appropriate:</b> When the variations are data type, traits, or
specialization variations which can be better handled by making the component a
template. Also not appropriate when choice of variation is best done by some
setup or installation mechanism outside of the program itself.&nbsp; Thus
usually not appropriate to cope with platform differences.</p>
<p><b>Note:</b> There is a related technique where the interface is specified as
an abstract (pure virtual) base class (or an interface definition language), and
the implementation choice is passed off to some third-party, such as a
dynamic-link library or object-request broker. While that is a powerful
technique, it is way beyond the scope of this discussion.</p>
<h3>Template-based approaches</h3>
<p>Turning a class or function into a template is often an elegant way to cope
with variations.&nbsp; Template-based approaches provide optimal space and time
efficiency in return for constraining the implementation selection to compile
time.&nbsp;</p>
<p>Important template techniques include:</p>
<blockquote>
<ul>
<li>Data type parameterization.&nbsp; This allows a single component to
operate on a variety of data types, and is why templates were originally
invented.</li>
<li>Traits parameterization.&nbsp; If parameterization is complex, bundling
up aspects into a single traits helper class can allow great variation
while hiding messy details.&nbsp; The C++ Standard Library provides
several examples of this idiom, such as <code>iterator_traits&lt;&gt;</code>
(24.3.1 lib.iterator.traits) and <tt>char_traits&lt;&gt;</tt> (21.2
lib.char.traits).</li>
<li>Specialization.&nbsp; A template parameter can be used purely for the
purpose of selecting a specialization. For example:</li>
</ul>
<blockquote>
<blockquote>
<pre>SomeClass&lt;fast&gt; my_fast_object; // fast and small are empty classes
SomeClass&lt;small&gt; my_small_object; // used just to select specialization</pre>
</blockquote>
</blockquote>
</blockquote>
<p><b>Appropriate: </b>When the need for variation is due to data type or
traits, or is performance related like selecting among several algorithms, and
when a program might reasonably use more than one of the variations.</p>
<p><b>Not appropriate:</b>&nbsp; When the interfaces for variations are
different, or when choice of variation is best done by some mechanism outside of
the program itself.&nbsp; Thus usually not appropriate to cope with platform
differences.</p>
<hr>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->02 October, 2003<!--webbot bot="Timestamp" endspan i-checksum="38549" --></p>
<p>© Copyright Beman Dawes 2001</p>
<p>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

126
index.htm
View File

@ -1,126 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Boost More Information</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
</head>
<body bgcolor="#ffffff" text="#000000">
<table summary ="Navigational header"
border="1" cellpadding="2" bgcolor="#007f7f">
<tr>
<td bgcolor="#ffffff">
<img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font color="#ffffff" size="4" face="Arial">Home</font></a></td>
<td><a href="../libs/libraries.htm"><font color="#ffffff" size="4" face="Arial">Libraries</font></a></td>
<td><a href="../people/people.htm"><font color="#ffffff" size="4" face="Arial">People</font></a></td>
<td><a href="faq.htm"><font color="#ffffff" size="4" face="Arial">FAQ</font></a></td>
<td><a href="index.htm"><font color="#ffffff" size="4" face="Arial">More</font></a></td>
</tr>
</table>
<h1>More Information</h1>
<h2>Boost Policies</h2>
<blockquote>
<p><a href="discussion_policy.htm"><b>Mailing List Discussion Policy.</b></a>&nbsp;
What's acceptable and what isn't.</p>
<p><a href="lib_guide.htm"><b>Library Requirements and Guidelines</b></a>.&nbsp;
Basic standards for those preparing a submission.</p>
<P><A href="separate_compilation.html"><STRONG>Guidelines for Libraries with Separate
Source</STRONG></A>.&nbsp; Basic tutorial for libraries that require the
building of a separate link library.</P>
<p><a href="writingdoc/index.html"><strong>Writing Documentation for Boost</strong></a>
Basic guidelines for writing documentation and templates for quickly generating
documentation that follows the guidelines.</p>
<p><a href="test_policy.htm"><b>Test Policy and Protocols</b></a>.&nbsp; How
testing works at Boost.</p>
<p><a href="submission_process.htm"><b>Library Submission Process</b></a>.&nbsp;
How to submit a library to Boost.</p>
<p><a href="formal_review_process.htm"><b>Library Formal Review Process</b></a>.
Including how to submit a review comment.</p>
<p><a href="header.htm"><b>Header Policy</b></a>.&nbsp; Headers are where a
library contacts its users, so programming practices are particularly
important.</p>
<p><a href="imp_vars.htm"><b>Implementation Variations</b></a>.&nbsp; Sometimes
one size fits all, sometimes it doesn't.&nbsp; This page deals with the
trade-offs.</p>
<p><a href="library_reuse.htm"><b>Library Reuse</b></a>.&nbsp; Should Boost
libraries use other boost libraries?&nbsp; What about the C++ Standard
Library?&nbsp; It's another trade-off.</p>
<p><b><a href="moderators.html">Moderators</a></b>.&nbsp; Who they are and what
they do.</p>
</blockquote>
<h2>Boost Whatever</h2>
<blockquote>
<p><b><a href="license_info.html">License Information</a> </b>&nbsp;Information
about the Boost Software License.</p>
<p><b><a href="bibliography.html">Bibliography</a> </b>&nbsp;Print and online
publications relating to Boost and Boost libraries.</p>
<p><b><a href="../doc/html/who_s_using_boost_.html">Who's Using Boost?</a> </b>&nbsp;
Products and organisations that are using Boost.</p>
<p><a href="../status/compiler_status.html"><b>Compiler Status</b></a>&nbsp;&nbsp;Describes
what library works with which compiler.</p>
<p><b><a href="links.htm">Links</a></b>&nbsp; Links of special interest to Boost
users.</p>
<p><b><a href="formal_review_schedule.html">Formal Review Schedule</a></b>&nbsp;
Future, current, and recently past Formal Reviews.</p>
<p><b><a href="release_procedures.htm">Release Procedures</a></b>&nbsp; How
developers and the release manager prepare for a Boost release.</p>
<p><b><a href="updating_the_website.html">Updating the Website</a></b>&nbsp; How
developers can update the Boost website between releases.</p>
<p><a href="regression.html"><b>Internal Regression Test Suite</b></a>&nbsp;&nbsp;
Describes the tool for generating the compiler status tables
</p>
<p><b><a href="proposal.pdf">Proposal for a C++ Library Repository Web Site</a></b>&nbsp;
The original 1998 proposal that launched Boost.</p>
<p><b><a href="bugs.htm">How to report bugs</a></b>&nbsp; Ways to report Boost
bugs.</p>
<p><b><a href="requesting_new_features.htm">How to request features</a></b> Ways
to request new library features.</p>
<p><b><a href="cpp_committee_meetings.html">C++ Committee Meetings</a></b> FAQ for
Boost Members wishing to attend a standards committee meeting.</p>
<p><b><a href="boost_soc_06_overview.html">An overview of Boost participation in
Google Summer of Code&trade; 2006</a></b> A report of our first experience
in this open source initiative.</p>
<p><b><a href="version_history.html">Version History</a></b> Changes
and additions in past Boost releases.</p>
</blockquote>
<h2>Articles and Papers</h2>
<blockquote>
<p><a href="error_handling.html"><b>Error and Exception Handling</b></a> describes
approaches to errors and exceptions by <a href="../people/dave_abrahams.htm">David
Abrahams</a>.
</p>
<p><a href="count_bdy.htm"><b>Counted Body Techniques</b></a> by <a href="../people/kevlin_henney.htm">
Kevlin Henney</a> is must reading for those interested in reference
counting, a widely used object management idiom.&nbsp; Originally published in <a href="http://www.accu.org/c++sig/public/Overload.html">
Overload</a> magazine.</p>
<p><a href="generic_programming.html"><b>Generic Programming Techniques</b></a> by <a href="../people/dave_abrahams.htm">
David Abrahams</a> and <a href="../people/jeremy_siek.htm">Jeremy Siek</a> describe
some of the techniques used in Boost libraries.</p>
<p><a href="feature_model_diagrams.htm"><b>Feature Model Diagrams in text and HTML</b></a>
describes how to represent feature model diagrams in text form.</p>
<p><a href="borland_cpp.html"><b>Portability Hints: Borland C++ 5.5.1</b></a> describes
Borland C++ portability issues, with suggested workarounds.</p>
<p><a href="microsoft_vcpp.html"><b>Portability Hints: Microsoft VC++ 6.0 SP4</b></a>
describes Microsoft C++ portability issues, with suggested workarounds.</p>
<p><a href="int_const_guidelines.htm"><strong>Coding Guidelines for Integral Constant
Expressions</strong></a> describes how to work through the maze of
compiler related bugs surrounding this tricky topic.</p>
</blockquote>
<hr>
<p>
Revised
<!--webbot bot="Timestamp" s-type="EDITED"
s-format="%d %B, %Y" startspan -->10 May, 2005<!--webbot bot="Timestamp" endspan i-checksum="13987" --></p>
<p>
© Copyright Beman Dawes 2003.</p>
<p>
Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

328
int_const_guidelines.htm
View File

@ -1,328 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Template"
content="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot">
<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0">
<title></title>
</head>
<body bgcolor="#FFFFFF" link="#0000FF" vlink="#800080">
<h2 align="center">Coding Guidelines for Integral Constant
Expressions</h2>
<p>Integral Constant Expressions are used in many places in C++;
as array bounds, as bit-field lengths, as enumerator
initialisers, and as arguments to non-type template parameters.
However many compilers have problems handling integral constant
expressions; as a result of this, programming using non-type
template parameters in particular can be fraught with difficulty,
often leading to the incorrect assumption that non-type template
parameters are unsupported by a particular compiler. This short
article is designed to provide a set of guidelines and
workarounds that, if followed, will allow integral constant
expressions to be used in a manner portable to all the compilers
currently supported by boost. Although this article is mainly
targeted at boost library authors, it may also be useful for
users who want to understand why boost code is written in a
particular way, or who want to write portable code themselves.</p>
<h3>What is an Integral Constant Expression?</h3>
<p>Integral constant expressions are described in section 5.19 of
the standard, and are sometimes referred to as &quot;compile time
constants&quot;. An integral constant expression can be one of
the following:</p>
<ol>
<li>A literal integral value, for example 0u or 3L.</li>
<li>An enumerator value.</li>
<li>Global integral constants, for example: <font
face="Courier New"><code><br>
</code></font><code>const int my_INTEGRAL_CONSTANT = 3;</code></li>
<li>Static member constants, for example: <br>
<code>struct myclass<br>
{ static const int value = 0; };</code></li>
<li>Member enumerator values, for example:<br>
<code>struct myclass<br>
{ enum{ value = 0 }; };</code></li>
<li>Non-type template parameters of integral or enumerator
type.</li>
<li>The result of a <code>sizeof</code> expression, for
example:<br>
<code>sizeof(foo(a, b, c))</code></li>
<li>The result of a <code>static_cast</code>, where the
target type is an integral or enumerator type, and the
argument is either another integral constant expression,
or a floating-point literal.</li>
<li>The result of applying a binary operator to two integral
constant expressions: <br>
<code>INTEGRAL_CONSTANT1 op INTEGRAL_CONSTANT2 <br>
p</code>rovided that the operator is not an assignment
operator, or comma operator.</li>
<li>The result of applying a unary operator to an integral
constant expression: <br>
<code>op INTEGRAL_CONSTANT1<br>
</code>provided that the operator is not the increment or
decrement operator.</li>
</ol>
<p>&nbsp;</p>
<h3>Coding Guidelines</h3>
<p>The following guidelines are declared in no particular order (in
other words you need to obey all of them - sorry!), and may also
be incomplete, more guidelines may be added as compilers change
and/or more problems are encountered.</p>
<p><b><i>When declaring constants that are class members always
use the macro BOOST_STATIC_CONSTANT.</i></b></p>
<pre>template &lt;class T&gt;
struct myclass
{
BOOST_STATIC_CONSTANT(int, value = sizeof(T));
};</pre>
<p>Rationale: not all compilers support inline initialisation of
member constants, others treat member enumerators in strange ways
(they're not always treated as integral constant expressions).
The BOOST_STATIC_CONSTANT macro uses the most appropriate method
for the compiler in question.</p>
<p><b><i>Don't declare integral constant expressions whose type
is wider than int.</i></b></p>
<p>Rationale: while in theory all integral types are usable in
integral constant expressions, in practice many compilers limit
integral constant expressions to types no wider than <b>int</b>.</p>
<p><b><i>Don't use logical operators in integral constant
expressions; use template meta-programming instead.</i></b></p>
<p>The header &lt;boost/type_traits/ice.hpp&gt; contains a number
of workaround templates, that fulfil the role of logical
operators, for example instead of:</p>
<p><code>INTEGRAL_CONSTANT1 || INTEGRAL_CONSTANT2</code></p>
<p>Use:</p>
<p><code>::boost::type_traits::ice_or&lt;INTEGRAL_CONSTANT1,INTEGRAL_CONSTANT2&gt;::value</code></p>
<p>Rationale: A number of compilers (particularly the Borland and
Microsoft compilers), tend to not to recognise integral constant
expressions involving logical operators as genuine integral
constant expressions. The problem generally only shows up when
the integral constant expression is nested deep inside template
code, and is hard to reproduce and diagnose.</p>
<p><b><i>Don't use any operators in an integral constant
expression used as a non-type template parameter</i></b></p>
<p>Rather than:</p>
<p><code>typedef myclass&lt;INTEGRAL_CONSTANT1 ==
INTEGRAL_CONSTANT2&gt; mytypedef;</code></p>
<p>Use:</p>
<p><code>typedef myclass&lt; some_symbol&gt; mytypedef;</code></p>
<p>Where <code>some_symbol</code> is the symbolic name of a an
integral constant expression whose value is <code>(INTEGRAL_CONSTANT1
== INTEGRAL_CONSTANT2).</code></p>
<p>Rationale: the older EDG based compilers (some of which are
used in the most recent version of that platform's compiler),
don't recognise expressions containing operators as non-type
template parameters, even though such expressions can be used as
integral constant expressions elsewhere.</p>
<p><b><i>Always use a fully qualified name to refer to an
integral constant expression.</i></b></p>
<p>For example:</p>
<pre><code>typedef</code> myclass&lt; ::boost::is_integral&lt;some_type&gt;::value&gt; mytypedef;</pre>
<p>Rationale: at least one compiler (Borland's), doesn't
recognise the name of a constant as an integral constant
expression unless the name is fully qualified (which is to say it
starts with ::).</p>
<p><b><i>Always leave a space after a '&lt;' and before '::'</i></b></p>
<p>For example:</p>
<pre><code>typedef</code> myclass&lt; ::boost::is_integral&lt;some_type&gt;::value&gt; mytypedef;
^
ensure there is space here!</pre>
<p>Rationale: &lt;: is a legal digraph in it's own right, so &lt;::
is interpreted as the same as [:.</p>
<p><b><i>Don't use local names as integral constant expressions</i></b></p>
<p>Example:</p>
<pre>template &lt;class T&gt;
struct foobar
{
BOOST_STATIC_CONSTANT(int, temp = computed_value);
typedef myclass&lt;temp&gt; mytypedef; // error
};</pre>
<p>Rationale: At least one compiler (Borland's) doesn't accept
this.</p>
<p>Although it is possible to fix this by using:</p>
<pre>template &lt;class T&gt;
struct foobar
{
BOOST_STATIC_CONSTANT(int, temp = computed_value);
typedef foobar self_type;
typedef myclass&lt;(self_type::temp)&gt; mytypedef; // OK
};</pre>
<p>This breaks at least one other compiler (VC6), it is better to
move the integral constant expression computation out into a
separate traits class:</p>
<pre>template &lt;class T&gt;
struct foobar_helper
{
BOOST_STATIC_CONSTANT(int, temp = computed_value);
};
template &lt;class T&gt;
struct foobar
{
typedef myclass&lt; ::foobar_helper&lt;T&gt;::value&gt; mytypedef; // OK
};</pre>
<p><b><i>Don't use dependent default parameters for non-type
template parameters.</i></b></p>
<p>For example:</p>
<pre>template &lt;class T, int I = ::boost::is_integral&lt;T&gt;::value&gt; // Error can't deduce value of I in some cases.
struct foobar;</pre>
<p>Rationale: this kind of usage fails for Borland C++. Note that
this is only an issue where the default value is dependent upon a
previous template parameter, for example the following is fine:</p>
<pre>template &lt;class T, int I = 3&gt; // OK, default value is not dependent
struct foobar;</pre>
<p>&nbsp;</p>
<h3>Unresolved Issues</h3>
<p>The following issues are either unresolved or have fixes that
are compiler specific, and/or break one or more of the coding
guidelines.</p>
<p><b><i>Be careful of numeric_limits</i></b></p>
<p>There are three issues here:</p>
<ol>
<li>The header &lt;limits&gt; may be absent - it is
recommended that you never include &lt;limits&gt;
directly but use &lt;boost/pending/limits.hpp&gt; instead.
This header includes the &quot;real&quot; &lt;limits&gt;
header if it is available, otherwise it supplies it's own
std::numeric_limits definition. Boost also defines the
macro BOOST_NO_LIMITS if &lt;limits&gt; is absent.</li>
<li>The implementation of std::numeric_limits may be defined
in such a way that its static-const members may not be
usable as integral constant expressions. This contradicts
the standard but seems to be a bug that affects at least
two standard library vendors; boost defines
BOOST_NO_LIMITS_COMPILE_TIME_CONSTANTS in &lt;boost/config.hpp&gt;
when this is the case.</li>
<li>There is a strange bug in VC6, where the members of std::numeric_limits
can be &quot;prematurely evaluated&quot; in template
code, for example:</li>
</ol>
<pre>template &lt;class T&gt;
struct limits_test
{
BOOST_STATIC_ASSERT(::std::numeric_limits&lt;T&gt;::is_specialized);
};</pre>
<p>This code fails to compile with VC6 even though no instances
of the template are ever created; for some bizarre reason <code>::std::numeric_limits&lt;T&gt;::is_specialized
</code>always evaluates to false, irrespective of what the
template parameter T is. The problem seems to be confined to
expressions which depend on std::numeric_limts: for example if
you replace <code>::std::numeric_limits&lt;T&gt;::is_specialized</code>
with <code>::boost::is_arithmetic&lt;T&gt;::value</code>, then
everything is fine. The following workaround also works but
conflicts with the coding guidelines:</p>
<pre>template &lt;class T&gt;
struct limits_test
{
BOOST_STATIC_CONSTANT(bool, check = ::std::numeric_limits&lt;T&gt;::is_specialized);
BOOST_STATIC_ASSERT(check);
};</pre>
<p>So it is probably best to resort to something like this:</p>
<pre>template &lt;class T&gt;
struct limits_test
{
#ifdef BOOST_MSVC
BOOST_STATIC_CONSTANT(bool, check = ::std::numeric_limits&lt;T&gt;::is_specialized);
BOOST_STATIC_ASSERT(check);
#else
BOOST_STATIC_ASSERT(::std::numeric_limits&lt;T&gt;::is_specialized);
#endif
};</pre>
<p><b><i>Be careful how you use the sizeof operator</i></b></p>
<p>As far as I can tell, all compilers treat sizeof expressions
correctly when the argument is the name of a type (or a template-id),
however problems can occur if:</p>
<ol>
<li>The argument is the name of a member-variable, or a local
variable (code may not compile with VC6).</li>
<li>The argument is an expression which involves the creation
of a temporary (code will not compile with Borland C++).</li>
<li>The argument is an expression involving an overloaded
function call (code compiles but the result is a garbage
value with Metroworks C++).</li>
</ol>
<p><b><i>Don't use boost::is_convertible unless you have to</i></b></p>
<p>Since is_convertible is implemented in terms of the sizeof
operator, it consistently gives the wrong value when used with
the Metroworks compiler, and may not compile with the Borland's
compiler (depending upon the template arguments used).</p>
<hr>
<p><i>© Copyright Dr John Maddock 2001</i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
<p>&nbsp;</p>
<p>&nbsp;</p>
</body>
</html>

931
lib_guide.htm
View File

@ -1,931 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>
Boost Library Requirements and Guidelines
</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta name="Microsoft Border" content="none, default">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF">
<img src="../boost.png" alt="boost.png (6897 bytes)" width="277"
height="86">
</td>
<td>
<a href="../index.htm"><font face="Arial" color=
"#FFFFFF"><big>Home</big></font></a>
</td>
<td>
<a href="../libs/libraries.htm"><font face="Arial" color=
"#FFFFFF"><big>Libraries</big></font></a>
</td>
<td>
<a href="../people/people.htm"><font face="Arial" color=
"#FFFFFF"><big>People</big></font></a>
</td>
<td>
<a href="faq.htm"><font face="Arial" color=
"#FFFFFF"><big>FAQ</big></font></a>
</td>
<td>
<a href="index.htm"><font face="Arial" color=
"#FFFFFF"><big>More</big></font></a>
</td>
</tr>
</table>
<h1 align="left">
Boost Library Requirements and Guidelines
</h1>
<p align="left">
<a href="#Introduction">Introduction</a><br>
<a href="#Requirements">Requirements</a><br>
&nbsp;&nbsp;&nbsp; <a href="#License">License requirements</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Portability">Portability requirements</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Ownership">Ownership</a><br>
<a href="#Guidelines">Guidelines</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Design_and_Programming">Design and
programming</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Directory_structure">Directory structure and
filenames</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Naming_consistency">Naming
consistency</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Documentation">Documentation</a><br>
<a href="#Rationale">Rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href=
"#Exception-specification">Exception-specification rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Naming">Naming conventions rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#code_fonts">Source code fonts
rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Tabs">Tabs rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#JavaScript">ECMAScript/JavaScript
rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Rationale_rationale">Rationale
rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Acknowledgements">Acknowledgements
rationale</a>
</p>
<h2 align="left">
<a name="Introduction" id="Introduction">Introduction</a>
</h2>
<p align="left">
This page describes requirements and guidelines for the content of a
library submitted to Boost.
</p>
<p align="left">
See the <a href="submission_process.htm">Boost Library Submission
Process</a> page for a description of the process involved.
</p>
<h2 align="left">
<a name="Requirements" id="Requirements">Requirements</a>
</h2>
<p>
To avoid the frustration and wasted time of a proposed library being
rejected, it must meets these requirements:
</p>
<ul>
<li>The license must meet the <a href="#License">license requirements</a>
below. Restricted licenses like the GPL and LGPL are not acceptable.
</li>
<li>The copyright <a href="#Ownership">ownership</a> must be clear.
</li>
<li>The library must be generally useful and not restricted to a narrow
problem domain.
</li>
<li>The library must meet the <a href="#Portability">portability
requirements</a> below.&nbsp;
</li>
<li>The library must come reasonably close to meeting the <a href=
"#Guidelines">Guidelines</a> below.
<ul>
<li>
<a href="#Design_and_Programming">Design and Programming</a>
</li>
<li>
<a href="#Directory_structure">Directory Structure</a>
</li>
<li>
<a href="#Documentation">Documentation</a>
</li>
</ul>
</li>
<li>The author must be willing to participate in discussions on the mailing
list, and to refine the library accordingly.
</li>
</ul>
<p>
There's no requirement that an author read the mailing list for a time
before making a submission. It has been noted, however, that submissions
which begin "I just started to read this mailing list ..." seem to fail,
often embarrassingly.
</p>
<h3 align="left">
<a name="License" id="License">License</a> requirements
</h3>
<p>
The preferred way to meet the license requirements is to use the <a href=
"../LICENSE_1_0.txt">Boost Software License</a>. See <a href=
"license_info.html">license information</a>. If for any reason you do not
intend to use the Boost Software License, please discuss the issues on the
Boost <a href="mailing_lists.htm#main">developers mailing list</a> first.
</p>
<p>
The license requirements:
</p>
<ul>
<li>Must be simple to read and understand.
</li>
<li>Must grant permission without fee to copy, use and modify the software
for any use (commercial and non-commercial).
</li>
<li>Must require that the license appear on all copies of the software
source code.
</li>
<li>Must not require that the license appear with executables or other
binary uses of the library.
</li>
<li>Must not require that the source code be available for execution or
other binary uses of the library.
</li>
<li>May restrict the use of the name and description of the library to the
standard version found on the Boost web site.
</li>
</ul>
<h3 align="left">
<a name="Portability" id="Portability">Portability</a> requirements
</h3>
<ul>
<li>
<p align="left">
A library's interface must portable and not restricted to a particular
compiler or operating system.
</p>
</li>
<li>
<p align="left">
A library's implementation must if possible be portable and not
restricted to a particular compiler or operating system.&nbsp; If a
portable implementation is not possible, non-portable constructions are
acceptable if reasonably easy to port to other environments, and
implementations are provided for at least two popular operating systems
(such as UNIX and Windows).
</p>
</li>
<li>
<p align="left">
There is no requirement that a library run on C++ compilers which do
not conform to the ISO standard.&nbsp;
</p>
</li>
<li>
<p align="left">
There is no requirement that a library run on any particular C++
compiler.&nbsp; Boost contributors often try to ensure their libraries
work with popular compilers.&nbsp; The boost/config.hpp <a href=
"../libs/config/config.htm">configuration header</a> is the preferred
mechanism for working around compiler deficiencies.
</p>
</li>
</ul>
<p align="left">
Since there is no absolute way to prove portability, many boost submissions
demonstrate practical portability by compiling and executing correctly with
two different C++ compilers, often under different operating systems.&nbsp;
Otherwise reviewers may disbelieve that porting is in fact practical.
</p>
<h3 align="left">
<a name="Ownership" id="Ownership">Ownership</a>
</h3>
<p align="left">
Are you sure you own the library you are thinking of
submitting?&nbsp;&nbsp; "How to Copyright Software" by MJ Salone, Nolo
Press, 1990 says:
</p>
<blockquote>
<p align="left">
Doing work on your own time that is very similar to programming you do
for your employer on company time can raise nasty legal problems.&nbsp;
In this situation, it's best to get a written release from your employer
in advance.
</p>
</blockquote>
<p align="left">
Place a copyright notice in all the important files you submit. Boost won't
accept libraries without clear copyright information.
</p>
<h2 align="left">
<a name="Guidelines" id="Guidelines">Guidelines</a>
</h2>
<p align="left">
Please use these guidelines as a checklist for preparing the content a
library submission.&nbsp; Not every guideline applies to every library, but
a reasonable effort to comply is expected.
</p>
<h3>
<a name="Design_and_Programming" id="Design_and_Programming">Design and
Programming</a>
</h3>
<ul>
<li>Aim first for clarity and correctness; optimization should be only a
secondary concern in most Boost libraries.
</li>
</ul>
<ul>
<li>Aim for ISO Standard C++. Than means making effective use of the
standard features of the language, and avoiding non-standard compiler
extensions. It also means using the C++ Standard Library where applicable.
</li>
</ul>
<ul>
<li>Headers should be good neighbors. See the <a href="header.htm">header
policy</a>. See <a href="#Naming_consistency">Naming consistency</a>.
</li>
</ul>
<ul>
<li>Follow quality programming practices. See, for example, "Effective C++"
2nd Edition, and "More Effective C++", both by Scott Meyers, published by
Addison Wesley.
</li>
</ul>
<ul>
<li>Use the C++ Standard Library or other Boost libraries, but only when
the benefits outweigh the costs.&nbsp; Do not use libraries other than the
C++ Standard Library or Boost. See <a href="library_reuse.htm">Library
reuse</a>.
</li>
</ul>
<ul>
<li>Read <a href="imp_vars.htm">Implementation Variation</a> to see how to
supply performance, platform, or other implementation variations.
</li>
</ul>
<ul>
<li>Read the <a href="separate_compilation.html">guidelines for libraries
with separate source</a> to see how to ensure that compiled link libraries
meet user expectations.
</li>
</ul>
<ul>
<li>Use the naming conventions of the C++ Standard Library (See <a href=
"#Naming">Naming conventions rationale</a>):<br>
&nbsp;
<ul>
<li>Names (except as noted below) should be all lowercase, with words
separated by underscores.
</li>
<li>Acronyms should be treated as ordinary names (e.g.
<code>xml_parser</code> instead of <code>XML_parser</code>).
</li>
<li>Template parameter names begin with an uppercase letter.
</li>
<li>Macro (gasp!) names all uppercase and begin with BOOST_.
</li>
</ul>
</li>
</ul>
<ul>
<li>Choose meaningful names - explicit is better than implicit, and
readability counts. There is a strong preference for clear and descriptive
names, even if lengthy.
</li>
</ul>
<ul>
<li>Use exceptions to report errors where appropriate, and write code that
is safe in the face of exceptions.
</li>
</ul>
<ul>
<li>Avoid exception-specifications. See <a href="#Exception-specification">
exception-specification rationale</a>.
</li>
</ul>
<ul>
<li>Provide sample programs or confidence tests so potential users can see
how to use your library.
</li>
</ul>
<ul>
<li>Provide a regression test program or programs which follow the
<a href="test_policy.htm">Test Policies and Protocols</a>.
</li>
</ul>
<ul>
<li>Although some boost members use proportional fonts, tabs, and
unrestricted line lengths in their own code, boost's widely distributed
source code should follow more conservative guidelines:
<ul>
<li>Use fixed-width fonts.&nbsp; See <a href="#code_fonts">fonts
rationale</a>.
</li>
<li>Use spaces rather than tabs. See <a href="#Tabs">tabs
rationale</a>.
</li>
<li>Limit line lengths to 80 characters.
</li>
</ul>
</li>
</ul>
<ul>
<li>End all documentation files (HTML or otherwise) with a copyright
message and a licensing message. See <a href="license_info.html">license
information</a> page for the preferred form.
</li>
</ul>
<ul>
<li>Begin all source files (including programs, headers, scripts, etc.)
with:<br>
&nbsp;
<ul>
<li>A comment line describing the contents of the file.<br>
&nbsp;
</li>
<li>Comments describing copyright and licensing: again, the preferred
form is indicated in the <a href="license_info.html">license
information</a> page<br>
<br>
Note that developers should not provide a copy of
<code>LICENSE_1_0.txt</code> with their libraries: Boost
distributions already include a copy in the Boost root directory.<br>
&nbsp;
</li>
<li>A comment line referencing your library on the Boost web site. For
example:<br>
<br>
<code>//&nbsp; See http://www.boost.org/libs/foo/ for library home
page.</code><br>
<br>
where <code>foo</code> is the directory name (see below) for the
library. As well as aiding users who come across a Boost file
detached from its documentation, some of Boost's automatic tools
depend on this comment to identify which library header files belong
to.
</li>
</ul>
</li>
</ul>
<ul>
<li>Make sure your code compiles in the presence of the <code>min()</code>
and <code>max()</code> macros. Some platform headers define
<code>min()</code> and <code>max()</code> macros which cause some common
C++ constructs to fail to compile. Some simple tricks can protect your code
from inappropriate macro substitution:<br>
&nbsp;
<ul>
<li>If you want to call <code>std::min()</code> or
<code>std::max()</code>:<br>
&nbsp;
<ul>
<li>If you do not require argument-dependent look-up, use
<code>(std::min)(a,b)</code>.
</li>
<li style="list-style: none">
<br>
</li>
<li>If you do require argument-dependent look-up, you should:
</li>
<li style="list-style: none">
<br>
<ul>
<li>
<code>#include &lt;boost/config.hpp&gt;</code>
</li>
<li>Use <code>BOOST_USING_STD_MIN();</code> to bring
<code>std::min()</code> into the current scope.
</li>
<li>Use <code>min BOOST_PREVENT_MACRO_SUBSTITUTION
(a,b);</code> to make an argument-dependent call to
<code>min(a,b)</code>.
</li>
</ul>
</li>
</ul>
</li>
<li style="list-style: none">
<br>
</li>
<li>If you want to call
<code>std::numeric_limits&lt;int&gt;::max()</code>, use
<code>(std::numeric_limits&lt;int&gt;::max)()</code> instead.
</li>
<li style="list-style: none">
<br>
</li>
<li>If you want to call a <code>min()</code> or <code>max()</code>
member function, instead to doing <code>obj.min()</code>, use
<code>(obj.min)()</code>.<br>
</li>
<li style="list-style: none">
<br>
</li>
<li>If you want to declare or define a function or a member function
named <code>min</code> or <code>max</code>, then you must use the
<code>BOOST_PREVENT_MACRO_SUBSTITUTION</code> macro. Instead of writing
<code>int min() { return 0; }</code> you should write <code>int min
BOOST_PREVENT_MACRO_SUBSTITUTION () { return 0; }</code><br>
This is true regardless if the function is a free (namespace scope)
function, a member function or a static member function, and it
applies for the function declaration as well as for the function
definition.<br>
</li>
</ul>
</li>
</ul>
<h3>
<a name="Directory_structure" id="Directory_structure">Directory
Structure</a> and Filenames
</h3>
<ul>
<li>File and directory names must contain only <b>lowercase</b> ASCII
letters , numbers, underscores, and a period.&nbsp; Leading character must
be alphabetic. Maximum length 31. Only a single period is permitted.&nbsp;
These requirements ensure file and directory names are relatively portable.
</li>
<li>Files intended to be processed by a C++ compiler as part of a
translation unit should have <b>a three-letter filename extension ending in
"pp"</b>. Other files should <i>not</i> use extensions ending in "pp". This
convention makes it easy to identify all of the C++ source in Boost.
</li>
<li>All libraries have at their highest level a primary directory named for
the particular library. See <a href="#Naming_consistency">Naming
consistency</a>. The primary directory may have sub-directories.
</li>
<li>For very simple libraries implemented entirely within the library
header, all files go in the primary directory (except headers, which go in
the boost header directory).
</li>
</ul>
<blockquote>
<p>
<b>Boost standard sub-directory names</b>
</p>
<table border="1" cellpadding="5">
<tr>
<td>
<b>Sub-directory</b>
</td>
<td>
<b>Contents</b>
</td>
<td>
<b>Required</b>
</td>
</tr>
<tr>
<td>
<code>build</code>
</td>
<td>
Library build files such as a Jamfile.
</td>
<td>
If any build files.
</td>
</tr>
<tr>
<td>
<code>doc</code>
</td>
<td>
Documentation (HTML) files.
</td>
<td>
If several doc files.
</td>
</tr>
<tr>
<td>
<code>example</code>
</td>
<td>
Sample program files.
</td>
<td>
If several sample files.
</td>
</tr>
<tr>
<td>
<code>src</code>
</td>
<td>
Source files which must be compiled to build the library.&nbsp;
</td>
<td>
If any source files.
</td>
</tr>
<tr>
<td>
<code>test</code>
</td>
<td>
Regression or other test programs or scripts.
</td>
<td>
If several test files.
</td>
</tr>
</table>
</blockquote>
<h4>
<a name="Redirection" id="Redirection">Redirection</a>
</h4>
<p>
The primary directory should always contain a file named index.html (or
index.htm). Authors have requested this so that they can publish URL's in
the form <i>http://www.boost.org/libs/lib-name</i> with the assurance a
documentation reorganization won't invalidate the URL. Boost's internal
tools are also simplified by knowing that a library's documentation is
always reachable via the simplified URL.
</p>
<p>
If the documentation is in a doc sub-directory, the primary directory
index.html file should just do an automatic redirection to the doc
subdirectory:
</p>
<blockquote>
<pre>
&lt;html&gt;
&lt;head&gt;
&lt;meta http-equiv="refresh" content="0; URL=doc/index.html"&gt;
&lt;/head&gt;
&lt;body&gt;
Automatic redirection failed, please go to
&lt;a href="doc/index.html"&gt;doc/index.html&lt;/a&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
</blockquote>
<h3>
<a name="Naming_consistency">Naming consistency</a>
</h3>
<p>
As library developers and users have gained experience with Boost, the
following consistent naming approach has come to be viewed as very helpful,
particularly for larger libraries that need their own header subdirectories
and namespaces.
</p>
<p>
Here is how it works. The library is given a name that describes the
contents of the library. Cryptic abbreviations are strongly discouraged.
Following the practice of the C++ Standard Library, names are usually
singular rather than plural. For example, a library dealing with file
systems might chose the name "filesystem", but not "filesystems", "fs" or
"nicecode".
</p>
<ul>
<li>The library's primary directory (in parent <i>boost-root/libs</i>) is
given that same name.&nbsp; For example,
<i>boost-root/libs/filesystem</i>.<br>
&nbsp;
</li>
<li>The library's primary header directory (in parent
<i>boost-root/boost</i>) is given that same name. For example,
<i>boost-root/boost/filesystem</i>.<br>
&nbsp;
</li>
<li>The library's primary namespace (in parent <i>::boost</i>) is given
that same name, except when there's a component with that name (e.g.,
<i>boost::tuple</i>), in which case the namespace name is pluralized. For
example, <i>::boost::filesystem</i>.
</li>
</ul>
<p>
When documenting Boost libraries, follow these conventions (see also the
following section of this document):
</p>
<ul>
<li>The library name is set in roman type.
</li>
<li>The library name is capitalized.
</li>
<li>A period between "Boost" and the library name (e.g., Boost.Bind) is
used if and only if the library name is not followed by the word "library".
</li>
<li>The word "library" is not part of the library name and is therefore
lowercased.
</li>
</ul>
<p>
Here are a few examples of how to apply these conventions:
</p>
<ul>
<li>Boost.Bind was written by Peter Dimov.
</li>
<li>The Boost Bind library was written by Peter Dimov.
</li>
<li>I regularly use Bind, a Boost library written by Peter Dimov.
</li>
</ul>
<h3>
<a name="Documentation" id="Documentation">Documentation</a>
</h3>
<p>
Even the simplest library needs some documentation; the amount should be
proportional to the need.&nbsp; The documentation should assume the readers
have a basic knowledge of C++, but are not necessarily experts.
</p>
<p>
The format for documentation should be HTML, and should not require an
advanced browser or server-side extensions. Style sheets are acceptable.
ECMAScript/JavaScript is not acceptable. The documentation entry point
should always be a file named index.html or index.htm; see <a href=
"#Redirection">Redirection</a>.
</p>
<p>
There is no single right way to do documentation. HTML documentation is
often organized quite differently from traditional printed documents.
Task-oriented styles differ from reference oriented styles. In the end, it
comes down to the question: Is the documentation sufficient for the
mythical "average" C++ programmer to use the library successfully?
</p>
<p>
Appropriate topics for documentation often include:
</p>
<ul>
<li>General introduction to the library.
</li>
<li>Description of each class.
</li>
<li>Relationship between classes.
</li>
<li>For each function, as applicable, description, requirements
(preconditions), effects, post-conditions, returns, and throws.
</li>
<li>Discussion of error detection and recovery strategy.
</li>
<li>How to use including description of typical uses.
</li>
<li>How to compile and link.
</li>
<li>How to test.
</li>
<li>Version or revision history.
</li>
<li>Rationale for design decisions.&nbsp; See <a href=
"#Rationale">Rationale rationale</a>.
</li>
<li>Acknowledgements.&nbsp; See <a href="#Acknowledgements">Acknowledgments
rationale.</a>
</li>
</ul>
<p>
If you need more help with how to write documentation you can check out the
article on <a href="writingdoc/index.html">Writing Documentation for
Boost</a>.
</p>
<h2>
<a name="Rationale" id="Rationale">Rationale</a>
</h2>
<p>
Rationale for some of the requirements and guidelines follows.
</p>
<hr>
<h3>
<a name="Exception-specification" id=
"Exception-specification">Exception-specification</a> rationale
</h3>
<p>
Exception specifications [ISO 15.4] are sometimes coded to indicate what
exceptions may be thrown, or because the programmer hopes they will
improved performance.&nbsp; But consider the following member from a smart
pointer:
</p>
<pre>
T&amp; operator*() const throw() { return *ptr; }
</pre>
<p>
This function calls no other functions; it only manipulates fundamental
data types like pointers Therefore, no runtime behavior of the
exception-specification can ever be invoked.&nbsp; The function is
completely exposed to the compiler; indeed it is declared inline Therefore,
a smart compiler can easily deduce that the functions are incapable of
throwing exceptions, and make the same optimizations it would have made
based on the empty exception-specification. A "dumb" compiler, however, may
make all kinds of pessimizations.
</p>
<p>
For example, some compilers turn off inlining if there is an
exception-specification.&nbsp; Some compilers add try/catch blocks. Such
pessimizations can be a performance disaster which makes the code unusable
in practical applications.
</p>
<p>
Although initially appealing, an exception-specification tends to have
consequences that require <b>very</b> careful thought to understand. The
biggest problem with exception-specifications is that programmers use them
as though they have the effect the programmer would like, instead of the
effect they actually have.
</p>
<p>
A non-inline function is the one place a "throws nothing"
exception-specification may have some benefit with some compilers.
</p>
<hr>
<h3>
<a name="Naming" id="Naming">Naming</a> conventions rationale
</h3>
<p>
The C++ standard committee's Library Working Group discussed this issue in
detail, and over a long period of time. The discussion was repeated again
in early boost postings. A short summary:
</p>
<ul>
<li>Naming conventions are contentious, and although several are widely
used, no one style predominates.
</li>
<li>Given the intent to propose portions of boost for the next revision of
the C++ standard library, boost decided to follow the standard library's
conventions.
</li>
<li>Once a library settles on a particular convention, a vast majority of
stakeholders want that style to be consistently used.
</li>
</ul>
<hr>
<h3>
Source <a name="code_fonts" id="code_fonts">code fonts</a> rationale
</h3>
<p>
Dave Abrahams comments: An important purpose (I daresay the primary
purpose) of source code is communication: the documentation of intent. This
is a doubly important goal for boost, I think. Using a fixed-width font
allows us to communicate with more people, in more ways (diagrams are
possible) right there in the source. Code written for fixed-width fonts
using spaces will read reasonably well when viewed with a variable-width
font, and as far as I can tell every editor supporting variable-width fonts
also supports fixed width. I don't think the converse is true.
</p>
<hr>
<h3>
<a name="Tabs" id="Tabs">Tabs</a> rationale
</h3>
<p>
Tabs are banned because of the practical problems caused by tabs in
multi-developer projects like Boost, rather than any dislike in principle.
See <a href="mailing_lists.htm#archive">mailing list archives</a>. Problems
include maintenance of a single source file by programmers using tabs and
programmers using spaces, and the difficulty of enforcing a consistent tab
policy other than just "no tabs". Discussions concluded that Boost files
should either all use tabs, or all use spaces, and thus the decision to
stick with spaces.
</p>
<hr>
<h3>
ECMAScript/<a name="JavaScript" id="JavaScript">JavaScript</a> rationale
</h3>
<p>
Before the 1.29.0 release, two Boost libraries added ECMAScript/JavaScript
documentation. Controversy followed (see <a href=
"mailing_lists.htm#archive">mailing list archives</a>), and the developers
were asked to remove the ECMAScript/JavaScript. Reasons given for banning
included:
</p>
<ul>
<li>Incompatible with some older browsers and some text based browsers.
</li>
<li>Makes printing docs pages difficult.
</li>
<li>Often results in really bad user interface design.
</li>
<li>"It's just annoying in general."
</li>
<li>Would require Boost to test web pages for ECMAScript/JavaScript
compliance.
</li>
<li>Makes docs maintenance by other than the original developer more
difficult.
</li>
</ul>
<hr>
<h3>
<a name="Rationale_rationale" id="Rationale_rationale">Rationale
rationale</a>
</h3>
<p>
Rationale is defined as "The fundamental reasons for something; basis" by
the American Heritage Dictionary.
</p>
<p>
Beman Dawes comments:&nbsp; Failure to supply contemporaneous rationale for
design decisions is a major defect in many software projects. Lack of
accurate rationale causes issues to be revisited endlessly, causes
maintenance bugs when a maintainer changes something without realizing it
was done a certain way for some purpose, and shortens the useful lifetime
of software.
</p>
<p>
Rationale is fairly easy to provide at the time decisions are made, but
very hard to accurately recover even a short time later.
</p>
<hr>
<h3>
<a name="Acknowledgements" id="Acknowledgements">Acknowledgements</a>
rationale
</h3>
<p>
As a library matures, it almost always accumulates improvements suggested
to the authors by other boost members.&nbsp; It is a part of the culture of
boost.org to acknowledge such contributions, identifying the person making
the suggestion.&nbsp; Major contributions are usually acknowledged in the
documentation, while minor fixes are often mentioned in comments within the
code itself.
</p>
<hr>
<p>
Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->
04 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
</p>
<p>
&copy; <a name="Copyright" id="Copyright">Copyright</a> Beman Dawes 2003.
</p>
<p>
Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

75
library_reuse.htm
View File

@ -1,75 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Boost Library Reuse</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
&nbsp;
<h1>Boost Library reuse: cost versus benefit trade-offs</h1>
<p>A Boost library <b>should not</b> use libraries other than Boost or the C++
Standard Library.</p>
<p>A Boost library <b>should</b> use other Boost Libraries or the C++ Standard
Library, but only when the benefits outweigh the costs.&nbsp;</p>
<p>The benefits of using components from other libraries may include clearer,
more understandable code, reduced development and maintenance costs, and the
assurance which comes from reusing well-known and trusted building blocks.</p>
<p>The costs may include undesirable coupling between components, and added
compilation and runtime costs.&nbsp; If the interface to the additional
component is complex, using it may make code less readable, and thus actually
increase development and maintenance costs.</p>
<p>Negative effects of coupling become obvious when one library uses a second
library which uses a third, and so on. The worst form of coupling requires the
user understand each of the coupled libraries. Coupling may also reduce the
portability of a library - even in case when all used libraries are
self-sufficient (see example of questionable usage of &lt;iostream&gt; library
below).</p>
<p><b>Example where another boost component should certainly be used:</b>&nbsp;
boost::noncopyable (in <a href="../boost/utility.hpp">boost/utility.hpp</a>) has
considerable benefits; it simplifies code, improves readability, and signals
intent.&nbsp; Costs are low as coupling is limited;&nbsp; noncopyable itself
uses no other classes and its header includes only the lightweight headers
&lt;boost/config.hpp&gt; and &lt;cstddef&gt;.&nbsp; There are no runtime costs
at all. With costs so low and benefits so high, other boost libraries should use
boost::noncopyable when the need arises except in exceptional circumstances.</p>
<p><b>Example where a standard library component might possibly be used:</b>
Providing diagnostic output as a debugging aid can be a nice feature for a
library. Yet using Standard Library &lt;iostream&gt; can involves a lot of
additional cost, particularly if &lt;iostream&gt; is unlikely to be use
elsewhere in the application.&nbsp; In certain GUI or embedded applications,
coupling to &lt;iostream&gt; would be a disqualification.&nbsp;&nbsp;&nbsp;
Consider redesign of the boost library in question so that the user supplies the
diagnostic output mechanism.</p>
<p><b>Example where another boost component should not be used:</b>&nbsp; The
boost dir_it library has considerable coupling and runtime costs, not to mention
portability issues for unsupported operating systems.&nbsp; While completely
appropriate when directory iteration is required, it would not be reasonable for
another boost library to use dir_it just to check that a file is available
before opening.&nbsp; C++ Standard Library file open functionality does this at
lower cost.&nbsp; Don't use dir_it just for the sake of using a boost library.</p>
<hr>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->02 October 2003<!--webbot bot="Timestamp" endspan i-checksum="32277" --></p>
<p>© Copyright Beman Dawes 2000</p>
<p>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

280
license_info.html
View File

@ -1,280 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html">
<title>Boost Software License Background</title>
</head>
<body bgcolor="#FFFFFF">
<table summary="Navigational header"
border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Information about the <a href="../LICENSE_1_0.txt">Boost Software License</a> </h1>
<p><a href="../LICENSE_1_0.txt">License text</a><br>
<a href="#Introduction">Introduction</a><br>
<a href="#History">History</a><br>
<a href="#Rationale">Rationale</a><br>
<a href="#FAQ">FAQ</a><br>
<a href="#Transition">Transition</a><br>
<a href="#Acknowledgements">Acknowledgements</a></p>
<h2><a name="Introduction">Introduction</a></h2>
<p>The <a href="../LICENSE_1_0.txt">Boost Software License</a>
specifies the terms and conditions of use for those Boost libraries
that it covers.</p>
<p>Currently, some Boost libraries have their own licenses. The hope is that
eventually all Boost libraries will be covered by the Boost Software
License. In the meantime, <b>all</b> libraries comply with the <a
href="#requirements">Boost License requirements</a>.</p>
<h2><a name="History">History</a></h2>
<p>As Boost grew, it became unmanageable for each Boost file to have
its own license. Users complained that each license needed to be reviewed, and that
reviews were difficult or impossible if Boost libraries contained many different licenses.
Boost moderators and maintainers spent excessive time dealing with license
issues. Boost developers often copied existing licenses without actually knowing
if the license wording met legal needs.</p>
<p>To clarify these licensing issues, the Boost moderators asked for help from
the <a href="http://cyber.law.harvard.edu">Berkman Center for Internet &amp; Society</a>
at Harvard Law School, Cambridge, Massachusetts, USA. It was requested that a
single Boost license be developed that met the traditional requirements that Boost licenses, particularly:</p>
<a name="requirements"></a>
<ul>
<li>Must be simple to read and understand. </li>
<li>Must grant permission without fee to copy, use and modify the software for
any use (commercial and non-commercial). </li>
<li>Must require that the license appear with all copies [including
redistributions] of the software source code. </li>
<li>Must not require that the license appear with executables or other binary
uses of the library. </li>
<li>Must not require that the source code be available for execution or other
binary uses of the library. </li>
</ul>
<p>Additionally, other common open source licenses were studied to see what
additional issues were being treated, and additions representing good legal
practice were also requested. The result is the <a href="../LICENSE_1_0.txt">Boost
Software License</a>.</p>
<h2><a name="Rationale">Rationale</a></h2>
<p>The following rationale was provided by Devin Smith, the
lawyer who wrote the Boost Software License. It has been edited slightly for
brevity. Editorial additions are shown in square brackets.</p>
<h3>Benefit of Common Software License</h3>
<p>If one of Boost's goals is to ease use and adoption of the various
libraries made available by Boost, it does make sense to try to
standardize the licenses under which the libraries are made available to
users. (I make some recommendations about a possible short-form license
below.)</p>
<p>[Standardizing the license will not] necessarily address the issue of satisfying
corporate licensees. Each corporation will have its own concerns, based
on their own experiences with software licensing and distribution and,
if they're careful, will want to carefully review each license, even if
they've been told that they're all standard. I would expect that,
unless we're remarkably brilliant (or lucky) in drafting the standard
Boost license, the standard license won't satisfy the legal departments
of all corporations. I imagine that some will, for instance, absolutely
insist that licensors provide a warranty of title and provide
indemnification for third-party intellectual property infringement
claims. Others may want functional warranties. (If I were advising the
corporations, I would point out that they're not paying anything for the
code and getting such warranties from individual programmers, who
probably do not have deep pockets, is not that valuable anyway, but
other lawyers may disagree.)</p>
<p>But this can be addressed, not by trying to craft the perfect standard
license, but by informing the corporations that they can, if they don't like the
standard license, approach the authors to negotiate a different, perhaps even
paid, license.</p>
<p>One other benefit of adopting a standard license is to help ensure that
the license accomplishes, from a legal perspective, what the authors
intend. For instance, many of the [original] licenses for the libraries available
on boost.org do not disclaim the warranty of title, meaning that the
authors could, arguably, be sued by a user if the code infringes the
rights of a third party and the user is sued by that third party. I
think the authors probably want to disclaim this kind of liability.</p>
<h3>Short-Form License</h3>
<p>Without in anyway detracting from the draft license that's been
circulated [to Boost moderators], I'd like to propose an alternative &quot;short-form&quot; license that
Boost could have the library authors adopt. David [Abrahams] has expressed a
desire to keep things as simple as possible, and to try to move away
from past practice as little as possible, and this is my attempt at a
draft.</p>
<p>This license, which is very similar to the BSD license and the MIT
license, should satisfy the Open Source Initiative's Open Source
Definition: (i) the license permits free redistribution, (ii) the
distributed code includes source code, (iii) the license permits the
creation of derivative works, (iv) the license does not discriminate
against persons or groups, (v) the license does not discriminate against
fields of endeavor, (vi) the rights apply to all to whom the program is
redistributed, (vii) the license is not specific to a product, and (viii) the
license is technologically neutral (i.e., it does not [require] an explicit gesture of
assent in order to establish a contract between licensor and licensee).</p>
<p>This license grants all rights under the owner's copyrights (as well as an
implied patent license), disclaims all liability for use of the code (including
intellectual property infringement liability), and requires that all subsequent
copies of the code [except machine-executable object code], including partial copies and derivative works, include the
license.</p>
<h2><a name="FAQ">FAQ</a></h2>
<p><b>How should Boost programmers apply the license to source and
header files?</b></p>
<p>Add a comment based on the following template, substituting
appropriate text for the italicized portion:
<br>
<br>
<pre>
// Copyright <i>Joe Coder 2004 - 2006</i>.
// 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)
</pre>
<br>
Please leave an empty line before and after the above comment block.
It is fine if the copyright and license messages are not on different lines; in
no case there should be other intervening text. Do not include
"All rights reserved" anywhere.<br>
<p>Other ways of licensing source files have been considered, but some
of them turned out to unintentionally nullify legal elements of the
license. Having fixed language for referring to the license helps
corporate legal departments evaluate the boost distribution.
Creativity in license reference language is strongly discouraged, but
judicious changes in the use of whitespace are fine.
<p><b>How should the license be applied to documentation files, instead?</b></p>
<p>Very similarly to the way it is applied to source files: the user should
see the very same text indicated in the template above, with the only difference
that both the local and the web copy of LICENSE_1_0.txt should be linked to.
Refer to the HTML source code of this page in case of doubt.
<p>Note that the location of the local LICENSE_1_0.txt needs to be indicated
relatively to the position of your documentation file
(<code>../LICENSE_1_0.txt</code>, <code>../../LICENSE_1_0.txt</code> etc.)</p>
<p><b>How is the Boost license different from the
<a href="http://www.opensource.org/licenses/gpl-license.php">GNU General Public
License (GPL)</a>?</b></p>
<p>The Boost license permits the creation of derivative works for
commercial or non-commercial use with no legal requirement to release
your source code. Other differences include Boost not requiring
reproduction of copyright messages for object code redistribution, and
the fact that the Boost license is not &quot;viral&quot;: if you
distribute your own code along with some Boost code, the Boost license
applies only to the Boost code (and modified versions thereof); you
are free to license your own code under any terms you like. The GPL is
also much longer, and thus may be harder to understand.</p>
<p><b>Why the phrase &quot;machine-executable object code generated by a source
language processor&quot;?</b></p>
<p>To distinguish cases where we do not require reproduction of the copyrights
and license, such as object libraries, shared libraries, and final program
executables, from cases where reproduction is still required, such as
distribution of self-extracting archives of source code or precompiled header
files. More detailed wording was rejected as not being legally necessary, and
reducing readability.</p>
<p><b>Why is the &quot;disclaimer&quot; paragraph of the license entirely in uppercase?</b></p>
<p>Capitalization of these particular provisions is a US legal mandate for
consumer protection. (Diane Cabell)</p>
<p><b>Does the copyright and license cover interfaces too?</b></p>
<p>The conceptual interface to a library isn't covered. The particular
representation expressed in the header is covered, as is the documentation,
examples, test programs, and all the other material that goes with the library.
A different implementation is free to use the same logical interface, however.
Interface issues have been fought out in court several times; ask a lawyer for
details.</p>
<p><b>Why doesn't the license prohibit the copyright holder from patenting the
covered software?</b></p>
<p>No one who distributes their code under the terms of this license could turn
around and sue a user for patent infringement. (Devin Smith)</p>
<p>Boost's lawyers were well aware of patent provisions in licenses like the GPL
and CPL, and would have included such provisions in the Boost license if they
were believed to be legally useful.</p>
<p><b>Why doesn't the copyright message say &quot;All rights reserved&quot;?</b></p>
<p>Devin Smith says &quot;I don't think it belongs in the copyright notice for
anything (software, electronic documentation, etc.) that is being licensed. It
belongs in books that are sold where, in fact, all rights (e.g., to reproduce
the book, etc.) are being reserved in the publisher or author. I think it
shouldn't be in the BSD license.&quot;</p>
<p><b>Do I have to copyright/license trivial files?</b>
<p>Even a test file that just contains an empty <code>main()</code>
should have a copyright. Files without copyrights make corporate
lawyers nervous, and that's a barrier to adoption. The more of Boost
is uniformly copyrighted and licensed, the less problem people will
have with mounting a Boost release CD on a corporate server.
<p><b>Can I use the Boost license for my own projects outside Boost?</b>
<p>Sure; there are no restrictions on the use of the license itself.
<h2><a name="Transition">Transition</a></h2>
<p>To ease the transition of the code base towards the new common
license, several people decided to give a <a
href="blanket-permission.txt">blanket permission</a> for all
their contributions to use the new license. This hopefully helps
maintainers to switch to the new license once the list contains enough
names without asking over and over again for each change. Please
consider adding your name to the list.</p>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
<p>Dave Abrahams led the Boost effort to develop better licensing. The legal
team was led by
<a href="http://cyber.law.harvard.edu/people/cabell/index.html">Diane Cabell</a>,
Director, Clinical Programs, <a href="http://cyber.law.harvard.edu">Berkman
Center for Internet &amp; Society</a>, Harvard Law School.
<a href="http://www.nixonpeabody.com/attorneys_detail1.asp?ID=121">Devin Smith</a>, attorney, <a href="http://www.nixonpeabody.com/default.asp">
Nixon Peabody LLP</a>, wrote the Boost License. Eva Chan, Harvard Law School,
contributed analysis of Boost issues and drafts of various legal documents.
Boost members reviewed drafts of the license. Beman Dawes wrote this web page.</p>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->27 August, 2004<!--webbot bot="Timestamp" endspan i-checksum="39365" --></p>
<p> &copy; Copyright 2003-2004 Beman Dawes, Daniel Frey, David Abrahams.</p>
<p> Distributed under the Boost Software License, Version 1.0.
(See accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

74
links.htm
View File

@ -1,74 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Links</title>
</head>
<body bgcolor="#FFFFFF">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td>
<td><a href="../more/faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="../more/index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Links</h1>
<p>Here are a few links of special interest to Boost users. For general queries,
try your favorite search engine.</p>
<h2><a name="CommercialSupport">Commercial Support</a> for Boost Libraries</h2>
<ul>
<li><a href="http://www.boost-consulting.com">Boost Consulting</a> - Support,
training, and consulting from Boost experts.</li>
</ul>
<h2><a name="cpp">C++</a> Organizations</h2>
<ul>
<li><a href="http://www.open-std.org/jtc1/sc22/wg21/">C++ Standards Committee</a> -
Issues lists and papers give insight into current status and future
directions.</li>
<li><a href="http://www.accu.org">Association of C &amp; C++ Users</a> - Over 2400
book reviews, and lots more.</li>
</ul>
<h2>Online Publications</h2>
<ul>
<li><a href="http://www.artima.com/cppsource/index.jsp">The C++ Source</a> -
<i>&quot;The Premier Online Journal for the C++ Community&quot;</i>.</li>
</ul>
<h2>Copies of the C++ Standard</h2>
<ul>
<li>
<a href="http://webstore.ansi.org/ansidocstore/product.asp?sku=INCITS%2FISO%2FIEC+14882%2D2003">
ANSI Store</a> - The full C++ Standard including TC1 corrections (INCITS/ISO/IEC 14882) is available
as a PDF document for $18 US. The document is certainly not a
tutorial, but is interesting to those who care about the
precise specification of both the language and the standard
library.</li>
<li>
<a href="http://www.wiley.com/WileyCDA/WileyTitle/productCd-0470846747.html">
Book</a> - The full C++ Standard including TC1 corrections is also available
in book form, list price $65 US. Since the content of the book is the same as
the much cheaper ANSI PDF, the book form is only of interest to those who
prefer a physical book, say for a school or company library.</li>
</ul>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->02 October, 2004<!--webbot bot="Timestamp" endspan i-checksum="38677" --></p>
<p>© Copyright Beman Dawes 2002</p>
<p>Distributed under the Boost Software License, Version 1.0. (See accompanying
file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at
<a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

408
mailing_lists.htm
View File

@ -1,408 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Mailing Lists</title>
<meta name="generator" content=
"Microsoft FrontPage 5.0">
<meta name="generator" content="Microsoft FrontPage 5.0">
<meta name="generator" content="Microsoft FrontPage 5.0">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<style type="text/css">
@import ../boost.css
.first {
margin-top: 0 }
.last {
margin-bottom: 0 }
div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning, div.admonition {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title,
div.admonition p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
</style>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table summary="Navigational header"
border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt=
"boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color=
"#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color=
"#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color=
"#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color=
"#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color=
"#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Boost Mailing Lists and other resources</h1>
<p>The mailing lists are the heart of the Boost community.&nbsp; You may
read the lists via full-content email, email digests, or via newsgroup
reader.</p>
<p>Hosting for the mailing lists is donated by the <a href=
"http://www.osl.iu.edu/">Open Systems Lab at Indiana University</a>.</p>
<p>Access to Boost mailing lists via newsgroup (NNTP) is contributed by
<a href="http://www.gmane.org/">GMANE</a>.</p><a name="gmane_post" id=
"gmane_post"></a><a name="important_notes" id="important_notes"></a>
<div class="admonition-note admonition">
<p class="first admonition-title">Before Posting</p>
<p class="last">
<b>Read the <a href="discussion_policy.htm">Discussion Policy and
Guide to Effective Posting</a>.</b>&nbsp; Doing so will help you
to ensure that your post is read by the people who can help you
and received in the spirit in which it was intended.
<p>
<b>Subscribe your posting address.</b>&nbsp; As an anti-spam
measure, postings to most Boost mailing lists will only be
accepted if the posting's "From:" header contains an email
address that is subscribed to the list.&nbsp; If you try to post from
an address that isn't subscribed, you will probably get a
message that says:</p>
<blockquote>
<tt>You are not allowed to post to this mailing list, and your message
has been automatically rejected. If you think that your messages are
being rejected in error, contact the mailing list owner at</tt> <i>list
administrator's email address</i>.
</blockquote>If you need to post from multiple email addresses, you
should subscribe each one separately.&nbsp; You can configure your subscription
settings for any address to disable mail delivery via each mailing list's
web interface.
<p>Even postings made through the <a href=
"http://www.gmane.org">GMane</a> news server need to be made from
subscribed addresses because GMane simply forwards your postings
on to the appropriate email list.&nbsp; Don't be fooled by GMane's
authentication message that says "you are now authorized to post
to this list" after you answer its autogenerated mail; only
subscribed addresses may post.</p>
</div>
<dl>
<dt><a href="#users">Boost Users</a> list
<dt><a href="#main">Boost developers</a> list</dt>
<dd>
<dl>
<dt><a href="#archive">Archives</a> for the Boost developers
list</dt>
</dl>
</dd>
<dt><a href="#announce">Boost Announce</a> list</dt>
<dt><a href="#interest">Boost Interest</a> list</dt>
<dt><a href="#projects">Project-Specific</a> lists</dt>
<dd>
<dl>
<dt><a href="#jamboost">Boost.Build</a> list</dt>
<dt><a href="#cplussig">Python C++-Sig</a> (for Boost.Python)</dt>
<dt><a href="#langbinding">Language Binding</a> (for generalized C++
bindings)</dt>
<dt><a href="#spirit">Boost.Spirit</a> lists</dt>
<dt><a href="https://lists.sourceforge.net/lists/listinfo/boost-docs">Boost.Documentation</a> list</dt>
<dt><a href="#testing">Testing</a> list (about regression-testing the
boost libraries, not for the Boost.Test library specifically)</dt>
<dt><a href="#ublas">Boost.uBlas (numerics)</a> list</dt>
<dt><a href="#thread">Boost.Thread</a> list</dt>
</dl>
</dd>
<dt><a href="#sandbox">Boost Sandbox CVS</a></dt>
<dt><a href="#IRC">#boost IRC channel</a></dt>
</dl>
<h2>Boost <a name="users" id="users">Users</a> mailing list (also available
via newsgroup)</h2>
<p>This list is oriented toward casual users of the Boost
libraries.&nbsp;It is a good place to start if you are having
trouble getting started with Boost or its individual libraries. Feel
free to post both "newbie" and more challenging questions, but
please check first to see if there's an
appropriate <a href="#projects">Project-Specific</a> list; you'll
often get better answers in a forum dedicated to your problem
area.&nbsp; This list is relatively
low volume (less than 500 per month).&nbsp; Subscribe or unsubscribe
at the <a href=
"http://lists.boost.org/mailman/listinfo.cgi/boost-users">Boost Users list
home page</a>.
</p>
<p>For those who prefer to participate via an NNTP (<a name=
"users_newsgroup" id="users_newsgroup">newsgroup</a>) interface, a gateway
to the Boost Users mailing list is available at <a href=
"news://news.gmane.org/gmane.comp.lib.boost.user">news://news.gmane.org/gmane.comp.lib.boost.user</a>.
You can also browse <a href=
"http://news.gmane.org/thread.php?group=gmane.comp.lib.boost.user">Gmane's
searchable archive</a>.</p>
<h2><a name="main" id="main">Boost</a> developers mailing list (also
available via newsgroup)</h2>
<p>This is the main Boost mailing list.&nbsp; It is high volume (over 1000
messages per month), very technical, and oriented toward Boost library
developers. It is also read by many other members interested in watching
the Boost library development process.&nbsp; Virtually all Boost decisions,
major or minor, technical or otherwise, are reached via public discussion
on this mailing list.&nbsp; It is where the formal reviews of proposed
libraries take place. Subscribe or unsubscribe at <a href=
"http://lists.boost.org/mailman/listinfo.cgi/boost">http://lists.boost.org/mailman/listinfo.cgi/boost</a>.</p>
<p>When we talk about the "members of Boost", we are talking about those
signed up for this main mailing list.</p>
<p>For those who prefer to participate via an NNTP (<a name="newsgroup" id=
"newsgroup">newsgroup</a>) interface, a gateway to the Boost mailing list
is available at <a href=
"news://news.gmane.org/gmane.comp.lib.boost.devel">news://news.gmane.org/gmane.comp.lib.boost.devel</a>.
<p>Preliminary libraries under discussion are available from the <a href=
"http://boost-consulting.com/vault/">Vault</a>.</p>
<h3><a name="archive" id="archive">Archives</a> for Boost developers
list</h3>
<p>A <a href=
"http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/boost/">searchable
mailing list archive</a> has been generously contributed to the <a href=
"http://aspn.activestate.com">ActiveState Programmer Network</a> by
<a href="http://aspn.activestate.com">ActiveState Corporation</a>. <a href=
"http://aspn.activestate.com"><img alt="ASPN logo" align="top" src=
"http://www.activestate.com/img/ASPN_logo_smallest.gif" width="65" height=
"20"></a><a href="http://www.activestate.com"><img alt="Active State logo"
align="top" src="http://aspn.activestate.com/ASPN/img/ASLogo_57x25.gif"
width="57" height= "25"></a></p>Other archives of Boost messages include the
<a href="http://news.gmane.org/thread.php?group=gmane.comp.lib.boost.devel">Boost
GMane NNTP Archive</a>, <a href=
"http://www.mail-archive.com/boost%40lists.boost.org/">The Mail
Archive</a>, <a
href="http://archives.free.net.ph/list/boost.en.html">The Free
Network Group</a>, and of course there is a Google search link for our <a href=
"http://lists.boost.org/Archives/boost/">MailMan Archive</a> on
<a href="../index.htm">our home page</a>.
<h2>Boost <a name="announce" id="announce">Announce</a> mailing list</h2>
<p>This is an announce-only list for notification of upcoming software
releases and formal reviews of proposed libraries. One to three messages
per month.&nbsp; Subscribe or unsubscribe at the <a href=
"http://lists.boost.org/mailman/listinfo.cgi/boost-announce">Boost Announce
list home page</a>.</p><a name="interest" id="interest"></a>
<h2>Boost Interest Mailing List</h2>
<p>This list is a moderated low-traffic announcement-only list of interest
to the Boost community. On topic messages will include announcements of
books, magazine articles, papers, talks, seminars, products, tools, events,
or conferences on advanced uses of C++,
generic/generative/meta-programming, and, of course, the Boost libraries.
Off topic will be discussion of any kind and job postings. Subscribe or
unsubscribe at the <a href=
"http://lists.boost.org/mailman/listinfo.cgi/boost-interest">Boost-Interest
home page</a>.</p>
<h2><a name="projects" id="projects">Project-Specific lists</a></h2>Several
mailing lists have been established for specific Boost projects:
<dl>
<dd>
<h3><a name="jamboost" id="jamboost">Boost.Build</a>
list</h3>The mailing list for the <a href=
"../tools/build">Boost Build System</a> is located <a href=
"http://lists.boost.org/mailman/listinfo.cgi/boost-build">here</a>. GMane provides
<a href="news://news.gmane.org/gmane.comp.lib.boost.build">NNTP
access</a> and <a href=
"http://news.gmane.org/thread.php?group=gmane.comp.lib.boost.build">Searchable
Archives</a> as well.
<h3><a name="cplussig" id="cplussig">Python C++-Sig</a> (for
Boost.Python)</h3>The <a href=
"http://www.python.org/community/sigs/current/c++-sig/">Python C++-sig</a> is not
strictly Boost-specific, but nearly all the traffic concerns <a href=
"../libs/python">Boost.Python</a>. See also the <a href=
"#langbinding">Language Binding</a> list below. GMane provides <a href=
"news://news.gmane.org/gmane.comp.python.c%2b%2b">NNTP access</a> and
<a href=
"http://news.gmane.org/thread.php?group=gmane.comp.python.c%2b%2b">Searchable
Archives</a> as well. There are also searchable archives at
<a href=
"http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/cpp-sig">ASPN</a>.
<h3><a name="langbinding" id="langbinding">Language Binding</a></h3>The
<a href=
"http://lists.sourceforge.net/lists/listinfo/boost-langbinding">Language
Binding</a> list is for discussion of a generalized framework for
binding C++ to other languages and systems based on the technology of
<a href="../libs/python">Boost.Python</a> and <a href=
"http://luabind.sourceforge.net/">Luabind</a>. The plan is to provide a
single front-end for describing bindings with runtime-pluggable back
ends for binding to specific languages. It is <b>highly recommended</b>
that new subscribers read through the <a href=
"http://news.gmane.org/thread.php?group=gmane.comp.lib.boost.langbinding">
message history</a> <b>from the beginning</b> before posting; it will
save time as much design progress has already been made. GMane provides
<a href="news://news.gmane.org/gmane.comp.lib.boost.langbinding">NNTP
access</a> and <a href=
"http://news.gmane.org/thread.php?group=gmane.comp.lib.boost.langbinding">
Searchable Archives</a> as well.
<h3><a name="spirit" id="spirit">Boost.Spirit</a> lists</h3>Spirit has
two additional mailing lists. <a href=
"https://lists.sourceforge.net/lists/listinfo/spirit-general">Spirit-general</a>
for Spirit users and <a href=
"https://lists.sourceforge.net/lists/listinfo/spirit-devel">Spirit-devel</a>
for Spirit developers (open to anyone who wishes to hang out with
Spirit coders). Both have <a href="http://www.gmane.org">GMane</a> NNTP
access (<a href=
"news://news.gmane.org/gmane.comp.parsers.spirit.general">Spirit-general</a>
and <a href=
"news://news.gmane.org/gmane.comp.parsers.spirit.devel">Spirit-devel</a>)
with searchable archives ( <a href=
"http://news.gmane.org/thread.php?group=gmane.comp.parsers.spirit.general">
Spirit-general</a> and <a href=
"http://news.gmane.org/thread.php?group=gmane.comp.parsers.spirit.devel">
Spirit-devel</a>).
<h3><a name="boostdocs" id="boostdocs">Boost.Documentation</a>
list</h3>The SourceForge mailing list for the <a href=
"../doc/html/boostbook.html">Boost Documentation System</a> is located <a href=
"https://lists.sourceforge.net/lists/listinfo/boost-docs">here</a>.
GMane provides <a href=
"news://news.gmane.org/gmane.comp.lib.boost.documentation">NNTP
access</a> and <a href=
"http://news.gmane.org/thread.php?group=gmane.comp.lib.boost.documentation">
Searchable Archives</a> as well.
<h3><a name="ublas" id="ublas">uBLAS development</a> (ublas-dev)
list</h3>A seperate user and developer mailing list for <a href=
"../libs/numeric/ublas/doc/index.htm">Boost uBLAS</a> specific topics is
located <a href="http://lists.boost.org/">here</a>.
<h3><a name="thread" id="thread">Thread development</a> (threads-devel)
list</h3>A seperate developer mailing list for <a href=
"../libs/thread/doc/index.html">Boost Thread</a> specific topics is
located
<a href="http://lists.boost.org/mailman/listinfo.cgi/threads-devel">here</a>.
<p><strong>Important: </strong>This mailing list is for the discussion of
the specification and implementation of Boost.Threads only &mdash;
questions regarding usage should be directed to the
<a href="#users">Boost Users</a> list, or the main
<a href="#main">Boost developers</a> list.
<p>GMane provides <a href=
"news://news.gmane.org/gmane.comp.lib.boost.threads-devel">NNTP
access</a> and <a href=
"http://news.gmane.org/thread.php?group=gmane.comp.lib.boost.threads-devel">
Searchable Archives</a> as well.
<h3><a name="testing" id="testing">Testing</a> list</h3>
<p>The setup, procedures and tools necessary for running Boost
regression tests are discussed on <a href=
"http://lists.boost.org/mailman/listinfo.cgi/boost-testing">this
list</a>. The list main participants are regression runners - people
who run Boost tests on a variety of compilers and platforms, and the
maintainers of tools for collecting and processing test results.</p>
<p><b>Important:</b> questions relevant to a wider audience, including
questions about Boost.Test framework or test results for a particular
library, should be posted to main development list.</p><a href=
"news://news.gmane.org/gmane.comp.lib.boost.documentation">NNTP
access</a> and <a href=
"http://news.gmane.org/gmane.comp.lib.boost.testing">Searchable
Archives</a> are available on <a href="http://www.gmane.org">GMane</a>.
</dd>
</dl>
<h2>Boost <a name="sandbox" id="sandbox">Sandbox</a> CVS</h2>
<p>In addition to the main <a href="getting_started.html#CVS">Boost CVS
repository</a>, a separate Sandbox CVS is available for Boost developers
wishing to collaborate on projects prior to formal acceptance of a new
library.&nbsp; Read-only access is available <a href=
"http://boost.cvs.sourceforge.net/boost-sandbox/boost-sandbox/">
via the web</a>, or via CVS client at:</p>
<blockquote>
<p>
&nbsp;<code>:pserver:anonymous@boost-sandbox.cvs.sourceforge.net:/cvsroot/boost-sandbox</code></p>
</blockquote>
<p><b>For write access</b> to the sandbox, contact the project admins
listed on its <a href=
"http://sourceforge.net/projects/boost-sandbox/">Sourceforge Project
Page</a>.</p>
<h2>#boost <a name="IRC" id="IRC">IRC</a> channel</h2>
<p>In addition to the mailing lists presented above, a #boost IRC channel on
<a href="http://freenode.net">freenode</a> is frequented by some boost users.
As usual with IRC channels, one should not necessarily expect that his questions
will be answered. The channel is not moderated.</p>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y"
startspan -->11 December, 2006<!--webbot bot="Timestamp" endspan
i-checksum="39365" --></p>
<p>Copyright Beman Dawes and David Abrahams 2001-2005</p>
<p>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

326
microsoft_vcpp.html
View File

@ -1,326 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<title>Portability Hints: Microsoft Visual C++ 6.0 SP4</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2" summary="">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt=
"boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial,Helvetica" color=
"#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color=
"#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial,Helvetica" color=
"#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial,Helvetica" color=
"#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial,Helvetica" color=
"#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Portability Hints: Microsoft Visual C++ 6.0 SP4</h1>
<p>Similar to the <a href="borland_cpp.html">portability hints for Borland
C++</a>, this page provides hints on some language features of the
Microsoft Visual C++ version 6.0 service pack 4 compiler. A list of
acknowledged deficiencies can be found at the <a href=
"http://support.microsoft.com/support/kb/articles/q243/4/51.asp">Microsoft
support site</a>.</p>
<p>Each entry in the following list describes a particular issue, complete
with sample source code to demonstrate the effect. Most sample code herein
has been verified to compile with gcc 2.95.2 and Comeau C++ 4.2.44.</p>
<h2>Preprocessor symbol</h2>
<p>The preprocessor symbol <code>_MSC_VER</code> is defined for all
Microsoft C++ compilers. Its value is the internal version number of the
compiler interpreted as a decimal number. Since a few other compilers also
define this symbol, boost provides the symbol <code>BOOST_MSVC</code>,
which is defined in <a href="../boost/config.hpp">boost/config.hpp</a> to
the value of _MSC_VER if and only if the compiler is really Microsoft
Visual C++. The following table lists some known values.</p>
<table border="1" summary="">
<tr>
<th>Compiler</th>
<th><code>BOOST_MSVC</code> value</th>
</tr>
<tr>
<td>Microsoft Visual C++ 6.0 (up to SP6)</td>
<td>1200</td>
</tr>
<tr>
<td>Microsoft embedded Visual C++ 4.0</td>
<td>1200-1202 (cross compilers)</td>
</tr>
</table>
<h2>Core Language</h2>
<h3>[chained using] Chaining <code>using</code>-declarations</h3>
<p>Chaining <code>using</code>-declarations does not work.</p>
<pre>
void f();
namespace N {
using ::f;
}
void g()
{
using N::f; // C2873: 'f': the symbol cannot be used in a using-declaration
}
</pre>
<h3>[explicit-instantiation] Explicit function template instantiation</h3>
<p>Trying to explicitly instantiate a function template leads to the wrong
function being called silently.</p>
<pre>
#include &lt;stdio.h&gt;
template&lt;class T&gt;
void f()
{
printf("%d\n", sizeof(T));
}
int main()
{
f&lt;double&gt;(); // output: "1"
f&lt;char&gt;(); // output: "1"
return 0;
}
</pre>
<h3>[for-scoping] Scopes of definitions in for-loops</h3>
<p>The scope of variable definitions in <code>for</code> loops should be
local to the loop's body, but it is instead local to the enclosing
block.</p>
<pre>
int main()
{
for(int i = 0; i &lt; 5; ++i)
;
for(int i = 0; i &lt; 5; ++i) // C2374: 'i': Redefinition; multiple initialization
;
return 0;
}
</pre>
<p><strong>Workaround:</strong> Enclose the offending <code>for</code>
loops in another pair of curly braces.</p>
<p>Another possible workaround (brought to my attention by Vesa Karvonen)
is this:</p>
<pre>
#ifndef for
#define for if (0) {} else for
#endif
</pre>
<p>Note that platform-specific inline functions in included headers might
depend on the old-style <code>for</code> scoping.</p>
<h3>[inclass-member-init] In-class member initialization</h3>
<p>In-class member initialization, required to implement a
Standard-conforming <code>std::numeric_limits</code> template, does not
work.</p>
<pre>
struct A
{
static const int i = 5; // "invalid syntax for pure virtual method"
};
</pre>
<p><strong>Workaround:</strong> Either use an enum (which has incorrect
type, but can be used in compile-time constant expressions), or define the
value out-of-line (which allows for the correct type, but prohibits using
the constant in compile-time constant expressions). See <a href=
"int_const_guidelines.htm">Coding Guidelines for Integral Constant
Expressions</a> for guidelines how to define member constants portably in
boost libraries.</p>
<h3>[koenig-lookup] Argument-dependent lookup</h3>
<p>Argument-dependent lookup, also called Koenig lookup, works for
overloaded operators, but not for ordinary functions. No additional
namespaces induced from the argument types seem to be considered.</p>
<pre>
namespace N {
struct A {};
void f(A);
}
void g()
{
N::A a;
f(a); // 'f': undeclared identifier
}
</pre>
<h3>[template-friend] Templates as friends</h3>
<p>A Template cannot be declared a friend of a class.</p>
<pre>
template&lt;class T&gt;
struct A {};
struct B
{
template&lt;class T&gt;
friend struct A; // "syntax error"
};
</pre>
<h3>[member-template-outofline] Out-of-line definitions of member
templates</h3>
<p>Defining member templates outside their enclosing class does not
work.</p>
<pre>
template&lt;class T&gt;
struct A
{
template&lt;class U&gt;
void f();
};
template&lt;class T&gt;
template&lt;class U&gt; // "syntax error"
void A&lt;T&gt;::f() // "T: undeclared identifier"
{
}
</pre>
<p><strong>Workaround:</strong> Define member templates in-line within
their enclosing class.</p>
<h3>[partial-spec] Partial specialization</h3>
<p>Partial specialization of class templates does not work.</p>
<pre>
template&lt;class T&gt;
struct A {};
template&lt;class T&gt;
struct B {};
template&lt;class T&gt;
struct A&lt;B&lt;T&gt; &gt; {}; // template class was already defined as a non-template
</pre>
<p><strong>Workaround:</strong> In some situations where interface does not
matter, class member templates can simulate partial specialization.</p>
<h3>[template-value] Dependent template value parameters</h3>
<p>Template value parameters whose type depends on a previous template
parameter provoke an internal compiler error if the correct syntax (with
"typename") is used.</p>
<pre>
template&lt;class T, typename T::result_type&gt; // C1001: INTERNAL COMPILER ERROR: msc1.cpp, line 1794
struct B {};
// (omit "typename" and it compiles)
</pre>
<p><strong>Workaround:</strong> Leave off the "typename" keyword. That
makes the program non-conforming, though.</p>
<h3>[wchar_t] <code>wchar_t</code> is not built-in</h3>
<p>The type <code>wchar_t</code> is not a built-in type.</p>
<pre>
wchar_t x; // "missing storage class or type identifier"
</pre>
<p><strong>Workaround:</strong> When using Microsoft Visual C++, the header
<a href="../boost/config.hpp">boost/config.hpp</a> includes
<code>&lt;cstddef&gt;</code>, which defines <code>wchar_t</code> as a
typedef for <code>unsigned short</code>. Note that this means that the
compiler does not regard <code>wchar_t</code> and <code>unsigned
short</code> as distinct types, as is required by the standard, and so
ambiguities may emanate when overloading on <code>wchar_t</code>. The macro
<code>BOOST_NO_INTRINSIC_WCHAR_T</code> is defined in this situation.</p>
<h3>[delete-const-pointer] Deleting <code>const X *</code> does not
work</h3>
<p>Trying to delete a pointer to a cv-qualified type gives an error:</p>
<pre>
void f()
{
const int *p = new int(5);
delete p; // C2664: cannot convert from "const int *" to "void *"
}
</pre>
<p><strong>Workaround:</strong> Define the function</p>
<pre>
inline void operator delete(const void *p) throw()
{ operator delete(const_cast&lt;void*&gt;(p)); }
</pre>
<p>and similar functions for the other cv-qualifier combinations, for
operator delete[], and for the <code>std::nothrow</code> variants.</p>
<h2>Standard Library</h2>
<h3>[clib-namespace] C library names in global namespace instead of
std</h3>
<p>Library names from the &lt;c...&gt; headers are in the global namespace
instead of namespace std.</p>
<p><b>Workaround:</b>&nbsp; The header <a href=
"../libs/config/config.htm">boost/config.hpp</a> will define
BOOST_NO_STDC_NAMESPACE. It can be used as follows:</p>
<pre>
# ifdef BOOST_NO_STDC_NAMESPACE
namespace std { using ::abs; using ::fabs; }
# endif
</pre>
<p>Because std::size_t and std::ptrdiff_t are so commonly used, the
workaround for these is already provided in boost/config.hpp.</p>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2001-2002 <a href="../people/jens_maurer.htm">Jens
Maurer</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

81
moderators.html
View File

@ -1,81 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Moderators</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Boost Moderators</h1>
<p>The Boost moderators are <a href="../people/dave_abrahams.htm">Dave Abrahams</a>,
Carl Daniel, <a href="../people/beman_dawes.html">Beman Dawes</a>,
<a href="../people/jeff_garland.html">Jeff Garland</a>,
<a href="../people/doug_gregor.html">Doug Gregor</a>, and
<a href="../people/john_maddock.htm">John Maddock</a>. You can reach
the moderators at <a
href="mailto:boost-owner@lists.boost.org">boost-owner@lists.boost.org</a>.
<p>
<b>Note:</b> The boost moderators do not moderate any mailing lists
other than the main Boost developers' list. For example, the
boost-users list moderators are at
<a
href="mailto:boost-users-owner@lists.boost.org">boost-users-owner@lists.boost.org</a>.
The moderators of <a href="mailing_lists.htm">every other Boost list</a> can be reached
through its home page.
</p>
<h2>Moderator Functions</h2>
<ul>
<li>Monitor the mailing list to ensure dialog remains within the acceptable
boundaries set by the <a href="discussion_policy.htm">discussion policy</a>.
When discussion strays, use private email to gently remind, strongly rebuke,
or outright ban, as the situation demands.</li>
</ul>
<ul>
<li>Approve the initial postings of new (and thus still moderated) members,
and move members to the &quot;Group Policy&quot; posting status.</li>
</ul>
<ul>
<li>Administer the internal operations of the Boost web site, the main Boost
mailing list, the CVS repository, and other Boost administrative machinery.</li>
</ul>
<ul>
<li>Act as an executive committee overseeing important administrative and
policy decisions.&nbsp; Boost is a zero-budget organization with no income
and no expenses, so that eliminates the need for most management. Technical
decisions are worked out on the mailing list. The moderators handle the few
remaining decisions that need a definite answer.</li>
</ul>
<ul>
<li>Beyond the purely administrative duties, work to keep the Boost community
vibrant and alive. That may be as simple as saying &quot;thank you&quot; to
an individual member, or as complex as starting some major new
initiative.&nbsp; Do whatever it takes!</li>
</ul>
<hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->27 February, 2005<!--webbot bot="Timestamp" endspan i-checksum="40414" -->
</p>
<p>© Beman Dawes 2001-2004</p>
<p>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

BIN
proposal.pdf
View File

Binary file not shown.

9
regression.html
View File

@ -1,9 +0,0 @@
<html>
<head>
<meta http-equiv="refresh" content="0; URL=../tools/regression/index.htm">
</head>
<body>
Automatically loading index page... if nothing happens, please go to
<a href="../tools/regression/index.htm">http://www.boost.org/tools/regression/index.htm</a>.
</body>
</html>

276
release_mgr_checklist.html
View File

@ -1,276 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Release Manager's Checklist</title>
</head>
<body bgcolor="#FFFFFF">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF">
<img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td>
<td><a href="../more/faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="../more/index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Release Manager's Checklist</h1>
<p><a href="#Introduction">Introduction</a><br>
<a href="#Pre-release">Pre-release activities</a><br>
<a href="#Branch-for-release">CVS Branch for release</a><br>
<a href="#CVS-release">CVS Release</a><br>
<a href="#Distribution">Distribution</a></p>
<h2><a name="Introduction">Introduction</a></h2>
<p>Historically, items on this checklist were accomplished by scripts written
in Perl, Python, Bash, C++, and as Windows command files, or by point-and-click
on a FrontPage or other GUI based program. Long term the plan is to move as much
as possible of these to C++, as
the one language all Boost developers are comfortable with. </p>
<h2><a name="Pre-release">Pre-release</a> activities</h2>
<ul>
<li>After discussion on the main list, post the release schedule.<br>
&nbsp;</li>
<li>Verify the <i><b>root/index.htm</b></i>, <i><b>root/boost/version.hpp</b></i>, <i><b>root/Jamfile.v2</b></i> and
<i><b>root/Jamrules</b></i>
release numbers are correct and agree. <br>
&nbsp;</li>
<li>Verify via <a href="mailto:jamboost@yahoogroups.com">jamboost@yahoogroups.com</a>
that bjam pre-built executables up-to-date.<br>
&nbsp;</li>
<li>Remove the oldest &quot;Latest News&quot; from root/index.htm.<br>
&nbsp;</li>
<li>For each new library added this release:</li>
</ul>
<blockquote>
<ul>
<li>Verify root/index.htm Latest News entry has been made and reads well.<br>
&nbsp;</li>
<li>Verify root/libs/libraries.htm entry has been made, both in the
alphabetic list and in the category lists.<br>
&nbsp;</li>
<li>Verify the root/libs/xxx directory contains an index.htm or index.html
file; either the main docs or a redirection to the main docs. <b><i>To do:
automate this.</i></b><br>
&nbsp;</li>
<li>Skim read the primary docs pages to make sure they meet Boost
requirements and guidelines. <b><i>Don't leave this until too late; it has
turned up lots of issues in the past.<br>
&nbsp;</i></b></li>
<li>Generate the header dependency table and update the CVS.<b><i> To do:
coordinate with John Maddock's new dependency tools.</i></b></li>
</ul>
</blockquote>
<ul>
<li>Monitor
<a href="http://boost.sourceforge.net/regression-logs/inspection_report.html">
http://boost.sourceforge.net/regression-logs/inspection_report.html</a> to
verify problems are actively being reduced. Make sure none of the problems are
in files the release manager is responsible for.<br>
&nbsp;</li>
<li>Monitor regression tests (<a href="http://boost.sourceforge.net/regression-logs/inspection_report.html">http://boost.sourceforge.net/regression-logs</a>)
to verify that errors are actively being reduced or accounted for on key
platforms and compilers.<br>
&nbsp;<ul>
<li>Boost errors are being actively worked on by library maintainers.</li>
<li>Compiler or standard library errors are at least identified, and
preferably reported to the supplier.</li>
<li>No errors remain uninvestigated or unclassified.<br>
&nbsp;</li>
</ul>
</li>
<li>Monitor the developer and user mailing lists to verify that all posted
patches are being applied, rejected, or otherwise dealt with.<br>
&nbsp;</li>
<li>Monitor the developer and user mailing lists, and the SourceForge bug
tracker, to verify that all posted bug reports are being investigated, fixed,
rejected, or otherwise dealt with.<br>
&nbsp;</li>
<li>Monitor CVS commits to verify that all the expected and/or promised
content actually gets committed. Try to get developers to avoid last minute
commits of major changes.</li>
</ul>
<h2><a name="Branch-for-release">CVS Branch for release</a></h2>
<ul>
<li>Pre-release activities complete enough to justify branch-for-release?<br>
&nbsp;</li>
<li>Everybody happy?<br>
&nbsp;</li>
<li>Branch for release:<ul>
<li>Tag the main trunk&nbsp; <code>merged_to_RC_n_n_n</code>.</li>
<li>Branch the main trunk with the tag <code>RC_n_n_n</code>.<br>
&nbsp;</li>
</ul>
</li>
<li>Post notice on main list.&nbsp;Remind developers that fixes which apply
to both Main Trunk and Branch have to be committed separately to both.</li>
</ul>
<h2><a name="CVS-release">CVS Release</a></h2>
<ul>
<li>Pre-release activities all complete?<br>
&nbsp;</li>
<li>Post notice to make sure all developers ready.<br>
&nbsp;</li>
<li>Tag: WinCVS: Select site, then tag (Modify|Create tag..., toolbar T on doc). New
tag name: Version_1_21_2 (or whatever). If prior release failed, select
&quot;overwrite existing tags with the same name&quot;.</li>
</ul>
<h2><a name="Distribution">Distribution</a></h2>
<p>These procedures are given for a particular release manager's machine. The
plan is to replace them with more generic procedures over time.</p>
<ul>
<li>Create folders for export:<br>
<br>
&nbsp;&nbsp;&nbsp; c:\boost\boost_1_28_0<br>
&nbsp;&nbsp;&nbsp; c:\boost\temp\boost_1_28_0<br>
<br>
Note that several batch files assume these locations and naming schemes.<br>
&nbsp;</li>
<li>Export Win32 distribution: WinCVS | Remote | Checkout Module<br>
<br>
Checkout settings: module name and path on the server: boost, local folder to
checkout to: c:\boost\boost_1_28_0<br>
<b><i>[for 1.29.0 export, put everything in a boost_1_29_0/boost subdirectory.&nbsp;
Experiments with 1.30.0 tried boost/boost as the path on server, but that just
resulted in getting the boost header subdirectory only.]</i></b><br>
<br>
Checkout options: (check) By revision/tab/branch: Version_1_28_0, (check) Do
not create CVS directories (export)<br>
<br>
This results in the follow command: cvs -z9 export -r Version_1_28_0 boost (in
directory C:\boost\boost_1_28_0)<br>
<br>
(takes about ten minutes)<br>
<br>
(rename boost-root if needed !!!!!!!!!!!!!!!!!!!)<br>
&nbsp;</li>
<li>Export Unix distribution: similar to above, except target is c:\boost\temp\boost_1_28_0
and set global for UNIX nl.<br>
&nbsp;</li>
<li>!!!!!! VERY IMPORTANT: WinCVS | Set Preferences | Global back to non-UNIX nl.
!!!!!!!!!!!!!!!<br>
&nbsp;</li>
<li>Add regression results web pages into package (new in 1.33 so this is just a shot at the process - jeff)<br>
download all the regression results from website (may need meta-comm help on this)<br>
unpack the regression results into tools/regression/latest_release<br>
<br>
</li>
<li>General ZIP and TAR.GZ files<br>
<br>
n_n_n is 1_28_0 or whatever<br>
<br>
cd \boost<br>
boost_zip 1_21_2 (creates zip.log) <br>
boost_tar_gz 1_21_2<br>
bash<br>
&nbsp;&nbsp;&nbsp;
gunzip -c boost_1_21_2.tar.gz | bzip2 &gt; boost_1_21_2.tar.bz2<br>
&nbsp;&nbsp;&nbsp; exit<br>
&nbsp;</li>
<li>Upload and unpack the .zip release candidate to a SourceForge web services
sub-directory. Post a message to the main list asking developers to check
contents. (Daniel Frey has volunteered to help check).<br>
&nbsp;</li>
<li>Upload files for SourceForge release incoming directory using <b>WS_FTP Pro</b><ul>
<li>Start keep_isdn_awake</li>
<li>Connection: SourceForge Release Upload | connect</li>
<li>Select Local system: c:\boost</li>
<li>Select Remote system: /incoming</li>
<li>Drag-and-drop the three release files from Local system to Remote system</li>
<li>Disconnect</li>
<li>Stop keep_isdn_awake<br>
&nbsp;</li>
</ul>
</li>
<li>Complete the SourceForge
<a href="http://sourceforge.net/docman/display_doc.php?docid=6445&amp;group_id=1#createrelease">
release procedure</a>.<ul>
<li>Admin | File Releases | Add Release for package name boost</li>
<li>New release name: 1.21.2 | create this release</li>
<li>Step 1: paste in release notes (in HTML). <b>Be sure to note difference
between .zip and .gz/bz2 files.</b> Submit/Refresh</li>
<li>Step 2: Check appropriate files. Add Files and/or Refresh View</li>
<li>Step 3: For each file, select Processor and File Type, Update/Refresh</li>
<li>Setp 4: Email Release Notice: I'm sure. Send Notice.</li>
<li>Wait up to 30 minutes.</li>
<li>Check SourceForge release page and release notes with web browser.<br>
&nbsp;</li>
</ul>
</li>
<li><i><b>Consider putting up a temporary &quot;Update in progress&quot; root/index.html
during site update<br>
&nbsp;</b></i></li>
<li>Update the web site:<pre>cd ...\boost_1_28_0
tar -cf site.tar *
bzip2 -k site.tar
dir site.tar.bz2
pscp site.tar.bz2 beman_dawes@shell1.sourceforge.net:/home/groups/b/bo/boost/htdocs/
keep_idsn_awake in another window.
c:\bgd\util\putty\plink.exe beman_dawes@shell.sourceforge.net
cd /home/groups/b/bo/boost/htdocs
pwd
ls -l site.tar.bz2
rm -fr boost
rm -fr doc
rm -fr libs
rm -fr more
rm -fr people
rm -fr status
rm -fr tools
bunzip2 -kc site.tar.bz2 | tar -x
ls
exit
stop keep_isdn_awake</pre>
</li>
<li>Check actual <a href="http://www.boost.org">www.boost.org</a> site with
browser. Look at a bunch of files that should have been updated to make sure
the updates actually &quot;took&quot;.<br>
&nbsp;</li>
<li>Post a message announcing the release and recapping &quot;Latest News&quot;.&nbsp;
Post as separate messages to: boost, boost-announce, boost-users,
comp.lang.c++.moderated,
<a href="mailto:c++std-news@research.att.com">c++std-news@research.att.com</a><br>
&nbsp;</li>
<li>Using the SourceForge shell services (sf_shell_svc.bat), cd /home/groups/b/bo/boost/htdocs,
and rename regression tests as necessary.<br>
&nbsp;</li>
<li>Burn &quot;Key Directories&quot; CD for off-site backup.<br>
&nbsp;</li>
<li>Make sure CVS working copy is updated to main branch!<br>
&nbsp;</li>
<li>Ready <i><b>root/index.htm</b></i>, <i><b>root/boost/version.hpp</b></i>, <b>root/Jamfile.v2</b> and
<i><b>root/Jamrules</b></i> for the
next release and commit to CVS so developers have a place to add &quot;Latest news&quot;
blurbs.<br>
&nbsp;</li>
<li>Delete obsolete files from yahoogroups files section.</li>
</ul>
<hr>
<p>Revised:
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->21 November, 2005<!--webbot bot="Timestamp" endspan i-checksum="40405" --></p>
<p>© Copyright Beman Dawes 2001</p>
<p>Distributed under the Boost Software License, Version 1.0. (See accompanying
file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at
<a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

213
release_procedures.htm
View File

@ -1,213 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Release Procedures</title>
</head>
<body bgcolor="#FFFFFF">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF">
<img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td>
<td><a href="../more/faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="../more/index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Boost Release Procedures</h1>
<p><a href="#Introduction">Introduction</a><br>
<a href="#Overview">Procedure Overview</a><br>
<a href="#Developers">Procedures for Developers</a><br>
<a href="#Manager">Procedures for the Release Manager</a><br>
<a href="#FAQ">FAQ</a><br>
<a href="#Acknowledgements">Acknowledgements</a></p>
<h2><a name="Introduction">Introduction</a></h2>
<p>Each release of Boost software is overseen by a release manager, who
coordinates release activities via the Boost mailing list, as well as performing
the detailed procedures for the release.</p>
<p>Boost developers assist the release manager by reviewing regression test
logs, and committing fixes to CVS.</p>
<h2>Release Procedure <a name="Overview">Overview</a></h2>
<ul>
<li>Discussion on the main Boost mailing list to determine the target date for
release candidate branch and tag of the CVS main trunk.<br>
&nbsp;</li>
<li>Release manager performs release candidate branch, and also tags the
branch point in main trunk.<br>
&nbsp;</li>
<li>Regression tests run on release candidate branch.<br>
&nbsp;</li>
<li>Developers fix problems, test, and commit fixes. See below for details.<br>
&nbsp;</li>
<li>Repeat previous two steps until release manager is satisfied.<br>
&nbsp;</li>
<li>Release manager rolls out the actual release.</li>
</ul>
<h2>Release Procedures for <a name="Developers">Developers</a></h2>
<ul>
<li>As the release candidate branch date approaches (as announced on the main
mailing list), bring the main trunk CVS files you are responsible for into a
stable state.<br>
&nbsp;</li>
<li>If you know of changes in either your code or its dependencies, start
checking regression test results to ensure your tests still pass.&nbsp; Don't
necessarily wait for the initial release tagging.<br>
&nbsp;</li>
<li>After the release manager announces that the release candidate branch has
occurred, check the latest regression test results to be sure
your tests haven't broken.<br>
&nbsp;</li>
<li>Developers can continue working on main trunk code changes after
the release candidate branch has occurred. There is no need to wait until the release
itself.&nbsp;
Modified files committed to CVS on the main trunk will not be included in the release unless the
developer explicitly commits the changes to the release candidate branch.<br>
&nbsp;</li>
<li>If specific to the release candidate only, the fixes should be committed
directly to the release candidate branch. In the more common case of fixes
which apply to both the main trunk and the release branch, the fixes are best
made to the main trunk, and then merged into the release candidate branch. See
FAQ for <a href="#merged_to_RC_n_n_n">tag rationale</a>.<br>
<br>
After a fix has been committed to the main trunk, here is a
typical procedure (assuming the release candidate branch is named RC_1_26_2)
to merge the fixed main trunk into the release candidate branch:</li>
</ul>
<blockquote>
<ul>
<li>Command Line CVS:</li>
</ul>
<blockquote>
<ul>
<li>Fixed code is committed to main branch <br>
&nbsp;</li>
<li>Switch to the release candidate branch
<blockquote>
<code>cvs update -r RC_1_26_2</code></blockquote>
</li>
<li>Merge changes in a trunk since previous merge to branch
<blockquote>
<pre>cvs update -j<a href="#merged_to_RC_n_n_n">merged_to_RC_1_26_2</a> -jHEAD buggycode.hpp
--&gt; RCS file: /cvsroot/boost/.../buggycode.hpp,v
--&gt; retrieving revision 1.4
--&gt; retrieving revision 1.6
--&gt; Merging differences between 1.4 and 1.6 into buggycode.hpp</pre>
</blockquote>
</li>
<li>Commit merged branch
<blockquote>
<pre>cvs commit -m &quot;Merged fix for problem xyz from trunk to branch&quot; buggycode.hpp</pre>
</blockquote>
</li>
<li>Go back to main trunk
<blockquote>
<pre>cvs update -A</pre>
</blockquote>
</li>
<li>Move tag to a new merged point
<blockquote>
<pre>cvs tag -F -c merged_to_RC_1_28_2 buggycode.hpp</pre>
</blockquote>
</li>
<li>Repeat as needed
</li>
</ul>
</blockquote>
<ul>
<li>WinCVS:</li>
</ul>
<blockquote>
<ul>
<li>After fixed code is committed to main branch, switch to the release
candidate branch:</li>
</ul>
<blockquote>
<blockquote>
<p>Select file(s) if not already selected.</p>
<p>Modify | Update selection... |
Update settings | Sticky options | Retrieve rev/tag/branch: <code>RC_1_26_2</code> | OK</p>
</blockquote>
</blockquote>
<ul>
<li>Merge changes from main trunk into the release candidate branch:</li>
</ul>
<blockquote>
<blockquote>
<p>Modify | Update selection... |
Update settings | Merge options | Only this rev/tag: <code>
<a href="#merged_to_RC_n_n_n">merged_to_RC_1_26_2</a></code>
| Plus with this rev/tag: <code>HEAD</code> | OK</p>
</blockquote>
</blockquote>
<ul>
<li>Commit merge results:</li>
</ul>
<blockquote>
<blockquote>
<p>Modify | Commit... | Enter log message: ... | OK</p>
</blockquote>
</blockquote>
<ul>
<li>Go back to main trunk:</li>
</ul>
<blockquote>
<blockquote>
<p>Modify | Update selection... | Update settings | Reset any sticky
date/tag/-k options | OK</p>
</blockquote>
</blockquote>
<ul>
<li>Tag as new merge point:</li>
</ul>
<blockquote>
<blockquote>
<p>Modify | Create tag on selection... | Create tag settings | Enter the tag
name to create: <code>merged_to_RC_1_26_2</code>, Overwrite existing tags
with same name | OK.</p>
</blockquote>
</blockquote>
</blockquote>
</blockquote>
<h2>Release Procedures for the Release <a name="Manager">Manager</a></h2>
<p>At time of branch-for-release:</p>
<ul>
<li>Tag the main trunk&nbsp; <code>merged_to_RC_n_n_n</code>.</li>
<li>Branch the main trunk with the tag <code>RC_n_n_n</code>.</li>
</ul>
<p>See <a href="release_mgr_checklist.html">Release Manager's Checklist</a> for
full details.</p>
<h2><a name="FAQ">FAQ</a></h2>
<p><b>What is the purpose of the <i><a name="merged_to_RC_n_n_n">
merged_to_RC_n_n_n</a></i> tag?</b> This tag allows multiple merges from the
main trunk to the release candidate branch. Without it, merging an initial main
trunk fix&nbsp; into the release candidate branch would work, but merging a
second fix from main trunk to release candidate branch would result in a merge
conflict. Although this procedure seems convoluted, it works much better in
practice than several prior procedures we tried.</p>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
<p>This web page was written by Beman Dawes, with helpful suggestions from Dave
Abrahams and Steve Robbins. Jim Hyslop contributed the original CVS procedures.
Updated by Jeff Garland after 1.29 release based on list discussions.</p>
<hr>
<p>Revised:
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->02 October, 2003<!--webbot bot="Timestamp" i-checksum="38549" endspan --></p>
<p>© Copyright Beman Dawes 2002</p>
<p>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

278
report-apr-2006.html
View File

@ -1,278 +0,0 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Review Wizard Status Report for April 2006</title>
<link rel="stylesheet" href="http://www.boost.org/rst.css" type="text/css" />
</head>
<body>
<div class="document" id="review-wizard-status-report-for-april-2006">
<h1 class="title">Review Wizard Status Report for April 2006</h1>
<div class="section" id="news">
<h1><a name="news">News</a></h1>
<p>April 1, 2006 -- The &quot;Promotion Traits&quot; Review Begins (Fast-Track)
Proposal to add promote, integral_promotion and
floating_point_promotion class templates to type_traits library.</p>
<p>April 6, 2006 -- The &quot;Function Types&quot; Review Begins (Fast-Track)
This library provides a metaprogramming facility
to classify, decompose and synthesize function-, function pointer-,
function reference- and member function pointer types.</p>
<p>March 22, 2006 -- Asio Accepted
Announcement: <a class="reference" href="http://lists.boost.org/Archives/boost/2006/03/102287.php">http://lists.boost.org/Archives/boost/2006/03/102287.php</a></p>
<p>February 17, 2006 - Shared Memory Library Accepted
Announcement: <a class="reference" href="http://lists.boost.org/boost-announce/2006/02/0083.php">http://lists.boost.org/boost-announce/2006/02/0083.php</a></p>
<p>February 5, 2006 - Fixed String Library Rejected
Announcement: <a class="reference" href="http://lists.boost.org/boost-announce/2006/02/0081.php">http://lists.boost.org/boost-announce/2006/02/0081.php</a></p>
<p>We need experienced review managers. Please take a look at
the list of libraries in need of managers and check out their
descriptions. If you can serve as review manager for any of
them, email Ron Garcia or Tom Brinkman &quot;garcia at cs dot indiana dot edu&quot;
and &quot;reportbase at gmail dot com&quot; respectively.</p>
<p>A link to this report will be posted to www.boost.org.
If you would like us to make any modifications or additions to this
report before we do that, please email Ron or Tom.</p>
<p>If you're library author and plan on submitting a library for review
in the next 3-6 months, send Ron or Tom a
short description of your library and we'll add it to the
Libraries Under Construction below. We know that there are many
libaries that are near completion, but we have hard time keeping
track all of them. Please keep us informed about your progress.</p>
</div>
<div class="section" id="review-queue">
<h1><a name="review-queue">Review Queue</a></h1>
<blockquote>
<ul class="simple">
<li>Promotion Traits - April 1, 2006 (fast-track)</li>
<li>Function Types - April 6, 2006 (fast-track)</li>
<li>Fusion</li>
<li>Pimpl Pointer</li>
<li>Property Tree</li>
<li>Physical Quantities System</li>
<li>Intrusive Containers</li>
</ul>
</blockquote>
<hr class="docutils" />
<div class="section" id="function-types-mini-re-review">
<h2><a name="function-types-mini-re-review">Function Types (mini-re-review)</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Tobias Schwinger</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body">Tom Brinkman</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><a class="reference" href="http://boost-sandbox.sourceforge.net/vault/">http://boost-sandbox.sourceforge.net/vault/</a></td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><p class="first">This library provides a metaprogramming facility to classify,
decompose and synthesize function-, function pointer-, function
reference- and member function pointer types. For the purpose of
this documentation, these types are collectively referred to as
function types (this differs from the standard definition and
redefines the term from a programmer's perspective to refer to
the most common types that involve functions).</p>
<p>The classes introduced by this library shall conform to the
concepts of the Boost Metaprogramming library (MPL).</p>
<dl class="docutils">
<dt>The Function Types library enables the user to:</dt>
<dd><ul class="first last simple">
<li>test an arbitrary type for being a function type of specified kind,</li>
<li>inspect properties of function types,</li>
<li>view and modify sub types of an encapsulated function type with
MPL Sequence operations, and</li>
<li>synthesize function types.</li>
</ul>
</dd>
</dl>
<p class="last">This library supports variadic functions and can be configured
to support non-default calling conventions.</p>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="promotion-traits">
<h2><a name="promotion-traits">Promotion Traits</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Alexander Nasonov</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body">Tobias Schwinger</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><a class="reference" href="http://cpp-experiment.sourceforge.net/promote-20050917.tar.gz">http://cpp-experiment.sourceforge.net/promote-20050917.tar.gz</a></td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><p class="first">Proposal to add promote, integral_promotion and
floating_point_promotion class templates to type_traits library.</p>
<p>Alexander tried it on different compilers with various success:
GNU/Linux (gentoo-hardened): gcc 3.3 and 3.4, Intel 7, 8 and 9
Windows: VC7 free compiler
Sparc Solaris: Sun C++ 5.3 and 5.7</p>
<p class="last">See comments at the beginning of
promote_enum_test.cpp for what is broken.</p>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="intrusive-containers">
<h2><a name="intrusive-containers">Intrusive Containers</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Olaf Krzikalla</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body">Thorsten Ottosen</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><a class="reference" href="http://people.freenet.de/turtle++/intrusive.zip">http://people.freenet.de/turtle++/intrusive.zip</a></td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body">While intrusive containers were and are widely used in C, they became
more and more forgotten in the C++-world due to the presence of the
standard containers, which don't support intrusive
techniques. Boost.Intrusive not only reintroduces this technique to
C++, but also encapsulates the implementation in STL-like
interfaces. Hence anyone familiar with standard containers can use
intrusive containers with ease.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="fusion">
<h2><a name="fusion">Fusion</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Joel de Guzman</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body">Ron Garcia</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><a class="reference" href="http://spirit.sourceforge.net/dl_more/fusion_v2/">http://spirit.sourceforge.net/dl_more/fusion_v2/</a>
<a class="reference" href="http://spirit.sourceforge.net/dl_more/fusion_v2.zip">http://spirit.sourceforge.net/dl_more/fusion_v2.zip</a></td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><p class="first">Fusion is a library of heterogenous containers and views and
algorithms. A set of heterogenous containers (vector, list, set and
map) is provided out of the box along with view classes that present
various composable views over the data. The containers and views
follow a common sequence concept with an underlying iterator concept
that binds it all together, suitably making the algorithms fully
generic over all sequence types.</p>
<p class="last">The architecture is somewhat modeled after MPL which in turn is
modeled after STL. It is code-named &quot;fusion&quot; because the library is
the &quot;fusion&quot; of compile time metaprogramming with runtime programming.</p>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="pimpl-pointer">
<h2><a name="pimpl-pointer">Pimpl Pointer</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Asger Mangaard</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body">Need Volunteer</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body">Boost Sandbox (<a class="reference" href="http://boost-consulting.com/vault/">http://boost-consulting.com/vault/</a>) under pimpl_ptr.</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body">The pimpl idiom is widely used to reduce compile times and disable
code coupling. It does so by moving private parts of a class from the
.hpp file to the .cpp file.
However, it's implementation can be tricky, and with many pitfalls
(especially regarding memory management).
The pimpl_ptr library is a single header file, implementing a special
policy based smart pointer to greately ease the implementation of the
pimpl idiom.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="property-tree">
<h2><a name="property-tree">Property Tree</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Marcin Kalicinski</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body">Need Volunteer</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body">Boost Sandbox Vault - property_tree_rev4.zip
<a class="reference" href="http://kaalus.atspace.com/ptree">http://kaalus.atspace.com/ptree</a></td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body">Property tree is a data structure - a tree of (key, value)
pairs. It differs from its cousin, &quot;usual&quot; property map, because
it is hierarchical, not linear. Thus, it is more like a
minimalistic Document Object Model, but not bound to any
specific file format. It can store contents of XML files,
windows registry, JSON files, INI files, even command line
parameters. The library contains parsers for all these formats,
and more.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="physical-quantities-system">
<h2><a name="physical-quantities-system">Physical Quantities System</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Andy Little</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body">Need Volunteer</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><a class="reference" href="http://tinyurl.com/7m5l8">http://tinyurl.com/7m5l8</a></td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body">PQS (Physical Quantities System) is used for modelling
physical-quantities in C++ programs. The advantages over using
built-in types in the role include: trapping errors in
dimensional analysis, detailed semantic specifications for
reliable and repeatable conversions between units and
self-documentation of source code. PQS is based around the
principles and guidelines of the International System of Units
(SI). The library predefines a large number of quantities,
physical and maths constants using a common syntax. The library
also includes (or will soon include) classes for manipulating
quantities algebraically, for example angles (radians,
steradians, degrees,minutes,seconds) and vectors, matrices and
quaternions for more advanced modelling of physical systems.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
</div>
<div class="section" id="libraries-under-development">
<h1><a name="libraries-under-development">Libraries under development</a></h1>
<p>Geometry Library - Author - Andy Little (?)</p>
<p>C2_functions Library - Author - Marcus Mendenhall</p>
<p>Please let us know of any libraries you are currently
developing that you intend to submit for review.</p>
</div>
</div>
<hr class="docutils footer" />
<div class="footer">
Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>

325
report-jan-2006.html
View File

@ -1,325 +0,0 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Review Wizard Status Report for January 2006</title>
<link rel="stylesheet" href="http://www.boost.org/rst.css" type="text/css" />
</head>
<body>
<div class="document" id="review-wizard-status-report-for-january-2006">
<h1 class="title">Review Wizard Status Report for January 2006</h1>
<div class="section">
<h1><a id="news" name="news">News</a></h1>
<p>Happy New Year! Here are some statistics regarding Boost Library
reviews in 2005:</p>
<blockquote>
<ul class="simple">
<li>12 Libraries were reviewed</li>
<li>8 Libraries were accepted</li>
<li>1 Library (Function Types) was accepted pending a mini-review</li>
<li>2 Libraries were rejected</li>
<li>1 Library has yet to receive a final verdict (ASIO)</li>
</ul>
</blockquote>
<p>Policy Pointer has been removed from the review queue because the author has
stated that it is not quite ready.</p>
<p>We need review managers. Please take a look at the list of libraries
in need of managers and check out their descriptions. If you can
serve as review manager for any of them, send one of us an email.</p>
<dl class="docutils">
<dt>Note:</dt>
<dd>If you have any suggestions about how we could improve
the Review Wizard's status report,
please email &quot;reportbase at gmail dot com&quot;
and &quot;garcia at cs dot indiana dot edu&quot;.</dd>
</dl>
</div>
<div class="section">
<h1><a id="review-managers-needed" name="review-managers-needed">Review Managers Needed</a></h1>
<p>There are a few libraries in the review queue in need
of review managers. If you would like to volunteer to be a review
manager, please contact Ron or Tom.</p>
<p>The following libraries still require review managers:</p>
<blockquote>
<ul class="simple">
<li>Fusion</li>
<li>Shmem</li>
<li>Pimpl Pointer</li>
<li>Type Traits (modification)</li>
<li>Function Types</li>
</ul>
</blockquote>
</div>
<div class="section">
<h1><a id="review-queue" name="review-queue">Review Queue</a></h1>
<blockquote>
<ul class="simple">
<li>Fixed Strings - January 19 2006 - January 28 2006</li>
<li>Intrusive Containers</li>
<li>Function Types (mini-re-review)</li>
<li>Shmem</li>
<li>Fusion</li>
<li>Pimpl Pointer</li>
<li>Type Traits (modification)</li>
</ul>
</blockquote>
<hr class="docutils" />
<div class="section">
<h2><a id="fixed-strings" name="fixed-strings">Fixed Strings</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Reece Dunn</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body">Harmut Kaiser</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body">Boost Sandbox (<a class="reference" href="http://boost-sandbox.sourceforge.net/">http://boost-sandbox.sourceforge.net/</a>) under fixed_string</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body">The fixed string library provides buffer overrun protection for static
sized strings (char s[ n ]). It provides a C-style string
interface for compatibility with C code (for
example, porting a C program to C++).
There is also a std::string-style interface using a class based on
flex_string by Andre Alexandrescu with a few limitations due to the
non-resizable nature of the class.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h2><a id="intrusive-containers" name="intrusive-containers">Intrusive Containers</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Olaf Krzikalla</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body">to be determined</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><a class="reference" href="http://people.freenet.de/turtle++/intrusive.zip">http://people.freenet.de/turtle++/intrusive.zip</a></td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body">While intrusive containers were and are widely used in C, they became
more and more forgotten in the C++-world due to the presence of the
standard containers, which don't support intrusive
techniques. Boost.Intrusive not only reintroduces this technique to
C++, but also encapsulates the implementation in STL-like
interfaces. Hence anyone familiar with standard containers can use
intrusive containers with ease.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h2><a id="function-types-mini-re-review" name="function-types-mini-re-review">Function Types (mini-re-review)</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body"><p class="first">Tobias Schwinger</p>
</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body"><p class="first">to be determined</p>
</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><p class="first"><a class="reference" href="http://boost-sandbox.sourceforge.net/vault/">http://boost-sandbox.sourceforge.net/vault/</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><dl class="first last docutils">
<dt>This library provides a metaprogramming facility</dt>
<dd><p class="first last">to classify, decompose and synthesize function-,
function pointer-, function reference- and
member function pointer types. For the purpose
of this documentation, these types are
collectively referred to as function
types (this differs from the standard
definition and redefines the term from
a programmer's perspective to refer to
the most common types that involve functions).</p>
</dd>
<dt>The classes introduced by this library</dt>
<dd><p class="first last">shall conform to the concepts of the
Boost Metaprogramming library (MPL).</p>
</dd>
<dt>The Function Types library enables the user to:</dt>
<dd><ul class="first last simple">
<li>test an arbitrary type for
being a function type of specified kind,</li>
<li>inspect properties of function types,</li>
<li>view and modify sub types of an
encapsulated function type with
MPL Sequence operations, and</li>
<li>synthesize function types.</li>
</ul>
</dd>
<dt>This library supports variadic functions and</dt>
<dd><p class="first last">can be configured to support
non-default calling conventions.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h2><a id="shmem" name="shmem">Shmem</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body"><p class="first">Ion Gaztanaga</p>
</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body"><p class="first">to be determined</p>
</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><p class="first">Boost Sandbox Vault -&gt; Memory (<a class="reference" href="http://boost-sandbox.sourceforge.net/vault/index.php?direction=0&amp;order=&amp;directory=Memory">http://boost-sandbox.sourceforge.net/vault/index.php?direction=0&amp;order=&amp;directory=Memory</a>)</p>
<p><a class="reference" href="http://ice.prohosting.com/newfunk/boost/libs/shmem/doc/html/index.html">http://ice.prohosting.com/newfunk/boost/libs/shmem/doc/html/index.html</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><p class="first">Shmem offers tools to simplify shared memory usage in
applications. These include shared memory creation/destruction and
synchronization objects. It also implements dynamic allocation of
portions of a shared memory segment and an easy way to construct C++
objects in shared memory.</p>
<p class="last">Apart from this, Shmem implements a wide range of STL-like containers
and allocators that can be safely placed in shared memory, helpful to
implement complex shared memory data-bases and other efficient
inter-process communications.</p>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h2><a id="fusion" name="fusion">Fusion</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body"><p class="first">Joel de Guzman</p>
</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body"><p class="first">to be determined</p>
</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><p class="first"><a class="reference" href="http://spirit.sourceforge.net/dl_more/fusion_v2/">http://spirit.sourceforge.net/dl_more/fusion_v2/</a>
<a class="reference" href="http://spirit.sourceforge.net/dl_more/fusion_v2.zip">http://spirit.sourceforge.net/dl_more/fusion_v2.zip</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><p class="first">Fusion is a library of heterogenous containers and views and
algorithms. A set of heterogenous containers (vector, list, set and
map) is provided out of the box along with view classes that present
various composable views over the data. The containers and views
follow a common sequence concept with an underlying iterator concept
that binds it all together, suitably making the algorithms fully
generic over all sequence types.</p>
<p class="last">The architecture is somewhat modeled after MPL which in turn is
modeled after STL. It is code-named &quot;fusion&quot; because the library is
the &quot;fusion&quot; of compile time metaprogramming with runtime programming.</p>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h2><a id="pimpl-pointer" name="pimpl-pointer">Pimpl Pointer</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Asger Mangaard</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body">to be determined</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body">Boost Sandbox (<a class="reference" href="http://boost-consulting.com/vault/">http://boost-consulting.com/vault/</a>) under pimpl_ptr.</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body">The pimpl idiom is widely used to reduce compile times and disable
code coupling. It does so by moving private parts of a class from the
.hpp file to the .cpp file.
However, it's implementation can be tricky, and with many pitfalls
(especially regarding memory management).
The pimpl_ptr library is a single header file, implementing a special
policy based smart pointer to greately ease the implementation of the
pimpl idiom.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h2><a id="type-traits-modification" name="type-traits-modification">Type_Traits (modification)</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body"><p class="first">Alexander Nasonov</p>
</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body"><p class="first">to be determined</p>
</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><p class="first"><a class="reference" href="http://cpp-experiment.sourceforge.net/promote-20050917.tar.gz">http://cpp-experiment.sourceforge.net/promote-20050917.tar.gz</a>
or <a class="reference" href="http://cpp-experiment.sourceforge.net/promote-20050917/">http://cpp-experiment.sourceforge.net/promote-20050917/</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><p class="first">Proposal to add promote, integral_promotion and
floating_point_promotion class templates to type_traits library.</p>
<p>Alexander tried it on different compilers with various success:
GNU/Linux (gentoo-hardened): gcc 3.3 and 3.4, Intel 7, 8 and 9
Windows: VC7 free compiler
Sparc Solaris: Sun C++ 5.3 and 5.7</p>
<p>See comments at the beginning of promote_enum_test.cpp for what is broken.
<a class="reference" href="http://cpp-experiment.sourceforge.net/promote-20050917/libs/type_traits/test/promote_enum_test.cpp">http://cpp-experiment.sourceforge.net/promote-20050917/libs/type_traits/test/promote_enum_test.cpp</a></p>
<p class="last">Alexander requests a fast-track review.</p>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
</div>
<div class="section">
<h1><a id="libraries-under-development" name="libraries-under-development">Libraries under development</a></h1>
<div class="section">
<h2><a id="property-tree" name="property-tree">Property Tree</a></h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Marcin Kalicinski</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body">Boost Sandbox Vault (<a class="reference" href="http://boost-consulting.com/vault/">http://boost-consulting.com/vault/</a>)
property_tree_rev3.zip</td>
</tr>
</tbody>
</table>
</blockquote>
<p>Please let us know of any libraries you are currently
developing that you intend to submit for review.</p>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
Generated on: 2006-01-20 17:42 UTC.
</div>
</body>
</html>

329
report-sep-2007.html
View File

@ -1,329 +0,0 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Review Wizard Status Report for September 2007</title>
<link rel="stylesheet" href="http://boost.org/rst.css" type="text/css" />
</head>
<body>
<div class="document" id="review-wizard-status-report-for-september-2007">
<h1 class="title">Review Wizard Status Report for September 2007</h1>
<div class="section" id="news">
<h1>News</h1>
<dl class="docutils">
<dt>August 17, 2007 -- Time Series Accepted.</dt>
<dd>Announcement: <a class="reference external" href="http://lists.boost.org/boost-announce/2007/08/0142.php">http://lists.boost.org/boost-announce/2007/08/0142.php</a></dd>
<dt>July 24, 2007 -- Boost Version 1.34.1 Released.</dt>
<dd>This is a bug fix release addressing many problems with the 1.34.0 release.
Announcement: <a class="reference external" href="http://svn.boost.org/trac/boost/query?status=closed&amp;milestone=Boost+1.34.1">http://svn.boost.org/trac/boost/query?status=closed&amp;milestone=Boost+1.34.1</a></dd>
</dl>
<p>We need experienced review managers. Please take a look at the list
of libraries in need of managers and check out their descriptions. In
general review managers are active boost participants or library
contributors. If you can serve as review manager for any of them,
email Ron Garcia or John Phillips, &quot;garcia at cs dot indiana dot edu&quot;
and &quot;jphillip at capital dot edu&quot; respectively.</p>
<p>A link to this report will be posted to www.boost.org.
If you would like us to make any modifications or additions to this
report before we do that, please email Ron or John.</p>
<p>If you're library author and plan on submitting a library for review
in the next 3-6 months, send Ron or John a short description of your
library and we'll add it to the Libraries Under Construction below.
We know that there are many libraries that are near completion, but we
have hard time keeping track all of them. Please keep us informed
about your progress.</p>
</div>
<div class="section" id="review-queue">
<h1>Review Queue</h1>
<blockquote>
<ul class="simple">
<li>Exception</li>
<li>Finite State Machines</li>
<li>Floating Point Utilities</li>
<li>Switch</li>
<li>Property Map (fast-track)</li>
<li>Graph (fast-track)</li>
</ul>
</blockquote>
<hr class="docutils" />
<div class="section" id="exception">
<h2>Exception</h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body"><p class="first">Emil Dotchevski</p>
</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body"><p class="first">Need Volunteer</p>
</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><p class="first"><a class="reference external" href="http://www.revergestudios.com/boost-exception/boost-exception.zip">http://www.revergestudios.com/boost-exception/boost-exception.zip</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><p class="first">The purpose of this library is to free designers of
exception classes from having to consider what data needs to be
stored in exception objects in order for the catch site to be
able to make sense of what went wrong.</p>
<p class="last">When the exception class is used, arbitrary values can be stored
in any exception. This can be done directly in the
throw-expression, or at a later time as the exception object
propagates up the call stack. The ability to add data to any
exception object after it has been thrown is important, because
often some of the information needed to handle an exception is
unavailable at the time of the throw.</p>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="finite-state-machines">
<h2>Finite State Machines</h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body"><p class="first">Andrey Semashev</p>
</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body"><p class="first">Martin Vuille</p>
</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><p class="first"><a class="reference external" href="http://tinyurl.com/yjozfn">Boost Sandbox Vault</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><p class="first">The Boost.FSM library is an implementation of FSM (stands for
Finite State Machine) programming concept. The main goals of the
library are:</p>
<ul class="last simple">
<li>Simplicity. It should be very simple to create state machines using
this library.</li>
<li>Performance. The state machine infrastructure should not be
very time and memory-consuming in order to be applicable in
more use cases.</li>
<li>Extensibility. A developer may want to add more states to an
existing state machine. A developer should also be able to
specify additional transitions and events for the machine with
minimum modifications to the existing code.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="floating-point-utilities">
<h2>Floating Point Utilities</h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body"><p class="first">Johan RÂde</p>
</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body"><p class="first">Need Volunteer</p>
</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><p class="first"><a class="reference external" href="http://boost-consulting.com/vault/index.php?directory=Math%20-%20Numerics">Boost Sandbox Vault</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><p class="first">The Floating Point Utilities library contains the following:</p>
<ul class="last simple">
<li>Floating point number classification functions: fpclassify, isfinite,
isinf, isnan, isnormal (Follows TR1)</li>
<li>Sign bit functions: signbit, copysign, changesign (Follows TR1)</li>
<li>Facets that format and parse infinity and NaN according to the C99
standard. (These can be used for portable handling of infinity and NaN
in text streams.)</li>
</ul>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="switch">
<h2>Switch</h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Steven Watanabe</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body">Need Volunteer</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><a class="reference external" href="http://boost-consulting.com/vault/index.php?action=downloadfile&amp;filename=mcs_units_v0.7.1.zip&amp;directory=Units">Boost Sandbox Vault</a></td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body">The built in C/C++ switch statement is very efficient. Unfortunately,
unlike a chained if/else construct there is no easy way to use it when
the number of cases depends on a template parameter. The Switch library
addresses this issue.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="property-map-fast-track">
<h2>Property Map (fast-track)</h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body"><p class="first">Andrew Sutton</p>
</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body"><p class="first">Jeremy Siek</p>
</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><p class="first"><a class="reference external" href="http://svn.boost.org/svn/boost/sandbox/graph-v2">http://svn.boost.org/svn/boost/sandbox/graph-v2</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><p class="first">A number of additions and modifications to the Property Map Library,
including:</p>
<blockquote class="last">
<ul class="simple">
<li>A constant-valued property map, useful for naturally unweighted
graphs.</li>
<li>A noop-writing property map, useful when you have to provide an
argument, but just don't care about the output.</li>
<li>See
<a class="reference external" href="http://svn.boost.org/trac/boost/browser/sandbox/graph-v2/libs/property_map/ChangeLog">ChangeLog</a>
for details.</li>
</ul>
</blockquote>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="graph-fast-track">
<h2>Graph (fast-track)</h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body"><p class="first">Andrew Sutton</p>
</td>
</tr>
<tr class="field"><th class="field-name">Review Manager:</th><td class="field-body"><p class="first">Jeremy Siek</p>
</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><p class="first"><a class="reference external" href="http://svn.boost.org/svn/boost/sandbox/graph-v2">http://svn.boost.org/svn/boost/sandbox/graph-v2</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><p class="first">A number of additions and modifications to the Graph Library,
including:</p>
<ul class="last simple">
<li>Two new graph classes (undirected and directed) which are intended
to make the library more approachable for new developers</li>
<li>A suite of graph measures including degree and closeness
centrality, mean geodesic distance, eccentricity, and clustering
coefficients.</li>
<li>An algorithm for visiting all cycles in a directed graph (Tiernan's
from 1970ish). It works for undirected graphs too, but reports cycles
twice (one for each direction).</li>
<li>An algorithm for visiting all the cliques a graph (Bron&amp;Kerbosch).
Works for both directed and undirected.</li>
<li>Derived graph measures radius and diameter (from eccentricity) and
girth and circumference (from Tiernan), and clique number (from
Bron&amp;Kerbosch).</li>
<li>An exterior_property class that helps hides some of the weirdness
with exterior properties.</li>
<li>runtime and compile-time tests for the new algorithms.</li>
<li>a substantial amount of documentation</li>
<li>Graph cores, implemented by David Gleich (&#64;Stanford University)</li>
<li>Deterministic graph generators - capable of creating or inducing
specific types of graphs over a vertex set (e.g., star graph, wheel
graph, prism graph, etc). There are several other specific types that
could be added to this, but I haven't had the time just yet.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
</div>
<div class="section" id="libraries-under-development">
<h1>Libraries under development</h1>
<div class="section" id="dataflow">
<h2>Dataflow</h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Stjepan Rajko</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body">The Dataflow library provides generic support for data
producers, consumers, and connections between the two. It also
provides layers for several specific dataflow mechanisms, namely
Boost.Signals, VTK data/display pipelines, and plain
pointers. The Dataflow library came out of the Signal Network
GSoC project, mentored by Doug Gregor.</td>
</tr>
<tr class="field"><th class="field-name">Status:</th><td class="field-body">I am polishing the Dataflow library for submission, and am expecting
to add it to the review queue in the next couple of months.
I am currently ironing out some faults in the design of the library,
filling in missing features, and testing it on / adapting it to
different dataflow mechanisms (currently VTK and soon
Boost.Iostreams). As soon as I'm pretty sure that things are going
the right way, I'll submit this to the review queue while I do the
finishing touches.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="constrained-value">
<h2>Constrained Value</h2>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body"><p class="first">Robert Kawulak</p>
</td>
</tr>
<tr class="field"><th class="field-name">Download:</th><td class="field-body"><p class="first"><a class="reference external" href="http://rk.go.pl/f/constrained_value.zip">http://rk.go.pl/f/constrained_value.zip</a></p>
<p><a class="reference external" href="http://rk.go.pl/r/constrained_value">http://rk.go.pl/r/constrained_value</a> (Documentation)</p>
</td>
</tr>
<tr class="field"><th class="field-name">Description:</th><td class="field-body"><p class="first">The Constrained Value library contains class templates
useful for creating constrained objects. The simplest example
of a constrained object is hour. The only valid values for an hour
within a day are integers from the range [0, 23]. With this library,
you can create a variable which behaves exactly like int, but does
not allow for assignment of values which do not belong to the
allowed range. The library doesn't focus only on constrained
objects that hold a value belonging to a specified range (i.e.,
bounded objects). Virtually any constraint can be imposed using
appropriate predicate. You can specify what happens in case of
assignment of an invalid value, e.g. an exception may be thrown or
the value may be adjusted to meet the constraint criterions.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Status:</th><td class="field-body"><p class="first last">I'm planning to finish it in 1-2 months.</p>
</td>
</tr>
</tbody>
</table>
</blockquote>
<p>Please let us know of any libraries you are currently
developing that you intend to submit for review.</p>
</div>
</div>
</div>
</body>
</html>

56
requesting_new_features.htm
View File

@ -1,56 +0,0 @@
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Requesting New Features</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF">
<img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>
Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>
People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Requesting new features for Boost libraries</h1>
<p>If you have an idea for a feature or improvement to an existing Boost library
- go ahead and post it to either
<a href="http://www.boost.org/more/mailing_lists.htm#users">boost-users list</a>
or <a href="http://www.boost.org/more/mailing_lists.htm#main">boost mailing list</a>
(if you are posting for the first time, please read our
<a href="http://www.boost.org/more/discussion_policy.htm">discussion policy</a>
before you actually post). </p>
<p>You can also use our <a href="http://sourceforge.net/tracker/?group_id=7586">
feature request tracking facility</a> at SourceForge, but experience has shown
that posting to either of the mailing lists is usually a more effective way to
get attention of boost developers. </p>
<p>If your proposal has its merits, it's very likely that it will generate a
constructive discussion that might actually result in (sometimes substantial)
improvement of the library - and your name being put on the library's
<a href="http://www.boost.org/more/lib_guide.htm#Acknowledgements">
Acknowledgements</a> section! </p>
<hr>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->26 November, 2003<!--webbot bot="Timestamp" i-checksum="39365" endspan -->
</p>
<p>© Copyright <a href="../people/aleksey_gurtovoy.htm">Aleksey Gurtovoy</a>
2002</p>
<p> Distributed under the Boost Software License, Version 1.0.
(See accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

385
separate_compilation.html
View File

@ -1,385 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Guidelines for Authors of Boost Libraries Containing Separate Source</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<LINK href="../boost.css" type="text/css" rel="stylesheet"></head>
<body>
<TABLE summary="Page header" id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0">
<TR>
<td vAlign="top" width="300">
<h3><A href="../index.htm"><IMG height="86" alt="C++ Boost" src="../boost.png" width="277" border="0"></A></h3>
</td>
<TD width="353">
<H1 align="center">Guidelines for Authors of Boost Libraries Containing Separate
Source</H1>
</TD>
</TR>
</TABLE>
<BR>
<HR>
<P>These guidelines are designed for the authors of Boost libraries which have
separate source that need compiling in order to use the library. Throughout,
this guide refers to a fictitious "whatever" library, so replace all
occurrences of "whatever" or "WHATEVER" with your own library's name when
copying the examples.</P>
<H2>Contents</H2>
<dl class="index">
<dt><A href="#source_changes">Changes Affecting Source Code</A>
<dd>
<dl class="index">
<dt><A href="#abi">Preventing Compiler ABI Clashes</A> <DT><A href="#static_or_dynamic">Static
or Dymanic Libraries</A>&nbsp; <dt><A href="#dlls">Supporting Windows Dll's</A> <dt>
<a href="#auto-link">Automatic Library Selection and Linking with auto_link.hpp</a>
</dt>
</dl>
<dt><A href="#build_changes">Changes Affecting the Build System</A>
<dd>
<dl class="index">
<dt><A href="#jamfile">Creating the Library Jamfile</A> <dt><A href="#testing">Testing
Auto-linking</A> </dt>
</dl>
<dt><A href="#copyright">Copyright</A></dt>
</dl>
<h2><A name="source_changes"></A>Changes Affecting Source Code</h2>
<H3><A name="abi"></A>Preventing Compiler ABI Clashes</H3>
<P>There are some compilers (mostly Microsoft Windows compilers again!), which
feature a range of compiler switches that alter the ABI of C++ classes and
functions. By way of example, consider Borland's compiler which has the
following options:</P>
<PRE>-b (on or off - effects enum sizes).
-Vx (on or off - empty members).
-Ve (on or off - empty base classes).
-aX (alignment - 5 options).
-pX (Calling convention - 4 options).
-VmX (member pointer size and layout - 5 options).
-VC (on or off, changes name mangling).
-Vl (on or off, changes struct layout).
</PRE>
<P>These options are provided in addition to those affecting which runtime library
is used (more on which later); the total number of combinations of options can
be obtained by multiplying together the individual options above, so that gives
2*2*2*5*4*5*2*2 = 3200 combinations!
</P>
<P>The problem is that users often expect to be able to build the Boost libraries
and then just link to them and have everything just plain work, no matter what
their project settings are. Irrespective of whether this is a reasonable
expectation or not, without some means of managing this issue, the user may
well find that their program will experience strange and hard to track down
crashes at runtime unless the library they link to was built with the same
options as their project (changes to the default alignment setting are a prime
culprit). One way to manage this is with "prefix and suffix" headers: these
headers invoke compiler specific #pragma directives to instruct the compiler
that whatever code follows was built (or is to be built) with a specific set of
compiler ABI settings.</P>
<P>Boost.config provides the macro BOOST_HAS_ABI_HEADERS which is set whenever
there are prefix and suffix headers available for the compiler in use, typical
usage in a header like this:</P>
<PRE>#ifndef BOOST_WHATEVER_HPP
#define BOOST_WHATEVER_HPP
#include &lt;boost/config.hpp&gt;
// this must occur after all of the includes and before any code appears:
#ifdef BOOST_HAS_ABI_HEADERS
# include BOOST_ABI_PREFIX
#endif
//
// this header declares one class, and one function by way of examples:
//
class whatever
{
// details.
};
whatever get_whatever();
// the suffix header occurs after all of our code:
#ifdef BOOST_HAS_ABI_HEADERS
# include BOOST_ABI_SUFFIX
#endif
#endif
</PRE>
<P>You can include this code in your library source files as well if you want,
although you probably shouldn't need to:&nbsp;&nbsp;</P>
<UL>
<LI>
If you <EM>don't</EM>
use these in the library source files (but do in your library's headers) and
the user attempts to compile the library source with a non-default ABI setting,
then they will get compiler errors if there are any conflicts.
<LI>
If you <EM>do </EM>include them in both the library's headers and the library
source files, then the code should always compile no matter what the compiler
settings used, although the result might not match what the user was expecting:
since we've forced the ABI back into default mode.</LI></UL>
<H4>Rationale:</H4>
<P>Without some means of managing this issue, users often report bugs along the
line of "Your silly library always crashes when I try and call it" and so on.
These issues can be extremely difficult and time consuming to track down, only
to discover in the end that it's a compiler setting that's changed the ABI of
the class and/or function types of the program compared to those in the
pre-compiled library. The use of prefix/suffix headers can minimize this
problem, although probably not remove it completely.</P>
<H5>Counter Argument #1:</H5>
<P>Trust the user, if they want 13-byte alignment (!) let them have it.</P>
<H5>Counter Argument #2:</H5>
<P>Prefix/suffix headers have a tendency to "spread" to other boost libraries -
for example if boost::shared_ptr&lt;&gt; forms part of your class's ABI, then
including prefix/suffix headers in your code will be of no use unless
shared_ptr.hpp also uses them. Authors of header-only boost libraries may not
be so keen on this solution - with some justification - since they don't face
the same problem.</P>
<H3><A name="static_or_dynamic"></A>Static or Dynamic Libraries</H3>
<P>When the users runtime is dynamically linked the Boost libraries can be built
either as dynamic libraries (.so's on Unix platforms, .dll's on Windows) or as
static libraries (.a's on Unix, .lib's on Windows).&nbsp; So we have a choice
as to which is supported by default:</P>
<UL>
<LI>
On Unix platforms it typically makes no difference to the code: the user just
selects in their makesfile which library they prefer to link to.
<LI>
On Windows platforms, the code has to be specially annotated to support DLL's,
so we need to pick one option as the default and one as an alternative.
<LI>
On Windows platforms, we can inject special code to automatically select which
library variant to link against: so again we need to decide which is to be the
default (see the section on auto-linking below).</LI></UL>
<P>The recomendation is to pick static linking by default.</P>
<H4>Rationale:</H4>
<P>There is no one policy that fits all here.
</P>
<P>The rationale for the current behaviour was inherited from Boost.Regex (and
it's ancestor regex++): this library&nbsp;originally used dynamic linking by
default whenever the runtime was dynamic. It's actually safer that way should
you be using regex from a dll for example. However,&nbsp;this
behavior&nbsp;brought a persistent stream of user complaints: mainly about
deployment, all asking if static linking could be the default. After&nbsp;regex
changed behavior the complaints stopped, and the author hasn't had one
complaint about static linking by default being the wrong choice.</P>
<P>Note that other libraries might need to make other choices: for example
libraries that are intended to be used to implement dll pluggin's would like
need to use dynamic linking in almost all cases.</P>
<H3>Supporting Windows Dll's</H3>
<p>On most Unix-like platforms no special annotations of source code are required
in order for that source to be compiled as a shared library because all
external symbols are exposed. However the majority of Windows compilers require
that symbols that are to be imported or exported from a dll, be prefixed with
__declspec(dllimport) or __declspec(dllexport). Without this mangling of source
code, it is not possible to correctly build shared libraries on Windows
(historical note - originally these declaration modifiers were required on
16-bit Windows where the memory layout for exported classes was different from
that of "local" classes - although this is no longer an issue, there is still
no way to instruct the linker to "export everything", it also remains to be
seen whether 64-bit Windows will resurrect the segmented architecture that led
to this problem in the first place. Note also that the mangled names of
exported symbols are different from non-exported ones, so __declspec(dllimport)
is required in order to link to code within a dll).</p>
<p>In order to support the building of shared libraries on MS Windows your code
will have to prefix all the symbols that your library exports with a macro
(lets call it BOOST_WHATEVER_DECL) that your library will define to expand to
either __declspec(dllexport) or __declspec(dllimport) or nothing, depending
upon how your library is being built or used. Typical usage would look like
this:</p>
<pre>#ifndef BOOST_WHATEVER_HPP
#define BOOST_WHATEVER_HPP
#include &lt;boost/config.hpp&gt;
#ifdef BOOST_HAS_DECLSPEC // defined in config system
// we need to import/export our code only if the user has specifically
// asked for it by defining either BOOST_ALL_DYN_LINK if they want all boost
// libraries to be dynamically linked, or BOOST_WHATEVER_DYN_LINK
// if they want just this one to be dynamically liked:
#if defined(BOOST_ALL_DYN_LINK) || defined(BOOST_WHATEVER_DYN_LINK)
// export if this is our own source, otherwise import:
#ifdef BOOST_WHATEVER_SOURCE
# define BOOST_WHATEVER_DECL __declspec(dllexport)
#else
# define BOOST_WHATEVER_DECL __declspec(dllimport)
#endif // BOOST_WHATEVER_SOURCE
#endif // DYN_LINK
#endif // BOOST_HAS_DECLSPEC
//
// if BOOST_WHATEVER_DECL isn't defined yet define it now:
#ifndef BOOST_WHATEVER_DECL
#define BOOST_WHATEVER_DECL
#endif
//
// this header declares one class, and one function by way of examples:
//
class BOOST_WHATEVER_DECL whatever
{
// details.
};
BOOST_WHATEVER_DECL whatever get_whatever();
#endif
</pre>
And then in the source code for this library one would use:
<pre>
//
// define BOOST_WHATEVER SOURCE so that our library's
// setup code knows that we are building the library (possibly exporting code),
// rather than using it (possibly importing code):
//
#define BOOST_WHATEVER_SOURCE
#include &lt;boost/whatever.hpp&gt;
// class members don't need any further annotation:
whatever::whatever() { }
// but functions do:
BOOST_WHATEVER_DECL whatever get_whatever()
{
return whatever();
}
</pre>
<H4>Importing/exporting dependencies</H4>
<P>As well as exporting your main classes and functions (those that are actually
documented), Microsoft Visual C++ will warn loudly and often if you try to
import/export a class whose dependencies are not also exported. Dependencies
include: any base classes, any user defined types used as data members, plus
all of the dependencies of your dependencies and so on. This causes particular
problems when a dependency is a template class, because although it is
technically possible to export these, it is not at all easy, especially if the
template itself has dependencies which are implementation-specific details. In
most cases it's probably better to simply suppress the warnings using:</P>
<PRE>#ifdef BOOST_MSVC
# pragma warning(push)
# pragma warning(disable : 4251 4231 4660)
#endif
// code here
#ifdef BOOST_MSVC
#pragma warning(pop)
#endif
</PRE>
<p>This is safe provided that there are no dependencies that are (template)
classes with non-constant static data members, these really do need exporting,
otherwise there will be multiple copies of the static data members in the
program, and that's really really bad.
</p>
<p>Historical note: on 16-bit Windows you really did have to export all
dependencies or the code wouldn't work, however since the latest Visual Studio
.NET supports the import/export of individual member functions, it's a
reasonably safe bet that Windows compilers won't do anything nasty - like
changing the class's ABI - when importing/exporting a class.</p>
<h4>Rationale:</h4>
<p><EM>Why bother - doesn't the import/export mechanism take up more code that the
classes themselves?</EM></p>
<P>A good point, and probably true, however there are some circumstances where
library code must be placed in a shared library - for example when the
application consists of multiple dll's as well as the executable, and more than
one those dll's link to the same Boost library - in this case if the library
isn't dynamically linked and it contains any global data (even if that data is
private to the internals of the library) then really bad things can happen -
even without global data, we will still get a code bloating effect.
Incidentally, for larger applications, splitting the application into multiple
dll's can be highly advantageous - by using Microsoft's "delay load" feature
the application will load only those parts it really needs at any one time,
giving the impression of a much more responsive and faster-loading application.</P>
<p><EM>Why static linking by default? </EM>
</p>
<P>In the worked example above, the code assumes that the library will be
statically linked unless the user asks otherwise. Most users seem to prefer
this (there are no separate dll's to distribute, and the overall distribution
size is often significantly smaller this way as well: i.e. you pay for what you
use and no more), but this is a subjective call, and some libraries may even
only be available in dynamic versions (Boost.threads for example).</P>
<h3><A name="auto-link"></A>Automatic Library Selection and Linking with <a href="../boost/config/auto_link.hpp">
auto_link.hpp</a></h3>
<p>Many Windows compilers ship with multiple runtime libraries - for example
Microsoft Visual Studio .NET comes with 6 versions of the C and C++ runtime. It
is essential that the Boost library that the user links to is built against the
same C runtime as the program is built against. If that is not the case, then
the user will experience linker errors at best, and runtime crashes at worst.
The Boost build system manages this by providing different build variants, each
of which is build against a different runtime, and gets a slightly different
mangled name depending upon which runtime it is built against. For example the
regex libraries get named as follows when built with Visual Studio .NET 2003:</p>
<pre>boost_regex-vc71-mt-1_31.lib
boost_regex-vc71-mt-gd-1_31.lib
libboost_regex-vc71-mt-1_31.lib
libboost_regex-vc71-mt-gd-1_31.lib
libboost_regex-vc71-mt-s-1_31.lib
libboost_regex-vc71-mt-sgd-1_31.lib
libboost_regex-vc71-s-1_31.lib
libboost_regex-vc71-sgd-1_31.lib
</pre>
<p>The difficulty now is selecting which of these the user should link his or her
code to.</p>
<p>In contrast, most Unix compilers typically only have one runtime (or sometimes
two if there is a separate thread safe option). For these systems the only
choice in selecting the right library variant is whether they want debugging
info, and possibly thread safety.
</p>
<p>Historically Microsoft Windows compilers have managed this issue by providing a
#pragma option that allows the header for a library to automatically select the
library to link to. This makes everything automatic and extremely easy for the
end user: as soon as they include a header file that has separate source code,
the name of the right library build variant gets embedded in the object file,
and as long as that library is in the linker search path, it will get pulled in
by the linker without any user intervention.</p>
<p>Automatic library selection and linking can be enabled for a Boost library by
including the header &lt;boost/config/auto_link.hpp&gt;, after first defining
BOOST_LIB_NAME and, if applicable, BOOST_DYN_LINK.</p>
<pre>//
// Automatically link to the correct build variant where possible.
//
#if !defined(BOOST_ALL_NO_LIB) &amp;&amp; !defined(BOOST_WHATEVER_NO_LIB) &amp;&amp; !defined(BOOST_WHATEVER_SOURCE)
//
// Set the name of our library, this will get undef'ed by auto_link.hpp
// once it's done with it:
//
#define BOOST_LIB_NAME boost_whatever
//
// If we're importing code from a dll, then tell auto_link.hpp about it:
//
#if defined(BOOST_ALL_DYN_LINK) || defined(BOOST_WHATEVER_DYN_LINK)
# define BOOST_DYN_LINK
#endif
//
// And include the header that does the work:
//
#include &lt;boost/config/auto_link.hpp&gt;
#endif // auto-linking disabled
</pre>
<p>The library's user documentation should note that the feature can be disabled
by defining either BOOST_ALL_NO_LIB or BOOST_WHATEVER_NO_LIB:</p>
<P>If for any reason you need to debug this feature, the header
&lt;boost/config/auto_link.hpp&gt; will output some helpful diagnostic messages
if you first define BOOST_LIB_DIAGNOSTIC.</P>
<H2><A name="build_changes"></A>Changes Affecting the Build System</H2>
<H3><a name="build"></a><A name="jamfile"></A>Creating the library Jamfile</H3>
<P>The Jamfile for building library "whatever" typically lives in
boost-root/libs/whatever/build, the only extra step required is to add a
&lt;define&gt; requirement to the library target so that your code knows
whether it's building a dll or static library, a typical Jamfile would like
like this:</P>
<PRE>
lib boost_regex : ../src/whatever.cpp :
&lt;link&gt;shared:&lt;define&gt;BOOST_WHATEVER_DYN_LINK=1 ;
</PRE>
<H3><A name="testing"></A>Testing Auto-linking</H3>
<P>Testing the auto-link feature&nbsp;is somewhat convoluted, and requires access
to a compiler that supports the feature: refer to <A href="../libs/config/test/link/test/Jamfile.v2">
libs/config/test/link/test/Jamfile.v2</A> for an example.</P>
<HR>
<p><A name="copyright"></A>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
26 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39365" --></p>
<p><i>© Copyright John Maddock&nbsp;1998-
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan --> 2003<!--webbot bot="Timestamp" endspan i-checksum="746" --></i></p>
<P><I>Distributed under the Boost Software License, Version 1.0. (See accompanying
file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
http://www.boost.org/LICENSE_1_0.txt</a>)</I></P>
<P><EM>The use of code snippets from this article does not require the reproduction
of this copyright notice and license declaration; if you wish to provide
attribution then please provide a link to this article.</EM></P>
</body>
</html>

BIN
space.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 43 B

134
submission_process.htm
View File

@ -1,134 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Boost Library Submission Process</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Boost Library Submission Process</h1>
<p>This page describes the process a library developer goes through to get a
library accepted by Boost.</p>
<p>See the <a href="lib_guide.htm">Boost Library Requirements and Guidelines</a>
page for issues of content.</p>
<h3><b>Steps for getting a library accepted by Boost:</b></h3>
<ul>
<li><a href="#Learn">Learn about Boost</a>.</li>
<li><a href="#interest">Determine interest</a>.</li>
<li><a href="#Preliminary">Preliminary submission</a>.</li>
<li><a href="#Refinement">Refinement</a>.</li>
<li><a href="#Submission">Submission for review</a>.</li>
<li><a href="#Review">Formal Review</a>.</li>
<li><a href="#SitePosting">Web site posting</a>.</li>
<li><a href="#People">People page.</a></li>
<li><a href="#Lifecycle">Lifecycle</a>.</li>
</ul>
<h2><a name="Learn">Learn</a> about Boost</h2>
<p>Subscribe to the <a href="mailing_lists.htm#main">main developers mailing list</a> for a
while, or look through the <a href="mailing_lists.htm#archive">archives</a>.&nbsp;
Click around the <a href="../index.htm">web site</a>.&nbsp; Understand the <a href="lib_guide.htm">Requirements</a>.&nbsp;
Read the rest of this page to learn about the process.&nbsp; Otherwise, you will
just end up wasting everyone's time.</p>
<p>There is a culture associated with Boost, aimed at encouraging high quality
libraries by a process of discussion and refinement.</p>
<p>If what you really want is a site that will just post your library without
even looking at it, you should go elsewhere.</p>
<h2>Determine <a name="interest">interest</a></h2>
<p>Potential library submitters should use the Boost developers <a href="mailing_lists.htm">mailing
list</a> as a forum to gauge interest a possible submission.</p>
<p>A message might be as simple as &quot;Is there any interest in a library
which solves Traveling Salesperson problems in linear time?&quot;</p>
<p>A bit of further description or snippet of code may be helpful. Messages
should be plain text; not rich text, HTML, etc.</p>
<p>Please don't post lengthy descriptions, documentation, or code to the mailing
list, and no attachments, even small ones.&nbsp; Please post lengthy material in
the boost <a href="http://boost-sandbox.sourceforge.net/vault/">Sandbox Vault</a>.&nbsp;</p>
<h2><a name="Preliminary">Preliminary</a> submission</h2>
<p>If response to an initial query indicates interest, then post the preliminary
submission files in the <a href="http://boost-sandbox.sourceforge.net/vault/">Sandbox Vault</a> on
the sourceforge web site if you haven't already done so.</p>
<h2><a name="Refinement">Refinement</a></h2>
<p>Discuss, refine, resubmit.&nbsp; Repeat until satisfied.</p>
<p>The exact details of this process varies a lot.&nbsp; Sometimes it is public,
on the mailing list, sometimes a lot of discussion happens in private
emails.&nbsp; For some libraries the process is over quickly, for others it goes
on for months.&nbsp; It's often challenging, and sometimes leads off in
completely unexpected directions.&nbsp;&nbsp;</p>
<p>The <a href="mailing_lists.htm#archive">archive</a> of past
messages is one way to see how this process worked for other Boost
libraries.</p>
<h2><a name="Submission">Submission</a> for review&nbsp;</h2>
<p>All of the files which make up the library should be combined and compressed
into a single submission file using the .zip format.&nbsp; Free encoders
and decoders for this format running on many different platforms are available
at the <a href="http://www.info-zip.org/pub/infozip/">Info-ZIP</a> web site, which
includes a FAQ and much other useful information about the .zip format. Many
commercial compressor-archiver utilities also support this format.</p>
<p>The submission file should contain material as if on the
boost.org web site.&nbsp; The closer the submission file mirrors the final
<a href="lib_guide.htm#Directory_structure">directory
structure</a> and format of the web site, the better.
<p>Like a preliminary submission, post the final submission .zip file in the <a href="http://boost-sandbox.sourceforge.net/vault/">Sandbox Vault</a> of
the sourceforge site.
<h2>Formal <a name="Review">Review</a></h2>
<p>Before asking for formal review, your submission should be posted in the
Boost files/vault. Please verify that your submission compiles
and runs under at least two compilers.&nbsp; This flushes out obvious
portability problems.&nbsp; If you don't have access to a second compiler, ask
for help on the Boost mailing list.</p>
<p>Once a library author feels a submission (which presumably is now in the
files/vault) has matured enough for formal review, the author sends a message
requesting a formal review to the mailing list.&nbsp; Please use a subject in
the form &quot;Review Request: library&quot; where <i>library</i> is replaced by
the library name.</p>
<p>See <a href="formal_review_process.htm">Formal Review Process</a> for
details.</p>
<p>Formal Review schedules are posted on
the <a href="formal_review_schedule.html">web site</a>.&nbsp;</p>
<h2>Boost web <a name="SitePosting">site posting</a></h2>
<p>Once an accepted library is ready for inclusion on the Boost web site, the
submitter is typically given Boost CVS write access, and expected to check-in
and maintain the library in the CVS. Contact the moderators if you need write
access or CVS use isn't possible for you.</p>
<h2><a name="People">People</a> page</h2>
<p>If the boost.org web site doesn't already have your capsule biography
and&nbsp; picture (optional, with not-too-serious pictures preferred), please
send them to the Boost webmaster. It is
up to you as to whether or not the biography includes your email address or
other contact information.&nbsp; The preferred picture format is .jpg, but other
common formats are acceptable.&nbsp; The preferred image size is 500x375 but the
webmaster has photo editing software and can do the image preparation if
necessary.</p>
<h2><a name="Lifecycle">Lifecycle</a></h2>
<p>Libraries are software; they lose their value over time if not maintained.
Postings on the Boost developers or users mailing lists can alert you to
potential maintenance needs; please plan to maintain your library over time. If
you no longer can or wish to maintain your library, please post a message on the
Boost developers mailing list and help someone else take over as the library
maintainer.</p>
<hr>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->26 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39365" --></p>
<p>© Copyright Beman Dawes 2000</p>
<p>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

100
test_policy.htm
View File

@ -1,100 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Boost Test Policies and Protocols</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td>
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Boost Test Policies and Protocols</h1>
<p>The Boost libraries are intended to be both reliable and portable.&nbsp;
Every experienced programmer knows that means each library must be tested against a suitable number of test cases, on a wide range of platforms,
and then tested again (regression tested) every time a change is made and before
every release.&nbsp;</p>
<p>&quot;Quality assurance based on a wide range of targeted tests&quot; as one
of the key answers to C.A.R
Hoare's question
&quot;How did software get so reliable without proof.&quot;</p>
<h2>Regression test</h2>
<p>Boost uses an automatic <a href="regression.html"> regression test suite</a> which generates HTML
<a href="../status/compiler_status.html">compiler
status tables</a>.</p>
<h2>Test Policy</h2>
<h3>Required</h3>
<ul>
<li>Every Boost library should supply one or more suitable test programs to be
exercised by the Boost <a href="regression.html"> regression test suite</a>.&nbsp; In addition to
the usual compile-link-run tests expecting successful completion,
compile-only or compile-and-link-only tests may be performed, and success
for the test may be defined as failure of the steps.</li>
<li>Test program execution must report errors by returning a non-zero value.&nbsp; They
may also write to stdout or stderr, but that output should be relatively
brief.&nbsp; Regardless of other output, a non-zero return value is the only
way the regression test framework will recognize an error has
occurred.&nbsp;Note that test programs to be included in the status tables must
compile, link, and run quickly since the tests are executed many, many,
times.</li>
<li>Libraries with time consuming tests should be divided into a
fast-execution basic test program for the status tables, and a separate
full-coverage test program for exhaustive test cases.&nbsp; The basic test
should concentrate on compilation issues so that the status tables
accurately reflect the library's likelihood of correct compilation on a
platform.</li>
<li>If for any reason the usual test policies do not apply to a particular
library, an alternate test strategy must be implemented.</li>
<li>A <a href="regression.html#Adding_new_test">Jamfile</a> to drive the
regression tests for the library. &nbsp;&nbsp;</li>
</ul>
<h3>Optional (but highly recommended)</h3>
<p>The <a href="../libs/test/index.html">Boost Test Library</a> provides many
useful components which ease the construction of test programs.</p>
<ul>
<li>Use the library's
<a href="../libs/test/doc/components/test_tools/index.html">Test Tools</a> for the construction of simple test
programs that do not need much structure.</li>
<li>Use the library's
<a href="../libs/test/doc/components/utf/index.html">Unit Test
Framework</a> for the construction of more complex test programs that need to
be structured into individual tests
and test suites.</li>
</ul>
<h2>Suggested Protocol for Fixing Bugs or Adding Features.</h2>
<ul>
<li>First, add regression test cases that detects the bug or tests the
feature. Sometimes adding one case suggests similar untested cases, and they
are added too.</li>
<li>Second, for bugs, run the regression test and verify that the bug is now
detected.</li>
<li>Third, then, and only then, fix the bug or add the feature.</li>
<li>Finally, rerun the full regression tests - sometimes the change breaks
something else.</li>
</ul>
<h2>History</h2>
<p><a href="regression.html#History">See Regression Test History</a>.</p>
<h2>Acknowledgements</h2>
<p>Written by Beman Dawes. Jens Maurer, Paul Moore, Gary Powell and Jeremy Siek contributed helpful suggestions.</p>
<hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->08 January, 2004<!--webbot bot="Timestamp" endspan i-checksum="38708" -->
</p>
<p>© Copyright Beman Dawes 2001</p>
<p>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

111
updating_the_website.html
View File

@ -1,111 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Updating The Boost Website</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2" summary="Quick Links">
<tr>
<td bgcolor="#FFFFFF"><img src="../boost.png" alt=
"boost.png (6897 bytes)" width="277" height="86" /></td>
<td><a href="../index.htm"><font face="Arial" color=
"#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../libs/libraries.htm"><font face="Arial" color=
"#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/people.htm"><font face="Arial" color=
"#FFFFFF"><big>People</big></font></a></td>
<td><a href="faq.htm"><font face="Arial" color=
"#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="index.htm"><font face="Arial" color=
"#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Making Updates to the Boost Website Content</h1>
<p>Any boost developer can update the Boost website content between
releases.</p>
<ul>
<li>We <em>strongly</em> recommend the use of <a href=
"http://tidy.sourceforge.net/">HTML Tidy</a> when editing HTML and XHTML
files intented for the website. Using <code>tidy</code> helps in
preventing errors in the HTML, in keeping a clear revision history, and
in conforming to Web standards to help make the website readable by the
majority of people. The Boost web pages currently have a variety of
different types of HTML and XHTML content. Each needs to be dealt with
differently by <code>tidy</code>. Most pages are regular HTML 3.x/4.x,
for these use a <code>tidy</code> invocation of:
<pre>
tidy --tidy-mark no -i -wrap 78 -m <i>some_page.html</i>
</pre>Other pages are using the more recent XHTML 1.0 and XHTML 1.0 Strict
standards. Most notably this include the <a href="../index.htm">home
page</a>. Some additional options are needed to make <code>tidy</code>
enforce the XHTML standard:
<pre>
tidy --tidy-mark no -i -wrap 78 -m -asxhtml <i>some_page.html</i>
</pre>That command is also useful if one is converting from HTML to XHTML. To
have <code>tidy</code> check for the XHTML 1.0 Strict format use:
<pre>
tidy --tidy-mark no -i -wrap 78 -m -asxhtml --doctype strict <i>some_page.html</i>
</pre>If you have a choice as to what format to use, prefer the XHTML 1.0
Strict format as that opens the content to the widest audience.
</li>
<li>If the change you are making is intended to be part of a release, you
should first make the change in our CVS repository, so it doesn't get
lost or overwritten by the next person that updates the page between
releases. Of course if you don't check in (say because the change is not
supposed to be in the next release), and someone else changes the page
after you, the change may be lost. This procedure does not account for
that case; you'll have to use your head and figure out what to do.</li>
<li>You will upload the file(s) by <code>scp</code>'ing to the
appropriate subdirectory of
<code>shell.sf.net:/home/groups/b/bo/boost/htdocs/</code>. For example,
to update the page you are reading, I would issue
<pre>
scp updating_the_website.html david_abrahams@shell.sf.net:/home/groups/b/bo/boost/htdocs/more/
</pre>
</li>
<li>It is <b>crucial</b> to ensure that you set group write permission on
every file you upload. If you don't do that, nobody else will be able to
change it, which is particularly deadly at release time. If you are on
Unix or Cygwin, you may be able to do that with a <tt>chmod</tt> command
before uploading the file. The absolutely failsafe thing to do is to <tt>
ssh</tt> into <tt>shell.sf.net</tt> and do the <tt>chmod</tt> there.
The files also need to have general read permission, and any
directories should have general execute permission and the "set user or
group ID on execution" (s) bit should also be set. If you're not
touching any directories, you can do it all with one command, e.g.
<pre>
ssh david_abrahams@shell.sf.net "chmod a+r,g+rw /home/groups/b/bo/boost/htdocs/more/updating_the_website.html"
</pre>
</li>
</ul>
<hr />
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B,
%Y" startspan -->$Date$
<!--webbot bot="Timestamp" endspan
i-checksum="38708" --></p>
<p>&copy; Copyright David Abrahams 2005</p>
<p>&copy; Copyright Rene Rivera 2005</p>
<p>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

2608
version_history.html
View File

File diff suppressed because it is too large Load Diff

BIN
w3c_valid_css.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.1 KiB

BIN
w3c_valid_xhtml10.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.4 KiB

20
whos_using/Jamfile.v2
View File

@ -1,20 +0,0 @@
# Copyright John Maddock 2005. 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)
using quickbook ;
xml using : using.qbk ;
boostbook standalone
:
using
:
<xsl:param>nav.layout=none
#<xsl:param>navig.graphics=0
;
install html : ../../doc/html/boostbook.css ;
install ../ : ../../boost.png ;

1246
whos_using/using.qbk
View File

File diff suppressed because it is too large Load Diff

576
writingdoc/design.html
View File

@ -1,576 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<link rel="stylesheet" type="text/css" href="../../boost.css">
<title>Writing Documentation for Boost - HTML Design</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.html"><img height="86" width="277" alt="C++ Boost"
src="../../boost.png" border="0"></a></h3>
</td>
<td valign="top">
<h1 align="center">Writing Documentation for Boost</h1>
<h2 align="center">HTML Design</h2>
</td>
</tr>
</table>
<hr>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#common-pages">Common Pages Included in HTML
Documentation</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#index-page">Index</a></dt>
<dt><a href="#overview-page">Overview</a></dt>
<dt><a href="#definitions-page">Definitions</a></dt>
<dt><a href="#rationale-page">Rationale</a></dt>
<dt><a href="#configuration-page">Configuration Information</a></dt>
<dt><a href="#faq-page">Frequently Asked Questions</a></dt>
<dt><a href="#bibliography-page">Bibliography</a></dt>
<dt><a href="#acknowledgements-page">Acknowledgment</a></dt>
<dt><a href="#header-page">Header Reference</a></dt>
</dl>
</dd>
<dt><a href="#layout">Layout</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#page-banner">Page Banner</a></dt>
<dt><a href="#page-index">Page Index</a></dt>
<dt><a href="#content">Documentation Content</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#doc-footnotes">Footnotes</a></dt>
</dl>
</dd>
<dt><a href="#revision-info">Revision Information</a></dt>
<dt><a href="#copyright">Copyright Information</a></dt>
</dl>
</dd>
<dt><a href="#format">Format</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#style-sheets">Cascading Style Sheets</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#boost-style-sheet">Boost Style Sheet</a></dt>
</dl>
</dd>
</dl>
</dd>
<dt><a href="#templates">Templates</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#index-template">Index Page Template</a></dt>
<dt><a href="#overview-template">Overview Page Template</a></dt>
<dt><a href="#definitions-template">Definitions Page
Template</a></dt>
<dt><a href="#rationale-template">Rationale Page Template</a></dt>
<dt><a href="#configuration-template">Configuration Page
Template</a></dt>
<dt><a href="#faq-template">FAQ (Frequently Asked Questions) Page
Template</a></dt>
<dt><a href="#bibliography-template">Bibliography Page
Template</a></dt>
<dt><a href="#acknowledgements-template">Acknowledgments Page
Template</a></dt>
<dt><a href="#header-template">Header Page Template</a></dt>
</dl>
</dd>
</dl>
<h2><a name="introduction" id="introduction"></a>Introduction</h2>
<p>Boost places no requirements on the design of HTML documentation for
library submitters. If you are submitting a library for which documentation
already exists in either HTML or in a form easily converted to HTML then
there is no need for you to read this document. However, if you have not
yet written the documentation, or if you expect to have to translate
documentation written in a format not easily convertible to HTML then this
document can give you a lot of information on how to go about writing
documentation in HTML.</p>
<p>In several places this document assumes you're writing the documentation
to conform to the structure described in the <a href=
"structure.html">Documentation Structure</a> document. There is no
requirement that your documentation content follow these guidelines, but
they provide an effective way to communicate technical specifications for a
library in a terse yet precise manner that's familiar to many Boost
users.</p>
<p>This document also contains links to <a href="#templates">HTML template
files</a> that can be used to rapidly develop documentation for a library
submission. These templates follow the guidelines presented here and in the
<a href="structure.html">Documentation Structure</a> document.</p>
<h2><a name="common-pages" id="common-pages"></a>Common Pages Included in
HTML Documentation</h2>
<p>Most HTML documentation projects will contain some common pages. General
guidelines for these common pages are provided below.</p>
<h3><a name="index-page" id="index-page"></a>Index</h3>
<p>The index page is the first page presented to a user when he browses the
documentation. Generally this page should not contain any actual content,
but instead contains a list of links to specific content. At a minimum this
list should contain a link to every HTML page contained in the
documentation. Optionally, sub-lists may be provided for individual pages
linking to specific subjects within the page. These sub-lists should form a
"tree" hierarchy based on the level of heading tag used for the specific
subject. Inclusion of such sub-lists for every page can make the index
rather lengthy, and since each page should include its own <a href=
"#page-index">Page Index</a>, it may make the navigation of the
documentation easier if such sub-lists are avoided. However, there is one
exception to this guideline: reference documentation should contain a link
to every header file in the library and a sub-list with a link to every
macro, value, type, class, function and object (see <a href=
"structure.html">Documentation Structure</a>) found in the header. Users
aren't always sure what header file any of these may be contained in, so
this structure in the index allows for easy navigation of the reference
documentation.</p>
<p>The index list should generally be constructed using an HTML "definition
list" (&lt;dl&gt; and &lt;dt&gt; tags). A definition list has no bullets or
ordered specifications and produces a cleaner layout then an unordered list
(&lt;ul&gt; and &lt;li&gt; tags) or an ordered list (&lt;ol&gt; and
&lt;li&gt; tags). If you choose to use the common <a href=
"#boost-style-sheet">Boost Style Sheet</a> you should add a
<code>class="index"</code> attribute/value pair to the &lt;dl&gt; tag.</p>
<p>An Index page <a href="#index-template">template</a> is provided for
use.</p>
<h3><a name="overview-page" id="overview-page"></a>Overview</h3>
<p>The Overview page is used to introduce the reader to the library. It
should give a high-level overview of the purpose of the library and
introduce the reader to any concepts they may be unfamiliar with. This may
also be an appropriate place for some "light" rationale, though more
thorough presentation of any rationale would be better placed in the
<a href="#rationale-page">Rational Page</a>.</p>
<p>Like most content pages, the Overview page should include a <a href=
"#page-index">Page Index</a>.</p>
<p>An Overview page <a href="#overview-template">template</a> is provided
for use.</p>
<h3><a name="definitions-page" id="definitions-page"></a>Definitions</h3>
<p>The Definitions page is used to provide a list of definitions for terms
that a user may be unfamiliar with.</p>
<p>The definition list should generally be constructed using an HTML
"definition list" (&lt;dl&gt; and &lt;DT&gt; tags). A definition list has
no bullets or ordered specifications and produces a cleaner layout then an
unordered list (&lt;UL&gt; and &lt;li&gt; tags) or an ordered list
(&lt;ol&gt; and &lt;li&gt; tags). If you choose to use the common <a href=
"#boost-style-sheet">Boost Style Sheet</a> you should add a
<code>class="definition"</code> attribute/value pair to the &lt;dl&gt;
tag.</p>
<p>Because this page's content should only contain a list of definitions,
it should not have a <a href="#page-index">Page Index</a>.</p>
<p>A Definitions page <a href="#definitions-template">template</a> is
provided for use.</p>
<h3><a name="rationale-page" id="rationale-page"></a>Rationale</h3>
<p>The Rationale page is used to provide lengthy descriptions of the
rationale behind the library's design. This information helps users to
understand why a library was designed the way it was and may reduce the
frequency of a number of frequently asked questions. For a better
description of why rationale is important see the <a href=
"http://www.boost.org/more/lib_guide.htm#Rationale">Rationale rationale</a>
in the general submission guidelines.</p>
<p>Like most content pages, the Rationale page should include a <a href=
"#page-index">Page Index</a>.</p>
<p>A Rationale page <a href="#rationale-template">template</a> is provided
for use.</p>
<h3><a name="configuration-page" id="configuration-page"></a>Configuration
Information</h3>
<p>The Configuration Information page is used to document configuration
macros used by the library. Such macros belong in one of three groups:
macros used by library implenters defined in
<code>&lt;boost/config.hpp&gt;</code>, macros used by library users to
detect platform configuration information and macros defined by library
users to configure library behavior.</p>
<p>Like most content pages, the Overview page should include a <a href=
"#page-index">Page Index</a>.</p>
<p>A Configuration page <a href="#configuration-template">template</a> is
provided for use.</p>
<h3><a name="faq-page" id="faq-page"></a>Frequently Asked Questions</h3>
<p>As a library matures the users will have questions about the usage of
the library. Often users will ask the same questions over and over again.
Rather than having to deal with answering the question every time it's
asked, a Frequently Asked Questions (commonly known as FAQs) page can be
used to document the questions and answers. This is such a valuable piece
of documentation not only for the users but for the maintainers as well,
that a FAQ page should be provided from the outset. If there are no
questions that will obviously become a FAQ, the initial page may just
indicate that there are no FAQs yet. This empty place holder helps to
indicate to the users that you plan to address any FAQs as they occur.</p>
<p>The <a href="#page-index">Page Index</a> for the FAQ page should contain
a list of all the questions contained in the document. The actual question
entries should be formatted with the question in a heading tag and the
answers in standard paragraph format. This provides a clean presentation
that's easy to read.</p>
<p>A Frequently Asked Questions page <a href="#faq-template">template</a>
is provided for use.</p>
<h3><a name="bibliography-page" id=
"bibliography-page"></a>Bibliography</h3>
<p>The Bibliography page is used to document any bibliographical
information associated with references made within the documentation to
external resources. Parenthetical references are used within the
documentation which link to entries in the Bibliography page.
Bibliographical entries provide detailed information about the external
resource and may contain hyper links to the resource if it's available
online. There are several formal styles used for writing bibliographies.
You may use what ever style you want, but one of the better styles to
consider using can be referenced <a href=
"http://www.columbia.edu/cu/cup/cgos/idx_basic.html">here</a>.</p>
<p>Since the Bibliography page should contain only bibliographical
information there is no need for a <a href="#page-index">Page
Index</a>.</p>
<p>A Bibliography page <a href="#bibliography-template">template</a> is
provided for use.</p>
<h3><a name="acknowledgements-page" id=
"acknowledgements-page"></a>Acknowledgment</h3>
<p>The Acknowledgment page is used to give credit where credit is due. When
individuals provide input on the design or implementation, or when you make
use of someone else's work, you should acknowledge them. This is a courtesy
that you'd expect others to extend to you, so you should strive to
acknowledge the efforts of everyone else in your own documentation.</p>
<p>Since the Acknowledgment page should contain only a list of
acknowledgment there is no need for a <a href="#page-index">Page
Index</a>.</p>
<p>An Acknowledgments page <a href=
"#acknowledgements-template">template</a> is provided for use.</p>
<h3><a name="header-page" id="header-page"></a>Header Reference</h3>
<p>The Header Reference pages are the most important pages in your
documentation. They document all library headers, including all the macros,
values, types, classes, functions and objects defined in them. In general
it may prove useful to follow the guidelines in <a href=
"structure.html">Documentation Structure</a> when writing the content for
these pages.</p>
<p>Like most content pages, the Header Reference pages should include a
<a href="#page-index">Page Index</a>.</p>
<p>A Header Reference page <a href="#header-template">template</a> is
provided for use.</p>
<h2><a name="layout" id="layout"></a>Layout</h2>
<p>There are certain page layout concepts that will be used frequently in
many of your pages. This section outlines some general guidelines that you
can follow when designing each of these layout concepts for your
documentation.</p>
<h3><a name="page-banner" id="page-banner"></a>Page Banner</h3>
<p>The Page Banner is located at the very top of a page and provides quick
information about the page contents. This includes the Boost logo, which
indicates to the reader that this page is part of the Boost web site, a
title for the documentation (generally the library name) and the page
title. The Boost logo should hyper link to the Boost home page on the index
page and to the index page on all other pages. This allows the user to
easily navigate through the Boost web site and through the documentation.
The &lt;title&gt; tag for the HTML page should consist of the documentation
title and the page title separated by a hyphen.</p>
<p>The Page Banner should be separated from the rest of the page by the use
of an &lt;hr&gt; tag. This helps to clearly separate the actual content
from the title information and produces cleaner text.</p>
<h3><a name="page-index" id="page-index"></a>Page Index</h3>
<p>The page index is used to quickly navigate to the various sections of
the documentation on the page, and when present should be located just
below the Page Banner.</p>
<p>The index list should generally be constructed using an HTML "definition
list" (&lt;dl&gt; and &lt;DT&gt; tags). A definition list has no bullets or
ordered specifications and produces a cleaner layout then an unordered list
(&lt;UL&gt; and &lt;li&gt; tags) or an ordered list (&lt;ol&gt; and
&lt;li&gt; tags). If you choose to use the Boost Style Sheet you should add
a <code>class="page-index"</code> attribute/value pair to the &lt;dl&gt;
tag.</p>
<p>Most pages should include a Page Index.</p>
<h3><a name="content" id="content"></a>Documentation Content</h3>
<p>The page's actual documentation content will be formatted according to
the specific needs of individual pages, and should be placed right after
the Page Index if present, or after the Page Banner if not. In general the
documentation content will take the form of paragraph text contained
underneath section headings.</p>
<h3><a name="doc-footnotes" id="doc-footnotes"></a>Footnotes</h3>
<p>Footnotes may be used within a page's documentation. Within the
documentation content a footnote reference should take the form of a
footnote number in parentheses (the parentheses make it easier for the
reader to click on the hyper link) hyper linking to the actual footnote at
the bottom of the page's documentation content. You may either use the
&lt;sup&gt; tag to format such footnote numbers, or, preferably, you can
use a CSS style class in order to distinguish the number as a footnote
instead of as part of the actual text. If you choose to use the common
<a href="#boost-style-sheet">Boost Style Sheet</a>, a <code>footnote</code>
class is defined for this purpose.</p>
<h3><a name="revision-info" id="revision-info"></a>Revision
Information</h3>
<p>At the bottom of every page should be some revision information
indicating when the page was last revised. This information should be
separated from the rest of the page above by an &lt;hr&gt; tag. The
following HTML code snippet can be used to track this revision information
(this code uses some server components that exist on the Boost web site to
automatically track revision dates with out the need for hand editing the
date text):</p>
<pre>
&lt;hr&gt;
&lt;p&gt;Revised
&lt;!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --&gt;
01 January, 2001
&lt;!--webbot bot="Timestamp" endspan i-checksum="39359" --&gt;
&lt;/p&gt;
</pre>
<h3><a name="copyright" id="copyright"></a>Copyright Information</h3>
<p>The very bottom of the page should contain any copyright information
that applies to the document.</p>
<h2><a name="format" id="format"></a>Format</h2>
<p>This section provides general guidelines for formatting documentation
using HTML. The description of the various "common pages" gave specific
details for formatting specific sections of the documentation, which should
override these guidelines.</p>
<h3><a name="code-format" id="code-format"></a>Code</h3>
<p>Code within the documentation should be placed within either
&lt;code&gt;&lt;/code&gt; or &lt;pre&gt;&lt;/pre&gt; tags. For code that's
placed inline with other text you use &lt;code&gt;&lt;/code&gt; tags, while
&lt;pre&gt;&lt;/pre&gt; tags are used for code "blocks". If a cascading
style sheet is used to specify formatting for these tags, a fixed width
sans serif font should be used. This insures that the code is easily
distinguishable from the rest of the text. It may also be beneficial to set
the style for &lt;pre&gt;&lt;/pre&gt; tags to indent the text, to help
separate code blocks from other structural HTML blocks. The <a href=
"#boost-style-sheet">Boost Style Sheet</a> specifies formatting for these
tags.</p>
<p><b>Note:</b> "Code" includes variable names, function names, etc.</p>
<h3><a name="lists" id="lists"></a>Lists</h3>
<p>Lists should be constructed as unordered (&lt;UL&gt; and &lt;li&gt;
tags), ordered (&lt;ol&gt; and &lt;li&gt; tags) or definition (&lt;dl&gt;
and &lt;DT&gt; tags) lists in HTML. You use an unordered list when you need
a collection of items that don't have any kind of logical ordering, such as
a list of data types that are defined by the library and can be used for a
template argument. You use an ordered list when the collection of items
must be grouped in a logical ordering, such as when enumerating the steps
that an action logically performs. You use a definition list when the list
consists of not only items that have no logical ordering, but also contains
definitions/descriptions/etc. of the items. A good example of this is the
function specifications as described in <a href=
"structure.html">Documentation Structure</a>.</p>
<h3><a name="graphics" id="graphics"></a>Graphics</h3>
<p>Graphics should be used very sparingly, if at all. Graphic images
greatly effect the download time for many people, which can discourage
users from reading the documentation. If you need graphic images to help
illustrate something in your documentation consider supplying only a link
to the image within the documentation, instead of embedding it directly in
the text. If an image is going to be included in the text of the document
you should specify the image's size in the &lt;img&gt; tag, in order to
allow the user's browser to optimize the formatting of the text before the
image is loaded.</p>
<h3><a name="non-breaking-spaces" id="non-breaking-spaces"></a>Non-breaking
Spaces</h3>
<p>Non-breaking spaces (&amp;nbsp;) should be avoided in HTML text.
Generally there are more appropriate ways to format the document, such as
using list constructs or specifying indentation as a style attribute or in
cascading style sheets.</p>
<h3><a name="style-sheets" id="style-sheets"></a>Cascading Style
Sheets</h3>
<p>Cascading style sheets allow you to apply some advanced formatting
styles to an HTML document. More importantly, they allow you to change the
formatting in a single file and effect all pages using the style sheet.
Instead of struggling to produce a specific format in HTML it's often
easier and more flexible to specify the formatting in a style sheet.</p>
<h4><a name="boost-style-sheet" id="boost-style-sheet"></a>Boost Style
Sheet</h4>
<p>The concept of using cascading style sheets to format HTML is such a
good idea that it can be beneficial to apply this across the entire Boost
site. Of course we can't require this (if Boost were to require such trivia
for submissions it's likely that many programmers would be discouraged from
contributing). However, a "standard" Boost style sheet
(http://www.boost.org/boost.css) is supplied anyway, so that a contributer
can quickly and easily produce clear and consistent documentation that
reflects a Boost "brand" if they so choose. If, at a later date, it's
decided to update the Boost "brand", it may be done in this single file and
all documents using the style sheet will automatically be updated.</p>
<p>The Boost supplied style sheet not only specifies styles for many
standard tags, it also specifies several style "classes". A class is
specified for a given tag instead of being applied to all instances of a
given tag type. Below is a list of the classes specified in the Boost style
sheet and a description of when to use them:</p>
<dl>
<dt><b>index</b> Used for &lt;dl&gt; tags when writing index lists.</dt>
<dt><b>page-index</b> Used for &lt;dl&gt; tags when writing page index
lists.</dt>
<dt><b>Footnote</b> Used when writing Footnote numbers.</dt>
<dt><b>function-semantics</b> Used for &lt;dl&gt; tags when writing
function semantic lists.</dt>
</dl>
<h2><a name="templates" id="templates"></a>Templates</h2>
<p>Instead of hand coding every HTML page, HTML "templates" can be used
instead. The list below provides links to templates that may be used when
writing documentation for a contribution to Boost. Links provided in these
templates assume the files will reside in the "traditional" directory
hierarchy of <i>boost/libs/library/doc</i>. They may need correcting if the
file will reside in some other location.</p>
<p><b>Note:</b> Since these "templates" are just HTML pages simply clicking
on the links below will load the template in your browser. You will need to
use a browser specific method to download the files instead of loading them
into the browser (for instance, on most Windows browsers you can right
click on the link and select the appropriate command from the context
sensitive menu).</p>
<ul>
<li><a name="index-template" id="index-template"></a><a href=
"template/index.html">Index Page Template</a></li>
<li><a name="overview-template" id="overview-template"></a><a href=
"template/overview.html">Overview Page Template</a></li>
<li><a name="definitions-template" id="definitions-template"></a><a href=
"template/definitions.html">Definitions Page Template</a></li>
<li><a name="rationale-template" id="rationale-template"></a><a href=
"template/rationale.html">Rationale Page Template</a></li>
<li><a name="configuration-template" id=
"configuration-template"></a><a href=
"template/configuration.html">Configuration Page Template</a></li>
<li><a name="faq-template" id="faq-template"></a><a href=
"template/faq.html">FAQ (Frequently Asked Questions) Page
Template</a></li>
<li><a name="bibliography-template" id=
"bibliography-template"></a><a href=
"template/bibliography.html">Bibliography Page Template</a></li>
<li><a name="acknowledgements-template" id=
"acknowledgements-template"></a><a href=
"template/acknowledgments.html">Acknowledgments Page Template</a></li>
<li><a name="header-template" id="header-template"></a><a href=
"template/header.html">Header Page Template</a></li>
</ul>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2001 <a href=
"mailto:williamkempf@hotmail.com">William E. Kempf</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

57
writingdoc/index.html
View File

@ -1,57 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<link rel="stylesheet" type="text/css" href="../../boost.css">
<title>Writing Documentation for Boost</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">Writing Documentation for Boost</h1>
<h2 align="center">Index</h2>
</td>
</tr>
</table>
<hr>
<h2>Contents</h2>
<dl class="index">
<dt><a href="introduction.html">Introduction</a></dt>
<dt><a href="structure.html">Documentation Structure</a></dt>
<dt><a href="design.html">HTML Design</a></dt>
</dl>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2001 <a href=
"mailto:williamkempf@hotmail.com">William E. Kempf</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

68
writingdoc/introduction.html
View File

@ -1,68 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<link rel="stylesheet" type="text/css" href="../../boost.css">
<title>Writing Documentation for Boost - Introduction</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.html"><img height="86" width="277" alt="C++ Boost"
src="../../boost.png" border="0"></a></h3>
</td>
<td valign="top">
<h1 align="center">Writing Documentation for Boost</h1>
<h2 align="center">Introduction</h2>
</td>
</tr>
</table>
<hr>
<p>Boost does not have any requirements on how you write your
documentation. If you are submitting a library that already has written
documentation in HTML format, there is no reason to change it to follow any
of the guidelines presented here. However, if you have documentation that's
not in HTML format and can't be easily converted to HTML, or if you're
starting on a library from scratch or have a library with no documentation
then these guidelines can make writing the documentation much easier.</p>
<p>The section on <a href="structure.html">Documentation Structure</a>
describes how to go about structuring the documentation's content. This
section may be helpful even for libraries that already have documentation.
If there's a desire to present the library for possible inclusion by the
C++ Standards Committee then there may be a need to restructure the
documentation's content in order to insure the content meets explicit
requirements for library components (Section 17.3).</p>
<p>The section on <a href="design.html">HTML Design</a> gives general rules
to follow when writing HTML documentation in order to give a professional
and consistent look. This section also contains some template files that
can be used to rapidly create documentation pages.</p>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2001 <a href=
"mailto:williamkempf@hotmail.com">William E. Kempf</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

433
writingdoc/structure.html
View File

@ -1,433 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<link rel="stylesheet" type="text/css" href="../../boost.css">
<title>Writing Documentation for Boost - Documentation Structure</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.html"><img height="86" width="277" alt="C++ Boost"
src="../../boost.png" border="0"></a></h3>
</td>
<td valign="top">
<h1 align="center">Writing Documentation for Boost</h1>
<h2 align="center">Documentation Structure</h2>
</td>
</tr>
</table>
<hr>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#standards-conforming">Standards Conforming
Documentation</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#elements">Document elements</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#summary">Summary</a></dt>
<dt><a href="#requirements">Requirements</a></dt>
<dt><a href="#detailed-specs">Detailed specifications</a></dt>
<dt><a href="#ref-cpp">References to the Standard C++
library</a></dt>
<dt><a href="#ref-c">References to the Standard C
library</a></dt>
</dl>
</dd>
<dt><a href="#other">Other conventions</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#type-descs">Type descriptions</a></dt>
</dl>
</dd>
</dl>
</dd>
<dt><a href="#more">More Information</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#function-semantic-explanations">Function semantic
element explanations</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#requires">Requires</a></dt>
<dt><a href="#effects">Effects</a></dt>
<dt><a href="#postconditions">Postconditions</a></dt>
<dt><a href="#returns">Returns</a></dt>
<dt><a href="#throws">Throws</a></dt>
<dt><a href="#complexity">Complexity</a></dt>
<dt><a href="#rationale">Rationale</a></dt>
</dl>
</dd>
</dl>
</dd>
<dt><a href="#footnotes">Footnotes</a></dt>
</dl>
<h2><a name="introduction" id="introduction">Introduction</a></h2>
<p>Boost itself does not require any specific documentation structure. The
C++ Standard, however, has very explicit requirements for the description
of library components (Section 17.3). So for Boost libraries likely to be
proposed for inclusion in the standard, it is highly desirable to structure
documentation in a way that meets the requirements of the the standard.
Doing so eliminates the need to rewrite the documentation for
standardization.</p>
<p>Library developers should remember that for a library to be accepted as
part of the C++ Standard Library, the proposal must include full wording.
The committee will not do that work for you.</p>
<p>Beyond that, the documentation structure required for the standard is an
effective way to communicate the technical specifications for a library.
Although terse, it is already familiar to many Boost users, and is far more
precise than most ad hoc documentation structures.</p>
<p>The following description is for the structure of documentation required
by the standard. Boost libraries should also provided additional
documentation, such as introductory, tutorial, example, and rationale
material.</p>
<h2><a name="standards-conforming" id="standards-conforming">Standards
Conforming</a> Documentation</h2>
<h3><a name="elements" id="elements">Document elements</a></h3>
<p>Each document contains the following elements, as applicable<a class=
"footnote" href="#footnote1">(1)</a>:</p>
<ul>
<li><a href="#summary">Summary</a></li>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#detailed-specs">Detailed specifications</a></li>
<li><a href="#ref-cpp">References to the Standard C++ library</a></li>
<li><a href="#ref-c">References to the Standard C library</a></li>
</ul>
<h4><a name="summary" id="summary">Summary</a></h4>
<p>The Summary provides a synopsis of the category, and introduces the
first-level subclauses. Each subclause also provides a summary, listing the
headers specified in the subclause and the library entities provided in
each header.</p>
<p>Paragraphs labeled "Note(s):" or "Example(s):" are informative, other
paragraphs are normative.</p>
<p>The summary and the detailed specifications are presented in the
order:</p>
<ul>
<li>Macros</li>
<li>Values</li>
<li>Types</li>
<li>Classes</li>
<li>Functions</li>
<li>Objects</li>
</ul>
<h4><a name="requirements" id="requirements">Requirements</a></h4>
<p>The library can be extended by a C++ program. Each clause, as
applicable, describes the requirements that such extensions must meet. Such
extensions are generally one of the following:</p>
<ul>
<li>Template arguments</li>
<li>Derived classes</li>
<li>Containers, iterators, and/or algorithms that meet an interface
convention</li>
</ul>
<p>Interface convention requirements are stated as generally as possible.
Instead of stating "<code>class X</code> has to define a member function
<code>operator++()</code>," the interface requires "for any object
<code>x</code> of <code>class X</code>, <code>++x</code> is defined." That
is, whether the operator is a member is unspecified.</p>
<p>Requirements are stated in terms of well-defined expressions, which
define valid terms of the types that satisfy the requirements. For every
set of requirements there is a table that specifies an initial set of the
valid expressions and their semantics. Any generic algorithm that uses the
requirements is described in terms of the valid expressions for its formal
type parameters.</p>
<p>Template argument requirements are sometimes referenced by name.</p>
<p>In some cases the semantic requirements are presented as C++ code. Such
code is intended as a specification of equivalance of a construct to
another construct, not necessarily as the way the construct must be
implemented.<a class="footnote" href="#footnote2">(2)</a></p>
<h4><a name="detailed-specs" id="detailed-specs">Detailed
specification</a></h4>
<p>The detailed specifications each contain the following elements:</p>
<ul>
<li>Name and brief description</li>
<li>Synopsis (class definition or function prototype, as
appropriate)</li>
<li>Restrictions on template arguments, if any</li>
<li>Description of class invariants</li>
<li>Description of function semantics</li>
</ul>
<p>Descriptions of class member functions follow the order (as
appropriate)<a class="footnote" href="#footnote3">(3)</a>:</p>
<ul>
<li>Constructor(s) and destructor</li>
<li>Copying and assignment functions</li>
<li>Comparison functions</li>
<li>Modifier functions</li>
<li>Observer functions</li>
<li>Operators and other non-member functions</li>
</ul>
<p>Descriptions of function semantics contain the following <a name=
"function-elements" id="function-elements">elements</a> (as
appropriate)<a class="footnote" href="#footnote4">(4):</a></p>
<dl class="function-semantics">
<dt><b><a href="#requires">Requires:</a></b> the preconditions for
calling the function</dt>
<dt><b><a href="#effects">Effects:</a></b> the actions performed by the
function</dt>
<dt><b><a href="#postconditions">Postconditions:</a></b> the observable
results established by the function</dt>
<dt><b><a href="#returns">Returns:</a></b> a description of the value(s)
returned by the function</dt>
<dt><b><a href="#throws">Throws:</a></b> any exceptions thrown by the
function, and the conditions that would cause the exception</dt>
<dt><b><a href="#complexity">Complexity:</a></b> the time and/or space
complexity of the function</dt>
<dt><b><a href="#rationale">Rationale:</a></b> the rationale for the
function's design or existence</dt>
</dl>
<p>Complexity requirements specified in the library clauses are upper
bounds, and implementations that provide better complexity guarantees
satisfy the requirements.</p>
<h4><a name="ref-cpp" id="ref-cpp">References to the C++ Standard
library</a></h4>
<h4><a name="ref-c" id="ref-c">References to the C Standard
library</a></h4>
<h3><a name="other" id="other">Other conventions</a></h3>
<p>These conventions are for describing implementation-defined types, and
member functions.</p>
<h4><a name="type-descs" id="type-descs">Type descriptions</a></h4>
<p>The Requirements subclauses may describe names that are used to specify
constraints on template arguments.</p>
<h2><a name="more" id="more">More Information</a></h2>
<h3><a name="function-semantic-explanations" id=
"function-semantic-explanations">Function semantic element
explanations</a></h3>
<p>The function semantic element description <a href=
"#function-elements">above</a> is taken directly from the C++ standard, and
is quite terse. Here is a more detailed explanation of each of the
elements.</p>
<p>Note the use of the <code>&lt;code&gt; ... &lt;/code&gt;</code> font tag
to distinguish actual C++ usage from English prose.</p>
<h4><a name="requires" id="requires">Requires</a></h4>
<p>Preconditions for calling the function, typically expressed as
predicates. The most common preconditions are requirements on the value of
arguments, often in the form of C++ expressions. For example,</p>
<pre>
<code>void limit( int * p, int min, int max );</code>
</pre>
<dl class="function-semantics">
<dt><b>Requires:</b> <code>p != 0 &amp;&amp; min &lt;= max</code></dt>
</dl>
<p>Requirements already enforced by the C++ language rules (such as the
type of arguments) are not repeated in Requires paragraphs.</p>
<h4><a name="effects" id="effects">Effects</a></h4>
<p>The actions performed by the function, described either in prose or in
C++. A description in prose is often less limiting on implementors, but is
often less precise than C++ code.</p>
<p>If an effect is specified in one of the other elements, particularly
<i>postconditions</i>, <i>returns</i>, or <i>throws</i>, it is not also
described in the <i>effects</i> paragraph. Having only a single description
ensures that there is one and only one specification, and thus eliminates
the risk of divergence.</p>
<h4><a name="postconditions" id="postconditions">Postconditions</a></h4>
<p>The observable results of the function, such as the value of variables.
Postconditions are often expressed as predicates that are true after the
function completes, in the form of C++ expressions. For example:</p>
<pre>
void make_zero_if_negative( int &amp; x );
</pre>
<dl class="function-semantics">
<dt><b>Postcondition:</b> <code>x &gt;= 0</code></dt>
</dl>
<h4><a name="returns" id="returns">Returns</a></h4>
<p>The value returned by the function, usually in the form of a C++
expression. For example:</p>
<pre>
int sum( int x, int y );
</pre>
<dl class="function-semantics">
<dt><b>Returns:</b> <code>x + y</code></dt>
</dl>
<p>Only specify the return value; the type is already dictated by C++
language rules.</p>
<h4><a name="throws" id="throws">Throws</a></h4>
<p>Specify both the type of exception thrown, and the condition that causes
the exception to be thrown. For example, the <code>std::basic_string</code>
class specifies:</p>
<pre>
void resize(size_type n, charT c);
</pre>
<dl class="function-semantics">
<dt><b>Throws:</b> <code>length_error</code> if <code>n &gt;
max_size()</code>.</dt>
</dl>
<h4><a name="complexity" id="complexity">Complexity</a></h4>
<p>Specifying the time and/or space complexity of a function is often not
desirable because it over-constrains implementors and is hard to specify
correctly. Complexity is thus often best left as a quality of
implementation issue.</p>
<p>A library component, however, can become effectively non-portable if
there is wide variation in performance between conforming implementations.
Containers are a prime example. In these cases it becomes worthwhile to
specify complexity.</p>
<p>Complexity is often specified in generalized <a href=
"http://hissa.nist.gov/dads/HTML/bigOnotation.html">"Big-O"
notation</a>.</p>
<h4><a name="rationale" id="rationale">Rationale</a></h4>
<p>Specifying the rationale for a function's design or existence can often
give users a lot of insight into why a library is designed the way it is.
More importantly, it can help prevent "fixing" something that wasn't really
broken as the library matures.</p>
<h2><a name="footnotes" id="footnotes">Footnotes</a></h2>
<dl>
<dt><a class="footnote" name="footnote1" id="footnote1">(1)</a> To save
space, items that do not apply to a clause are omitted. For example, if a
clause does not specify any requirements, there will be no "Requirements"
subclause.</dt>
<dt><a class="footnote" name="footnote2" id="footnote2">(2)</a> Although
in some cases the code is unambiguously the optimum implementation.</dt>
<dt><a class="footnote" name="footnote3" id="footnote3">(3)</a> To save
space, items that do not apply to a class are omitted. For example, if a
class does not specify any comparison functions, there will be no
"Comparison functions" subclause.</dt>
<dt><a class="footnote" name="footnote4" id="footnote4">(4)</a> To save
space, items that do not apply to a function are omitted. For example, if
a function does not specify any precondition, there will be no "Requires"
paragraph.</dt>
</dl>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2001 <a href=
"mailto:williamkempf@hotmail.com">William E. Kempf</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

48
writingdoc/template/acknowledgments.html
View File

@ -1,48 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<title>{{Library}} - Acknowledgments</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">{{Library}}</h1>
<h2 align="center">Acknowledgments</h2>
</td>
</tr>
</table>
<hr>
{{text}}
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2006 <a href=
"mailto:{{address}}">{{author}}</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

48
writingdoc/template/bibliography.html
View File

@ -1,48 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<title>{{Library}} - Bibliography</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">{{Library}}</h1>
<h2 align="center">Bibliography</h2>
</td>
</tr>
</table>
<hr>
{{bibliographical information}}
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2006 <a href=
"mailto:{{address}}">{{author}}</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

145
writingdoc/template/configuration.html
View File

@ -1,145 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<title>{{Library}} - Configuration</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">{{Library}}</h1>
<h2 align="center">Configuration</h2>
</td>
</tr>
</table>
<hr>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#app-defined">Application Defined Macros</a></dt>
<dt><a href="#lib-defined-public">Public Library Defined Macros</a></dt>
<dt><a href="#lib-defined-impl">Library Defined Implementation
Macros</a></dt>
</dl>
<h2><a name="introduction" id="introduction"></a>Introduction</h2>
<p>{{library}} uses several configuration macros in <a href=
"http://www.boost.org/libs/config/config.htm">&lt;boost/config.hpp&gt;</a>,
as well as configuration macros meant to be supplied by the application.
These macros are documented here.</p>
<h2><a name="app-defined" id="app-defined"></a>Application Defined
Macros</h2>
<p>These are the macros that may be defined by an application using
{{library}}.</p>
<table summary="application defined macros" cellspacing="10" width="100%">
<tr>
<td><b>Macro</b></td>
<td><b>Meaning</b></td>
</tr>
<tr>
<td>{{macro}}</td>
<td>{{meaning}}</td>
</tr>
<tr>
<td>{{macro}}</td>
<td>{{meaning}}</td>
</tr>
</table>
<h2><a name="lib-defined-public" id="lib-defined-public"></a>Public Library
Defined Macros</h2>
<p>These macros are defined by {{library}} but are expected to be used by
application code.</p>
<table summary="public library defined macros" cellspacing="10" width=
"100%">
<tr>
<td><b>Macro</b></td>
<td><b>Meaning</b></td>
</tr>
<tr>
<td>{{macro}}</td>
<td>{{meaning}}</td>
</tr>
<tr>
<td>{{macro}}</td>
<td>{{meaning}}</td>
</tr>
</table>
<h2><a name="lib-defined-impl" id="lib-defined-impl"></a>Library Defined
Implementation Macros</h2>
<p>These macros are defined by {{library}} and are implementation details
of interest only to implementers.</p>
<table summary="library defined implementation macros" cellspacing="10"
width="100%">
<tr>
<td><b>Macro</b></td>
<td><b>Meaning</b></td>
</tr>
<tr>
<td>{{macro}}</td>
<td>{{meaning}}</td>
</tr>
<tr>
<td>{{macro}}</td>
<td>{{meaning}}</td>
</tr>
</table>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2006 <a href=
"mailto:{{address}}">{{author}}</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

Some files were not shown because too many files have changed in this diff Show More