Boost provides free peer-reviewed portable C++
+ source libraries.
+
+
We emphasize libraries that work well with the C++
+ Standard Library. Boost libraries are intended to be
+ widely useful, and usable across a broad spectrum of
+ applications. The Boost license encourages
+ both commercial and non-commercial use.
+
+
We aim to establish "existing practice" and
+ provide reference implementations so that Boost
+ libraries are suitable for eventual standardization.
+ Ten Boost libraries are already included in the
+ C++
+ Standards Committee's Library Technical Report (
+
+ TR1) as a step toward becoming part of a future
+ C++ Standard. More Boost libraries are proposed for
+ the upcoming
+ TR2.
+
+
Getting
+ started:Boost works
+ on almost any modern operating system, including UNIX
+ and Windows variants. Follow the Getting Started Guide
+ to download and install Boost. Popular Linux and Unix
+ distributions such as Fedora, Debian, and NetBSD include pre-built
+ Boost packages. Boost may also already be available
+ on your organization's internal web
+ server.
+
+
Background:The Background Information
+ page has introductory material to help those
+ educating their organization about Boost.
+
+
+
+
+
+
+
Participation
+
+
+
+
+
Although Boost was begun by members of the C++
+ Standards Committee Library Working Group,
+ participation has expanded to include thousands of
+ programmers from the C++ community at large.
+
+
If you are interested in participating in Boost,
+ please join our main developers mailing
+ list. Discussions are highly technical, and list
+ members are encouraged to participate in formal
+ reviews of proposed libraries. There is also a
+ users mailing
+ list, and several project specific
+ lists.
+
+
Both the main Boost developers list and the users
+ list are also accessible as newsgroups.
+
+
+
+
+
+
+
Latest News
+
+
+
+
+
+
July 24, 2007 - Version 1.34.1
+
+
This is a bug fix release addressing many problems with the 1.34.0 release.
+ It is a recommended upgrade for all users of Boost 1.34.0. For a complete list of fixes see
+ Boost Trac.
+
+
Supported Compilers
+
+
New in this release is improved support for
+ the IBM XL C/C++ compiler.
+
+
Boost is tested on a wide range of compilers and
+ platforms. Since Boost libraries rely on modern C++
+ features not available in all compilers, not all
+ Boost libraries will work with every compiler.
+ The following compilers and platforms have been
+ extensively tested with Boost, although many other
+ compilers and platforms will work as well. For more
+ information, see the regression
+ test results.
Microsoft
+ Visual C++ 6.0 (sp5, with and without STLport),
+ 7.0, 7.1, 8.0. Note: Boost does not support the
+ non-standard "Safe" C++ Library shipping with
+ Visual C++ 8.0, which may result in many spurious
+ warnings from Boost headers and other
+ standards-conforming C++ code. To suppress these
+ warnings, define the macro
+ _SCL_SECURE_NO_DEPRECATE.
A great number of people contributed their time
+ and expertise to make this release possible. Special
+ thanks go to Kim Barrett consolidating Boost.Iostreams changes
+ from various branches and Rene Rivera for general build and installation
+ support.
See Compiler Status
+ page to find out what library works with which compiler.
+See Getting Started page to find out
+how to download, build, and install the libraries.
+
+
Documentation for some Boost libraries is available in other forms,
+ including DocBook, XSL Formatting Objects, and Unix man pages. This
+ documentation is available
+ on Sourceforge.
smart_ptr - Five smart
+ pointer class templates, from Greg Colvin, Beman Dawes,
+ Peter Dimov, and Darin Adler.
+
statechart - Arbitrarily
+ complex finite state machines can be implemented in easily readable and
+ maintainable C++ code, from Andreas Huber.
+
static_assert
+ - Static assertions (compile time assertions), from John
+ Maddock.
+
spirit - LL parser framework
+ represents parsers directly as EBNF grammars in inlined C++, from Joel de
+ Guzman and team.
+
string_algo -
+ String algorithms library, from Pavol Droba
+
test - Support for simple program testing,
+ full unit testing, and for program
+ execution monitoring, from Gennadiy Rozental.
+
thread - Portable C++
+ multi-threading, from William Kempf.
+
timer - Event timer,
+ progress timer, and progress display classes, from Beman
+ Dawes.
+
tokenizer - Break of a string or other
+ character sequence into a series of tokens, from John Bandela.
+
TR1 - An implementation of the Technical
+ Report on C++ Library Extensions, using other Boost libraries as a basis, from John Maddock.
+
tribool - 3-state boolean type library, from Doug Gregor.
+
tuple - Ease definition of functions returning multiple values, and more,
+ from Jaakko Järvi.
+
type_traits -
+ Templates for fundamental properties of types, from John
+ Maddock, Steve Cleary, et al.
+
typeof -
+ Typeof operator emulation, from Arkadiy Vertleyb and Peder Holt.
+
uBLAS - Basic linear algebra
+ for dense, packed and sparse matrices, from Joerg Walter and Mathias Koch.
+
utility - Class noncopyable
+ plus checked_delete(), checked_array_delete(), next(),
+ prior()
+ function templates, plus base-from-member idiom, from Dave Abrahams and others.
+
value_initialized - Wrapper for uniform-syntax value initialization,
+ from Fernando Cacciola, based on the original idea of David Abrahams.
+
variant - Safe, generic, stack-based discriminated union
+ container, from Eric Friedman and Itay Maman.
+
wave - Standards conformant
+ implementation of the mandated C99/C++ preprocessor functionality packed behind an easy to use iterator interface, from Hartmut Kaiser
+
xpressive - Regular expressions that can be written as strings or as expression templates,
+ and that can refer to each other and themselves recursively with the power of context-free grammars, from Eric Niebler.
format - Type-safe 'printf-like' format
+ operations, from Samuel Krempp.
+
iostreams - Framework for defining streams, stream buffers and i/o filters, from Jonathan Turkanis.
+
regex - Regular expression
+ library, from John Maddock
+
spirit - LL parser framework
+ represents parsers directly as EBNF grammars in inlined C++, from Joel de
+ Guzman and team.
+
string_algo -
+ String algorithms library, from Pavol Droba
+
tokenizer - Break of a string or other
+ character sequence into a series of tokens, from John Bandela
+
wave - Standards conformant implementation of the mandated C99/C++ preprocessor functionality packed behind an easy to use iterator interface, from Hartmut Kaiser.
+
xpressive - Regular expressions that can be written as strings or as expression templates,
+ and that can refer to each other and themselves recursively with the power of context-free grammars, from Eric Niebler.
pool - Memory pool management, from
+ Steve Cleary.
+
smart_ptr - Five smart
+ pointer class templates, from Greg Colvin, Beman Dawes,
+ Peter Dimov, and Darin Adler.
+
utility - Class noncopyable
+ plus checked_delete(), checked_array_delete(), next(),
+ prior()
+ function templates, plus base-from-member idiom, from Dave Abrahams and others.
filesystem - Portable paths,
+ iteration over directories, and other useful filesystem operations, from
+ Beman Dawes.
+
optional - Discriminated-union
+ wrapper for optional values, from Fernando Cacciola.
+
program_options - Access to configuration
+ data given on command line, in config files and other sources, from Vladimir Prus.
+
statechart - Arbitrarily
+ complex finite state machines can be implemented in easily readable and
+ maintainable C++ code, from Andreas Huber.
+
timer - Event timer,
+ progress timer, and progress display classes, from Beman
+ Dawes.
+
TR1 - An implementation of the Technical
+ Report on C++ Library Extensions, using other Boost libraries as a basis, from John Maddock.
+
tribool - 3-state boolean type library, from Doug Gregor.
+
typeof -
+ Typeof operator emulation, from Arkadiy Vertleyb and Peder Holt.
+
utility - Class noncopyable
+ plus checked_delete(), checked_array_delete(), next(),
+ prior()
+ function templates, plus base-from-member idiom, from Dave Abrahams and others.
+
value_initialized - Wrapper for uniform-syntax value initialization,
+ from Fernando Cacciola, based on the original idea of David Abrahams.
+ In a word, Productivity. 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.
+
+
+
+ Ten of the Boost libraries are included in the C++
+ Standard Library's TR1, and so are slated for later full
+ standardization. More Boost libraries are in the pipeline for TR2.
+ Using Boost libraries gives an organization a head-start in adopting new
+ technologies.
+
+
+ Many organization already use programs implemented with Boost, like Adobe
+ Acrobat
+ Reader 7.0.
+
+
+ Who else is using Boost?
+
+
+
+ See the Who's Using Boost
+ page 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.
+
+
+ What do others say about Boost?
+
+
+ "...one of the most highly regarded and expertly designed C++ library
+ projects in the world."
+
+ "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..."
+
+ For relatively straightforward support needs, users rely on the mailing lists. One of the advantages of Boost is
+ the responsiveness of other users and Boost developers.
+
+ Boost has its own license, developed with
+ help from the Harvard Law School. The Boost license polices 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.
+
+
+
+ What about other intellectual property issues?
+
+
+ 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.
+
+
+ Why would anyone give away valuable software for free?
+
+
+
+ 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.
+
+
+ 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.
+
+
+ Who pays Boost's expenses?
+
+
+ Boost doesn't really have any expenses! All the infrastructure is
+ contributed by supporters, such as the Open Systems Lab at Indiana University,
+
+ SourceForge, Boost Consulting, MetaCommunications, 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.
+
+ David Abrahams and Aleksey Gurtovoy, C++ Template Metaprogramming: Concepts,
+ Tools, and Techniques from Boost and Beyond. Addison-Wesley, November,
+ 2004. ISBN: 0-321-22725-5.
+ www.awprofessional.com/titles/0321227255/
+
+ Additional information and two sample chapters are available at:
+ boost-consulting.com/tmpbook/
+
David Brownell, C++ Techniques for
+ Tomorrow That Can be Implemented Today (a.k.a. Boosting your Code).
+ NWCPP, November 13, 2002. www.nwcpp.org/Meetings/2002/11.html
Andrei Alexandrescu, Generic<Programming>:
+ Efficient Generic Sorting and Searching in C++ (I): In Search of a Better
+ Search. C/C++ Users Journal, October, 2002.
+ www.cuj.com/documents/s=7978/cujcexp2010alexandr/
+ boost::type_traits
+
James Curran, Access Raw Data with
+ Performance Counters in Visual C++. DevX.com, October, 2002.
+ www.devx.com/cplus/article/7951
+ Devotes several paragraphs to boost::shared_ptr<>.
+
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.
+
+
+ If a publication is available both in print and online, cite it in the
+ appropriate print
+ section, with a hyperlink to the online version.
+
+ Bookmark the contents of [...] in the first column to make it easy to link to
+ the entry.
+
+ 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 a-z
+ appended.
+
+ Inside each section, entries are grouped by year and, within a year, alphabetically
+ sorted by author name.
+
+ In the text, spell out absolute URL's so that printed versions of this page
+ include the full URL.
+
+
+
diff --git a/more/blanket-permission.txt b/more/blanket-permission.txt
new file mode 100644
index 0000000000..018d5eaea8
--- /dev/null
+++ b/more/blanket-permission.txt
@@ -0,0 +1,101 @@
+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)
+
+--- end ---
+
diff --git a/more/boost-dark-trans.png b/more/boost-dark-trans.png
new file mode 100644
index 0000000000..1aa16e202f
Binary files /dev/null and b/more/boost-dark-trans.png differ
diff --git a/more/boost_1_33_0.jpg b/more/boost_1_33_0.jpg
new file mode 100644
index 0000000000..6f26ef38d3
Binary files /dev/null and b/more/boost_1_33_0.jpg differ
diff --git a/more/borland_cpp.html b/more/borland_cpp.html
new file mode 100644
index 0000000000..49781ed196
--- /dev/null
+++ b/more/borland_cpp.html
@@ -0,0 +1,394 @@
+
+
+
+
+
+
+
+ Portability Hints: Borland C++ 5.5.1
+
+
+
+
It is a general aim for boost libraries to be portable. 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.
+
+
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 http://www.borland.com/.
+
+
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.
+
+
Preprocessor symbol
+
+
The preprocessor symbol __BORLANDC__ 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.
+
+
+
+
Compiler
+
+
__BORLANDC__ value
+
+
+
+
Borland C++ Builder 4
+
+
0x0540
+
+
+
+
Borland C++ Builder 5
+
+
0x0550
+
+
+
+
Borland C++ 5.5
+
+
0x0550
+
+
+
+
Borland C++ 5.5.1
+
+
0x0551
+
+
+
+
Borland C++ Builder 6
+
+
0x0560
+
+
+
+
Core Language
+
+
[using-directive] Mixing using-declarations and
+ using-directives
+
+
Mixing using-directives (which refer to whole namespaces)
+ and namespace-level using-declarations (which refer to
+ individual identifiers within foreign namespaces) causes ambiguities where
+ there are none. The following code fragment illustrates this:
[using template] using-declarations for class
+ templates
+
+
Identifiers for class templates can be used as arguments to
+ using-declarations as any other identifier. However, the
+ following code fails to compile with Borland C++:
+
+template<class T>
+class X { };
+
+namespace N
+{
+ // "cannot use template 'X<T>' without specifying specialization parameters"
+ using ::X;
+};
+
+
+
[template const arg] Deduction of constant arguments to function
+ templates
+
+
Template function type deduction should omit top-level constness.
+ However, this code fragment instantiates "f<const int>(int)":
+
+template<class T>
+void f(T x)
+{
+ x = 1; // works
+ (void) &x;
+ T y = 17;
+ y = 20; // "Cannot modify a const object in function f<const int>(int)"
+ (void) &y;
+}
+
+int main()
+{
+ const int i = 17;
+ f(i);
+}
+
+
+
[function address] Resolving addresses of overloaded functions
+
+
Addresses of overloaded functions are not in all contexts properly
+ resolved (std:13.4 [over.over]); here is a small example:
+
+template<class Arg>
+void f( void(*g)(Arg) );
+
+void h(int);
+void h(double);
+
+template<class T>
+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<int>(h2); // this also works (std:13.4-1.3)
+
+ // "Cannot generate template specialization from h(int)",
+ // "Could not find a match for f<Arg>(void (*)(int))"
+ f<double>(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<void(*)(double)>(h)); // should work (std:13.4-1.6 with 5.2.9)
+}
+
+
+
Workaround: Always use C-style casts when determining
+ addresses of (potentially) overloaded functions.
+
+
[string conversion] Converting const char * to
+ std::string
+
+
Implicitly converting const char * parameters to
+ std::string arguments fails if template functions are
+ explicitly instantiated (it works in the usual cases, though):
+
+#include <string>
+
+template<class T>
+void f(const std::string & s)
+{}
+
+int main()
+{
+ f<double>("hello"); // "Could not find a match for f<T>(char *)"
+}
+
+
+
+
Workaround: 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 std::string or declare the
+ template function as taking a const char * parameter.
+
+
[template value defaults] Dependent default arguments for template
+ value parameters
+
+
Template value parameters which default to an expression dependent on
+ previous template parameters don't work:
+
+template<class T>
+struct A
+{
+ static const bool value = true;
+};
+
+// "Templates must be classes or functions", "Declaration syntax error"
+template<class T, bool v = A<T>::value>
+struct B {};
+
+int main()
+{
+ B<int> x;
+}
+
+
+
+
Workaround: If the relevant non-type template parameter
+ is an implementation detail, use inheritance and a fully qualified
+ identifier (for example, ::N::A<T>::value).
+
+
[function partial ordering] Partial ordering of function templates
+
+
Partial ordering of function templates, as described in std:14.5.5.2
+ [temp.func.order], does not work:
Workaround: Declare all such functions uniformly as
+ either taking a value or a reference parameter.
+
+
[instantiate memfun ptr] Instantiation with member function
+ pointer
+
+
When directly instantiating a template with some member function
+ pointer, which is itself dependent on some template parameter, the compiler
+ cannot cope:
+
+template<class U> class C { };
+template<class T>
+class A
+{
+ static const int v = C<void (T::*)()>::value;
+};
+
+
+
Workaround: Use an intermediate
+ typedef:
+
+template<class U> class C { };
+template<class T>
+class A
+{
+ typedef void (T::*my_type)();
+ static const int v = C<my_type>::value;
+};
+
+
+
(Extracted from e-mail exchange of David Abrahams, Fernando Cacciola,
+ and Peter Dimov; not actually tested.)
+
+
Library
+
+
[cmath.abs] Function double std::abs(double) missing
+
+
The function double std::abs(double) should be defined
+ (std:26.5-5 [lib.c.math]), but it is not:
Note that int std::abs(int) will be used without warning if
+ you write std::abs(5.1).
+
+
Similar remarks apply to seemingly all of the other standard math
+ functions, where Borland C++ fails to provide float and
+ long double overloads.
+
+
Workaround: Use std::fabs instead if type
+ genericity is not required.
+
+
Appendix: Additional issues with Borland C++ version 5.5
+
+
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.
+
+
[inline friend] Inline friend functions in template classes
+
+
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<int>. However, Borland C++ v5.5
+ expects the function f to be declared beforehand:
+
+namespace N {
+template<class T>
+class A
+{
+ // "f is not a member of 'N' in function main()"
+ friend bool f(T x, T y) { return x < y; }
+};
+}
+
+int main()
+{
+ N::A<int> a;
+}
+
+
+
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].
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 boost public
+ CVS repository.
+
+
+
If you are a Boost user, or a Boost developer that doesn't have a CVS
+ write access:
+
+
+
Submit a bug report to either
+ boost-users list,
+ boost mailing
+ list, or our bug
+ tracking facility; 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;
+
+
+
If you have a proposed patch to the code, post it along with your bug
+ report, preferably in the unified diffs format (cvs diff -du);
+ 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 intentional_bug.hpp:
+
+
+
Download the latest version of intentional_bug.hpp from CVS.
+
Make sure that the bug is still present in the code.
+
Copy the file intentional_bug.hpp to a file called intentional_bug.hpp.orig.
+
Apply your changes to intentional_bug.hpp.
+
Run "diff -du intentional_bug.hpp.orig intentional_bug.hpp > intentional_bug.hpp.patch" from the command prompt.
+
Submit the patch file together with an explanation of the bug
+and the proposed fix; and don't forget to include the word patch or bug
+in the subject if you're submitting to the boost mailing list.
+
+
+
+
+
+
+
+
+
If you are a Boost developer, and you have a CVS write access:
+
+
+
If the bug is trivial (e.g. misspelled name, missed typename,
+ 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
+ boost mailing
+ list (if the author is not very active on the list, you also might want
+ to consider cc'ing him as well);
+
+
+
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;
+
+
+
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.
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....
+
+
+
+
And then there were none...
+
+
+
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.
+
+
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 PROXY
+ pattern described in Design Patterns [Gamma, Helm, Johnson &
+ Vlissides, Addison-Wesley, ISBN 0-201-63361-2]. The
+ intent is given as
+
+
+
Provide a surrogate or placeholder for another object to control
+ access to it.
+
+
+
Coplien [Advanced C++ Programming Styles and Idioms,
+ Addison-Wesley, ISBN 0-201-56365-7] defines a set
+ of idioms related to this essential separation of a handle and a body
+ part. The Taligent Guide to Designing Programs [Addison-Wesley,
+ ISBN 0-201-40888-0] identifies a number of specific
+ categories for proxies (aka surrogates). Broadly speaking they fall into
+ two general categories:
+
+
+
Hidden: 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 COPY ON WRITE
+ pattern (a specialisation of LAZY EVALUATION) requires the use of a hidden reference counted
+ body.
+
+
Explicit: 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 SMART POINTER 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.
+
+
+
+
+
Attached vs detached
+
+
+
For reference counted smart pointers there are two places the count can
+ exist, resulting in two different patterns, both outlined in
+ Software Patterns [Coplien, SIGS, ISBN
+ 0-884842-50-X]:
+
+
+
COUNTED BODY or ATTACHED
+ COUNTED
+ HANDLE/BODY 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.
+
+
DETACHED COUNTED
+ HANDLE/BODY 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.
+
+
+
Even with this simple analysis, it seems that the DETACHED COUNTED HANDLE/BODY 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 - counted_ptr. [The Boost name is shared_ptr rather than counted_ptr.]
+
+
A common implementation of COUNTED BODY 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 COUNTED BODY
+ approach is perhaps only of use in specialised situations.
+
+
+
+
A requirements based approach
+
+
+
It is the question of openness that convinced me to revisit the
+ problems with the COUNTED BODY 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?
+
+
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.
+
+
This requirements based approach can be applied to reference counting.
+ The operations we need for a type to be Countable are loosely:
+
+
+
An acquire operation that registers
+ interest in a Countable object.
+
+
A release operation unregisters
+ interest in a Countable object.
+
+
An acquired query that returns
+ whether or not a Countable object is currently acquired.
+
+
A dispose operation that is
+ responsible for disposing of an object that is no longer acquired.
+
+
+
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.
+
+
For a type to be Countable it must satisfy the following
+ requirements, where ptr is a non-null
+ pointer to a single object (i.e. not an array) of the type, and
+ #function indicates number of calls
+ to function(ptr):
Note that the two arguments to dispose
+ 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.
+
+
In addition the following requirements must also be satisfied, where
+ null is a null pointer to the
+ Countable type:
+
+
+
+
+
Expression
+
+
Return type
+
+
Semantics and notes
+
+
+
+
acquire(null)
+
+
no requirement
+
+
action: none
+
+
+
+
release(null)
+
+
no requirement
+
+
action: none
+
+
+
+
acquired(null)
+
+
convertible to bool
+
+
return: false
+
+
+
+
dispose(null, null)
+
+
no requirement
+
+
action: none
+
+
+
+
+
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.
+
+
+
+
Getting smart
+
+
+
Given the Countable requirements for a type, it is possible to
+ define a generic smart pointer type that uses them for reference counting:
The interface to this class has been kept intentionally simple, e.g.
+ member templates and throw specs have been
+ omitted, for exposition. The majority of the functions are quite simple in
+ implementation, relying very much on the assign member as a keystone function:
Conformance to the requirements means that a type can be used with
+ countable_ptr. Here is an implementation
+ mix-in class (mix-imp) that confers countability on its derived
+ classes through member functions. This class can be used as a class
+ adaptor:
Notice that the manipulation functions are const and that the count
+ member itself is mutable. This is because
+ countability is not a part of an object's abstract state: memory
+ management does not depend on the const-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.
+
+
So how do we make this class Countable? A simple set of
+ forwarding functions does the job:
Any type that now derives from countability may now be used with countable_ptr:
+
+
+
+class example : public countability
+{
+ ...
+};
+
+void simple()
+{
+ countable_ptr<example> ptr(new example);
+ countable_ptr<example> qtr(ptr);
+ ptr.clear(); // set ptr to point to null
+} // allocated object deleted when qtr destructs
+
+
+
+
+
+
+
Runtime mixin
+
+
+
The challenge is to apply COUNTED BODY 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 Countability on any object, i.e. anything pointed to
+ by a void *! It goes without saying that
+ void is perhaps the least committed of any type.
+
+
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:
We have overloaded operator new with a
+ dummy argument to distinguish it from the regular global operator new. This is comparable to the use of the
+ std::nothrow_t type and std::nothrow object in the standard library. The
+ placement operator delete 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.
+
+
The result of a new expression using
+ countable 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:
An important constraint to observe here is the alignment of
+ count 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 union to coalign count
+ 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 new or
+ malloc.
+
+
Again, note that the count is not considered to be a part of the
+ logical state of the object, and hence the conversion from
+ const to non-const - count is in
+ effect a mutable type.
+
+
The allocator functions themselves are fairly straightforward:
+
+
+
+void *operator new(size_t size, const countable_new &)
+{
+ count *allocated = static_cast<count *>(::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 &)
+{
+ ::operator delete(header(ptr));
+}
+
+
+
+
+
Given a correctly allocated header, we now need the Countable
+ functions to operate on const void * to
+ complete the picture:
The most complex of these is the dispose 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 const void *
+ distinguishes it from the earlier dispose shown for const countability *.
+
+
+
+
Getting smarter
+
+
+
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
+ countable_ptr we defined earlier? Good
+ news: nothing!
+
+
+
+class example
+{
+ ...
+};
+
+void simple()
+{
+ countable_ptr<example> ptr(new(countable) example);
+ countable_ptr<example> qtr(ptr);
+ ptr.clear(); // set ptr to point to null
+} // allocated object deleted when qtr destructs
+
+
+
+
+
The new(countable) 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
+ delete on an object allocated with
+ new(countable), results in undefined
+ behaviour. This is similar to what happens when you mix new[] with delete or
+ malloc with delete. The whole point of Countable conformance
+ is that Countable objects are used with countable_ptr, and this ensures the correct use.
+
+
However, accidents will happen, and inevitably you may forget to
+ allocate using new(countable) and instead
+ use new. This error and others can be
+ detected in most cases by extending the code shown here to add a check
+ member to the count, 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.
+
+
+
+
Conclusion
+
+
+
There are two key concepts that this article has introduced:
+
+
+
The use of a generic requirements based approach to simplify and
+ adapt the use of the COUNTED BODY pattern.
+
+
The ability, through control of allocation, to dynamically and
+ non-intrusively add capabilities to fixed types using the RUNTIME MIXIN pattern.
+
+
+
The application of the two together gives rise to a new variant of the
+ essential COUNTED BODY
+ pattern, UNINTRUSIVE COUNTED BODY. You can take this theme
+ even further and contrive a simple garbage collection system for C++.
+
+
The complete code for countable_ptr,
+ countability, and the countable new is also available.
+
+
+
+
+ First published inOverload25,
+ April 1998, ISSN 1354-3172
+
Who can attend C++ Committee meetings? Members of
+J16 (the INCITS/ANSI committee) or of a WG21 (ISO) member country committee
+("national body" in
+ISO-speak).
+INCITS has broadened J16 membership requirements so anyone can
+join, regardless of nationality or employer.
+
In addition, a small number of "technical experts" who are not committee
+members can also attend meetings. The "technical expert" umbrella is broad enough to cover
+the
+Boost members who attend meetings.
+
When and where is the next meeting? 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
+list of meeting locations and
+dates. Detailed information about a particular meeting, including hotel
+information, is usually provided in a paper appearing in one of
+mailings for the prior meeting. If there isn't a link to
+it on the
+Meetings web page, you will have to go to
+the committee's
+Papers page and search a bit.
+
Is there a fee for attending meetings? 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.
+
What is the schedule? 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.)
+
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 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.
+
Sometimes there are evening technical sessions; the details aren't
+usually available until the Monday morning meeting. There may be a
+reception one evening, and, yes, significant others are
+invited. Again, details usually become available Monday morning.
+
What actually happens at the meetings? 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.
+
The working groups are where most technical activities take place. 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.
+
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.
+
Lunch break is an hour and a half. 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.
+
Do I have to stay at the main hotel? 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.
+
What do people wear at meetings? Programmer casual. No neckties
+to be seen.
+
What should I bring to a meeting? 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.
+
What should I do to prepare for a meeting? 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.
+
What is a "Paper"? 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.
+Papers are available
+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: "See the pre-Redmond mailing."
+
What is a "Mailing"? A mailing is the
+set of papers prepared four to six times a year before and after each meeting,
+or between meetings. It
+is physically just a
+.zip or .gz
+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.
+
What is a "Reflector"? The committee's mailing lists are
+called "reflectors". There are a number of them; "all", "core", "lib", and "ext"
+are the main ones. As a courtesy, Boost technical experts can be added to
+committee reflectors at the request of a committee member.
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.
+
+
Boost CVS access via command line or graphical clients
For those
+ who have CVS clients installed, the libraries are also available from the
+ public Boost CVS
+ repository. 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.
+
+
See the much improved CVS documentation (Section
+ F) from SourceForge, which includes links to the home pages for various GUI
+ and command line clients.
+
+
The general procedure for command-line clients is something like
+ this:
+
+
+ cvs -d:pserver:anonymous@boost.cvs.sourceforge.net:/cvsroot/boost
+ login
+ [Hit <return> when it asks for a password]
+ cvs -z3 -d:pserver:anonymous@boost.cvs.sourceforge.net:/cvsroot/boost
+ checkout boost
+ cvs -d:pserver:anonymous@boost.cvs.sourceforge.net:/cvsroot/boost
+ logout
+
Read the manual for your CVS client for further information.
+
+
This access is read-only; if you are a library author and wish to have
+ CVS write access, please contact one of the moderators.
For access to the CVS archive from any modern web
+ browser, you can also use the web
+ browser interface. Try one of the color diffs to see how a
+ file has changed over time. Note: this interface is only suitable
+ for viewing individual files and their revision histories.
+
+
Some of the Boost documentation is generated from BoostBook XML 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
+ Nightly Generated Documentation 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.
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.
Queries to determine interest in a possible library submission.
+
+
Technical discussions about a proposed or existing library, including
+ bug reports and requests for help.
+
+
Formal Reviews of proposed libraries.
+
+
Reports of user experiences with Boost libraries.
+
+
Boost administration or policies.
+
+
Compiler specific workarounds as applied to Boost libraries.
+
+
+
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.
+
+
Unacceptable Topics
+
+
+
Advertisements for commercial products.
+
+
Requests for help getting non-boost code to compile with your
+ compiler. Try the comp.lang.c++.moderated newsgroup instead.
+
+
Requests for help interpreting the C++ standard. Try the comp.std.c++
+ newsgroup instead.
+
+
Job offers.
+
+
Requests for solutions to homework assignments.
+
+
+
Effective Posting
+
+
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.
+
+
Well-Crafted Posting is Worth the Effort
+
+
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.
+
+
Put the Library Name in the Subject Line
+
+
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.
+
+
+ Subject: [Regex] Why doesn't this pattern match?
+
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.
+
+
+
+
Don't Use Tabs
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.
+
+
+
+
Limit Line Length
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.
+
+
+
+
Don't Overquote
Please prune extraneous quoted text 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.
+
+
Use a Readable Quotation Style
+
+
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:
+
+
+
+Person-you're-replying-to wrote:
+
+> Some part of a paragraph that you wish to reply to goes
+> here; there may be several lines.
+
+Your response to that part of the message goes here. There may,
+of course, be several lines.
+
+> The second part of the paragraph that is relevant to your
+> reply goes here; agiain there may be several lines.
+
+Your response to the second part of the message goes here.
+...
+
+
+
For more information about effective use of quotation in
+ posts, see this
+ helpful guide.
+
+
Keep the Formatting of Quotations Consistent
+
+
Some email and news clients use poor word wrapping algorithms that leave
+ successive lines from the same quotation with differing numbers of leading
+ ">" characters. Microsoft Outlook and Outlook
+ Express, 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 your posting; whether you get your point across depends on its
+ readability.
+
+
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: Outlook
+ Quotefix for Outlook Users and OE QuoteFix for
+ users of Outlook Express.
+
+
Summarizing and Referring to Earlier Messages
+
+
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).
+
+
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 message archives. To help to keep those
+ URLs short, you can use tinyurl.com.
+ Citing the relevant portion of a message you link to is often helpful (if
+ the citation is small).
+
+
Maintain the Integrity of Discussion Threads
+
+
When starting a new topic, always send a fresh message, 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.
+
+
By the same token, When replying to an existing message, use your
+ mailer's "Reply" function, so that the reply shows up as part of the
+ same discussion thread.
+
+
Do not reply to digests 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 GMane web
+ interface.
+
+
Keep The Size of Your Posting Manageable
+
+
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.
+
+
Prohibited Behavior
+
+
Prohibited behavior will not be tolerated. The moderators will ban
+ postings by abusers.
+
+
Flame wars
+
+
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.
+
+
Third-party attacks
+
+
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.
+
+
Does this mean that we ban the occasional complaint or wry remark about
+ a troublesome compiler? No, but be wary of overdoing it.
+
+
Off-topic posts
+
+
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.
+
+
Culture
+
+
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.
+
+
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.
+
+
Guidelines for Effective Discussions
+
+
Apply social engineering to prevent heated technical discussion from
+ degenerating into a shouting match, and to actively encourage the
+ cooperation upon which Boost depends.
+
+
+
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." 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.
+
+
If most of the discussion has been code-free generalities, posting a
+ bit of sample code can focus people on the practical issues.
+
+
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.
+
+
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."
+
+
+
Avoid Parkinson's Bicycle Shed. 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. 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.
+
+
Library Names
+
+
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.Name", or
+ in a long form as "the Boost Name library." For example:
+
+
+ Boost.Python serves a very different purpose from the Boost
+ Graph library.
+
Note that the word "library" is not part of the name, and as
+ such isn't capitalized.
+
+
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:
+
+
+
the proposed Boost Name library
+
+
the Boost.Name candidate
+
+
the Name library (probably the best choice where
+ applicable)
+
+
+
Note that this policy only applies to discussions, not to the
+ documentation, directory structure, or even identifiers in the code of
+ potential Boost libraries.
The simple answer is: ``whenever the semantic and performance
+ characteristics of exceptions are appropriate.''
+
+
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.
+
+
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 handle 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 be the exception, not the rule.
+
+
How should I design my exception classes?
+
+
+
Derive your exception class
+ from std::exception. Except in *very* rare
+ circumstances where you can't afford the cost of a virtual
+ table,
+ std::exception makes a reasonable exception base class,
+ and when used universally, allows programmers to catch "everything"
+ without resorting to catch(...). For more about
+ catch(...), see below.
+
+
Use virtual inheritance. 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:
+
+
+
+The program above prints "whoops" because the
+C++ runtime can't resolve which exception instance to
+match in the first catch clause.
+
+
+
+
+ Don't embed a std::string object 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 throw-expression that includes construction such as:
+
+
+
+throw some_exception();
+
+
+
+
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.
+
+
+
Format the what() message on demand, 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
+ what() function with a catch(...) block so
+ that you have a fallback in case the formatting code throws
+
+
Don't worry too much about the what()
+ message. 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 user-comprehensible error message at the point an
+ exception is thrown. Certainly, internationalization is beyond the
+ scope of the exception class author. Peter Dimov makes an excellent argument
+ that the proper use of a what() string is to serve as a
+ key into a table of error message formatters. Now if only we could get
+ standardized what() strings for exceptions thrown by the
+ standard library...
+
+
Expose relevant information about the cause of the error in
+ your exception class' public interface. A fixation on the
+ what() 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 as numbers 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
+ what() string, you will make life very difficult for
+ programmers who need to do something more (e.g. subtraction) with them
+ than dumb output.
+
+
Make your exception class immune to double-destruction 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.
+
+
+
What About Programmer Errors?
+
+
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 assert() or
+ something like it.
+
+
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.
+
+
Note for Windows developers: unfortunately, the native
+ exception-handling used by most Windows compilers actually throws an
+ exception when you use assert(). 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 catch(...) will catch these not-really-C++
+ exceptions. Fortunately, there is a simple but little-known workaround,
+ which is to use the following incantation:
+ 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.
+
+
How should I handle exceptions?
+
+
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.
+
+
Avoid catch(...) when possible
+ 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
+ _set_se_translator hack described above. The result is that
+ catch(...) 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.
+
+
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 std::exception and
+ everyone substituted
+ catch(std::exception&) for catch(...), the
+ world would be a better place.
+
+
Sometimes, catch(...), 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
+ must stop unwinding it's probably still your best bet. One obvious
+ place where this occurs is at language boundaries.
What do the Boost version numbers mean? 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.
+
+Is there any assurance libraries actually work as claimed? 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.
+See the Status page for an
+indication of how well a library works on specific platforms.
+
+
+How can the Boost libraries be used successfully for important projects?
+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.
Are commercial libraries requiring a fee acceptable? 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.
+
+
Are shareware libraries acceptable? No. Only free libraries
+will be accepted.
+
+
Are open source license libraries acceptable? 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. 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 License requirements.
+
+This is subject to review for a particularly important piece of software, or as the
+industry changes.
+
+
Must full source code be provided? Yes, these are source code libraries.
+
+
What about documentation? 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. HTML is the preferred form.
+
+
Are platform specific libraries acceptable? 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.
+
+
Must a library do useful work? No. A library meant as a teaching example or
+demonstration might not actually do any work.
+
+
Can an existing library be accepted by Boost? Yes, although it would
+have to be "Boostified" to meet the requirements. The Boost
+Graph and Regex libraries are examples of libraries which began life elsewhere.
+
+
Who owns the libraries? 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
+License requirements.. It is up to
+potential users to decide if the terms acceptable, and not to use
+libraries with unacceptable copyrights or licenses.
+
+
Is there a formal relationship between Boost.org and the C++ Standards Committee?
+ 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.
+
+
Will the Boost.org libraries become part of the next C++ Standard? Some
+might, someday, but that is up to the standards committee. Committee
+members who also participate in Boost will definitely be proposing at least some
+Boost libraries for standardization.
+
+
Libraries which are "existing practice" 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.
+
+
Where does the name "Boost" come from? 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
+"Boost" 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)
+
+
Is the web site a commercial business? 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.
+
+
Is there any charge for submitting libraries or reviews to Boost.org? No. Unlike
+the standards committees, you don't have to pay to volunteer!
+
+
Will the site include material beyond libraries? 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.
+
+
Why isn't there a separate boost mailing list for my favorite
+library? 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".
+
+
How can I cope with the large volume of boost mailing list messages?
+One approach is to use the "digest" 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. The "no
+mail" option turns off list email entirely.
+
+
Another approach is to follow the list traffic via an NTTP newsgroup reader.
+See Mailing List newsgroup
+information.
+
+
Why do Boost headers have a .hpp suffix rather than .h or none at all?
+File extensions communicate the "type" 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)
+
+
What should I do if I spot a bug in the Boost code or documentation?
+See the suggestions on the Bugs page.
In their seminal book, Generative Programming, Czarnecki and Eisenecker (C&E))
+describe how to build feature models [C&E 4.4] consisting of a feature
+diagram plus semantic, rationale, and other attributes. Feature models are
+then used to drive design cycles which eventually lead to manual or automatic
+assembly of configurations.
+
Feature models provide a language to describe the library variability that is
+often such an issue in boost.org discussions. The Whorf hypothesis that
+"Language shapes the way we think, and determines what we can think
+about" seems to apply. 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.
+
The graphical feature diagrams presented by C&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. A feature model can also take advantage of the hyperlinks
+inherent in HTML.
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.
details ::= "(" feature-list ")" // required features
+ | "[" feature-list "]" // optional features
+
feature-list ::= element { "|" element } // one only
+ | element { "+" element } // one or more
+ | element { "," element } // all
+ // [a+b] equivalent to [a,b]
+
element ::= feature
+ | details
+
concept-name ::= name
+
feature-name ::= name
+
+
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.
+
At least one instance of each name should be hyperlinked to the corresponding
+Feature Description.
+
While the grammar is intended for written communication between people, it
+may also be trivially machine parsed for use by automatic tools.
+
+
Descriptive information is associated with each concept or feature. According
+to [C&E 4.4.2] this includes:
+
+
Semantic descriptions.
+
Rationale.
+
Stakeholders and client programs.
+
Exemplar systems.
+
Constraints and default dependency rules.
+
Availability sites, binding sites, and binding mode.
+
Open/Closed attribute.
+
+
What is a Feature?
+
A feature [C&E 4.9.1] is "anything users or client programs might
+want to control about a concept. Thus, during feature modeling, we
+document no only functional features ... but also implementation features, ...,
+various optimizations, alternative implementation techniques, and so on."
organization [ ordered + indexed ] // zero or more (4 configurations)
+
indexed [ hash-function ] // zero or one (2 configurations)
+
performance ( fast | small | balanced ) // exactly one (3 configurations)
+
interface ( STL-style + cursor-style ) // one or more (3 configurations)
+
+
There should be feature descriptions for some-container, organization,
+ordered, indexed, hash-function, performance, fast, small, balanced, interface,
+STL-style, and cursor-style.
+
The number of possible configurations is (2 + 2*2) * 3 * 3 = 54,
+assuming no constraints.
+
There are equivalent representations. For example:
Proposed libraries are accepted into Boost only after undergoing a
+ formal review, where Boost mailing list members comment on their evaluation
+ of the library.
+
+
The final "accept" or "reject" decision is made by the Review Manager, based on the review comments received
+ from boost mailing list members.
+
+
Boost mailing list members are encouraged to submit Formal Review
+ comments:
+
+
+
+
Publicly on the mailing list.
+
+
Privately to the Review Manager.
+
+
+
+
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.
Your comments may be brief or lengthy, but basically the Review Manager
+ needs your evaluation of the library. If you identify problems along
+ the way, please note if they are minor, serious, or showstoppers.
+
+
Here are some questions you might want to answer in your review:
+
+
+
What is your evaluation of the design?
+
+
What is your evaluation of the implementation?
+
+
What is your evaluation of the documentation?
+
+
What is your evaluation of the potential usefulness of the
+ library?
+
+
Did you try to use the library? With what compiler? Did
+ you have any problems?
+
+
How much effort did you put into your evaluation? A glance? A quick
+ reading? In-depth study?
+
+
Are you knowledgeable about the problem domain?
+
+
+
And finally, every review should answer this question:
+
+
+
Do you think the library should be accepted as a Boost library?
+ Be sure to say this explicitly so that your other comments don't obscure
+ your overall opinion.
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. 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.
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.
+
+
The Review Manager:
+
+
+
Checks the submission to make sure it really is complete enough to
+ warrant formal review. See the Boost
+ Library Requirements and Guidelines. If necessary, work with
+ the submitter to verify the code compiles and runs correctly on several
+ compilers and platforms.
+
+
Finalizes the schedule with the Review Wizard
+ and the submitter .
+
+
Posts a notice of the review schedule on the regular boost mailing list, the
+ boost-users
+ mailing list, and the boost-announce mailing
+ list.
+
+
+
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.
+
+
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.
+
+
+
+
Inspects the Boost library
+ catalogue 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.
+
+
Urges people to do reviews if they aren't forthcoming.
+
+
Follows review discussions regarding the library, moderating or
+ answering questions as needed.
+
+
Asks the review wizard for permission to extend
+ the review schedule if it appears that too few reviews will be submitted
+ during the review period.
+
+
Decides if there is consensus to accept the library, and if there are
+ any conditions attached.
See Submission Process for a
+ description of the steps a library developer goes through to get a library
+ accepted by Boost.
+
+
A proposed library should remain stable during the review period; it
+ will just confuse and irritate reviewers if there are numerous
+ changes. It is, however, useful to upload fixes for serious bugs
+ right away, particularly those which prevent reviewers from fully
+ evaluating the library. Post a notice of such fixes on the mailing
+ list.
+
+
Library improvements suggested by reviewers should normally be held
+ until after the completion of review period. If the suggested changes
+ might affect reviewer's judgments, post a notice of the pending change
+ on the mailing list.
The Review Wizard coordinates the formal review schedule:
+
+
+
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.
+
+
When a formal review is requested for a library:
+
+
+
+
+
Assign a review manager and suggests a schedule, after checking
+ (via private email) availability of the volunteers at the top of
+ review manager queue.
+
+
Finalize the schedule, once the review manager verifies the
+ library is actually ready for review.
+
+
Resolve schedule slips or other issues with review managers and
+ submitters.
+
+
+
+
Maintains a schedule of both past and pending reviews, in the form of
+ the Review Schedule web
+ page.
+
+
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 ...?"
+
+
Monitors the general review process, and makes minor adjustments as
+ needed, or queries the list about possible major adjustments.
+
The role of Boost Review Wizard is currently played by Tom Brinkman and Ronald Garcia (garcia at
+ cs dot indiana dot edu).
+
+
The technique must be already in use in Boost libraries and the new
+ component provides a common implementation.
+
+
A full Boost-conformant implementation is available in the
+ sandbox.
+
+
The Review Wizard determines that the proposal qualifies for fast
+ track review.
+
+
+
Procedure:
+
+
+
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.
+
+
After the review period ends, the submitter will post a review
+ summary containing proposed changes to the reviewed implementation.
+
+
The Review Wizard will accept or reject the proposed library and
+ proposed changes.
+
+
After applying the proposed changes, the component is checked into
+ CVS like any other library.
+
Reviews are usually scheduled on a first-come-first-served basis, and
+normally last ten days. See Formal
+Review Process for more information.
+
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.
We try to rotate the task of Review Manager between many experienced Boost
+members, both to ensure fairness, and to spread the workload. If you would
+like to volunteer to become a review manager, please contact
+Tom Brinkman (Review Wizard).
+
+
Revised
+15 Apr 2005
+
+
Copyright Beman Dawes, Tom Brinkman, Jeff Garland 2001 - 2005
Abstract. 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.
+
+
Keywords: exception-safety, exceptions, STL, C++
+
+
1 What is exception-safety?
+
+
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.
+
+
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.
+
+
In a generic component, we usually have an additional expectation of
+ exception-neutrality, which means that exceptions thrown by a
+ component's type parameters should be propagated, unchanged, to the
+ component's caller.
+
+
2 Myths and Superstitions
+
+
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.
+
+
It's almost as though exceptions are viewed as a mysterious
+ attack 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.
+
+
``Interactions between templates and exceptions are not
+ well-understood.'' 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.
+
+
``It is well known to be impossible to write an exception-safe
+ generic container.'' This claim is often heard with reference to
+ an article by Tom Cargill [4]
+ 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.1
+ 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.
+
+
``Dealing with exceptions will slow code down, and templates are
+ used specifically to get the best possible performance.'' 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 [7].
+ 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.
+
+
``Exceptions make it more difficult to reason about a program's
+ behavior.'' 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:
+
+
In the example above, there is a ``hidden'' call to
+ X::~X() in lines 6 and 7. Granted, using exceptions, there is
+ no code devoted to error handling visible:
+
+
+
int f() // 1
+{ // 2
+ X x; // 3
+ int result = x.g(); // 4
+ // ...More code here...
+ return result; // 5
+}
+
+
+
+
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
+ exactly 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.
+
+
There is an even more important way in which exceptions can enhance
+ correctness: by allowing simple class invariants. In the first example, if
+ x'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 X is used, whether he is handling a
+ full-fledged X or some abortive attempt to construct one (or
+ worse: someone simply forgot to call the initializer!)
+
+
3 A contractual basis for exception-safety
+
+
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.2
+ The generic component might, in return, provide one of the following
+ guarantees:
+
+
+
The basic guarantee: that the invariants of the component are
+ preserved, and no resources are leaked.
+
+
The strong guarantee: that the operation has either completed
+ successfully or thrown an exception, leaving the program state exactly as
+ it was before the operation started.
+
+
The no-throw guarantee: that the operation will not throw an
+ exception.
+
+
+
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:
+
+
Since all we know about v after an exception is that it is valid, the
+ function is allowed to print any random sequence of Xs.3
+ It is ``safe'' in the sense that it is not allowed to crash, but
+ its output may be unpredictable.
+
+
The strong 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 strong guarantee.4).
+
+
The no-throw 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 no-throw guarantee turns out to be
+ important for other reasons, as we shall see.5
+
+
4 Legal Wrangling
+
+
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
+ vector<T>::erase gives the basic guarantee for
+ any T, but for types whose copy constructor and copy
+ assignment operator do not throw, it gives the no-throw guarantee.6
+
+
5 What level of exception-safety should a component specify?
+
+
From a client's point-of-view, the strongest possible level of safety
+ would be ideal. Of course, the no-throw guarantee is simply
+ impossible for many operations, but what about the strong guarantee?
+ For example, suppose we wanted atomic behavior for
+ vector<T>::insert. 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.
+
+
One possible alternative would be to redefine insert 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 basic 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.
+
+
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 strong
+ guarantee, almost any operation on a standard container which gives the
+ basic guarantee can be made strong using the ``make a
+ new copy'' strategy described above:
+
+
+
template <class Container, class BasicOp>
+void MakeOperationStrong( Container& c, const BasicOp& op )
+{
+ Container tmp(c); // Copy c
+ op(tmp); // Work on the copy
+ c.swap(tmp); // Cannot fail7
+}
+
+
+
+
This technique can be folded into a wrapper class to make a similar
+ container which provides stronger guarantees (and different performance
+ characteristics).8
+
+
6 Should we take everything we can get?
+
+
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 introsort algorithm [6],
+ which represents a substantial improvement in worst-case complexity over
+ the well-established quicksort.
+
+
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:
+
+
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 strong
+ guarantee within the natural levels of safety provided by set and list:
+
+
What does our code actually require of the library? We need to examine
+ the lines where non-const operations occur:
+
+
+
Line 4: if the insertion fails but set_impl is modified
+ in the process, our invariant is violated. We need to be able to rely on
+ the strong guarantee from set<T>::insert.
+
+
Line 7: likewise, if push_back fails, but
+ list_impl is modified in the process, our invariant is
+ violated, so we need to be able to rely on the strong guarantee
+ from list<T>::insert.
+
+
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 no-throw guarantee from
+ set<T>::erase.9
+
+
Line 11: for the same reasons, we also depend on being able to pass
+ the i to the erase function: we need the
+ no-throw guarantee from the copy constructor of
+ set<T>::iterator.
+
+
+
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
+ no-throw 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. 10
+
+
7 Automated testing for exception-safety
+
+
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.
+
+
The test program started with the basics: reinforcement and
+ instrumentation, especially of the global operators new and
+ delete.11Instances 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.
+
+
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
+ ThisCanThrow was added. A call to ThisCanThrow
+ also had to be added everywhere that the generic operation being tested
+ might throw an exception, for example in the global operator
+ new, for which an instrumented replacement was supplied.
+
+
+
// Use this as a type parameter, e.g. vector<TestClass>
+struct TestClass
+{
+ TestClass( int v = 0 )
+ : p( ThisCanThrow(), new int( v ) ) {}
+ TestClass( const TestClass& rhs )
+ : p( ThisCanThrow(), new int( *rhs.p ) ) {}
+ const TestClass& operator=( const TestClass& rhs )
+ { ThisCanThrow(); *p = *rhs.p; }
+ bool operator==( const TestClass& rhs ) const
+ { ThisCanThrow(); return *p == *rhs.p; }
+ ...etc...
+ ~TestClass() { delete p; }
+};
+
+
+
+
ThisCanThrow 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 strong
+ guarantee: 12
+
+
+
extern int gThrowCounter; // The throw counter
+void ThisCanThrow()
+{
+ if (gThrowCounter-- == 0)
+ throw 0;
+}
+
+template <class Value, class Operation>
+void StrongCheck(const Value& v, const Operation& 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 strong guarantee
+ assert( unchanged );
+ }
+ // Specialize as desired for each container type, to check
+ // integrity. For example, size() == distance(begin(),end())
+ CheckInvariant(v); // Check any invariant
+ }
+}
+
+
+
+
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 StrongCheck above
+ were instrumental in performing the tests on a wide range of values and
+ operations.
+
+
8 Further Reading
+ To my knowledge, there are currently only two descriptions of STL
+ exception-safety available. The original specification [2]
+ for the reference exception-safe implementation of the STL is an informal
+ specification, simple and self-explanatory (also verbose), and uses the
+ basic- and strong-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.
+
+
The description of exception-safety in the C++ Standard [1]
+ is only slightly more formal, but relies on hard-to-read
+ ``standardese'' and an occasionally subtle web of implication.13
+ In particular, leaks are not treated directly at all. It does have the
+ advantage that it is the standard.
+
+
The original reference implementation [5]
+ 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 [3]
+ 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.
+
+
B. Fomitchev, Adapted SGI STL Version
+ 1.0, with exception handling code by D. Abrahams, available at http://www.stlport.org.
+
+
D. R. Musser, ``Introspective Sorting
+ and Selection Algorithms,'' Software-Practice and Experience
+ 27(8):983-993, 1997.
+
+
Bjarne Stroustrup, The Design And
+ Evolution of C++. Addison Wesley, Reading, MA, 1995, ISBN
+ 0-201-54330-3, Section 16.9.1.
+
+
+
Footnotes
+
+
1 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.
+
+
2 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.
+
+
3 In practice of course, this function would
+ make an extremely poor random sequence generator!
+
+
4 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.
+
+
5 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.
+
+
6 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.
+
+
7 Associative containers whose
+ Compare object might throw an exception when copied cannot use
+ this technique, since the swap function might fail.
+
+
8 This suggests another potential use for the
+ oft-wished-for but as yet unseen container_traits<>
+ template: automated container selection to meet exception-safety
+ constraints.
+
+
9 One might be tempted to surround the erase
+ operation with a try/catch block to reduce the
+ requirements on set<T> 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.
+
+
10 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.
+
+
11 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.
+
+
12 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.
+
+
13 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.
diff --git a/more/generic_programming.html b/more/generic_programming.html
new file mode 100644
index 0000000000..23a12413e0
--- /dev/null
+++ b/more/generic_programming.html
@@ -0,0 +1,474 @@
+
+
+
+
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.
+
+
As a simple example of generic programming, we will look at how one
+ might generalize the memcpy() function of the C standard
+ library. An implementation of memcpy() might look like the
+ following:
+
+
+ The memcpy() function is already generalized to some extent by
+ the use of void* 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
+ memcpy(), the function's minimal requirements are
+ that it needs to traverse through the sequence using some sort
+ of pointer, access elements pointed to, write the elements
+ to the destination, and compare pointers to know when to stop. The
+ C++ standard library groups requirements such as these into
+ concepts, in this case the Input Iterator
+ concept (for region2) and the Output Iterator
+ concept (for region1).
+
+
If we rewrite the memcpy() as a function template, and use
+ the Input
+ Iterator and Output Iterator
+ concepts to describe the requirements on the template parameters, we can
+ implement a highly reusable copy() function in the following
+ way:
+
+
Using the generic copy() function, we can now copy elements
+ from any kind of sequence, including a linked list that exports iterators
+ such as std::list.
+
+
+ A concept is a set of requirements
+ consisting of valid expressions, associated types, invariants, and
+ complexity guarantees. A type that satisfies the requirements is
+ said to model the concept. A concept can extend the
+ requirements of another concept, which is called
+ refinement.
+
+
+
Valid Expressions are C++
+ expressions which must compile successfully for the objects involved in
+ the expression to be considered models of the concept.
+
+
Associated Types 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 traits class.
+
+
Invariants 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.
+
+
Complexity Guarantees 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.
+
+
+
The concepts used in the C++ Standard Library are documented at the SGI STL
+ site.
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 std::iterator_traits<T>
+ looks something like this:
+ The traits' value_type gives generic code the type which the
+ iterator is "pointing at", while the iterator_category can be
+ used to select more efficient algorithms depending on the iterator's
+ capabilities.
+
+
A key feature of traits templates is that they're
+ non-intrusive: 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.
+
+
For an in-depth description of std::iterator_traits, see this page
+ provided by SGI. Another very different expression of the traits idiom in
+ the standard is std::numeric_limits<T> which provides
+ constants describing the range and capabilities of numeric types.
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 std::advance()
+ function in the C++ Standard Library, which increments an iterator
+ n times. Depending on the kind of iterator, there are different
+ optimizations that can be applied in the implementation. If the iterator
+ is random
+ access (can jump forward and backward arbitrary distances), then the
+ advance() function can simply be implemented with i +=
+ n, and is very efficient: constant time. Other iterators must be
+ advanced in steps, making the operation linear in n. If the
+ iterator is bidirectional,
+ then it makes sense for n to be negative, so we must decide
+ whether to increment or decrement the iterator.
+
+
The relation between tag dispatching and traits classes is that the
+ property used for dispatching (in this case the
+ iterator_category) is often accessed through a traits class. The
+ main advance() function uses the iterator_traits
+ class to get the iterator_category. It then makes a call the the
+ overloaded advance_dispatch() function. The appropriate
+ advance_dispatch() is selected by the compiler based on whatever
+ type the iterator_category resolves to, either input_iterator_tag,
+ bidirectional_iterator_tag,
+ or random_access_iterator_tag.
+ A tag is simply a class whose only purpose is to convey
+ some property for use in tag dispatching and similar techniques. Refer to
+ this page
+ for a more detailed description of iterator tags.
+
+
+
+namespace std {
+ struct input_iterator_tag { };
+ struct bidirectional_iterator_tag { };
+ struct random_access_iterator_tag { };
+
+ namespace detail {
+ template <class InputIterator, class Distance>
+ void advance_dispatch(InputIterator& i, Distance n, input_iterator_tag) {
+ while (n--) ++i;
+ }
+
+ template <class BidirectionalIterator, class Distance>
+ void advance_dispatch(BidirectionalIterator& i, Distance n,
+ bidirectional_iterator_tag) {
+ if (n >= 0)
+ while (n--) ++i;
+ else
+ while (n++) --i;
+ }
+
+ template <class RandomAccessIterator, class Distance>
+ void advance_dispatch(RandomAccessIterator& i, Distance n,
+ random_access_iterator_tag) {
+ i += n;
+ }
+ }
+
+ template <class InputIterator, class Distance>
+ void advance(InputIterator& i, Distance n) {
+ typename iterator_traits<InputIterator>::iterator_category category;
+ detail::advance_dispatch(i, n, category);
+ }
+}
+
An adaptor is a class template which builds on another type or
+ types to provide a new interface or behavioral variant. Examples of
+ standard adaptors are std::reverse_iterator,
+ which adapts an iterator type by reversing its motion upon
+ increment/decrement, and std::stack, which adapts a
+ container to provide a simple stack interface.
+
+
A more comprehensive review of the adaptors in the standard can be
+ found
+ here.
Note: The type generator concept has largely been
+ superseded by the more refined notion of a metafunction. See
+ C++ Template
+ Metaprogramming for an in-depth discussion of metafunctions.
+
+
A type generator is a template whose only purpose is to
+ synthesize a new type or types based on its template argument(s)[1]. The generated type is usually expressed as a nested typedef
+ named, appropriately type. A type generator is usually used to
+ consolidate a complicated type expression into a simple one. This example
+ uses an old version of iterator_adaptor
+ whose design didn't allow derived iterator types. As a result, every
+ adapted iterator had to be a specialization of iterator_adaptor
+ itself and generators were a convenient way to produce those types.
+
+
+
+template <class Predicate, class Iterator,
+ class Value = complicated default,
+ class Reference = complicated default,
+ class Pointer = complicated default,
+ class Category = complicated default,
+ class Distance = complicated default
+ >
+struct filter_iterator_generator {
+ typedef iterator_adaptor<
+
+ Iterator,filter_iterator_policies<Predicate,Iterator>,
+ Value,Reference,Pointer,Category,Distance> type;
+};
+
+
+
+
Now, that's complicated, but producing an adapted filter iterator
+ using the generator is much easier. You can usually just write:
An object generator 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 "make_", after
+ std::make_pair(const T&, const U&).
A policy class is a template parameter used to transmit behavior. An
+ example from the standard library is std::allocator,
+ which supplies memory management behaviors to standard containers.
+
+
Policy classes have been explored in detail by Andrei Alexandrescu in this chapter
+ of his book, Modern C++ Design. He writes:
+
+
+
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.
+
+
Because you can mix and match policies, you can achieve a
+ combinatorial set of behaviors by using a small core of elementary
+ components.
+
+
+
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.
+ This paper describes an old version of iterator_adaptor
+ that used non-orthogonal policies. There is also precedent in the
+ standard library: std::char_traits,
+ despite its name, acts as a policies class that determines the behaviors
+ of std::basic_string.
+
+
Notes
+ [1] Type generators are sometimes viewed as a workaround
+ for the lack of ``templated typedefs'' in C++.
+
+
+
+
+
+
diff --git a/more/getting_started.html b/more/getting_started.html
new file mode 100644
index 0000000000..62d669e763
--- /dev/null
+++ b/more/getting_started.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+Automatically loading index page... if nothing happens, please go to
+getting_started/index.html.
+
+
+
+
+
diff --git a/more/getting_started.rst b/more/getting_started.rst
new file mode 100644
index 0000000000..131d7ee1ad
--- /dev/null
+++ b/more/getting_started.rst
@@ -0,0 +1,1004 @@
+============================
+ |(logo)|__ Getting Started
+============================
+
+.. |(logo)| image:: ../boost.png
+ :alt: Boost
+ :class: boost-logo
+
+__ ../index.htm
+
+
+.. section-numbering::
+ :depth: 2
+
+.. contents:: Contents
+ :depth: 2
+ :class: sidebar small
+
+.. ## Update this substitution for each release
+
+.. |boost_ver| replace:: ``boost_1_34_0``
+.. |boost_ver-bold| replace:: **boost_1_34_0**
+
+.. |root| replace:: ``/``\ *path*\ ``/``\ *to*\ ``/``\ |boost_ver|
+.. |winroot| replace:: *path*\ ``\``\ *to*\ ``\``\ |boost_ver|
+.. |winroot-default| replace:: ``C:\Program``\ `` ``\ ``Files\boost\``\ |boost_ver|
+.. |bold-winroot-default| replace:: **C:\\Program Files\\boost\\**\ |boost_ver-bold|
+
+Introduction
+============
+
+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.
+
+We identify Unix and its variants such as Linux, FreeBSD, and MacOS
+collectively as \*nix. If you're not targeting Microsoft Windows,
+the instructions for \*nix users will probably work for you.
+Cygwin users working from the Cygwin ``bash`` prompt should also
+follow the \*nix instructions. To use your Cygwin compiler from
+the Windows command prompt, follow the instructions for Windows
+users.
+
+Although Boost supports a wide variety of Windows compilers
+(including older Microsoft compilers), most instructions for
+Windows users cover only the Visual Studio .NET 2003 and Visual
+Studio 2005. We hope that gives you enough information to adapt
+them for your own compiler or IDE.
+
+Get Boost
+=========
+
+There are basically three ways to get Boost on your system:
+
+1. **Windows Installer**: Boost Consulting provides an installer_
+ for Windows platforms that installs a complete Boost
+ distribution, plus optional precompiled library binaries for
+ Visual Studio, and (optionally) a prebuilt version of the
+ ``bjam`` build tool.
+
+ .. _Windows installer: http://www.boost-consulting.com/download.html
+ .. |Windows installer| replace:: **Windows installer**
+ .. _Boost Consulting: http://boost-consulting.com
+ .. _installer: `Windows installer`_
+
+
+2. **Download**: users of other platforms—and Windows
+ users who prefer to build everything from scratch—can `download
+ a complete Boost distribution`__ from SourceForge.
+
+ .. ## Update this link for each release
+ __ http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&release_id=376197
+
+ - **Windows**: Download and run |boost_ver|\ ``.exe``
+ to unpack the distribution. [#zip]_
+
+ - ***nix**: Download |boost_ver|\ ``.tar.bz2``. Then, in the
+ directory where you want to put the Boost installation,
+ execute
+
+ .. parsed-literal::
+
+ tar --bzip2 -xf */path/to/*\ |boost_ver|\ .tar.bz2
+
+3. **Boost packages** from RedHat, Debian, or some other
+ distribution packager: these instructions may not work for you
+ if you use 3rd party packages, because other packagers sometimes
+ choose to break Boost up into several packages or to reorganize
+ the directory structure of the Boost distribution. [#packagers]_
+
+The Structure of a Boost Distribution
+=====================================
+
+This is is a sketch of the directory structure you'll get when you
+unpack your Boost installation (windows users replace forward
+slashes with backslashes):
+
+.. parsed-literal::
+
+ |boost_ver-bold|\ **/** .................\ *The “boost root directoryâ€*
+ **index.htm** .........\ *A copy of www.boost.org starts here*
+ **boost/** .........................\ *All Boost Header files*
+ **libs/** ............\ *Tests, .cpp*\ s\ *, docs, etc., by library* [#installer-src]_
+ **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: small
+
+ 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 Type Traits Library's ``is_void.hpp`` header in
+ ``boost/type_traits/is_void.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
+ ``boost/python.hpp``.
+
+ * Most libraries place private headers in a subdirectory called
+ ``detail/`` or ``aux_/``. Don't look in these directories and
+ expect to find anything you can use.
+
+A few things are worth noting right off the bat:
+
+1. The path to the “boost root directory†is sometimes referred to
+ as ``$BOOST_ROOT`` in documentation and mailing lists. If you
+ used the Windows installer, that will usually be |winroot-default|.
+
+2. To compile anything in Boost, you need a directory containing
+ the ``boost/`` subdirectory in your ``#include`` path. For most
+ compilers, that means adding
+
+ .. parsed-literal::
+
+ -I\ |root|
+
+ to the command line. 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.
+
+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
+
+ or
+
+ .. parsed-literal::
+
+ #include "boost/\ *whatever*\ .hpp"
+
+ depending on your religion as regards the use of angle bracket
+ includes. Even Windows users can use forward slashes in
+ ``#include`` directives; your compiler doesn't care.
+
+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.
+
+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 can't be used without separate
+compilation are:
+
+* Boost.Filesystem
+* Boost.IOStreams
+* Boost.ProgramOptions
+* Boost.Python_
+* Boost.Regex
+* Boost.Serialization
+* Boost.Signals
+* Boost.Test
+* Boost.Thread
+* Boost.Wave
+
+The DateTime library has a separately-compiled component that
+is only needed if you're using its to/from_string and/or
+serialization features or if you're targeting Visual C++ 6.x or
+Borland. The Graph library also has a separately-compiled part,
+but you won't need it unless you intend to `parse GraphViz
+files`__.
+
+__ ../libs/graph/doc/read_graphviz.html
+
+.. ## Keep the list of non-header-only libraries up-to-date
+
+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
+ #include
+ #include
+ #include
+
+ int main()
+ {
+ using namespace boost::lambda;
+ typedef std::istream_iterator in;
+
+ std::for_each(
+ in(std::cin), in(), std::cout << (_1 * 3) << " " );
+ }
+
+Copy the text of this program into a file called ``example.cpp``.
+
+.. _unix-header-only:
+
+Build on \*nix
+--------------
+
+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
+
+.. |next| replace:: *next...*
+
+|next|__
+
+__ `Errors and Warnings`_
+
+Build from the Visual Studio 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, type the following command and
+hit the return key:
+
+.. parsed-literal::
+
+ cl /EHsc /I\ |winroot| *path*\ \\\ *to*\ \\example.cpp
+
+To test the result, type:
+
+.. parsed-literal::
+
+ echo 1 2 3 | example
+
+|next|__
+
+__ `Errors and Warnings`_
+
+.. _vs-header-only:
+
+Build in 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, e.g.
+ |winroot-default|.
+* 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.
+
+Errors and Warnings
+-------------------
+
+Don't be alarmed if you see compiler warnings from 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.
+
+Get Boost Library Binaries
+==========================
+
+If you want to use any of the separately-compiled Boost libraries,
+you'll need library binaries.
+
+Install Visual Studio Binaries
+------------------------------
+
+The `Windows installer`_ supplied by Boost Consulting will download
+and install pre-compiled binaries into the ``lib\`` subdirectory of
+the boost root, typically |winroot-default|\ ``\lib\``.
+
+|next|__
+
+__ `Link Your Program to a Boost Library`_
+
+Build and Install \*nix Binaries
+--------------------------------
+
+Issue the following commands in the shell (don't type ``$``; it
+represents the shell's prompt):
+
+.. parsed-literal::
+
+ **$** cd |root|
+ **$** ./configure --help
+
+Select your configuration options and invoke ``./configure`` again.
+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. Finally,
+
+.. parsed-literal::
+
+ **$** make install
+
+which 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|__
+
+__ `Expected Build Output`_
+
+Build and Install Other Binaries
+--------------------------------
+
+If you're not using Visual C++ 7.1 or 8.0, or you're a \*nix user
+who wants want to build with a toolset other than your system's
+default, or if you want a nonstandard variant build of Boost
+(e.g. optimized, but with debug symbols), you'll need to use
+Boost.Build_ to create your own binaries.
+
+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`__.
+
+__ http://www.boost.org/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 apend 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
+
+For example, on Windows, your session might look like:
+
+.. parsed-literal::
+
+ C:\WINDOWS> cd |winroot-default|
+ |winroot-default|> bjam **\\**
+ **--build-dir=**\ %TEMP%\\build-boost **\\**
+ **--toolset=msvc stage**
+
+And on Unix:
+
+.. parsed-literal::
+
+ $ cd ~/|boost_ver|
+ $ bjam **--build-dir=**\ ~/build-boost **--prefix=**\ ~/boost
+
+In either case, 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
+
+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.
+
+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`_.
+
+__ file:///home/dave/src/boost/libs/iostreams/doc/installation.html
+
+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
+ #include
+ #include
+
+ 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;
+ }
+ }
+
+.. _Boost.Regex: ../libs/regex
+
+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.
+
+.. Note:: Boost.Python_ users should read that library's own `build
+ documentation`__ as there are several library-specific issues to
+ consider.
+
+.. _Boost.Python: ../libs/python/index.html
+__ ../libs/python/doc/building.html
+
+Link to a Boost Library on Windows
+----------------------------------
+
+.. _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 to a Boost Library from the Visual Studio 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 |winroot-default|\ ``\lib``:
+
+.. parsed-literal::
+
+ cl /EHsc /I |winroot| example.cpp **\\**
+ **/link /LIBPATH:** |bold-winroot-default|\ **\\lib**
+
+|next|__
+
+__ `Test Your Program`_
+
+Link to a Boost Library in 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. |winroot-default|\ ``\lib\``.
+3. From the *Build* menu, select *Build Solution*.
+
+|next|__
+
+__ `Test Your Program`_
+
+Link to a Boost Library On \*nix
+--------------------------------
+
+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`__.
+
+__ unix-header-only_
+
+Library Naming
+--------------
+
+When auto-linking is not available, you need to know how Boost
+binaries are named so you can choose the right one for your build
+configuration. 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 \*nix 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 ``gcc`` toolset, whose
+ names always end in ``.a``— ``.lib`` indicates a static or import
+ library. Where supported by \*nix toolsets, 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
+
+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.
+
+Test Your Program on Microsoft Windows
+......................................
+
+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?â€
+
+Test Your Program on \*nix
+..........................
+
+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?â€
+
+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`_
+
+.. 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: mailing_lists.htm#users
+.. _Boost.Build Wiki: http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build_V2
+.. _Boost.Build mailing list: mailing_lists.htm#jamboost
+
+
+.. _`Using command-line tools in Windows`:
+.. _`command prompt`:
+.. _`command-line tool`:
+
+Appendix: Using command-line tools in Windows
+=============================================
+
+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 *Command Prompt*, click the *Start* menu button, click
+*Run*, type “cmdâ€, and then click OK.
+
+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 |winroot-default|
+
+One way to name a directory you know about is to write
+
+.. parsed-literal::
+
+ %HOMEDRIVE%%HOMEPATH%\\\ *directory-name*
+
+which indicates a sibling folder of your “My Documents†folder.
+
+Long commands can be continued across several lines by typing
+backslashes at the ends of all but the last line. Many of the
+examples on this page use that technique to save horizontal
+space.
+
+------------------------------
+
+.. [#zip] If you prefer not to download executable programs, download
+ |boost_ver|\ ``.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.
+
+.. [#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: mailing_lists.htm#main
+
+.. [#installer-src] If you used the `Windows 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.
+
+.. [#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.
+
+.. [#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.
+
+.. [#lowercase-l] That option is a dash followed by a lowercase “Lâ€
+ character, which looks very much like a numeral 1 in some fonts.
+
+.. [#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. All though 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.
+
diff --git a/more/getting_started/Jamfile.v2 b/more/getting_started/Jamfile.v2
new file mode 100644
index 0000000000..770aae934d
--- /dev/null
+++ b/more/getting_started/Jamfile.v2
@@ -0,0 +1,23 @@
+# 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 :
+
+ "--link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet)
+ ;
+}
+
+alias htmls : $(bases) ;
+stage . : $(bases) ;
diff --git a/more/getting_started/detail/binary-head.rst b/more/getting_started/detail/binary-head.rst
new file mode 100644
index 0000000000..21f32aba72
--- /dev/null
+++ b/more/getting_started/detail/binary-head.rst
@@ -0,0 +1,10 @@
+.. 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.
+
diff --git a/more/getting_started/detail/build-from-source-head.rst b/more/getting_started/detail/build-from-source-head.rst
new file mode 100644
index 0000000000..57cdf9f383
--- /dev/null
+++ b/more/getting_started/detail/build-from-source-head.rst
@@ -0,0 +1,126 @@
+.. 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`__.
+
+__ `building bjam`_
+
+
+.. _toolset:
+.. _toolset-name:
+
+Identify Your Toolset
+.....................
+
+First, find the toolset corresponding to your compiler in the
+following table.
+
+.. Note:: If you previously chose a toolset for the purposes of
+ `building bjam`_, you should assume it won't work and instead
+ choose newly from the table below.
+
+.. _building bjam: ../../doc/html/jam/building.html
+
++-----------+--------------------+-----------------------------+
+|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. ``intel-9.0`` or
+``borland-5.4.3``. |windows-version-name-caveat|
+
+
+.. _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
diff --git a/more/getting_started/detail/build-from-source-tail.rst b/more/getting_started/detail/build-from-source-tail.rst
new file mode 100644
index 0000000000..5a07b715cb
--- /dev/null
+++ b/more/getting_started/detail/build-from-source-tail.rst
@@ -0,0 +1,67 @@
+.. 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)
+
+Building the special ``stage`` target places Boost
+library 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`_.
+
diff --git a/more/getting_started/detail/build-simple-head.rst b/more/getting_started/detail/build-simple-head.rst
new file mode 100644
index 0000000000..487610e344
--- /dev/null
+++ b/more/getting_started/detail/build-simple-head.rst
@@ -0,0 +1,28 @@
+.. 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
+ #include
+ #include
+ #include
+
+ int main()
+ {
+ using namespace boost::lambda;
+ typedef std::istream_iterator in;
+
+ std::for_each(
+ in(std::cin), in(), std::cout << (_1 * 3) << " " );
+ }
+
+Copy the text of this program into a file called ``example.cpp``.
+
diff --git a/more/getting_started/detail/common-footnotes.rst b/more/getting_started/detail/common-footnotes.rst
new file mode 100644
index 0000000000..980600b719
--- /dev/null
+++ b/more/getting_started/detail/common-footnotes.rst
@@ -0,0 +1,26 @@
+.. 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.
+
diff --git a/more/getting_started/detail/common-unix.rst b/more/getting_started/detail/common-unix.rst
new file mode 100644
index 0000000000..c1cdf491c5
--- /dev/null
+++ b/more/getting_started/detail/common-unix.rst
@@ -0,0 +1,24 @@
+.. 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:: ``Â ``
+
+.. |windows-version-name-caveat| replace:: ``Â ``
+
+.. |command-line tool| replace:: command-line tool
+
+
+.. include:: common.rst
diff --git a/more/getting_started/detail/common-windows.rst b/more/getting_started/detail/common-windows.rst
new file mode 100644
index 0000000000..fa0102c4e3
--- /dev/null
+++ b/more/getting_started/detail/common-windows.rst
@@ -0,0 +1,34 @@
+.. 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*
+
+
+.. |windows-version-name-caveat| replace:: **On Windows, append a version
+ number even if you only have one version installed** (unless you
+ are using the msvc or gcc toolsets, which have special version
+ detection code) or `auto-linking`_ will fail.
+
+.. |command-line tool| replace:: `command-line tool`_
+
+.. include:: common.rst
diff --git a/more/getting_started/detail/common.rst b/more/getting_started/detail/common.rst
new file mode 100644
index 0000000000..591c05b175
--- /dev/null
+++ b/more/getting_started/detail/common.rst
@@ -0,0 +1,5 @@
+.. 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*
diff --git a/more/getting_started/detail/conclusion.rst b/more/getting_started/detail/conclusion.rst
new file mode 100644
index 0000000000..7c74e95342
--- /dev/null
+++ b/more/getting_started/detail/conclusion.rst
@@ -0,0 +1,39 @@
+.. 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/index.html
+.. _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
+
diff --git a/more/getting_started/detail/distro.rst b/more/getting_started/detail/distro.rst
new file mode 100644
index 0000000000..708dfd1ab6
--- /dev/null
+++ b/more/getting_started/detail/distro.rst
@@ -0,0 +1,88 @@
+.. 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
+
+ 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.
+
diff --git a/more/getting_started/detail/errors-and-warnings.rst b/more/getting_started/detail/errors-and-warnings.rst
new file mode 100644
index 0000000000..770d46eae3
--- /dev/null
+++ b/more/getting_started/detail/errors-and-warnings.rst
@@ -0,0 +1,16 @@
+.. 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`_
+
diff --git a/more/getting_started/detail/header-only.rst b/more/getting_started/detail/header-only.rst
new file mode 100644
index 0000000000..c1f1dd3b3e
--- /dev/null
+++ b/more/getting_started/detail/header-only.rst
@@ -0,0 +1,48 @@
+.. 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
diff --git a/more/getting_started/detail/library-naming.rst b/more/getting_started/detail/library-naming.rst
new file mode 100644
index 0000000000..76d99ed5c2
--- /dev/null
+++ b/more/getting_started/detail/library-naming.rst
@@ -0,0 +1,80 @@
+.. 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
+
diff --git a/more/getting_started/detail/link-head.rst b/more/getting_started/detail/link-head.rst
new file mode 100644
index 0000000000..c4a59958be
--- /dev/null
+++ b/more/getting_started/detail/link-head.rst
@@ -0,0 +1,39 @@
+.. 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
+ #include
+ #include
+
+ 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.
+
diff --git a/more/getting_started/detail/links.rst b/more/getting_started/detail/links.rst
new file mode 100644
index 0000000000..e1a181c231
--- /dev/null
+++ b/more/getting_started/detail/links.rst
@@ -0,0 +1,16 @@
+.. 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
diff --git a/more/getting_started/detail/release-variables.rst b/more/getting_started/detail/release-variables.rst
new file mode 100644
index 0000000000..f0660524e7
--- /dev/null
+++ b/more/getting_started/detail/release-variables.rst
@@ -0,0 +1,12 @@
+.. 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.1
+.. |boost_ver| replace:: ``boost_1_34_1``
+.. |boost_ver-bold| replace:: **boost_1_34_1**
+
+.. _sf-download: http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041
\ No newline at end of file
diff --git a/more/getting_started/detail/test-head.rst b/more/getting_started/detail/test-head.rst
new file mode 100644
index 0000000000..90e1ce7557
--- /dev/null
+++ b/more/getting_started/detail/test-head.rst
@@ -0,0 +1,16 @@
+.. 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.
+
diff --git a/more/getting_started/index.html b/more/getting_started/index.html
new file mode 100644
index 0000000000..2f60d00baa
--- /dev/null
+++ b/more/getting_started/index.html
@@ -0,0 +1,58 @@
+
+
+
+
+
+
+Boost Getting Started
+
+
+
+
+
Getting Started
+
+
+
+
+
+
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:
+
+$ 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!
+
+
+
+
+
diff --git a/more/getting_started/index.rst b/more/getting_started/index.rst
new file mode 100644
index 0000000000..23bfa7bd0b
--- /dev/null
+++ b/more/getting_started/index.rst
@@ -0,0 +1,60 @@
+.. 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
+
diff --git a/more/getting_started/unix-variants.html b/more/getting_started/unix-variants.html
new file mode 100644
index 0000000000..67db82e790
--- /dev/null
+++ b/more/getting_started/unix-variants.html
@@ -0,0 +1,791 @@
+
+
+
+
+
+
+Boost Getting Started on Unix Variants
+
+
+
+
+
In the directory where you want to put the Boost installation,
+execute
+
+tar --bzip2 -xf /path/to/boost_1_34_1.tar.bz2
+
+
+
+
+
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.1 If you have
+any trouble, we suggest using an official Boost distribution
+from SourceForge.
This is a sketch of the resulting directory structure:
+
+boost_1_34_1/ .................The “boost root directoryâ€
+ index.htm .........A copy of www.boost.org starts here
+ boost/ .........................All Boost Header files
+
+ libs/ ............Tests, .cpps, 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
+
+
+
Header Organization
+
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
+
+boost/python/def.hpp.
+
+
+
Some libraries have an “aggregate header†in boost/ that
+#includes all of the library's other headers. For
+example, Boost.Python's aggregate header is
+
+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:
+
+
The path to the boost root directory (often /usr/local/boost_1_34_1) is
+sometimes referred to as $BOOST_ROOT in documentation and
+mailing lists .
+
+
To compile anything in Boost, you need a directory containing
+the boost/ subdirectory in your #include path.
+
+
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:
+
+#include <boost/whatever.hpp>
+
+
or
+
+#include "boost/whatever.hpp"
+
+
depending on your preference regarding the use of angle bracket
+includes.
+
+
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.
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.
+
+
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.
+
+
+
The only Boost libraries that must be built separately are:
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.
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:
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.3Errors 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.
Issue the following commands in the shell (don't type $; that
+represents the shell's prompt):
+
+$ cd path/to/boost_1_34_1
+$ ./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
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,
+
+$ 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.
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).
+
+
+
+
Boost.Build is a text-based system for developing, testing, and
+installing software. To use it, you'll need an executable called
+bjam.
First, find the toolset corresponding to your compiler in the
+following table.
+
+
Note
+
If you previously chose a toolset for the purposes of
+building bjam, you should assume it won't work and instead
+choose newly from the table below.
+
+
+
+
+
+
+
+
+
Toolset
+Name
+
Vendor
+
Notes
+
+
+
+
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.
+
+
+
+
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. intel-9.0 or
+borland-5.4.3.
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.
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:
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.
+
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.
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.
There are two main challenges associated with linking:
+
+
Tool configuration, e.g. choosing command-line options or IDE
+build settings.
+
Identifying the library binary, among all the build variants,
+whose compile configuration is compatible with the rest of your
+project.
+
+
There are two main ways to link to libraries:
+
+
You can specify the full path to each library:
+
+$ c++ -I path/to/boost_1_34_1 example.cpp -o example \
+ ~/boost/lib/libboost_regex-gcc34-mt-d-1_34.a
+
+
+
You can separately specify a directory to search (with -Ldirectory) and a library name to search for (with -llibrary,2 dropping the filename's leading lib and trailing
+suffix (.a in this case):
+
+$ c++ -I path/to/boost_1_34_1 example.cpp -o example \
+ -L~/boost/lib/ -lboost_regex-gcc34-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 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.4
+
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.
using the STLPort standard library rather than the default one supplied with
+your compiler.
+
+
n
+
using STLPort's deprecated “native iostreams†feature.6
+
+
+
+
+
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.
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.
+
+
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):
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.
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.
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.
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.
These libraries were compiled without optimization
+or inlining, with full debug symbols enabled, and without
+NDEBUG#defined. 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.
This feature of STLPort is deprecated because it's
+impossible to make it work transparently to the user; we don't
+recommend it.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/more/getting_started/unix-variants.rst b/more/getting_started/unix-variants.rst
new file mode 100644
index 0000000000..4cf74c466e
--- /dev/null
+++ b/more/getting_started/unix-variants.rst
@@ -0,0 +1,236 @@
+.. 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, Build Custom Binaries
+-------------------------
+
+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 stage
+
+.. 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-gcc34-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-gcc34-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
diff --git a/more/getting_started/windows.html b/more/getting_started/windows.html
new file mode 100644
index 0000000000..1bf314540f
--- /dev/null
+++ b/more/getting_started/windows.html
@@ -0,0 +1,881 @@
+
+
+
+
+
+
+Boost Getting Started on Windows
+
+
+
+
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.
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.
+
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_1_34_1.exe and run it to install a complete Boost
+distribution.1
This is a sketch of the resulting directory structure:
+
+boost_1_34_1\ .................The “boost root directoryâ€
+ index.htm .........A copy of www.boost.org starts here
+ boost\ .........................All Boost Header files
+ lib\ .....................precompiled library binaries
+ libs\ ............Tests, .cpps, 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
+
+
+
Header Organization
+
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
+
+boost\python\def.hpp.
+
+
+
Some libraries have an “aggregate header†in boost\ that
+#includes all of the library's other headers. For
+example, Boost.Python's aggregate header is
+
+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:
+
+
The path to the boost root directory (often C:\ProgramFiles\boost\boost_1_34_1) is
+sometimes referred to as $BOOST_ROOT in documentation and
+mailing lists .
+
+
To compile anything in Boost, you need a directory containing
+the boost\ subdirectory in your #include path. 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.
+
+
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:
+
+#include <boost/whatever.hpp>
+
+
or
+
+#include "boost/whatever.hpp"
+
+
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
+#include directives; your compiler doesn't care.
+
+
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.
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.
+
+
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.
+
+
+
The only Boost libraries that must be built separately are:
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.
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:
Copy the text of this program into a file called example.cpp.
+
+
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.
+
+
+
Command Prompt Basics
+
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.
+
All commands are executed within the context of a current
+directory in the filesystem. To set the current directory,
+type:
+
+cd path\to\some\directory
+
+
followed by Return. For example,
+
+cd C:\ProgramFiles\boost\boost_1_34_1
+
+
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.
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:
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.5Errors 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.
The installer supplied by Boost Consulting will download and
+install pre-compiled binaries into the lib\ subdirectory of the
+boost root, typically C:\ProgramFiles\boost\boost_1_34_1\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.
First, find the toolset corresponding to your compiler in the
+following table.
+
+
Note
+
If you previously chose a toolset for the purposes of
+building bjam, you should assume it won't work and instead
+choose newly from the table below.
+
+
+
+
+
+
+
+
+
Toolset
+Name
+
Vendor
+
Notes
+
+
+
+
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.
+
+
+
+
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. intel-9.0 or
+borland-5.4.3. On Windows, append a version
+number even if you only have one version installed (unless you
+are using the msvc or gcc toolsets, which have special version
+detection code) or auto-linking will fail.
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.
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:
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.
+
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.
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.
There are two main challenges associated with linking:
+
+
Tool configuration, e.g. choosing command-line options or IDE
+build settings.
+
Identifying the library binary, among all the build variants,
+whose compile configuration is compatible with the rest of your
+project.
+
+
+
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.
+
The GCC toolchains (Cygwin and MinGW) are notable exceptions;
+GCC users should refer to the linking instructions for Unix
+variant OSes for the appropriate command-line options to use.
Right-click example in the Solution Explorer pane and
+select Properties from the resulting pop-up menu
+
In Configuration Properties > Linker > Additional Library
+Directories, enter the path to the Boost binaries,
+e.g. C:\ProgramFiles\boost\boost_1_34_1\lib\.
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 C:\ProgramFiles\boost\boost_1_34_1\lib:
If, like Visual C++, your compiler supports auto-linking,
+you can probably skip to the next step.
+
+
+
+
+
+
+
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.6
+
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.
using the STLPort standard library rather than the default one supplied with
+your compiler.
+
+
n
+
using STLPort's deprecated “native iostreams†feature.8
+
+
+
+
+
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.
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.
If you prefer not to download executable programs,
+download boost_1_34_1.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.
+
+
+
+
+
+
[2]
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.
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.
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.
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.
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.
These libraries were compiled without optimization
+or inlining, with full debug symbols enabled, and without
+NDEBUG#defined. 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.
This feature of STLPort is deprecated because it's
+impossible to make it work transparently to the user; we don't
+recommend it.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/more/getting_started/windows.rst b/more/getting_started/windows.rst
new file mode 100644
index 0000000000..1750a00ab9
--- /dev/null
+++ b/more/getting_started/windows.rst
@@ -0,0 +1,316 @@
+.. 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 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=**\ C:\\temp\\build-boost **^**
+ More? **--toolset=**\ msvc stage
+
+.. include:: detail/build-from-source-tail.rst
+
+.. _auto-linking:
+
+.. 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.
+
+ The GCC toolchains (Cygwin and MinGW) are notable exceptions;
+ GCC users should refer to the `linking instructions for Unix
+ variant OSes`__ for the appropriate command-line options to use.
+
+__ unix-variants.html#link-your-program-to-a-boost-library
+
+
+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
diff --git a/more/google_logo_25wht.gif b/more/google_logo_25wht.gif
new file mode 100644
index 0000000000..151f527a95
Binary files /dev/null and b/more/google_logo_25wht.gif differ
diff --git a/more/header.htm b/more/header.htm
new file mode 100644
index 0000000000..3df5ceee7f
--- /dev/null
+++ b/more/header.htm
@@ -0,0 +1,103 @@
+
+
+
+
+
+Boost Header policy
+
+
+
+
+
+
+
+
Header files are the place where a library comes into contact with user code
+and other libraries. To co-exist peacefully and productively, headers must
+be "good neighbors".
+
Here are the standards for boost headers. Many of
+these are also reasonable guidelines for general use.
+
+
Header filenames should have a .hpp (lowercase) extension.
+
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. The sample
+ header uses the Boost convention of all uppercase letters, with the
+ header name prefixed by the namespace name, and suffixed with HPP, separated
+ by underscores.
+
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.
+ Libraries which are designed to work well with other Boost libraries should
+ be placed in namespace boost.
+
+
Make sure that a translation unit consisting of just the
+ contents of the header file will compile successfully.
+
+
Place the header file in a sub-directory to prevent conflict with
+ identically named header files in other libraries. The parent
+ directory is added to the compiler's include search path. Then both
+ your code and user code specifies the sub-directory in #include
+ directives. Thus the header sample header
+ would be included by #include <boost/furball.hpp>
+
The preferred ordering for class definitions is public members, protected
+ members, and finally private members.
+
Include the boost/config.hpp configuration
+ header if there is a need to deal with compiler or platform
+ configuration issues.
+
+
Sample Header
+
// Boost general library furball.hpp header file ---------------------------//
+
+ < Copyright and license notice, as indicated in the license page >
+
+// See http://www.boost.org/ for latest version.
+
+#ifndef BOOST_FURBALL_HPP
+#define BOOST_FURBALL_HPP
+
+namespace boost {
+
+// Furball class declaration -----------------------------------------------//
+
+ class furball
+ {
+ public:
+ void throw_up();
+ private:
+ int whatever;
+ }; // furball
+
+} // namespace
+
+#endif // include guard
+
Coding Style
+
The alert reader will have noticed that the sample
+header employs a certain coding style for indentation, positioning braces,
+commenting ending braces, and similar formatting issues. These stylistic
+issues are viewed as personal preferences and are not part of the Boost Header
+Policy.
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.
+
Dietmar Kühl, one of the original boost.org contributors, comments "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."
+
+
Implementation variations
+
+
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.
+
Boost libraries generally use a configuration
+header, boost/config.hpp, to capture compiler and platform
+dependencies. Although the use of boost/config.hpp is not required, it is
+the preferred approach for simple configuration problems.
+
Boost policy
+
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. That means boost libraries will use the
+techniques below described as appropriate for dealing with platform
+dependencies.
+
The Boost policy toward implementation variations designed to enhance
+performance is to avoid them unless the benefits greatly exceed the full
+costs. The term "full costs" is intended to include both
+tangible costs like extra maintenance, and intangible cost like increased
+difficulty in user understanding.
+
+
Techniques for providing implementation variations
+
+
Several techniques may be used to provide implementation variations. Each is
+appropriate in some situations, and not appropriate in other situations.
+
Single general purpose implementation
+
The first technique is to simply not provide implementation variation at
+all. Instead, provide a single general purpose implementation, and forgo
+the increased complexity implied by all other techniques.
+
Appropriate: 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.
+
Not appropriate: When implementation requires platform specific
+features, or when there are multiple implementation possible with widely
+differing performance characteristics.
+
Beman Dawes comments "In design discussions some implementation is often
+alleged to be much faster than another, yet 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! A single general purpose implementation is
+often just fine."
+
Or as Donald Knuth said, "Premature optimization is the root of all
+evil." (Computing Surveys, vol 6, #4, p 268).
+
Macros
+
While the evils of macros are well known, there remain a few cases where
+macros are the preferred solution:
+
+
+
Preventing multiple inclusion of headers via #include guards.
+
Passing minor configuration information from a configuration
+ header to other files.
+
+
+
Appropriate: 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.
+
Not appropriate: If other techniques will do.
+
To minimize the negative aspects of macros:
+
+
+
Only use macros when they are clearly superior to other
+ techniques. They should be viewed as a last resort.
+
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.
+
+
+
Separate files
+
A library component can have multiple variations, each contained in its own
+separate file or files. The files for the most appropriate variation are
+copied to the appropriate include or implementation directories at installation
+time.
+
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:
+
+
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
+
+
Appropriate: When different platforms require different
+implementations, or when there are major performance differences between
+possible implementations.
+
Not appropriate: When it makes sense to use more that one of the
+variations in the same installation.
+
Separate components
+
Rather than have several implementation variations of a single component,
+supply several separate components. For example, the Boost library currently
+supplies scoped_ptr and shared_ptr classes rather than
+a single smart_ptr class parameterized to distinguish between the
+two cases. There are several ways to make the component choice:
+
+
+
Hardwired by the programmer during coding.
+
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.)
+
+
+
Appropriate: 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.
+
Not appropriate: 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. Thus
+usually not appropriate to cope with platform differences.
+
Note: 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.
+
Template-based approaches
+
Turning a class or function into a template is often an elegant way to cope
+with variations. Template-based approaches provide optimal space and time
+efficiency in return for constraining the implementation selection to compile
+time.
+
Important template techniques include:
+
+
+
Data type parameterization. This allows a single component to
+ operate on a variety of data types, and is why templates were originally
+ invented.
+
Traits parameterization. If parameterization is complex, bundling
+ up aspects into a single traits helper class can allow great variation
+ while hiding messy details. The C++ Standard Library provides
+ several examples of this idiom, such as iterator_traits<>
+ (24.3.1 lib.iterator.traits) and char_traits<> (21.2
+ lib.char.traits).
+
Specialization. A template parameter can be used purely for the
+ purpose of selecting a specialization. For example:
+
+
+
+
SomeClass<fast> my_fast_object; // fast and small are empty classes
+SomeClass<small> my_small_object; // used just to select specialization
+
+
+
+
Appropriate: 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.
+
Not appropriate: When the interfaces for variations are
+different, or when choice of variation is best done by some mechanism outside of
+the program itself. Thus usually not appropriate to cope with platform
+differences.
Writing Documentation for Boost
+ Basic guidelines for writing documentation and templates for quickly generating
+ documentation that follows the guidelines.
Coding Guidelines for Integral Constant
+Expressions
+
+
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.
+
+
What is an Integral Constant Expression?
+
+
Integral constant expressions are described in section 5.19 of
+the standard, and are sometimes referred to as "compile time
+constants". An integral constant expression can be one of
+the following:
+
+
+
A literal integral value, for example 0u or 3L.
+
An enumerator value.
+
Global integral constants, for example:
+ const int my_INTEGRAL_CONSTANT = 3;
+
Static member constants, for example:
+ struct myclass
+ { static const int value = 0; };
+
Member enumerator values, for example:
+ struct myclass
+ { enum{ value = 0 }; };
+
Non-type template parameters of integral or enumerator
+ type.
+
The result of a sizeof expression, for
+ example:
+ sizeof(foo(a, b, c))
+
The result of a static_cast, where the
+ target type is an integral or enumerator type, and the
+ argument is either another integral constant expression,
+ or a floating-point literal.
+
The result of applying a binary operator to two integral
+ constant expressions:
+ INTEGRAL_CONSTANT1 op INTEGRAL_CONSTANT2
+ provided that the operator is not an assignment
+ operator, or comma operator.
+
The result of applying a unary operator to an integral
+ constant expression:
+ op INTEGRAL_CONSTANT1
+ provided that the operator is not the increment or
+ decrement operator.
+
+
+
+
+
Coding Guidelines
+
+
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.
+
+
When declaring constants that are class members always
+use the macro BOOST_STATIC_CONSTANT.
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.
+
+
Don't declare integral constant expressions whose type
+is wider than int.
+
+
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 int.
+
+
Don't use logical operators in integral constant
+expressions; use template meta-programming instead.
+
+
The header <boost/type_traits/ice.hpp> contains a number
+of workaround templates, that fulfil the role of logical
+operators, for example instead of:
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.
+
+
Don't use any operators in an integral constant
+expression used as a non-type template parameter
Where some_symbol is the symbolic name of a an
+integral constant expression whose value is (INTEGRAL_CONSTANT1
+== INTEGRAL_CONSTANT2).
+
+
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.
+
+
Always use a fully qualified name to refer to an
+integral constant expression.
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 ::).
+
+
Always leave a space after a '<' and before '::'
+
+
For example:
+
+
typedef myclass< ::boost::is_integral<some_type>::value> mytypedef;
+ ^
+ ensure there is space here!
+
+
Rationale: <: is a legal digraph in it's own right, so <::
+is interpreted as the same as [:.
+
+
Don't use local names as integral constant expressions
Don't use dependent default parameters for non-type
+template parameters.
+
+
For example:
+
+
template <class T, int I = ::boost::is_integral<T>::value> // Error can't deduce value of I in some cases.
+struct foobar;
+
+
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:
+
+
template <class T, int I = 3> // OK, default value is not dependent
+struct foobar;
+
+
+
+
Unresolved Issues
+
+
The following issues are either unresolved or have fixes that
+are compiler specific, and/or break one or more of the coding
+guidelines.
+
+
Be careful of numeric_limits
+
+
There are three issues here:
+
+
+
The header <limits> may be absent - it is
+ recommended that you never include <limits>
+ directly but use <boost/pending/limits.hpp> instead.
+ This header includes the "real" <limits>
+ header if it is available, otherwise it supplies it's own
+ std::numeric_limits definition. Boost also defines the
+ macro BOOST_NO_LIMITS if <limits> is absent.
+
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 <boost/config.hpp>
+ when this is the case.
+
There is a strange bug in VC6, where the members of std::numeric_limits
+ can be "prematurely evaluated" in template
+ code, for example:
This code fails to compile with VC6 even though no instances
+of the template are ever created; for some bizarre reason ::std::numeric_limits<T>::is_specialized
+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 ::std::numeric_limits<T>::is_specialized
+with ::boost::is_arithmetic<T>::value, then
+everything is fine. The following workaround also works but
+conflicts with the coding guidelines:
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:
+
+
+
The argument is the name of a member-variable, or a local
+ variable (code may not compile with VC6).
+
The argument is an expression which involves the creation
+ of a temporary (code will not compile with Borland C++).
+
The argument is an expression involving an overloaded
+ function call (code compiles but the result is a garbage
+ value with Metroworks C++).
+
+
+
Don't use boost::is_convertible unless you have to
+
+
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).
The author must be willing to participate in discussions on the mailing
+ list, and to refine the library accordingly.
+
+
+
+
+ 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.
+
+ The preferred way to meet the license requirements is to use the Boost Software License. See license information. If for any reason you do not
+ intend to use the Boost Software License, please discuss the issues on the
+ Boost developers mailing list first.
+
+
+
+ The license requirements:
+
+
+
Must be simple to read and understand.
+
+
Must grant permission without fee to copy, use and modify the software
+ for any use (commercial and non-commercial).
+
+
Must require that the license appear on all copies of the software
+ source code.
+
+
Must not require that the license appear with executables or other
+ binary uses of the library.
+
+
+
Must not require that the source code be available for execution or
+ other binary uses of the library.
+
+
May restrict the use of the name and description of the library to the
+ standard version found on the Boost web site.
+
+ A library's interface must portable and not restricted to a particular
+ compiler or operating system.
+
+
+
+
+ A library's implementation must if possible be portable and not
+ restricted to a particular compiler or operating system. 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).
+
+
+
+
+
+ There is no requirement that a library run on C++ compilers which do
+ not conform to the ISO standard.
+
+
+
+
+
+ There is no requirement that a library run on any particular C++
+ compiler. Boost contributors often try to ensure their libraries
+ work with popular compilers. The boost/config.hpp configuration header is the preferred
+ mechanism for working around compiler deficiencies.
+
+
+
+
+ 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.
+
+ Otherwise reviewers may disbelieve that porting is in fact practical.
+
+ Are you sure you own the library you are thinking of
+ submitting? "How to Copyright Software" by MJ Salone, Nolo
+ Press, 1990 says:
+
+
+
+
+ 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.
+ In this situation, it's best to get a written release from your employer
+ in advance.
+
+
+
+ Place a copyright notice in all the important files you submit. Boost won't
+ accept libraries without clear copyright information.
+
+ Please use these guidelines as a checklist for preparing the content a
+ library submission. Not every guideline applies to every library, but
+ a reasonable effort to comply is expected.
+
Aim first for clarity and correctness; optimization should be only a
+ secondary concern in most Boost libraries.
+
+
+
+
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.
+
Follow quality programming practices. See, for example, "Effective C++"
+ 2nd Edition, and "More Effective C++", both by Scott Meyers, published by
+ Addison Wesley.
+
+
+
+
+
Use the C++ Standard Library or other Boost libraries, but only when
+ the benefits outweigh the costs. Do not use libraries other than the
+ C++ Standard Library or Boost. See Library
+ reuse.
+
+
+
+
Read Implementation Variation to see how to
+ supply performance, platform, or other implementation variations.
+
Names (except as noted below) should be all lowercase, with words
+ separated by underscores.
+
+
Acronyms should be treated as ordinary names (e.g.
+ xml_parser instead of XML_parser).
+
+
Template parameter names begin with an uppercase letter.
+
+
+
Macro (gasp!) names all uppercase and begin with BOOST_.
+
+
+
+
+
+
Choose meaningful names - explicit is better than implicit, and
+ readability counts. There is a strong preference for clear and descriptive
+ names, even if lengthy.
+
+
+
+
+
Use exceptions to report errors where appropriate, and write code that
+ is safe in the face of exceptions.
+
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:
+
End all documentation files (HTML or otherwise) with a copyright
+ message and a licensing message. See license
+ information page for the preferred form.
+
+
+
+
Begin all source files (including programs, headers, scripts, etc.)
+ with:
+
+
+
+
A comment line describing the contents of the file.
+
+
+
Comments describing copyright and licensing: again, the preferred
+ form is indicated in the license
+ information page
+
+
+ Note that developers should not provide a copy of
+ LICENSE_1_0.txt with their libraries: Boost
+ distributions already include a copy in the Boost root directory.
+
+
+
A comment line referencing your library on the Boost web site. For
+ example:
+
+
+ // See http://www.boost.org/libs/foo/ for library home
+ page.
+
+ where foo 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.
+
+
+
+
+
+
+
Make sure your code compiles in the presence of the min()
+ and max() macros. Some platform headers define
+ min() and max() macros which cause some common
+ C++ constructs to fail to compile. Some simple tricks can protect your code
+ from inappropriate macro substitution:
+
+
+
+
If you want to call std::min() or
+ std::max():
+
+
+
If you do not require argument-dependent look-up, use
+ (std::min)(a,b).
+
+
+
+
+
+
If you do require argument-dependent look-up, you should:
+
+
+
+
+
+
+ #include <boost/config.hpp>
+
+
Use BOOST_USING_STD_MIN(); to bring
+ std::min() into the current scope.
+
+
Use min BOOST_PREVENT_MACRO_SUBSTITUTION
+ (a,b); to make an argument-dependent call to
+ min(a,b).
+
+
+
+
+
+
+
+
+
+
If you want to call
+ std::numeric_limits<int>::max(), use
+ (std::numeric_limits<int>::max)() instead.
+
+
+
+
+
+
If you want to call a min() or max()
+ member function, instead to doing obj.min(), use
+ (obj.min)().
+
+
+
+
+
+
If you want to declare or define a function or a member function
+ named min or max, then you must use the
+ BOOST_PREVENT_MACRO_SUBSTITUTION macro. Instead of writing
+ int min() { return 0; } you should write int min
+ BOOST_PREVENT_MACRO_SUBSTITUTION () { return 0; }
+
+ 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.
+
File and directory names must contain only lowercase ASCII
+ letters , numbers, underscores, and a period. Leading character must
+ be alphabetic. Maximum length 31. Only a single period is permitted.
+ These requirements ensure file and directory names are relatively portable.
+
+
Files intended to be processed by a C++ compiler as part of a
+ translation unit should have a three-letter filename extension ending in
+ "pp". Other files should not use extensions ending in "pp". This
+ convention makes it easy to identify all of the C++ source in Boost.
+
+
+
All libraries have at their highest level a primary directory named for
+ the particular library. See Naming
+ consistency. The primary directory may have sub-directories.
+
+
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).
+
+
+
+
+ Boost standard sub-directory names
+
+
+
+
+
+ Sub-directory
+
+
+ Contents
+
+
+
+ Required
+
+
+
+
+ build
+
+
+
+ Library build files such as a Jamfile.
+
+
+ If any build files.
+
+
+
+
+
+ doc
+
+
+ Documentation (HTML) files.
+
+
+ If several doc files.
+
+
+
+
+
+ example
+
+
+ Sample program files.
+
+
+ If several sample files.
+
+
+
+
+
+ src
+
+
+ Source files which must be compiled to build the library.
+
+
+
+ If any source files.
+
+
+
+
+ test
+
+
+
+ Regression or other test programs or scripts.
+
+ 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 http://www.boost.org/libs/lib-name 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.
+
+
+ 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:
+
+
+
+
+<html>
+<head>
+<meta http-equiv="refresh" content="0; URL=doc/index.html">
+</head>
+<body>
+Automatic redirection failed, please go to
+<a href="doc/index.html">doc/index.html</a>
+
+</body>
+</html>
+
+ 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.
+
+
+
+ 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".
+
+
+
The library's primary directory (in parent boost-root/libs) is
+ given that same name. For example,
+ boost-root/libs/filesystem.
+
+
+
+
The library's primary header directory (in parent
+ boost-root/boost) is given that same name. For example,
+ boost-root/boost/filesystem.
+
+
+
The library's primary namespace (in parent ::boost) is given
+ that same name, except when there's a component with that name (e.g.,
+ boost::tuple), in which case the namespace name is pluralized. For
+ example, ::boost::filesystem.
+
+
+
+
+ When documenting Boost libraries, follow these conventions (see also the
+ following section of this document):
+
+
+
The library name is set in roman type.
+
+
The library name is capitalized.
+
+
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".
+
+
+
The word "library" is not part of the library name and is therefore
+ lowercased.
+
+
+
+ Here are a few examples of how to apply these conventions:
+
+
+
Boost.Bind was written by Peter Dimov.
+
+
The Boost Bind library was written by Peter Dimov.
+
+
+
I regularly use Bind, a Boost library written by Peter Dimov.
+
+ Even the simplest library needs some documentation; the amount should be
+ proportional to the need. The documentation should assume the readers
+ have a basic knowledge of C++, but are not necessarily experts.
+
+
+
+ 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 Redirection.
+
+
+ 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?
+
+
+ Appropriate topics for documentation often include:
+
+
+
+
General introduction to the library.
+
+
Description of each class.
+
+
Relationship between classes.
+
+
For each function, as applicable, description, requirements
+ (preconditions), effects, post-conditions, returns, and throws.
+
+
Discussion of error detection and recovery strategy.
+
+
+
How to use including description of typical uses.
+
+ Exception specifications [ISO 15.4] are sometimes coded to indicate what
+ exceptions may be thrown, or because the programmer hopes they will
+ improved performance. But consider the following member from a smart
+ pointer:
+
+
+ T& operator*() const throw() { return *ptr; }
+
+
+ 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. 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.
+
+
+
+ For example, some compilers turn off inlining if there is an
+ exception-specification. Some compilers add try/catch blocks. Such
+ pessimizations can be a performance disaster which makes the code unusable
+ in practical applications.
+
+
+ Although initially appealing, an exception-specification tends to have
+ consequences that require very 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.
+
+
+
+ A non-inline function is the one place a "throws nothing"
+ exception-specification may have some benefit with some compilers.
+
+ 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:
+
+
+
+
Naming conventions are contentious, and although several are widely
+ used, no one style predominates.
+
+
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.
+
+
Once a library settles on a particular convention, a vast majority of
+ stakeholders want that style to be consistently used.
+
+ 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.
+
+ Tabs are banned because of the practical problems caused by tabs in
+ multi-developer projects like Boost, rather than any dislike in principle.
+ See mailing list archives. 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.
+
+ Before the 1.29.0 release, two Boost libraries added ECMAScript/JavaScript
+ documentation. Controversy followed (see mailing list archives), and the developers
+ were asked to remove the ECMAScript/JavaScript. Reasons given for banning
+ included:
+
+
+
Incompatible with some older browsers and some text based browsers.
+
+
Makes printing docs pages difficult.
+
+
Often results in really bad user interface design.
+
+
+
"It's just annoying in general."
+
+
Would require Boost to test web pages for ECMAScript/JavaScript
+ compliance.
+
+
Makes docs maintenance by other than the original developer more
+ difficult.
+
+ Rationale is defined as "The fundamental reasons for something; basis" by
+ the American Heritage Dictionary.
+
+
+ Beman Dawes comments: 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.
+
+
+ Rationale is fairly easy to provide at the time decisions are made, but
+ very hard to accurately recover even a short time later.
+
+ As a library matures, it almost always accumulates improvements suggested
+ to the authors by other boost members. It is a part of the culture of
+ boost.org to acknowledge such contributions, identifying the person making
+ the suggestion. Major contributions are usually acknowledged in the
+ documentation, while minor fixes are often mentioned in comments within the
+ code itself.
+
Boost Library reuse: cost versus benefit trade-offs
+
A Boost library should not use libraries other than Boost or the C++
+Standard Library.
+
A Boost library should use other Boost Libraries or the C++ Standard
+Library, but only when the benefits outweigh the costs.
+
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.
+
The costs may include undesirable coupling between components, and added
+compilation and runtime costs. If the interface to the additional
+component is complex, using it may make code less readable, and thus actually
+increase development and maintenance costs.
+
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 <iostream> library
+below).
+
Example where another boost component should certainly be used:
+boost::noncopyable (in boost/utility.hpp) has
+considerable benefits; it simplifies code, improves readability, and signals
+intent. Costs are low as coupling is limited; noncopyable itself
+uses no other classes and its header includes only the lightweight headers
+<boost/config.hpp> and <cstddef>. 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.
+
Example where a standard library component might possibly be used:
+Providing diagnostic output as a debugging aid can be a nice feature for a
+library. Yet using Standard Library <iostream> can involves a lot of
+additional cost, particularly if <iostream> is unlikely to be use
+elsewhere in the application. In certain GUI or embedded applications,
+coupling to <iostream> would be a disqualification.
+Consider redesign of the boost library in question so that the user supplies the
+diagnostic output mechanism.
+
Example where another boost component should not be used: The
+boost dir_it library has considerable coupling and runtime costs, not to mention
+portability issues for unsupported operating systems. 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. C++ Standard Library file open functionality does this at
+lower cost. Don't use dir_it just for the sake of using a boost library.
The Boost Software License
+specifies the terms and conditions of use for those Boost libraries
+that it covers.
+
+
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, all libraries comply with the Boost License requirements.
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.
+
To clarify these licensing issues, the Boost moderators asked for help from
+the Berkman Center for Internet & Society
+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:
+
+
+
+
Must be simple to read and understand.
+
Must grant permission without fee to copy, use and modify the software for
+ any use (commercial and non-commercial).
+
Must require that the license appear with all copies [including
+ redistributions] of the software source code.
+
Must not require that the license appear with executables or other binary
+ uses of the library.
+
Must not require that the source code be available for execution or other
+ binary uses of the library.
+
+
+
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 Boost
+Software License.
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.
+
+
Benefit of Common Software License
+
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.)
+
[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.)
+
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.
+
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.
+
Short-Form License
+
Without in anyway detracting from the draft license that's been
+circulated [to Boost moderators], I'd like to propose an alternative "short-form" 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.
+
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).
+
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.
How should Boost programmers apply the license to source and
+header files?
+
+
Add a comment based on the following template, substituting
+appropriate text for the italicized portion:
+
+
+
+// Copyright Joe Coder 2004 - 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)
+
+
+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.
+
+
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.
+
+
How should the license be applied to documentation files, instead?
+
+
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.
+
+
Note that the location of the local LICENSE_1_0.txt needs to be indicated
+relatively to the position of your documentation file
+(../LICENSE_1_0.txt, ../../LICENSE_1_0.txt etc.)
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 "viral": 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.
+
+
Why the phrase "machine-executable object code generated by a source
+language processor"?
+
+
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.
+
+
Why is the "disclaimer" paragraph of the license entirely in uppercase?
+
+
Capitalization of these particular provisions is a US legal mandate for
+consumer protection. (Diane Cabell)
+
+
Does the copyright and license cover interfaces too?
+
+
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.
+
+
Why doesn't the license prohibit the copyright holder from patenting the
+covered software?
+
+
No one who distributes their code under the terms of this license could turn
+around and sue a user for patent infringement. (Devin Smith)
+
+
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.
+
+
Why doesn't the copyright message say "All rights reserved"?
+
+
Devin Smith says "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."
+
+
Do I have to copyright/license trivial files?
+
+
Even a test file that just contains an empty main()
+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.
+
+
+
Can I use the Boost license for my own projects outside Boost?
+
+
Sure; there are no restrictions on the use of the license itself.
+
+
To ease the transition of the code base towards the new common
+license, several people decided to give a blanket permission 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.
Dave Abrahams led the Boost effort to develop better licensing. The legal
+team was led by
+Diane Cabell,
+Director, Clinical Programs, Berkman
+Center for Internet & Society, Harvard Law School.
+Devin Smith, attorney,
+Nixon Peabody LLP, 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.
The C++ Source -
+ "The Premier Online Journal for the C++ Community".
+
+
Copies of the C++ Standard
+
+
+
+ ANSI Store - 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.
+
+
+ Book - 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.
Access to Boost mailing lists via newsgroup (NNTP) is contributed by
+ GMANE.
+
+
+
Before Posting
+
+
+
+ Read the Discussion Policy and
+ Guide to Effective Posting. 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.
+
+
+ Subscribe your posting address. 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. If you try to post from
+ an address that isn't subscribed, you will probably get a
+ message that says:
+
+
+ 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 atlist
+ administrator's email address.
+
If you need to post from multiple email addresses, you
+ should subscribe each one separately. You can configure your subscription
+ settings for any address to disable mail delivery via each mailing list's
+ web interface.
+
+
Even postings made through the GMane news server need to be made from
+ subscribed addresses because GMane simply forwards your postings
+ on to the appropriate email list. 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.
Boost Users mailing list (also available
+ via newsgroup)
+
+
This list is oriented toward casual users of the Boost
+ libraries. 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 Project-Specific list; you'll
+ often get better answers in a forum dedicated to your problem
+ area. This list is relatively
+ low volume (less than 500 per month). Subscribe or unsubscribe
+ at the Boost Users list
+ home page.
+
Boost developers mailing list (also
+ available via newsgroup)
+
+
This is the main Boost mailing list. 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. Virtually all Boost decisions,
+ major or minor, technical or otherwise, are reached via public discussion
+ on this mailing list. It is where the formal reviews of proposed
+ libraries take place. Subscribe or unsubscribe at http://lists.boost.org/mailman/listinfo.cgi/boost.
+
+
When we talk about the "members of Boost", we are talking about those
+ signed up for this main mailing list.
This is an announce-only list for notification of upcoming software
+ releases and formal reviews of proposed libraries. One to three messages
+ per month. Subscribe or unsubscribe at the Boost Announce
+ list home page.
+
+
Boost Interest Mailing List
+
+
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. Job postings
+ are accepted at the moderators' discretion. Subscribe or
+ unsubscribe at the Boost-Interest
+ home page.
The
+ Language
+ Binding list is for discussion of a generalized framework for
+ binding C++ to other languages and systems based on the technology of
+ Boost.Python and Luabind. The plan is to provide a
+ single front-end for describing bindings with runtime-pluggable back
+ ends for binding to specific languages. It is highly recommended
+ that new subscribers read through the
+ message historyfrom the beginning before posting; it will
+ save time as much design progress has already been made. GMane provides
+ NNTP
+ access and
+ Searchable Archives as well.
+
+
+
A seperate developer mailing list for Boost Thread specific topics is
+ located
+ here.
+
Important: This mailing list is for the discussion of
+ the specification and implementation of Boost.Threads only —
+ questions regarding usage should be directed to the
+ Boost Users list, or the main
+ Boost developers list.
+
+
+
The setup, procedures and tools necessary for running Boost
+ regression tests are discussed on this
+ list. 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.
+
+
Important: 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.
In addition to the main Boost CVS
+ repository, a separate Sandbox is available for Boost developers
+ wishing to collaborate on projects prior to formal acceptance of a new
+ library. Read-only access is available via Subversion and web browser at
+ http://svn.boost.org/svn/boost/sandbox.
+
+
In addition to the mailing lists presented above, a #boost IRC channel on
+ freenode 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.
+
+
+
Revised
+ 04 December, 2005
+
+
Copyright Beman Dawes and David Abrahams 2001-2005
Similar to the portability hints for Borland
+ C++, 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 Microsoft
+ support site.
+
+
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.
+
+
Preprocessor symbol
+
+
The preprocessor symbol _MSC_VER 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 BOOST_MSVC,
+ which is defined in boost/config.hpp to
+ the value of _MSC_VER if and only if the compiler is really Microsoft
+ Visual C++. The following table lists some known values.
+
+
+
+
Compiler
+
+
BOOST_MSVC value
+
+
+
+
Microsoft Visual C++ 6.0 (up to SP6)
+
+
1200
+
+
+
+
Microsoft embedded Visual C++ 4.0
+
+
1200-1202 (cross compilers)
+
+
+
+
Core Language
+
+
[chained using] Chaining using-declarations
+
+
Chaining using-declarations does not work.
+
+void f();
+
+namespace N {
+ using ::f;
+}
+
+void g()
+{
+ using N::f; // C2873: 'f': the symbol cannot be used in a using-declaration
+}
+
+
+
[explicit-instantiation] Explicit function template instantiation
+
+
Trying to explicitly instantiate a function template leads to the wrong
+ function being called silently.
The scope of variable definitions in for loops should be
+ local to the loop's body, but it is instead local to the enclosing
+ block.
+
+int main()
+{
+ for(int i = 0; i < 5; ++i)
+ ;
+ for(int i = 0; i < 5; ++i) // C2374: 'i': Redefinition; multiple initialization
+ ;
+ return 0;
+}
+
+
+
Workaround: Enclose the offending for
+ loops in another pair of curly braces.
+
+
Another possible workaround (brought to my attention by Vesa Karvonen)
+ is this:
+
+#ifndef for
+#define for if (0) {} else for
+#endif
+
+
+
Note that platform-specific inline functions in included headers might
+ depend on the old-style for scoping.
+
+
[inclass-member-init] In-class member initialization
+
+
In-class member initialization, required to implement a
+ Standard-conforming std::numeric_limits template, does not
+ work.
+
+struct A
+{
+ static const int i = 5; // "invalid syntax for pure virtual method"
+};
+
+
+
Workaround: 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 Coding Guidelines for Integral Constant
+ Expressions for guidelines how to define member constants portably in
+ boost libraries.
+
+
[koenig-lookup] Argument-dependent lookup
+
+
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.
Workaround: Define member templates in-line within
+ their enclosing class.
+
+
[partial-spec] Partial specialization
+
+
Partial specialization of class templates does not work.
+
+template<class T>
+struct A {};
+
+template<class T>
+struct B {};
+
+template<class T>
+struct A<B<T> > {}; // template class was already defined as a non-template
+
+
+
Workaround: In some situations where interface does not
+ matter, class member templates can simulate partial specialization.
+
+
[template-value] Dependent template value parameters
+
+
Template value parameters whose type depends on a previous template
+ parameter provoke an internal compiler error if the correct syntax (with
+ "typename") is used.
+
+template<class T, typename T::result_type> // C1001: INTERNAL COMPILER ERROR: msc1.cpp, line 1794
+struct B {};
+ // (omit "typename" and it compiles)
+
+
+
+
Workaround: Leave off the "typename" keyword. That
+ makes the program non-conforming, though.
+
+
[wchar_t] wchar_t is not built-in
+
+
The type wchar_t is not a built-in type.
+
+wchar_t x; // "missing storage class or type identifier"
+
+
+
Workaround: When using Microsoft Visual C++, the header
+ boost/config.hpp includes
+ <cstddef>, which defines wchar_t as a
+ typedef for unsigned short. Note that this means that the
+ compiler does not regard wchar_t and unsigned
+ short as distinct types, as is required by the standard, and so
+ ambiguities may emanate when overloading on wchar_t. The macro
+ BOOST_NO_INTRINSIC_WCHAR_T is defined in this situation.
+
+
[delete-const-pointer] Deleting const X * does not
+ work
+
+
Trying to delete a pointer to a cv-qualified type gives an error:
+
+void f()
+{
+ const int *p = new int(5);
+ delete p; // C2664: cannot convert from "const int *" to "void *"
+}
+
+Note: 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
+boost-users-owner@lists.boost.org.
+The moderators of every other Boost list can be reached
+through its home page.
+
+
+
Moderator Functions
+
+
Monitor the mailing list to ensure dialog remains within the acceptable
+ boundaries set by the discussion policy.
+ When discussion strays, use private email to gently remind, strongly rebuke,
+ or outright ban, as the situation demands.
+
+
+
Approve the initial postings of new (and thus still moderated) members,
+ and move members to the "Group Policy" posting status.
+
+
+
Administer the internal operations of the Boost web site, the main Boost
+ mailing list, the CVS repository, and other Boost administrative machinery.
+
+
+
Act as an executive committee overseeing important administrative and
+ policy decisions. 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.
+
+
+
Beyond the purely administrative duties, work to keep the Boost community
+ vibrant and alive. That may be as simple as saying "thank you" to
+ an individual member, or as complex as starting some major new
+ initiative. Do whatever it takes!
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.
Remove the oldest "Latest News" from root/index.htm.
+
+
For each new library added this release:
+
+
+
+
Verify root/index.htm Latest News entry has been made and reads well.
+
+
Verify root/libs/libraries.htm entry has been made, both in the
+ alphabetic list and in the category lists.
+
+
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. To do:
+ automate this.
+
+
Skim read the primary docs pages to make sure they meet Boost
+ requirements and guidelines. Don't leave this until too late; it has
+ turned up lots of issues in the past.
+
+
Generate the header dependency table and update the CVS. To do:
+ coordinate with John Maddock's new dependency tools.
Boost errors are being actively worked on by library maintainers.
+
Compiler or standard library errors are at least identified, and
+ preferably reported to the supplier.
+
No errors remain uninvestigated or unclassified.
+
+
+
+
Monitor the developer and user mailing lists to verify that all posted
+ patches are being applied, rejected, or otherwise dealt with.
+
+
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.
+
+
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.
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
+ "overwrite existing tags with the same name".
These procedures are given for a particular release manager's machine. The
+plan is to replace them with more generic procedures over time.
+
+
Create folders for export:
+
+ c:\boost\boost_1_28_0
+ c:\boost\temp\boost_1_28_0
+
+ Note that several batch files assume these locations and naming schemes.
+
+
Export Win32 distribution: WinCVS | Remote | Checkout Module
+
+ Checkout settings: module name and path on the server: boost, local folder to
+ checkout to: c:\boost\boost_1_28_0
+ [for 1.29.0 export, put everything in a boost_1_29_0/boost subdirectory.
+ Experiments with 1.30.0 tried boost/boost as the path on server, but that just
+ resulted in getting the boost header subdirectory only.]
+
+ Checkout options: (check) By revision/tab/branch: Version_1_28_0, (check) Do
+ not create CVS directories (export)
+
+ This results in the follow command: cvs -z9 export -r Version_1_28_0 boost (in
+ directory C:\boost\boost_1_28_0)
+
+ (takes about ten minutes)
+
+ (rename boost-root if needed !!!!!!!!!!!!!!!!!!!)
+
+
Export Unix distribution: similar to above, except target is c:\boost\temp\boost_1_28_0
+ and set global for UNIX nl.
+
+
!!!!!! VERY IMPORTANT: WinCVS | Set Preferences | Global back to non-UNIX nl.
+ !!!!!!!!!!!!!!!
+
+
Add regression results web pages into package (new in 1.33 so this is just a shot at the process - jeff)
+ download all the regression results from website (may need meta-comm help on this)
+ unpack the regression results into tools/regression/latest_release
+
+
+
+
General ZIP and TAR.GZ files
+
+ n_n_n is 1_28_0 or whatever
+
+ cd \boost
+ boost_zip 1_21_2 (creates zip.log)
+ boost_tar_gz 1_21_2
+ bash
+
+ gunzip -c boost_1_21_2.tar.gz | bzip2 > boost_1_21_2.tar.bz2
+ exit
+
+
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).
+
+
Upload files for SourceForge release incoming directory using WS_FTP Pro
+
Start keep_isdn_awake
+
Connection: SourceForge Release Upload | connect
+
Select Local system: c:\boost
+
Select Remote system: /incoming
+
Drag-and-drop the three release files from Local system to Remote system
Check SourceForge release page and release notes with web browser.
+
+
+
+
Consider putting up a temporary "Update in progress" root/index.html
+ during site update
+
+
Update the web site:
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
+
+
Check actual www.boost.org site with
+ browser. Look at a bunch of files that should have been updated to make sure
+ the updates actually "took".
+
+
Post a message announcing the release and recapping "Latest News".
+ Post as separate messages to: boost, boost-announce, boost-users,
+ comp.lang.c++.moderated,
+ c++std-news@research.att.com
+
+
Using the SourceForge shell services (sf_shell_svc.bat), cd /home/groups/b/bo/boost/htdocs,
+ and rename regression tests as necessary.
+
+
Burn "Key Directories" CD for off-site backup.
+
+
Make sure CVS working copy is updated to main branch!
+
+
Ready root/index.htm, root/boost/version.hpp, root/Jamfile.v2 and
+ root/Jamrules for the
+ next release and commit to CVS so developers have a place to add "Latest news"
+ blurbs.
+
+
Delete obsolete files from yahoogroups files section.
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.
+
Boost developers assist the release manager by reviewing regression test
+logs, and committing fixes to CVS.
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.
+
+
If you know of changes in either your code or its dependencies, start
+ checking regression test results to ensure your tests still pass. Don't
+ necessarily wait for the initial release tagging.
+
+
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.
+
+
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.
+ 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.
+
+
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 tag rationale.
+
+ 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:
+
+
+
+
Command Line CVS:
+
+
+
+
Fixed code is committed to main branch
+
+
Switch to the release candidate branch
+
+ cvs update -r RC_1_26_2
+
+
Merge changes in a trunk since previous merge to branch
+
+
cvs update -jmerged_to_RC_1_26_2 -jHEAD buggycode.hpp
+ --> RCS file: /cvsroot/boost/.../buggycode.hpp,v
+ --> retrieving revision 1.4
+ --> retrieving revision 1.6
+ --> Merging differences between 1.4 and 1.6 into buggycode.hpp
+
+
+
Commit merged branch
+
+
cvs commit -m "Merged fix for problem xyz from trunk to branch" buggycode.hpp
+
+
+
Go back to main trunk
+
+
cvs update -A
+
+
+
Move tag to a new merged point
+
+
cvs tag -F -c merged_to_RC_1_28_2 buggycode.hpp
+
+
+
Repeat as needed
+
+
+
+
+
WinCVS:
+
+
+
+
After fixed code is committed to main branch, switch to the release
+ candidate branch:
Merge changes from main trunk into the release candidate branch:
+
+
+
+
Modify | Update selection... |
+ Update settings | Merge options | Only this rev/tag:
+ merged_to_RC_1_26_2
+ | Plus with this rev/tag: HEAD | OK
+
+
+
+
Commit merge results:
+
+
+
+
Modify | Commit... | Enter log message: ... | OK
+
+
+
+
Go back to main trunk:
+
+
+
+
Modify | Update selection... | Update settings | Reset any sticky
+ date/tag/-k options | OK
+
+
+
+
Tag as new merge point:
+
+
+
+
Modify | Create tag on selection... | Create tag settings | Enter the tag
+ name to create: merged_to_RC_1_26_2, Overwrite existing tags
+ with same name | OK.
What is the purpose of the
+merged_to_RC_n_n_n tag? This tag allows multiple merges from the
+main trunk to the release candidate branch. Without it, merging an initial main
+trunk fix 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.
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.
April 1, 2006 -- The "Promotion Traits" Review Begins (Fast-Track)
+Proposal to add promote, integral_promotion and
+floating_point_promotion class templates to type_traits library.
+
April 6, 2006 -- The "Function Types" 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.
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 "garcia at cs dot indiana dot edu"
+and "reportbase at gmail dot com" respectively.
+
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.
+
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.
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).
+
The classes introduced by this library shall conform to the
+concepts of the Boost Metaprogramming library (MPL).
+
+
The Function Types library enables the user to:
+
+
test an arbitrary type for being a function type of specified kind,
+
inspect properties of function types,
+
view and modify sub types of an encapsulated function type with
+MPL Sequence operations, and
+
synthesize function types.
+
+
+
+
This library supports variadic functions and can be configured
+to support non-default calling conventions.
Proposal to add promote, integral_promotion and
+floating_point_promotion class templates to type_traits library.
+
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
+
See comments at the beginning of
+promote_enum_test.cpp for what is broken.
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.
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.
+
The architecture is somewhat modeled after MPL which in turn is
+modeled after STL. It is code-named "fusion" because the library is
+the "fusion" of compile time metaprogramming with runtime programming.
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.
Property tree is a data structure - a tree of (key, value)
+pairs. It differs from its cousin, "usual" 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.
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.
Happy New Year! Here are some statistics regarding Boost Library
+reviews in 2005:
+
+
+
12 Libraries were reviewed
+
8 Libraries were accepted
+
1 Library (Function Types) was accepted pending a mini-review
+
2 Libraries were rejected
+
1 Library has yet to receive a final verdict (ASIO)
+
+
+
Policy Pointer has been removed from the review queue because the author has
+stated that it is not quite ready.
+
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.
+
+
Note:
+
If you have any suggestions about how we could improve
+the Review Wizard's status report,
+please email "reportbase at gmail dot com"
+and "garcia at cs dot indiana dot edu".
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.
+
The following libraries still require review managers:
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.
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.
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).
+
+
The classes introduced by this library
+
shall conform to the concepts of the
+Boost Metaprogramming library (MPL).
+
+
The Function Types library enables the user to:
+
+
test an arbitrary type for
+being a function type of specified kind,
+
inspect properties of function types,
+
view and modify sub types of an
+encapsulated function type with
+MPL Sequence operations, and
+
synthesize function types.
+
+
+
This library supports variadic functions and
+
can be configured to support
+non-default calling conventions.
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.
+
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.
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.
+
The architecture is somewhat modeled after MPL which in turn is
+modeled after STL. It is code-named "fusion" because the library is
+the "fusion" of compile time metaprogramming with runtime programming.
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.
Proposal to add promote, integral_promotion and
+floating_point_promotion class templates to type_traits library.
+
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
If you have an idea for a feature or improvement to an existing Boost library
+- go ahead and post it to either
+boost-users list
+or boost mailing list
+(if you are posting for the first time, please read our
+discussion policy
+before you actually post).
+
You can also use our
+feature request tracking facility 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.
+
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
+
+Acknowledgements section!
+
+
+
+
\ No newline at end of file
diff --git a/more/separate_compilation.html b/more/separate_compilation.html
new file mode 100644
index 0000000000..3121aa4c6a
--- /dev/null
+++ b/more/separate_compilation.html
@@ -0,0 +1,385 @@
+
+
+
+ Guidelines for Authors of Boost Libraries Containing Separate Source
+
+
+
+
+
+
+
+
+
+
Guidelines for Authors of Boost Libraries Containing Separate
+ Source
+
+
+
+
+
+
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.
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:
+
-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).
+
+
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!
+
+
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.
+
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:
+
#ifndef BOOST_WHATEVER_HPP
+#define BOOST_WHATEVER_HPP
+
+#include <boost/config.hpp>
+
+// 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
+
+
You can include this code in your library source files as well if you want,
+ although you probably shouldn't need to:
+
+
+ If you don't
+ 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.
+
+ If you do 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.
+
Rationale:
+
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.
+
Counter Argument #1:
+
Trust the user, if they want 13-byte alignment (!) let them have it.
+
Counter Argument #2:
+
Prefix/suffix headers have a tendency to "spread" to other boost libraries -
+ for example if boost::shared_ptr<> 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.
+
Static or Dynamic Libraries
+
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). So we have a choice
+ as to which is supported by default:
+
+
+ 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.
+
+ 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.
+
+ 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).
+
The recomendation is to pick static linking by default.
+
Rationale:
+
There is no one policy that fits all here.
+
+
The rationale for the current behaviour was inherited from Boost.Regex (and
+ it's ancestor regex++): this library 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, this
+ behavior brought a persistent stream of user complaints: mainly about
+ deployment, all asking if static linking could be the default. After regex
+ changed behavior the complaints stopped, and the author hasn't had one
+ complaint about static linking by default being the wrong choice.
+
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.
+
Supporting Windows Dll's
+
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).
+
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:
+
#ifndef BOOST_WHATEVER_HPP
+#define BOOST_WHATEVER_HPP
+
+#include <boost/config.hpp>
+
+#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
+
+ And then in the source code for this library one would use:
+
+//
+// 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 <boost/whatever.hpp>
+
+// class members don't need any further annotation:
+whatever::whatever() { }
+// but functions do:
+BOOST_WHATEVER_DECL whatever get_whatever()
+{
+ return whatever();
+}
+
+
Importing/exporting dependencies
+
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:
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.
+
+
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.
+
Rationale:
+
Why bother - doesn't the import/export mechanism take up more code that the
+ classes themselves?
+
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.
+
Why static linking by default?
+
+
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).
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:
The difficulty now is selecting which of these the user should link his or her
+ code to.
+
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.
+
+
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.
+
Automatic library selection and linking can be enabled for a Boost library by
+ including the header <boost/config/auto_link.hpp>, after first defining
+ BOOST_LIB_NAME and, if applicable, BOOST_DYN_LINK.
+
//
+// Automatically link to the correct build variant where possible.
+//
+#if !defined(BOOST_ALL_NO_LIB) && !defined(BOOST_WHATEVER_NO_LIB) && !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 <boost/config/auto_link.hpp>
+#endif // auto-linking disabled
+
+
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:
+
If for any reason you need to debug this feature, the header
+ <boost/config/auto_link.hpp> will output some helpful diagnostic messages
+ if you first define BOOST_LIB_DIAGNOSTIC.
+
Changes Affecting the Build System
+
Creating the library Jamfile
+
The Jamfile for building library "whatever" typically lives in
+ boost-root/libs/whatever/build, the only extra step required is to add a
+ <define> 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:
Testing the auto-link feature is somewhat convoluted, and requires access
+ to a compiler that supports the feature: refer to
+ libs/config/test/link/test/Jamfile.v2 for an example.
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.
+
+
diff --git a/more/space.gif b/more/space.gif
new file mode 100644
index 0000000000..f37c0249d5
Binary files /dev/null and b/more/space.gif differ
diff --git a/more/submission_process.htm b/more/submission_process.htm
new file mode 100644
index 0000000000..9a8108aeb3
--- /dev/null
+++ b/more/submission_process.htm
@@ -0,0 +1,133 @@
+
+
+
+
+
+
+
+Boost Library Submission Process
+
+
+
+
+
Subscribe to the main developers mailing list for a
+while, or look through the archives.
+Click around the web site. Understand the Requirements.
+Read the rest of this page to learn about the process. Otherwise, you will
+just end up wasting everyone's time.
+
There is a culture associated with Boost, aimed at encouraging high quality
+libraries by a process of discussion and refinement.
+
If what you really want is a site that will just post your library without
+even looking at it, you should go elsewhere.
Potential library submitters should use the Boost developers mailing
+list as a forum to gauge interest a possible submission.
+
A message might be as simple as "Is there any interest in a library
+which solves Traveling Salesperson problems in linear time?"
+
A bit of further description or snippet of code may be helpful. Messages
+should be plain text; not rich text, HTML, etc.
+
Please don't post lengthy descriptions, documentation, or code to the mailing
+list, and no attachments, even small ones. Please post lengthy material in
+the Boost Vault.
If response to an initial query indicates interest, then post the preliminary
+submission files in the Boost Vault on
+the sourceforge web site if you haven't already done so.
Discuss, refine, resubmit. Repeat until satisfied.
+
The exact details of this process varies a lot. Sometimes it is public,
+on the mailing list, sometimes a lot of discussion happens in private
+emails. For some libraries the process is over quickly, for others it goes
+on for months. It's often challenging, and sometimes leads off in
+completely unexpected directions.
+
The archive of past
+messages is one way to see how this process worked for other Boost
+libraries.
All of the files which make up the library should be combined and compressed
+into a single submission file using the .zip format. Free encoders
+and decoders for this format running on many different platforms are available
+at the Info-ZIP web site, which
+includes a FAQ and much other useful information about the .zip format. Many
+commercial compressor-archiver utilities also support this format.
+
The submission file should contain material as if on the
+boost.org web site. The closer the submission file mirrors the final
+directory
+structure and format of the web site, the better.
+
Like a preliminary submission, post the final submission .zip file in the Boost Vault.
+
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. This flushes out obvious
+portability problems. If you don't have access to a second compiler, ask
+for help on the Boost mailing list.
+
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. Please use a subject in
+the form "Review Request: library" where library is replaced by
+the library name.
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.
If the boost.org web site doesn't already have your capsule biography
+and 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. The preferred picture format is .jpg, but other
+common formats are acceptable. The preferred image size is 500x375 but the
+webmaster has photo editing software and can do the image preparation if
+necessary.
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.
The Boost libraries are intended to be both reliable and portable.
+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.
+
"Quality assurance based on a wide range of targeted tests" as one
+of the key answers to C.A.R
+Hoare's question
+"How did software get so reliable without proof."
Every Boost library should supply one or more suitable test programs to be
+ exercised by the Boost regression test suite. 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.
+
Test program execution must report errors by returning a non-zero value. They
+ may also write to stdout or stderr, but that output should be relatively
+ brief. Regardless of other output, a non-zero return value is the only
+ way the regression test framework will recognize an error has
+ occurred. 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.
+
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. 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.
+
If for any reason the usual test policies do not apply to a particular
+ library, an alternate test strategy must be implemented.
+
A Jamfile to drive the
+ regression tests for the library.
+
+
Optional (but highly recommended)
+
The Boost Test Library provides many
+useful components which ease the construction of test programs.
+
+
Use the library's
+ Test Tools for the construction of simple test
+ programs that do not need much structure.
+
Use the library's
+ Unit Test
+ Framework for the construction of more complex test programs that need to
+ be structured into individual tests
+ and test suites.
+
+
Suggested Protocol for Fixing Bugs or Adding Features.
+
+
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.
+
Second, for bugs, run the regression test and verify that the bug is now
+ detected.
+
Third, then, and only then, fix the bug or add the feature.
+
Finally, rerun the full regression tests - sometimes the change breaks
+ something else.
Any boost developer can update the Boost website content between
+ releases.
+
+
+
We strongly recommend the use of HTML Tidy when editing HTML and XHTML
+ files intented for the website. Using tidy 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 tidy. Most pages are regular HTML 3.x/4.x,
+ for these use a tidy invocation of:
+
+tidy --tidy-mark no -i -wrap 78 -m some_page.html
+
Other pages are using the more recent XHTML 1.0 and XHTML 1.0 Strict
+standards. Most notably this include the home
+page. Some additional options are needed to make tidy
+enforce the XHTML standard:
+
+tidy --tidy-mark no -i -wrap 78 -m -asxhtml some_page.html
+
That command is also useful if one is converting from HTML to XHTML. To
+have tidy check for the XHTML 1.0 Strict format use:
+
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.
+
+
+
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.
+
+
You will upload the file(s) by scp'ing to the
+ appropriate subdirectory of
+ shell.sf.net:/home/groups/b/bo/boost/htdocs/. For example,
+ to update the page you are reading, I would issue
+
It is crucial 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 chmod command
+ before uploading the file. The absolutely failsafe thing to do is to
+ ssh into shell.sf.net and do the chmod 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.
+
This is a bug fix release addressing many problems with the 1.34.0 release.
+ It is a recommended upgrade for all users of Boost 1.34.0. For a complete list of fixes see
+ Boost Trac.
+
+
Supported Compilers
+
+
New in this release is improved support for
+ the IBM XL C/C++ compiler.
+
+
Boost is tested on a wide range of compilers and
+ platforms. Since Boost libraries rely on modern C++
+ features not available in all compilers, not all
+ Boost libraries will work with every compiler.
+ New in this release The
+ following compilers and platforms have been
+ extensively tested with Boost, although many other
+ compilers and platforms will work as well. For more
+ information, see the regression
+ test results.
Microsoft
+ Visual C++ 6.0 (sp5, with and without STLport),
+ 7.0, 7.1, 8.0. Note: Boost does not support the
+ non-standard "Safe" C++ Library shipping with
+ Visual C++ 8.0, which may result in many spurious
+ warnings from Boost headers and other
+ standards-conforming C++ code. To suppress these
+ warnings, define the macro
+ _SCL_SECURE_NO_DEPRECATE.
A great number of people contributed their time
+ and expertise to make this release possible. Special
+ thanks go to Kim Barrett consolidating Boost.Iostreams changes
+ from various branches and Rene Rivera for general build and installation
+ support.
+
+
+
+
1.34.0 (12 May 2007)
+
New Libraries
+
+
+
Foreach Library:
+ BOOST_FOREACH macro for easily iterating
+ over the elements of a sequence, from Eric
+ Niebler.
+
+
Statechart
+ Library: Arbitrarily complex finite state
+ machines can be implemented in easily readable and
+ maintainable C++ code, from Andreas Huber.
+
+
TR1 Library: An
+ implementation of the C++ Technical Report on
+ Standard Library Extensions, from John Maddock.
+ This library does not itself implement the TR1
+ components, rather it's a thin wrapper that will
+ include your standard library's TR1 implementation
+ (if it has one), otherwise it will include the
+ Boost Library equivalents, and import them into
+ namespace std::tr1. Highlights
+ include: Reference Wrappers, Smart Pointers,
+ result_of, Function Object Binders, Polymorphic
+ function wrappers, Type Traits, Random Number
+ Generators and Distributions, Tuples, Fixed Size
+ Array, Hash Function Objects, Regular Expressions,
+ and Complex Number Additional Algorithms.
+
+
Typeof
+ Library: Typeof operator emulation,
+ from Arkadiy Vertleyb and Peder Holt.
+
+
Xpressive
+ Library: Regular expressions that can be
+ written as strings or as expression templates, and
+ that can refer to each other and themselves
+ recursively with the power of context-free
+ grammars, from Eric Niebler.
Function
+ Library: Boost.Function now implements a
+ small buffer optimization, which can drastically
+ improve the performance when copying or
+ constructing Boost.Function objects storing small
+ function objects. For instance,
+ bind(&X:foo, &x, _1, _2)
+ requires no heap allocation when placed into a
+ Boost.Function object.
MultiArray
+ Library: Boost.MultiArray now by default
+ provides range-checking for
+ operator[]. Range checking can be
+ disabled by defining the macro
+ BOOST_DISABLE_ASSERTS before including
+ multi_array.hpp. A bug in
+ multi_array::resize() related
+ to storage orders was fixed.
Exceptions can be disabled by defining the
+ macro BOOST_PTR_CONTAINER_NO_EXCEPTIONS before
+ including any header. This macro is defined by
+ default if BOOST_NO_EXCEPTIONS is defined.
+
+
Additional
+ std::auto_ptr<T> overloads
+ added s.t. one can also pass
+ std::auto_ptr<T> instead of
+ only T* arguments to member
+ functions.
+
+
transfer() now has weaker
+ requirements s.t. one can transfer objects from
+ ptr_container<Derived> to
+ ptr_container<Base>,
Boost.Python now automatically appends C++
+ signatures to docstrings. The new
+ docstring_options.hpp header is
+ available to control the content of
+ docstrings.
+
+
+ stl_input_iterator, for
+ turning a Python iterable object into an STL
+ input iterator, from Eric Niebler.
+
+
Support for void* conversions
+ is added.
+
+
Integrated support for wrapping C++
+ functions built with the parameter library;
+ keyword names are automatically known to
+ docsstrings.
+
+
Enhancements to the API for better embedding support
+ (boost::python::import(),
+ boost::python::exec(),
+ and boost::python::exec_file()).
+
+
+
+
+
Signals Library:
+ More improvements to signal invocation performance from
+ Robert Zeh.
Wave now correctly recognizes pp-number
+ tokens as mandated by the C++ Standard, which
+ are converted to C++ tokens right before they
+ are returned from the library.
+
+
Several new preprocessing hooks have been
+ added. For a complete description please refer
+ to the related documentation page: The
+ Context Policy.
+
+
Shared library (dll) support has been added
+ for the generated Wave libraries.
+
+
The overall error handling has been
+ improved. It is now possible to recover and
+ continue after an error or a warning was
+ issued.
+
+
Support for optional comment and/or full
+ whitespace preservation in the generated output
+ stream has been added.
+
+
The Wave library now performs automatic
+ include guard detection to avoid accessing header
+ files more than once, if appropriate.
+
+
Full interactive mode has been added to the Wave
+ tool. Now the Wave tool can be used just like Python
+ or Perl for instance to interactively try out your
+ BOOST_PP macros. Additionally it is now possible to
+ load and save the current state of an interactive session
+ (macro tables et.al.).
+
+
The overall performance has been improved by upto
+ 40-60%, depending on the concrete files to process.
+
+
Support for new pragmas has been added allowing to
+ control certain library features from inside the
+ preprocessed sources (partial output redirection,
+ control of generated whitespace and #line directives).
+
+
Optional support for #pragma message "..."
+ has been added.
+
+
This version also includes a number of bug
+ fixes and usage improvements. For a complete
+ list of changes, see the libraries change log.
+
+
+
+
+
Supported Compilers
+
+
Boost is tested on a wide range of compilers and
+ platforms. Since Boost libraries rely on modern C++
+ features not available in all compilers, not all
+ Boost libraries will work with every compiler. The
+ following compilers and platforms have been
+ extensively tested with Boost, although many other
+ compilers and platforms will work as well. For more
+ information, see the regression
+ test results.
Microsoft
+ Visual C++ 6.0 (sp5, with and without STLport),
+ 7.0, 7.1, 8.0. Note: Boost does not support the
+ non-standard "Safe" C++ Library shipping with
+ Visual C++ 8.0, which may result in many spurious
+ warnings from Boost headers and other
+ standards-conforming C++ code. To suppress these
+ warnings, define the macro
+ _SCL_SECURE_NO_DEPRECATE.
A great number of people contributed their time
+ and expertise to make this release possible. Special
+ thanks go to Vladimir Prus for making Boost.Build version 2
+ a reality, David Abrahams for authoring a new getting
+ started guide and Greg D. for answering
+ countless questions.
+
+
+
+
+
1.33.1 (5 Dec 2005)
+
Updated Libraries
+
+
+
Any Library: Cast to
+ reference types introduced in 1.33.0 is now
+ documented on any_cast documentation
+ page.
The build now assumes Python 2.4 by
+ default, rather than 2.2
+
+
Support Python that's built without Unicode
+ support
+
+
Support for wrapping classes with
+ overloaded address-of (&)
+ operators
+
+
+
+
Smart Pointer
+ Library: Fixed problems under Metrowerks
+ CodeWarrior on PowerPC (Mac OS X) with inlining on,
+ GNU GCC on PowerPC 64.
+
+
Regex
+ Library: Fixed the supplied makefiles,
+ and other small compiler specific changes. Refer to
+ the regex
+ history page for more information on these and
+ other small changes.
+
+
Iostreams
+ Library: Improved the interface for
+ accessing a chain's components, added
+ is_open members to the file and file
+ descriptor devices, fixed memory-mapped files on
+ Windows, and made minor changes to the
+ documentation.
Added color_map parameter to
+ dijkstra_shortest_paths.
+
+
+
+
Signals
+ Library: Fixed problems with the use of
+ Signals across shared library boundaries.
+
+
Thread
+ library:read_write_mutex
+ has been removed due to problems with
+ deadlocks.
+
+
Wave library
+ (V1.2.1) Fixed a couple of problems, refer
+ to the change log
+ for further details.
+
+
+
Supported Compilers
+
+
Boost is tested on a wide range of compilers and
+ platforms. Since Boost libraries rely on modern C++
+ features not available in all compilers, not all
+ Boost libraries will work with every compiler. The
+ following compilers and platforms have been
+ extensively tested with Boost, although many other
+ compilers and platforms will work as well. For more
+ information, see the regression
+ test results.
+
+
New for this release: Support for building
+ with the newest STLport-5.0 was added. The support
+ includes building with MinGW Runtime 3.8 plus
+ STLport-5.0 improved to support wide character
+ operations. Apple GCC 4.0, HP Tru64 C++, and
+ Microsoft Visual C++ 8.0 are supported platforms. We
+ have added an experimental autoconf-like
+ configure script for Unix-like systems:
+ run configure --help for more
+ information.
Microsoft
+ Visual C++ 6.0 (sp5, with and without STLport),
+ 7.0, 7.1, 8.0. Note: Boost does not support the
+ non-standard "Safe" C++ Library shipping with
+ Visual C++ 8.0, which may result in many spurious
+ warnings from Boost headers and other
+ standards-conforming C++ code. To suppress these
+ warnings, define the macro
+ _SCL_SECURE_NO_DEPRECATE.
A great number of people contributed their time
+ and expertise to make this release possible. Special
+ thanks go to Aleksey Gurtovoy and Misha Bergal, who
+ managed to keep the regression testing system working
+ throughout the release process; David Abrahams, Beman
+ Dawes, Aleksey Gurtovoy, Bronek Kozicki, Rene Rivera
+ and Jonathan Turkanis for greatly improving the
+ quality of this release; Rene Rivera for the new
+ Boost web page design; and Zoltan "cad" Juhasz for
+ the new Boost logo.
+
+
+
1.33.0 (11 Aug 2005)
+
+
New Libraries
+
+
+
Iostreams
+ Library: Framework for defining streams,
+ stream buffers and i/o filters, from Jonathan
+ Turkanis.
+
+
Functional/Hash
+ Library: A TR1 hash function object that can
+ be extended to hash user defined types, from Daniel
+ James.
+
+
Parameter
+ Library: Write functions that accept
+ arguments by name: especially useful when a function
+ has more than one argument with a useful default value,
+ since named arguments can be passed in any order.
+
+
Pointer Container
+ Library: Containers for storing
+ heap-allocated polymorphic objects to ease
+ OO-programming, from Thorsten Ottosen.
+
+
Wave: Standards
+ conformant implementation of the mandated C99/C++
+ preprocessor functionality packed behind an easy to use
+ iterator interface, from Hartmut Kaiser.
+
+
+
Updated Libraries
+
+
+
Any Library:
+ any_cast has been enhanced to allow direct
+ access to any's held value.
gursoy
+ atun layout, from Jeremiah Willcock and
+ Doug Gregor of Indiana University.
+
+
king
+ ordering, from D. Kevin McGrath of Indiana
+ University.
+
+
+ cuthill mckee ordering has been recast as
+ an invocation of breadth first search and
+ now supports graphs with multiple components.
+
+
+ dijkstra shortest paths now uses a relaxed
+ heap [61]
+ as its priority queue, improving its complexity to
+ O(V log V) and improving real-world
+ performance for larger graphs.
+
+
read
+ graphviz now has a new, Spirit-based
+ parser that works for all graph types and supports
+ arbitrary properties on the graph, from Ron Garcia.
+ The old, Bison-based GraphViz reader has been
+ deprecated and will be removed in a future Boost
+ release. write
+ graphviz also supports dynamic
+ properties.
+
+
subgraph:
+ get_property now refers to the
+ subgraph property, not the root graph's
+ property.
+
+
See the history
+ for additional changes and bug fixes.
Option descriptions are now printed with word
+ wrapping.
+
+
Command line parser can bypass unregistered
+ options, instread of throwing.
+
+
Removed support for "implicit" (optional)
+ values.
+
+
New customization method
+ 'command_line_parser::extra_style_parser'. Unlike
+ 'additional_parser', allows the user to parse
+ several tokens and return a vector of options, not
+ just a single option.
Added support for docstrings on nonstatic
+ properties.
+
+
We now export the client-provided docstrings
+ for init<optional<> > and
+ XXX_FUNCTION_OVERLOADS() for
+ only the last overload.
+
+
Support for Embedded VC++ 4 and GCC-3.3 on
+ MacOS added
+
+
Introduced better support for rvalue
+ from-python conversions of shared_ptr.
+
+
Support for exposing
+ vector<T*> with the indexing
+ suite.
+
+
updated visual studio project build file.
+
+
Added search feature to the index page.
+
+
+
+
Random Number
+ Library: improved initialization for
+ mersenne_twister, algorithm by Makoto
+ Matsumoto and Takuji Nishimura, implemented for Boost
+ by Jens Maurer.
+ Note: All test vectors for
+ mersenne_twisters constructed or seeded
+ without parameters or with a single unsigned
+ int parameter become invalid.
+
+
Range Library:
+ Minor addition of convenience functions to
+ iterator range like front(),
+ back() and operator[]().
Signals Library:
+ added slot blocking/unblocking, from Frantz Maerten.
+ Huge improvements to signal invocation performance from
+ Robert Zeh.
+
+
+
Supported Compilers
+
+
Boost is tested on a wide range of compilers and
+ platforms. Since Boost libraries rely on modern C++
+ features not available in all compilers, not all Boost
+ libraries will work with every compiler. The following
+ compilers and platforms have been extensively tested with
+ Boost, although many other compilers and platforms will
+ work as well. For more information, see the regression
+ test results.
Microsoft Visual
+ C++ 6.0 (sp5, with and without STLport), 7.0, 7.1,
+ 8.0 beta. Note: due to intermittent problems with
+ Visual C++ 8.0 beta, and the presence of a variety of
+ pre-release compiler builds, we are unable to guarantee
+ compatibility until the final compiler is
+ released.
A great number of people contributed their time and
+ expertise to make this release possible. Special thanks
+ go to Aleksey Gurtovoy and Misha Bergal, who managed to
+ keep the regression testing system working throughout the
+ release process; David Abrahams, Beman Dawes, Aleksey
+ Gurtovoy, Rene Rivera and Jonathan Turkanis for greatly
+ improving the quality of this release; Rene Rivera for
+ the new Boost web page design; and Zoltan "cad" Juhasz
+ for the new Boost logo.
+
+
+
+
1.32.0 (19 Nov 2004)
+
+
Important - New Toolset Names
+
+
The names of some the Boost.Build toolsets have been
+ changed to remove the "." (dot) character
+ and to fix some other naming inconsistencies. For
+ example, vc7.1 toolset was renamed to become
+ vc-7_1. Please refer to the Supported Toolsets
+ section of the installation guide for the complete list
+ of the current toolset names. This change was made as a
+ part of the effort to make the Boost distribution
+ compatible with ISO 9660 level 2 requirements.
+
+
New Libraries
+
+
+
Assignment
+ Library: Filling containers with constant or
+ generated data has never been easier, from Thorsten
+ Ottosen.
+
+
Minmax
+ Library: Standard library extensions for
+ simultaneous min/max and min/max element computations,
+ from Hervé Brönnimann.
Program Options
+ Library: Access to configuration data given
+ on command line, in config files and other sources,
+ from Vladimir Prus.
+
+
Range Library: a
+ new infrastructure for generic algorithms that builds
+ on top of the new iterator concepts, from Thorsten
+ Ottosen.
+
+
Serialization
+ Library: Serialization/de-serialization of
+ arbitrary C++ data structures to various formats
+ including text, binary, and xml, from Robert
+ Ramey.
+
+
String Algorithms
+ Library: Collection of string related
+ algorithms for case conversion, trimming, find/replace
+ operations and more, from Pavol Droba.
+
+
Tribool: 3-state
+ boolean type library, from Doug Gregor.
+
+
+
Updated Libraries
+
+
+
Compose: This deprecated library has been
+ removed.
Major interface changes and improvements, many
+ of which are not backward compatible.
+ Please refer to the
+ 1.32 changelog for the detailed information
+ about upgrading to the new version.
Support for the new Python Bool type, thanks to
+ Daniel Holth.
+
+
Support for upcoming GCC symbol export control
+ features have been folded in, thanks to Niall
+ Douglas.
+
+
Improved support for
+ std::auto_ptr-like types.
+
+
Components used by other libraries have been
+ moved out of python/detail and into
+ boost/detail to improve dependency
+ relationships.
+
+
Miscellaneous bug fixes and compiler
+ workarounds.
+
+
+
+
Signals Library:
+ Introduced deterministic slot ordering, permitting
+ slots to be connected at the beginning or end of slot
+ groups or the slot list itself. Combiners may safely
+ have state and are accessible from the signal.
namespace names gets shorten; old one still
+ supported till next release
+
+
added proper encoding of XML PCDATA
+
+
support for wide string comparison
+ implemented
+
For complete list of changes see Test Library
+ release
+ notes.
+
+
+
+
Regression tests
+
+
This release has been extensively tested on a variety
+ of different compilers and platforms. It is known to
+ contain no regressions against the previous reference
+ release on the compilers and configurations tested.
+ Please refer to the corresponding
+ regression reports to see how well your compiler
+ performs on the new Boost codebase.
+
+
Acknowledgements
+
+
Aleksey Gurtovoy
+ managed this release. Managing a release at all is
+ an enormous job, and Aleksey always goes beyond merely
+ meeting requirements by insisting on the highest possible
+ quality. The Boost membership owes him a debt of
+ gratitude.
+
+
This release wouldn't have been possible without the
+ dedicated effort of many, many members of the Boost
+ community who generously contributed their outstanding
+ expertise, time and energy to making it happen. For
+ patches, bug fixes, troubleshooting, expert advice, and
+ prompt responses to the release manager's requests we
+ thank:
+
+
David Abrahams, Misha Bergal, Jonathan Brandmeyer,
+ Fernando Cacciola, Marshall Clow, Christopher Currie,
+ Pavol Droba, Caleb Epstein, Eric Friedman, Jeff Garland,
+ Michael Glassford, Doug Gregor, Joel de Guzman, Hubert
+ Holin, Jaakko Järvi, Hartmut Kaiser, Bronek Kozicki,
+ Tarjei Knapstad, Toon Knapen, Aaron W. LaFramboise,
+ Joaquín M López Muñoz, Christoph
+ Ludwig, John Maddock, Paul Mensonides, Guillaume
+ Melquiond, Thorsten Ottosen, Vladimir Prus, Robert Ramey,
+ Rene Rivera, Gennadiy Rozental, Stefan Slapeta, Jonathan
+ Turkanis, Pavel Vozenilek, Jonathan Wakely, Daryle
+ Walker, Victor A. Wagner Jr. and Martin Wille.
+
+
Also, our special thanks go to: John Maddock for the
+ managing the effort of converting the majority of the
+ Boost libraries to the Boost
+ Software License, Eric Niebler and Joel de Guzman for
+ taking on the important job of improving the Boost
+ documentation's look and feel, and last, but not least,
+ to our regression test runners, without whom we simply
+ would never have released: Toon Knapen, Bronek Kozicki,
+ Rene Rivera, Markus Schöpflin, Stefan Slapeta,
+ Victor A. Wagner Jr. and Martin Wille.
+
+
Thank you everybody!
+
+
+
+
1.31.0 (26 Jan 2004)
+
+
New License
+
+
A unified Boost Software
+ License has been developed and will gradually replace
+ the individual licenses for most Boost libraries. The new
+ license offers better legal protection for both users and
+ developers, and should speed user's legal reviews of
+ Boost libraries. Dave Abrahams led the Boost effort to
+ develop better licensing. The legal team was led by
+ Diane
+ Cabell, Director, Clinical Programs, Berkman Center for
+ Internet & Society, Harvard Law School.
+ Devin Smith, attorney, Nixon Peabody
+ LLP, wrote the Boost License. Eva Chan, Harvard Law
+ School, contributed analysis of issues and drafts of
+ various legal documents.
+
+
Note: Many of the Boost libraries are
+ still using earlier licenses, though all conform to the
+ Boost License
+ Requirements. After this release we will begin an
+ effort to move toward uniform use of the new license.
+
+
Build and Installation
+
+
+
New Getting
+ Started procedures ease download and installation,
+ from Rene Rivera and others.
+
+
Improved support for libraries requiring separate compilation,
+ from John Maddock and others.
+
+
+
New Libraries
+
+
+
enable_if:
+ Selective inclusion of function template overloads,
+ from Jaakko Järvi, Jeremiah Willcock, and Andrew
+ Lumsdaine. This is an important new technique which
+ exploits the SFINAE
+ (substitution-failure-is-not-an-error) principle.
+
+
Variant
+ Library: Safe, generic, stack-based
+ discriminated union container, from Eric Friedman and
+ Itay Maman.
+
+
+
Updated Libraries
+
+
+
Compose: This
+ library has been deprecated and will be removed in a
+ future release. Use Bind or Lambda
+ instead.
+
+
Date Time
+ Library: A whole host of bug fixes, new
+ features, and documentation improvements. See the Date
+ Time Change History for details.
+
+
Filesystem
+ Library: Several added functions, including
+ improved checking for directory and file name
+ portability.
+
+
Iterator Library: Major
+ version upgrade, with interface as proposed for the C++
+ library TR, including an improved
+ iterator_adaptor design plus several new
+ components, from David Abrahams, Jeremy Siek, and
+ Thomas Witt.
+
+
MultiArray:
+ The multi_array class template now
+ provides an element-preserving resize operation as well
+ as default construction (see the reference
+ manual for more information).
Multiple Scanner rules (no more scanner
+ business woes)
+
+
More dynamic parsers
+
+
Predefined actors
+
+
Numerous bug fixes and QOI stuff
+
+
...and more...
+
+
+
Starting from Spirit v1.8.0, ill conforming
+ compilers will no longer be supported. If you are
+ still using one of these older compilers, please use
+ Spirit v1.6.x. See Spirit's Site for more
+ details.
Fixed. Using MSVC++6 (SP5), calling the assign
+ action with a string value on parsers using the
+ file_iterator will not work.
+
+
Fixed: using assign semantic action in a
+ grammar with a multi_pass iterator adaptor applied
+ to an std::istream_iterator resulted in a failure
+ to compile under msvc 7.0.
+
+
Fixed: There is a bug in the
+ range_run<CharT>::set(range<CharT>
+ const& r) function in
+ "../boost/spirit/utility/impl/chset/range_run.ipp".
+
+
Fixed: handling of trailing whitespace bug
+ (ast_parse/pt_parse related)
Fixed: access_node_d[] and
+ access_match_d[] iterator bugs
+
+
Fixed a bug regarding thread safety of
+ Phoenix/Spirit closures.
+
+
+
+
The Boost Template Metaprogramming Library
+ (MPL)'s ..typeof implementation is now
+ compatible with Metrowerks CodeWarrior Pro8.
+
+
Boost.Function:
+ workaround for the new Borland patch (version 0x564)
+ and MSVC++ .NET 2003.
+
+
Boost.Config, Boost.Format, and
+ Boost.Regex
+ ..have been adjusted to avoid warnings with GCC-3.3,
+ and Boost.Format also now works with string types other
+ than std::string.
fixed a crashing bug in the
+ raw_function facility when no keyword
+ arguments were passed.
+
+
Improved conversion of NULL
+ shared_ptrs to Python.
+
+
+
+
+
+
+
1.30.0 (19 Mar 2003)
+
+
+
Filesystem
+ Library added - Portable paths, iteration over
+ directories, and other useful filesystem operations,
+ from Beman Dawes.
+
+
Optional
+ Library added - A discriminated-union wrapper for
+ optional values, from Fernando Cacciola.
+
+
Interval
+ Library added - Extends the usual arithmetic
+ functions to mathematical intervals, from Guillaume
+ Melquiond, Hervé Brönnimann and Sylvain
+ Pion.
+
+
MPL added
+ - Template metaprogramming framework of compile-time
+ algorithms, sequences and metafunction classes, from
+ Aleksey Gurtovoy.
+
+
Spirit
+ Library added - An LL (unlimited lookahead) parser
+ framework that represents parsers directly as EBNF
+ grammars in inlined C++ source code, complete with
+ semantic actions, ASTs and much more, from Joel de
+ Guzman and team.
Date-Time
+ Library - several fixes and small additions
+ including an interface change to partial_date. See the
+ Date-Time Change History for more details.
+
+
Function
+ Library - added support for assignment to zero (to
+ clear) and comparison against zero (to check if
+ empty).
+
+
Operators
+ Library - now takes advantage of named return value
+ optimization (NRVO) when available, from Daniel
+ Frey.
+ Test Library -
+ introduced following new facilities:
+
+
+
Automatic registration of unit tests
+
+
XML log format
+
+
XML report format
+
+
BOOST_CHECK_NO_THROW test tool
+
+
BOOST_BITWISE_CHECK test tool
+
+
+
For a complete list of changes see the Test
+ Library release
+ notes.
+
+
+
Many fixes and enhancements to other
+ libraries.
+
+
+
+
+
1.29.0 (10 Oct 2002)
+
+
+
Date-Time
+ Library added - Dates, times, leap seconds,
+ infinity, and more, from Jeff Garland.
+
+
Dynamic
+ Bitset added - A runtime sized version of the
+ std::bitset class from Jeremy Siek and
+ Chuck Allison.
+
+
Format
+ Library added - Type-safe 'printf-like' format
+ operations, from Samuel Krempp.
+
+
Function
+ Library: Major syntactic changes have been made.
+ Some old syntax and little-used features have been
+ deprecated (and will be removed shortly), and the
+ syntax for the boost::function class
+ template has been greatly improved on conforming
+ compilers. Please see the compatibility note for more
+ information.
+
+
Multi-array
+ Library added - Multidimensional containers and
+ adaptors for arrays of contiguous data, from Ron
+ Garcia.
Python
+ Library - Version 2 is released, from Dave Abrahams
+ and others. This is a major rewrite which works on many
+ more compilers and platforms, with a completely new
+ interface and lots of new features. Boost.Python v2
+ requires Python 2.2 or later.
Function
+ Library: user may request that
+ boost::function objects store a reference
+ to a function object target instead of a copy, using
+ ref.
+ Stateless objects are optimized so that they require no
+ dynamic storage.
Preprocessor
+ Library: changed macro prefix from
+ BOOST_PREPROCESSOR to BOOST_PP, added support for list
+ data structure manipulation, added examples, made
+ library ANSI C friendly, added generalized repetition
+ and iteration
+ primitives, improved reference manual.
+
+
Threads
+ Library: Mac Carbon implementation contributed by
+ Mac Murrett.
+
+
Minor fixes to many libraries.
+
+
+
+
+
1.26.0 (30 Nov 2001)
+
+
+
Common Factor
+ Library added. Greatest common divisor and least
+ common multiple, from Daryle Walker.
+
+
Preprocessor
+ Library added. Preprocessor metaprogramming tools
+ including repetition and recursion, from Vesa
+ Karvonen.
Random Number
+ Library: Removed iterator interface. Fixed
+ overflows in uniform_int<>. Both changes cause
+ random number sequences to differ compared to previous
+ boost releases.
+
+
operators.hpp:
+ Improvements from Daryle and Helmut Ziesel
Graph
+ Library: Final cleanup for upcoming the Boost Graph
+ Library book.
+
+
Thread
+ Library: Minor fixes - tests now pass on most Win32
+ and POSIX systems including Linux and Solaris.
+ Semaphore removed as too error prone.
+
+
Function
+ Library: direct support for member function
+ pointers and documentation updates.
+
+
Boost-Users
+ mailing list has been created to address topics of
+ interest to users of Boost libraries.
+
+
+ Boost Wiki web added. Provides a place for Boost
+ users to openly discuss and document the use of Boost
+ libraries. It is not officially maintained by Boost
+ developers.
+
+
+
+
+
1.25.0 (1 Oct 2001)
+
+
+
Thread
+ Library added. Portable C++ multi-programming at
+ last, from William Kempf.
Config
+ Library: major redesign with much improved and
+ automated configuration of Boost libraries for specific
+ compilers, from John Maddock.
+
+
Random Number
+ Library: Fixed bug when copying normal_distribution
+ and improved the documentation, from Michael Stevens
+ and Jens Maurer.
+
+
Special
+ functions, octonions,
+ quaternions
+ updated, now useable with many more compilers, plus
+ three new special functions, from Hubert Holin, Eric
+ Ford, and others.
+
+
Tokenizer
+ Library: fixes/enhancements to
+ escaped_list_separator based on empty fields and tokens
+ comments from Johan Nillson and Jens Maurer.
+
+
Coming Soon - A mailing list for Boost users!
+
+
+
+
+
1.24.0 (19 Aug 2001)
+
+
+
Tuple
+ Library added. Tuples ease definition of functions
+ returning multiple values, and more, from Jaakko
+ Järvi.
+
+
Minor fixes to some other libraries.
+
+
Boost Build
+ System added. Preliminary release of an innovative
+ build system for Boost libraries, from Dave Abrahams
+ and others.
Utility
+ Library: added checked_delete() and
+ checked_array_delete() functions.
+
+
+
+
+
1.21.2 (24 Apr 2001)
+
+
+
Compatibility
+ Library added: Help for non-conforming standard
+ libraries missing CXX headers from Ralf
+ Grosse-Kunstleve, and help for missing standard library
+ <limits> header from Jens Maurer. (These are
+ unreviewed implementation libraries, treated as
+ maintenance steps only.)
+
+
Random Number
+ Library: Split into separate headers, updated
+ documentation, added lagged_fibonacci generator.
Iterator
+ Adaptor Library added. Adapt a base type into a
+ standard conforming iterator, and more, from Dave
+ Abrahams, Jeremy Siek, and John Potter.
+
+
Pool
+ Library added. Memory pool management from Steve
+ Cleary.
+
+
Test
+ Library added. Support for program testing and
+ execution from Beman Dawes.
Graph
+ Library: Updated use of iterator adaptors. Changed
+ operator == for
+ adjacency_list::edge_descriptor to improve
+ semantics for multigraphs. Moved
+ adjacency_iterator_generator from
+ namespace detail to boost and
+ added documentation.
+ Renamed dynamic_components() to incremental_components(),
+ better matching graph literature terminology. Cleaned
+ up interface of connected_components()
+ and created separate strong_components()
+ function using Tarjan's more efficient algorithm. Fixed
+ documentation figures for adjacency_list
+ and adjacency_matrix.
+ Added docs for cuthill_mckee_ordering()
+ algorithm.
+
+
Python
+ Library upgraded. Better compatibility with Python
+ 2.0, NULL pointers and smart-pointers get converted
+ to/from python None, massive documentation
+ review/revision.
Terminology change: Several headers previously
+ lumped together as a "utility" library are now
+ considered separate libraries. For historical reasons,
+ their non-header files still live in the "utility"
+ sub-directory.
Added Experimental Compiler Status
+ page showing what library works with which
+ compilers.
+
+
+
+
+
1.15.1 (21 Jun 2000)
+
+
Fixes to cast.hpp and
+ operators
+ fix. Minor additions to config.hpp for Microsoft
+ compilers. The 1.15.0 operators changes seem to have
+ introduced incompatibilities. We are working on fixing
+ them, and have started to build a regression test to
+ prevent similar future problems.
Integer
+ Library status upgraded after removing bin_bun.hpp.
+ The "Experimental" library category has been removed; the
+ boost files/vault now serves the purpose. Minor fix to
+ smart_ptr.hpp line
+ endings.
Added iterator operators and helpers to header operators.hpp,
+ together with an iterator test program. This header is
+ maturing into something really useful for building
+ arithmetic or iterator user-defined types, so look it
+ over even if you browsed one of the earlier versions.
config.hpp minor
+ changes to aid library developers. No impact on library
+ users.
+
+
+
+
+
3 Sep 1999
+
+
The cast functions in the utility library were
+ considerably simplified.
+
+
+
+
1 Sep 1999
+
+
The cast functions initially in utility.hpp have been moved to
+ cast.hpp, still in the
+ utility
+ library.
+
+
+
+
1 Sep 1999
+
+
The category "Experimental" has been added to the
+ library page. The
+ integer library
+ is the first entry.
+
+
+
+
...And the remainder are lost to the mists of time (for
+ now, anyway)....
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/more/w3c_valid_css.png b/more/w3c_valid_css.png
new file mode 100644
index 0000000000..9b2f596e01
Binary files /dev/null and b/more/w3c_valid_css.png differ
diff --git a/more/w3c_valid_xhtml10.png b/more/w3c_valid_xhtml10.png
new file mode 100644
index 0000000000..2275ee6ea1
Binary files /dev/null and b/more/w3c_valid_xhtml10.png differ
diff --git a/more/whos_using/Jamfile.v2 b/more/whos_using/Jamfile.v2
new file mode 100644
index 0000000000..737c8b9d19
--- /dev/null
+++ b/more/whos_using/Jamfile.v2
@@ -0,0 +1,20 @@
+
+# Copyright John Maddock 2005. Use, modification, and distribution are
+# subject to the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+using quickbook ;
+
+xml using : using.qbk ;
+boostbook standalone
+ :
+ using
+ :
+ nav.layout=none
+ #navig.graphics=0
+ ;
+
+install html : ../../doc/html/boostbook.css ;
+install ../ : ../../boost.png ;
+
+
diff --git a/more/whos_using/using.qbk b/more/whos_using/using.qbk
new file mode 100644
index 0000000000..37c2086314
--- /dev/null
+++ b/more/whos_using/using.qbk
@@ -0,0 +1,966 @@
+[article Who's Using Boost?
+ [copyright 2005 Various Authors]
+ [license
+ 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
+ )
+ ]
+ [last-revision $Date$]
+]
+
+[section:intro]
+
+Open source isn't just for nerds and researchers. Real world programming challenges,
+irrespective of whether they are open or closed source, can benefit enormously from
+the thought and experience that has gone into the Boost software libraries. Put simply,
+for any given problem for which Boost provides a solution, Boost will strive to provide
+the best solution possible. It's up to you to decide whether we've achieved that, but
+as these pages will testify, many other developers have found our solutions to be the
+best for them.
+
+['Disclaimer:] Boost's developers try to ensure that the
+information on these pages is correct, but from time to time inadvertent
+mistakes are bound to occur:
+if you would like an entry in these pages to be removed or corrected please contact
+the [@mailto:boost-owner@lists.boost.org Boost Moderators].
+
+[endsect]
+
+[section:shrink Shrink Wrapped Boost]
+
+Boost has found it's way into many products that are available "off the shelf",
+including consumer applications from Adobe, through to business
+middleware from SAP.
+
+[blurb [*Adobe Photoshop CS2]\n\n
+[@http://www.adobe.com/products/photoshop/main.html Adobe Photoshop CS2]
+uses the
+[@http://opensource.adobe.com/ Adobe Software Libraries], which in
+turn depend upon large parts of Boost. The [@http://opensource.adobe.com/
+Adobe Software Libraries] are being rolled
+out across the Adobe product line to provide cross platform user interface logic.
+]
+
+[blurb [*Adobe Indesign]\n\n
+[@http://www.adobe.com/products/indesign/main.html Adobe Indesign] offers
+best of breed page design:
+Indesign and it's asociated SDK depend upon Boost
+[@../../libs/regex/index.html Regex],
+[@../../libs/functional/index.html Functional] and others.
+]
+
+[blurb [*SAP NetWeaver]\n\n
+[@http://www.sap.com/solutions/netweaver/index.epx SAP NetWeaver]
+is the technical foundation of mySAP Business Suite solutions,
+SAP xApps composite applications, partner solutions, and customer
+custom-built applications. [@../../libs/regex/index.html The Boost Regex library]
+provides the regular expression
+implementation for SAP's
+[@https://www.sdn.sap.com/sdn/developerareas/abap.sdn?node=linkDnode6-3 ABAP language].]
+
+[blurb [*Real Networks, Rhapsody]\n\n
+The [@http://www.real.com/ Rhapsody Music Service] allows its subscribers to legally
+download/transfer/burn over a million songs. The Rhapsody client
+software was built with many Boost libraries:\n\n
+['"[@../../libs/format/index.html Format]: Boost.Format is top notch. Using it is a bliss.\n
+[@../../libs/functional/index.html Functional],
+[@../../libs/function/index.html Function],
+and [@../../libs/bind/index.html Bind]: These three libraries,
+along with smart pointer are the most used in our application. I could not imagine
+not having them handy.\n
+[@../../libs/smart_ptr/index.html Smart Pointer]: Hands down, the most useful, and used library of the lot!\n
+[@../../libs/date_time/index.html Date Time]: Simple to use, effective, does the job. I love the
+flexible input string parsing facilities, and the
+human readable ISO output.\n
+[@../../libs/iterator/index.html Iterators]: Wow. Moving legacy iterating interfaces, or
+interfaces that should of been properly designed
+as iterators to STL compliant iterators was easy
+and painless. The gains in functionality to our
+code made by this library are invaluable.\n
+[@../../libs/regex/index.html Regex]: When you need it, it works magic.\n
+[@../../libs/thread/index.html Thread]: Used to implement the monitor pattern in key areas.\n
+[@../../libs/preprocessor/index.html Preprocessor]: Used to implement repetitive unit-test
+code generation. The codebase benefited
+greatly from the clarity boost.preprocessor
+brought."]
+]
+
+[blurb [*McAfee, Managed VirusScan 3]\n\n
+[@http://www.mcafeesecurity.com/us/products/mcafee/smb/managed_services/managed_vs_smb.htm McAfee Managed VirusScan],
+is an always on, automatic virus protection for desktops
+and servers.\n\n More details of the Boost libraries used can be found
+[@http://betavscan.mcafeeasap.com/beta/docs/readme/Readme.html here].]
+
+
+[blurb [*DataSolid GmbH Germany, CADdy++ Mechanical Design (c)]\n\n
+[@http://www.DataSolid.com CADdy++ Mechanical Design professional (c)]
+is a fully parametric 3D CAD
+application with unbroken link between 3D
+models and 2D drawings. CADdy++ uses the Boost libraries:
+[@../../libs/any/index.html Any],
+[@../../libs/tokenizer/index.html Tokenizer],
+[@../../libs/signals/index.html Signals],
+[@../../libs/property_map/index.html Property Map],
+[@../../libs/array/index.html Array],
+[@../../libs/bind/index.html Bind],
+[@../../libs/utility/operators.htm Operators],
+[@../../libs/tuple/index.html Tuple],
+[@../../libs/random/index.html Random].\n\n
+['"Many thanks to all the boost developers for their great work and effort
+spending into boost."]]
+
+[blurb [*Dimension 5, Miner3D]\n\n
+ Data visualization technology enabling advanced data analysis,
+ visualization, sonification and speech applications for business and science.\n
+ The [@http://www.miner3D.com Miner3D] application provides means for interactive visual analysis of
+ arbitrary tabular data from various data sources. It has a powerful OpenGL-based
+ visualization engine and an intuitive GUI. This combination helps a human eye
+ guide the application of statistical tools and spot the patterns that
+ might otherwise remain hidden.
+['"We are using the following boost libraries:
+[@../../libs/date_time/index.html Date Time],
+[@../../libs/variant/index.html Variant],
+[@../../libs/regex/index.html Regex],
+[@../../libs/format/index.html Format],
+[@../../libs/algorithm/string/index.html String Algorithms],
+[@../../libs/smart_ptr/index.html Smart Pointers],
+[@../../libs/mpl/index.html MPL],
+[@../../libs/type_traits/index.html Type Traits],
+[@../../libs/utility/operators.htm Operators],
+[@../../libs/dynamic_bitset/index.html Dynamic Bitset],
+[@../../libs/utility/enable_if.html Enable If],
+[@../../libs/timer/index.html Timer]."]
+]
+
+[blurb [*Synergy, mailIntercept]\n\n
+[@http://www.mintercept.com mailIntercept] from [@http://www.synergy.com.br Synergy]
+is a mail interceptor service for Exchange Server 2000/2003.\n
+mailIntercept intercepts and interprets the e-mails from a
+LAN using Exchange Server and converts the microsoft proprietary
+format to MIME and passes them to an SMTP filter and returns the
+emails to the Exchange Server as modified by the SMTP filter,
+converted back to the microsoft proprietary format and with its
+features preserved.\n\n
+mailIntercept was built using the following Boost libraries:
+[@../../libs/mpl/index.html MPL],
+[@../../libs/algorithm/string/index.html String Algorithm],
+[@../../libs/bind/index.html Bind],
+[@../../libs/spirit/phoenix/index.html Phoenix],
+[@../../libs/spirit/index.html Spirit],
+[@../../libs/ptr_container/index.html Pointer Container],
+[@../../libs/serialization/index.html Serialization],
+[@../../libs/regex/index.html Regex],
+[@../../libs/iterator/index.html Iterators],
+[@../../libs/lambda/index.html Lambda],
+[@../../libs/conversion/lexical_cast.htm Lexical Cast],
+[@../../libs/utility/operators.htm Operators],
+[@../../libs/smart_ptr/index.html Smart Pointer],
+[@../../doc/html/tribool.html Tribool] and
+[@../../libs/type_traits/index.html Type Traits]
+]
+
+[blurb [*Integrated Research P/L, PROGNOSIS IP Telephony Manager and IP Telephony Express]\n\n
+ [@http://www.ir.com PROGNOSIS] is a suite of IP telephony management software products,
+ specifically designed to address the key challenges of IP telephony
+ life cycle management, including network-readiness, assessment,
+ pre-deployment assurance testing, and ongoing Day-2 management of
+ Cisco CallManager, Cisco Unity, and Cisco AVVID infrastructure.
+['"The Boost libraries used were:
+[@../../libs/any/index.html Any],
+ [@../../libs/bind/index.html Bind],
+ [@../../libs/function/index.html Function],
+ [@../../libs/conversion/lexical_cast.htm Lexical Cast],
+ [@../../libs/mpl/index.html MPL],
+ [@../../libs/conversion/cast.htm#numeric_cast Numeric Cast],
+ [@../../libs/bind/ref.html Ref],
+ [@../../libs/regex/index.html Regex],
+ [@../../libs/smart_ptr/index.html Smart Pointer],
+ [@../../libs/thread/index.html Thread],
+ [@../../libs/type_traits/index.html Type Traits]."]
+]
+
+[blurb [*Kinook Software, Visual Build Professional]\n\n
+[@http://www.visualbuild.com/ Visual Build Professional]
+is a tool that enables developers,
+software process engineers, and build specialists to create an
+automated, repeatable process for building their software. Visual Build
+provides built-in support for Microsoft Visual Studio .NET and 2005,
+Visual Basic, Visual C++, Visual J++, SourceSafe, eMbedded Tools,
+Borland Delphi, JBuilder, C++Builder, and more.\n\n
+The following Boost Libraries were used:
+[@../../libs/any/index.html Any],
+[@../../libs/bind/mem_fn.html Mem_fn],
+[@../../libs/regex/index.html Regex],
+[@../../libs/smart_ptr/index.html Smart Pointer],
+[@../../libs/static_assert/index.html Static Assert]
+]
+
+[blurb [*Kinook Software, Ultra Recall]\n\n
+[@http://www.ultrarecall.com/ Ultra Recall]
+is a personal information management (PIM) /
+knowledge management (KM) application for Microsoft Windows. It helps
+you capture, organize, and recall all of your electronic information
+across all the applications that you use.\n\n
+Used the following Boost libraries:
+[@../../libs/format/index.html Format],
+[@../../libs/smart_ptr/index.html Shared Pointer],
+[@../../libs/static_assert/index.html Static Assert]
+]
+
+[blurb [*Applied Dynamics International, ADvantageDE]\n\n
+[@http://www.adi.com Applied Dynamics International (ADI)]
+provides state-of-the art software and
+hardware tools to the automotive, aerospace, and defense industries to
+design and test embedded control systems. ADI's tools provide advanced capabilities in real-time hardware-in-the-loop
+(HIL) simulation, rapid prototyping, and embedded controller software
+development. We have been a leading supplier of HIL simulation solutions
+since 1957.\n\n
+ADvantageDE is the development environment. It allows simulation models to
+be easily connected to one another or to hardware components for real-time
+simulation. ADvantageDE projects can be created for execution on your PC,
+Unix workstation or on our real-time platforms.\n\n
+ADvantageVI is the point of control and the graphical user interface for
+all of the run-time activities. The run-time architecture includes extensive
+features for interacting with, visualizing, and automating simulation and
+test activities.\n\n
+DasCom provides access to real-time simulation data from most Windows
+applications, such as Micrsoft Excel, National Instruments Labview, etc.\n\n
+The following Boost Libraries are used:
+[@../../libs/array/index.html Array],
+[@../../libs/assign/index.html Assign],
+[@../../libs/bind/index.html Bind],
+[@../../libs/crc/index.html CRC],
+[@../../libs/dynamic_bitset/index.html Dynamic Bitset],
+[@../../libs/utility/enable_if.html Enable If],
+[@../../libs/filesystem/index.html File System],
+[@../../libs/function/index.html Function],
+[@../../libs/functional/index.html Functional],
+[@../../libs/iterator/index.html Iterators],
+[@../../libs/lambda/index.html Lambda],
+[@../../libs/optional/index.html Optional],
+[@../../libs/preprocessor/index.html Preprocessor],
+[@../../libs/bind/ref.html Ref],
+[@../../libs/regex/index.html Regex],
+[@../../libs/serialization/index.html Serialization],
+[@../../libs/signals/index.html Signals],
+[@../../libs/smart_ptr/index.html Smart Pointer],
+[@../../libs/static_assert/index.html Static Assert],
+[@../../libs/spirit/index.html Spirit],
+[@../../libs/algorithm/string/index.html String Algorithm],
+[@../../libs/tokenizer/index.html Tokenizer]
+[@../../libs/tuple/index.html Tuple],
+[@../../libs/utility/index.html Uutility(Non-Copyable)] and
+[@../../libs/variant/index.html Variant]
+]
+
+[blurb [*PeerGuardian]\n\n
+[@http://methlabs.org/projects/peerguardian-2-windows/ PeerGuardian 2]
+is Methlabs premier IP blocker for Windows.
+With features like support for multiple lists, a list editor,
+automatic updates, and blocking all of IPv4 (TCP, UDP, ICMP, etc),
+PeerGuardian 2 is the safest and easiest way to protect your privacy on P2P.\n\n
+Boost Libraries used include
+[@../../libs/crc/index.html CRC],
+[@../../libs/bind/index.html Bind],
+[@../../libs/integer/index.html Integer],
+[@../../libs/function/index.html Function],
+[@../../libs/functional/index.html Functional],
+[@../../libs/smart_ptr/index.html Smart Pointers],
+[@../../libs/conversion/lexical_cast.htm Lexical cast],
+[@../../doc/html/string_algo.html String Algorithms],
+[@../../libs/random/index.html Random],
+[@../../libs/format/index.html Format],
+[@../../libs/utility/index.html Utility].]
+
+[blurb [*DECOMSYS::DESIGNER PRO]\n\n
+[@http://www.decomsys.com/ DECOMSYS::DESIGNER PRO] enables the user to design
+a highly complex [@http://www.flexray.com/ FlexRay] communication
+system, which is going to be the fundament for tomorrow's
+automotive electronics.\n\n
+['"Boost Libraries used:
+[@../../libs/bind/index.html Bind],
+[@../../libs/dynamic_bitset/index.html Dynamic Bitset],
+[@../../libs/format/index.html Format],
+[@../../libs/function/index.html Function],
+[@../../libs/iterator/index.html Iterators],
+[@../../libs/mpl/index.html MPL],
+[@../../libs/multi_index/index.html Multi Index],
+[@../../libs/utility/utility.htm#Class_noncopyable Non-Copyable],
+[@../../libs/utility/operators.htm Operators],
+[@../../libs/preprocessor/index.html Preprocessor (nice for generating data for unit tests)],
+[@../../libs/program_options/index.html Program Options (for the unit test programs)],
+[@../../libs/bind/ref.html Ref],
+[@../../libs/regex/index.html Regex],
+[@../../libs/serialization/index.html Serialization],
+[@../../libs/signals/index.html Signals],
+[@../../libs/smart_ptr/index.html SmartPointer],
+[@../../libs/spirit/index.html Spirit],
+[@../../libs/timer/index.html Timer] and
+[@../../libs/variant/index.html Variant]\n\n
+We are also planning to use Andreas Huber's FSM library and Iostreams
+(together with Serialize) once
+they are officially released."]
+]
+
+[blurb [*Wise Riddles Software, Audiomatic]\n\n
+[@http://www.WiseRiddles.com/Audiomatic Audiomatic]
+is a tool used to make system-wide macros and then launch those
+macros with a voice command or keyboard shortcut at any time... from any
+Windows application. Audiomatic enables you to launch programs, files, or
+websites; simulate keystrokes; play sounds; speak text; or even run scripts.
+You can do it all with a voice command or keyboard shortcut!
+['"Boost libraries Used:
+[@../../libs/bind/index.html Bind],
+[@../../libs/function/index.html Function],
+[@../../libs/smart_ptr/index.html Smart Pointers],
+[@../../libs/date_time/index.html Date Time],
+[@../../libs/algorithm/string/index.html String Algorithm],
+[@../../libs/utility/index.html Utility (Non-Copyable, Ref)],
+[@../../libs/regex/index.html Regex],
+[@../../libs/thread/index.html Thread],
+[@../../libs/mpl/index.html MPL] and
+[@../../libs/type_traits/index.html Type Traits]."]
+]
+
+[blurb [*Megahard Software Technologies Inc., Rule in Hell]\n\n
+[@http://www.ruleinhell.com Rule in Hell] is a
+Massively Multiplayer Online Role Playing Game (still in beta).\n\n
+The Boost libraries used were:
+[@../../libs/bind/index.html Bind],
+[@../../libs/function/index.html Function],
+[@../../libs/any/index.html Any],
+[@../../libs/tuple/index.html Tuples],
+[@../../libs/bind/ref.html Ref],
+[@../../libs/smart_ptr/index.html Shared Pointer],
+[@../../libs/type_traits/index.html Type Traits] and
+[@../../libs/utility/utility.htm#Class_noncopyable Non-Copyable].\n\n
+['"By far the combination of Bind, Function, Shared Pointer and Ref is what we use
+most heavily".]
+]
+
+[blurb [*Dr. Detlef Meyer-Eltz, TextTransformer]\n\n
+The [@http://www.texttransformer.com TextTransformer]
+is a Windows IDE for the generation of top down
+parsers with included c++ interpreter code for semantic actions. Both
+can be executed or debugged immediately on single source files or on
+groups of files. Generated parsers can be exported as c++ code
+including as well the interpretable code as any arbitrary other code.
+Tokens are defined as POSIX regular expressions and rules are defined
+in a similar syntax quasi as regular expressions of regular
+expressions. The construction of parse trees and their traversal is
+supported.\n\n
+['"The TextTransformer is essentially based on the Boost Regex library,
+by which the tokens for a parser can be defined. The Lexical Cast and
+the Format library are used for the integrated c++ interpreter. For
+the future also an interpreter version of the String Algorithm library is
+planned. The Program Options library will be used too to improve the
+command line version of the texttransformer."]
+]
+
+
+[blurb [*Redshift Software, The Thot Tool]\n\n
+[@http://thot-tool.com/ The Thot Tool]
+is an asset management tool for a group of game developers.
+Thot combines assets, both binary and text, with workflow automation
+into a unified whole, and was built using Boost
+[@../../libs/thread/index.html Threads],
+[@../../libs/smart_ptr/index.html Smart Pointer],
+[@../../libs/regex/index.html Regex],
+[@../../libs/mpl/index.html MPL],
+and [@../../libs/type_traits/index.html Type Traits].
+]
+
+[blurb [*Paragent, Paragent Manage 2.1]\n\n
+[@http://www.paragent.com/ Paragent Manage]
+is a Desktop Management Application that uses a
+lightweight agent written in C++. Unlike traditional desktop management
+solutions, Paragent Manage avoids the complexity and cost of servers by
+using peer-to-peer communication between agents and the administrative
+console. This allows real-time inventory searching, alerting and
+software auditing in an easy-to-deploy and maintain package.\n\n
+['"We have used Boost extensively throughout our agent, including:
+[@../../libs/thread/index.html Thread],
+[@../../libs/smart_ptr/index.html Shared Pointer],
+[@../../libs/bind/index.html Bind],
+[@../../libs/spirit/index.html Spirit],
+[@../../libs/date_time/index.html Date Time],
+[@../../libs/algorithm/string/index.html String Algorithms],
+[@../../libs/multi_index/index.html Multi Index],
+[@../../libs/filesystem/index.html Filesystem].\n\n
+Apart from some read_write_mutex issues we had, Boost has been a
+seamless part of our development, and has allowed us to develop and
+deploy a very complex, highly threaded networking agent with a built-in
+lisp-like xml-based scripting language all done in C++. Our entire
+development team would like to thank everyone for their hard work on
+behalf of C++ coders everywhere."]
+]
+
+[blurb [*LW-WORKS Software, Clipboard Recorder]\n\n
+[@http://www.lw-works.com/clipboard-recorder Clipboard Recorder]
+is an application that helps users to manage their
+clipboard history and provides easy ways for users to access their
+saved clipboard data.\n\n
+Libraries used:
+Smart Pointer, Serialization, Asio, String Algorithms, Bind, Thread,
+Conversion/Cast, Iostreams.
+]
+
+[endsect]
+
+[section:open Open Source Boost]
+
+Boost is used in a variety of Open Source Projects, both applications and libraries.
+Indeed many Open Source libraries developed around Boost have in the past been judged
+of high enough quality to be absorbed
+into the main Boost source tree, a process that will no doubt continue into the future.
+Others are in highly specialized niche markets, ranging from probability theory to
+astronomy, via mass spectroscopy: whatever your field of interest you'll find
+something of value in Boost.
+
+[blurb [*Adobe Software Libraries]\n\n
+The [@http://opensource.adobe.com/ Adobe Software Libraries] provide
+components for modeling the human interface appearance and behavior
+in a software application. The Adobe Software Libraries depend on many
+parts of Boost including [@../../libs/any/index.html Any],
+[@../../libs/bind/index.html Bind], [@../../libs/function/index.html Function],
+[@../../libs/mpl/index.html MPL], [@../../libs/utility/operators.htm Operators],
+[@../../libs/range/index.html Range], [@../../libs/static_assert/index.html Static Assertions],
+[@../../libs/thread/index.html Threads], and [@../../libs/type_traits/index.html Type Traits].\n\n
+Currently Boost and the Adobe Software Libraries are in use in around 30 Adobe products.
+]
+
+[blurb [*LyX Document Editor]\n\n
+[@http://www.lyx.org/ The LyX Document Editor]
+is an advanced open source document processor that encourages an
+approach to writing based on the structure of your documents,
+not their appearance. LyX produces high quality, professional output,
+using LaTeX, an industrial strength typesetting engine.\n\n
+LyX uses many parts of Boost, including [@../../libs/array/index.html Array],
+[@../../libs/bind/index.html Bind], [@../../libs/regex/index.html Regex],
+[@../../libs/type_traits/index.html Type Traits],
+[@../../libs/function/index.html Function],
+and [@../../libs/signals/index.html Signals].]
+
+[blurb [*CodeSynthesis XML Schema to C++ Data Binding Compiler (XSD) by Code Synthesis Tools CC]\n\n
+[@http://codesynthesis.com/products/xsd/ CodeSynthesis XML
+Schema to C++ Data Binding Compiler (XSD)] is an
+open-source, cross-platform XML Data Binding implementation for C++.
+Provided with an XML instance specification (XML Schema), it generates
+C++ classes that represent the given vocabulary as well as parsing and
+serialization code. You can then access the data stored in XML using
+types and functions that semantically correspond to your application
+domain rather than dealing with elements, attributes, and text in a
+direct representation of XML such as DOM or SAX.
+\n\n
+XSD uses the [@../../libs/regex/index.html Regex] and
+[@../../libs/filesystem/index.html Filesystem] libraries from Boost.
+[@../../libs/regex/index.html Regex] is used
+to perform transformations on file, type and member names.
+[@../../libs/filesystem/index.html Filesystem] is used to
+capture and manipulate XML Schema include and import paths.
+Additionally, we are planning to provide an optional mapping of XML
+Schema date and time types to C++ types from the Boost
+[@../../libs/date_time/index.html Date Time] library.
+]
+
+[blurb [*CGAL]\n\n
+[@http://www.cgal.org/ CGAL] is the Computational Geometry Algorithms Library,
+ an open source C++ library providing generic components
+ such as triangulations, convex hulls algorithms, boolean
+ operations of polygons and many other things.
+ ['"We currently use the following Boost libraries :
+ [@../../libs/utility/operators.htm Operators],
+ [@../../libs/iterator/index.html Iterators],
+ [@../../libs/tuple/index.html Tuples],
+ [@../../libs/concept_check/index.html Concept Check],
+ [@../../libs/mpl/index.html MPL],
+ [@../../libs/bind/index.html Bind],
+ [@../../libs/optional/index.html Optional] and
+ [@../../libs/smart_ptr/index.html Smart Pointers]."]
+]
+
+
+[blurb [*ALPS]\n\n
+[@http://alps.comp-phys.org/ ALPS] is an open source project to develop codes
+for the accurate simulation of quantum lattice models, such as quantum magnets,
+electronic systems and Bose-Einstein condensates. The main Boost libraries
+used are:
+[@../../libs/graph/index.html Graph],
+[@../../libs/random/index.html Random],
+[@../../libs/multi_array/index.html Multi Array],
+[@../../libs/program_options/index.html Program Options],
+[@../../libs/conversion/lexical_cast.htm Lexical Cast],
+[@../../libs/serialization/index.html Serialization],
+[@../../libs/regex/index.html Regex],
+[@../../libs/tuple/index.html Tuple],
+[@../../libs/filesystem/index.html Filesystem],
+[@../../libs/smart_ptr/index.html Smart Pointer],
+[@../../libs/bind/index.html Bind],
+[@../../libs/functional/index.html Functional] and
+[@../../libs/type_traits/index.html Type Traits]
+]
+
+[blurb [*SmartWin++]\n\n
+[@http://smartwin.sourceforge.net/ SmartWin++]
+is a 100% free GUI library for developing Windows applications,
+it's free both as in "free beer" and as in "free speech", you can freely use
+SmartWin++ for commercial applications and for Open Source applications!
+]
+
+[blurb [*Open VRML]\n\n
+[@http://openvrml.org/ Open VRML] is a free cross-platform runtime
+for VRML.
+The basic OpenVRML distribution includes libraries you can use to add
+VRML support to an application, and Lookat, a simple stand-alone VRML browser.
+]
+
+[blurb [*Bayes++]\n\n
+[@http://bayesclasses.sourceforge.net/Bayes++.html Bayes++] is an open source
+library that represents and implements a wide variety of numerical algorithms
+for Bayesian Filtering of discrete systems from the
+[@http://www.acfr.usyd.edu.au/ Australian Centre for Field Robotics].
+Bayes++ makes particularly heavy use of [@../../libs/numeric/ublas/index.html the Boost Ublas library]
+for matrix and numeric computations.
+]
+
+[blurb [*The C++/Tk Library]\n\n
+[@http://cpptk.sourceforge.net The C++/Tk Library] is an open source
+C++ interface to the Tk GUI Library.
+]
+
+[blurb [*GluCat]\n\n
+[@http://glucat.sourceforge.net/ GluCat] is a library of template classes
+which model the universal Clifford algebras over the real or complex fields,
+with arbitrary dimension and arbitrary signature.
+]
+
+[blurb [*OpenMS]\n\n
+[@http://open-ms.sourceforge.net/main.html OpenMS] is an open source C++ library
+for LC/MS data management, reduction, evaluation, visualization, storage and
+sophisticated statistical analyses. It can be used to develop mass
+spectrometry related applications.
+]
+
+[blurb [*libpdf++]\n\n
+[@http://libpdfxx.sourceforge.net/doc/index.html libpdf++] is an object-oriented
+library for generating PDF (portable document format) files. It is designed
+in a way that the objects in the document are mapped directly to classes
+in the library.
+]
+
+[blurb [*Regina]\n\n
+[@http://regina.sourceforge.net/ Regina] is a suite of mathematical software
+for 3-manifold topologists. It focuses upon the study of 3-manifold
+triangulations and includes support for normal surfaces and angle structures.
+]
+
+[blurb [*MetaFS]\n\n
+[@http://metafs.sourceforge.net/ MetaFS] is a daemon for Linux
+(and Linux only) that allows you to access information about your
+files (such as MP3 tags or JPEG's EXIF tags) easily and consistently
+using extended attributes. It also allows you to perform fast searches
+using this information. MetaFS is extensible, so anyone can write plug-ins
+to access new types of metadata.
+]
+
+[blurb [*The ASN.1 Tool]\n\n
+Abstract Syntax Notation One (ASN.1) is a
+formal language for abstractly describing messages to be exchanged among an
+extensive range of applications involving the Internet, intelligent network,
+cellular phones, ground-to-air communications, electronic commerce, secure
+electronic services, interactive television, intelligent transportation
+systems, Voice Over IP and others. \n\n
+[@http://iiiasn1.sourceforge.net/main.html The ASN.1 Tool] includes two parts :
+an ASN.1 compiler "asnparser" which compiles the Abstract Syntax to c++ files,
+and a runtime library which is used to link with the c++ files generated by
+asnparser. Based on the works of Open H.323 projects, it is developed for
+the needs of H.450 series protocol.
+]
+
+[blurb [*DGD]\n\n
+[@http://dgd.sourceforge.net/dgd_home.html DGD] (Depression Glass Debug)
+is simple, easy to use C++ ostream extension
+created with a goal to produce nice, readable and easy to understand trace logs]
+
+[blurb [*FEAR]\n\n
+[@http://fear.sourceforge.net/ FEAR] is a language independent
+open-source project providing portable support for the creation of
+genuine Artificial Intelligence within realistic simulated worlds.]
+
+[blurb [*XEngine]\n\n
+[@http://xengine.sourceforge.net/features.php XEngine] is a platform- and
+rendering-API-independent 3D engine for real-time visualization with
+support for programmable graphics pipeline architectures and is implemented in C++.]
+
+[blurb [*Spheral++]\n\n
+[@http://spheral.sourceforge.net/ Spheral++] is a numerical tool
+for simulating the evolution of a set of fluid or solid materials subject to
+hydrodynamic, gravitational, and radiative effects.
+Spherical++ uses [@../../libs/python/doc/index.html the Boost Python library].]
+
+[blurb [*C++ XML Objects]\n\n
+[@http://cppxmlobj.sourceforge.net/ C++ XML Objects] is a framework for persisting
+hierarchies of C++ objects to and from XML.]
+
+[blurb [*HippoDraw]\n\n
+[@http://www.slac.stanford.edu/grp/ek/hippodraw/index.html HippoDraw] provides a
+highly interactive data analysis environment.
+HippoDraw uses [@../../libs/python/doc/index.html the Boost Python library].]
+
+[blurb [*Orocos]\n\n
+[@http://people.mech.kuleuven.ac.be/~psoetens/orocos/doc/orocos-control-manual.html
+The Orocos Robot Control Software Application Framework].]
+
+[blurb [*ECell]\n\n
+The [@http://www.e-cell.org/ E-Cell Project] is an international research
+project aiming at developing necessary theoretical supports, technologies
+and software platforms to allow precise whole cell simulation.]
+
+[blurb [*VCS Made Easy]\n\n
+[@http://vcsme.sourceforge.net/ VCS Made Easy],
+or vcsme for short, is an utility whose main
+purpose is to simplify the maintenance of file trees managed by a version
+control system, such as the well known CVS or Subversion. Simply put,
+it automates the process of bringing all these directories to an up-to-date
+status with a single and simple command.\n\n
+['"The following Boost libraries were used:
+[@../../libs/format/index.html Format],
+[@../../libs/smart_ptr/index.html Smart Pointers],
+[@../../libs/utility/index.html Utility (noncopyable)] and
+[@../../libs/filesystem/index.html Filesystem]."]
+]
+
+[blurb [*Monotone]\n\n
+[@http://www.venge.net/monotone/ Monotone]
+is a free distributed version control system. It provides
+ a simple, single-file transactional version store, with fully disconnected
+ operation and an efficient peer-to-peer synchronization protocol. It
+ understands history-sensitive merging, lightweight branches, integrated
+ code review and 3rd party testing. It uses cryptographic version naming
+ and client-side RSA certificates. It has good internationalization support,
+ has no external dependencies, runs on linux, solaris, OSX, windows, and
+ other unixes, and is licensed under the GNU GPL.\n\n
+['"The followind Boost libraries were used:
+[@../../libs/date_time/index.html Date Time],
+[@../../libs/filesystem/index.html Filesystem],
+[@../../libs/conversion/index.html Conversion],
+[@../../libs/optional/index.html Optional],
+[@../../libs/random/index.html Random],
+[@../../libs/regex/index.html Regex],
+[@../../libs/smart_ptr/index.html Smart Pointers],
+[@../../libs/static_assert/index.html Static Assertions],
+[@../../libs/tokenizer/index.html Tokenizer],
+[@../../libs/tuple/index.html Tuple] and
+[@../../libs/test/index.html Test]."]
+]
+
+[blurb [*Hydranode Engine]\n\n
+[@http://hydranode.com/ Hydranode Engine]
+is a plugin-driven P2P client engine that relies
+heavily on Boost libraries. Hydranode codebase is licenced under GNU
+GPL, and is developed mainly by Alo Sarv. Currently in Beta phase,
+Hydranode runs on wide range of platforms, including Windows, Linux,
+BSD, Mac OS, Solaris etc.\n\n
+['"Hydranode Engine and plugins rely heavily on the following Boost
+libraries: Bind, Function, Lambda, MultiIndex, Signals, Threads,
+Smart Pointer, Format, Lexical Cast. Other Boost libraries being used
+include FileSystem, String Algorithm, Date Time, Program Options, Spirit,
+Random, Tokenizer, Type Traits, Tribool, Tuple and Any. Once Boost 1.33
+is released, I'm also looking forward to using the Boost Iostreams library
+in Hydranode.\n\n
+All complex data structures in Hydranode are implemented using
+Multi Index containers, which significantly reduced development time
+and kept code clean. Format is being used for all text formatting.
+Having Threads and FileSystem libraries available made cross-platform
+development lot easier in those areas."]
+]
+
+[blurb [*Hugin]\n\n
+With [@http://hugin.sourceforge.net/ hugin] you can assemble a mosiac of
+photographs into a complete
+immersive panorama, stitch any series of overlapping pictures and much more.]
+
+[blurb [*Enblend]\n\n
+[@http://enblend.sourceforge.net/ Enblend] is a tool for compositing images.
+Given a set of images that overlap
+in some irregular way, Enblend overlays them in such a way that the seam
+between the images is invisible, or at least very difficult to see.]
+
+[blurb [*GNU Source-highlight]\n\n
+[@http://www.gnu.org/software/src-highlite/source-highlight.html GNU Source-highlight],
+given a source file, produces a document with
+syntax highlighting. The colors and the styles can be specified
+(bold, italics, underline) by means of a configuration file, and some
+other options can be specified at the command line. The output format
+can be HTML, XHTML and ANSI color escape sequences. GNU Source Highlight
+is build around [@../../libs/regex/index.html the Boost Regex library]]
+
+[blurb [*Luabind]\n\n
+[@http://luabind.sourceforge.net/ Luabind] is a library that helps you create
+bindings between C++ and lua. It has the ability to expose functions and classes,
+written in C++, to lua. It will also supply the functionality to define classes
+in lua and let them derive from other lua classes or C++ classes.
+Lua classes can override virtual functions from their C++ baseclasses.
+It is written towards lua 5.0, and does not work with lua 4.]
+
+[blurb [*C++/Tcl]\n\n
+[@http://cpptcl.sourceforge.net/ C++/Tcl] is a library that allows the easy
+integration of C++ and Tcl.]
+
+[blurb [*QuantLib]\n\n
+The [@http://quantlib.org/ QuantLib] project provides a comprehensive software
+framework for quantitative finance. QuantLib is a free/open-source library
+for modeling, trading, and risk management in real-life.
+Boost components used include
+[@../../libs/smart_ptr/index.html Smart Pointers],
+[@../../libs/iterator/index.html Iterators],
+and [@../../libs/test/index.html the Test Framework].
+]
+
+[blurb [*CBCanaylzer]\n\n
+[@http://www.biozentrum.uni-wuerzburg.de/index.php?id=524 CBCanaylzer]
+ is developed by the Department of Bioinformatics,
+at the University of Wuerzburg.\n\n
+['"CBCAnalyzer (CBC = compensatory base change) is a tool to create ``small''
+phylogenetic trees from sequence alignments. To measure the distance of sequences
+the compensatory base changes are detected and counted. The bionj
+algorithm is then used to construct a tree. CBCAnalyzer is available on
+Windows, Linux and partly works on MacOSX. \n\n
+Boost libraries used:
+ [@../../libs/program_options/index.html Program Options]
+ - creates really nice output, and is both easy to extend and simple to handle.
+ [@../../libs/iterator/index.html Iterator],
+ [@../../libs/spirit/index.html Spirit]
+ - Saved a lot of my time, and makes the vast amount of biological file
+ formats simple to support,
+ [@../../libs/smart_ptr/index.html Shared Pointer],
+ [@../../libs/lambda/index.html Lambda].]
+]
+
+[blurb [*Profdist]\n\n
+[@http://www.biozentrum.uni-wuerzburg.de/index.php?id=523 Profdist]
+is developed by the Department of Bioinformatics, at the University of Wuerzburg.\n\n
+['"Profdist is a tool for the construction of large phylogenetic trees based on
+profile distances. The input alignment data gets extended by random
+picking of rows, and a clustering technique is used to create profiles
+of the most frequent subtrees. The iterative approach allows working on
+large datasets. Currently the application is very limited by the quality of
+wxWidgets, and only available for Windows and Linux. \n\n
+The Boost librarie used were:
+ [@../../libs/algorithm/string/index.html String Algorithms],
+ [@../../libs/bind/ref.html Ref],
+ [@../../libs/iterator/index.html Iterator],
+ [@../../libs/spirit/index.html Spirit],
+ [@../../libs/smart_ptr/index.html Shared Pointer] and
+ [@../../libs/lambda/index.html Lambda]."]
+]
+
+[blurb [*The Yake Engine]\n\n
+[@http://www.yake.org/ The Yake Engine]
+is a component-based, object-oriented engine written in C++
+and primarily designed for VR applications and games. It abstracts typical
+low-level and middleware APIs and provides various low, mid and application
+level functionality as well as tools to create and import content.
+]
+
+[blurb [*Python-Ogre]\n\n
+[@http://python-ogre.python-hosting.com/ Python-Ogre]
+is a Python bindings for Ogre 3D - a scene-oriented,
+flexible 3D engine.\n
+Python-Ogre uses Boost.Python to expose next libraries to Python:\n
+ * Ogre\n
+ * Newton\n
+ * ODE\n
+ * OgreAL\n
+ * CEGUI\n
+ * OIS\n
+]
+
+[endsect]
+
+[section:inhouse In House Boost]
+
+Whether you're a government department, an internet startup, or a specialist consultancy, in-house
+developement using the Boost Libraries can significantly shorten your
+development cycles.
+
+[blurb [*Google]\n\n
+[@http://code.google.com/p/google-gtags/ google-gtags] Provides server-based
+tags serving for large codebases. This is an extension to GNU Emacs and X-Emacs
+TAGS functionality, that uses [@../../libs/test/index.html Boost.Test] as its
+unit test framework.
+]
+
+[blurb [*LiquidNet]\n\n
+[@http://www.liquidnet.com/ LiquidNet] is Americas number one electronic
+marketplace for large block trading, and the 5th fastest growing company
+according to Inc Magazine. \n\n
+"['Boost Libraries most used, in order of importance:\n
+[@../../libs/smart_ptr/index.html Shared Pointer],
+[@../../libs/bind/index.html Bind],
+[@../../libs/python/doc/index.html Python],
+[@../../libs/conversion/lexical_cast.htm Lexical Cast],
+[@../../libs/optional/index.html Optional],
+[@../../libs/any/index.html Any] and
+[@../../libs/tuple/index.html Tuple]]
+]
+
+[blurb [*MetOcean Engineers]\n\n
+[@http://www.metoceanengineers.com MetOcean Engineers]
+are a leading consultancy providing oceanographic and meteorological
+services in support of coastal and ocean engineering and environmental
+protection. Core activities encompass: oceanographic measurements;
+metocean monitoring systems; coastal and ocean engineering; environmental
+consultancy; data management.\n\n
+Boost Libraries currently in use:
+[@../../libs/any/index.html Any],
+[@../../libs/assign/index.html Assign],
+[@../../libs/bind/index.html Bind],
+[@../../libs/date_time/index.html Date Time],
+[@../../libs/iterator/index.html Iterators],
+[@../../libs/conversion/lexical_cast.htm Lexical Cast],
+[@../../libs/mpl/index.html MPL],
+[@../../libs/spirit/phoenix/index.html Phoenix],
+[@../../libs/program_options/index.html Program Options],
+[@../../libs/bind/ref.html Ref],
+[@../../libs/smart_ptr/index.html Smart Pointer],
+[@../../libs/spirit/index.html Spirit],
+[@../../libs/algorithm/string/index.html String Algorithm],
+[@../../doc/html/tribool.html Tribool] and
+[@../../libs/variant/index.html Variant]
+]
+
+[blurb [*TeraView Ltd]\n\n
+[@http://www.teraview.com TeraView Ltd] develop terahertz based systems
+for a variety of applications
+including spectroscopy and imaging.\n\n
+['"We use:
+[@../../libs/thread/index.html Thread],
+[@../../libs/filesystem/index.html Filesystem],
+[@../../libs/date_time/index.html Date Time],
+[@../../libs/serialization/index.html Serialization],
+[@../../libs/smart_ptr/index.html Smart Pointer],
+[@../../libs/function/index.html Function],
+[@../../libs/bind/index.html Bind],
+[@../../libs/iterator/index.html Iterator],
+[@../../libs/conversion/lexical_cast.htm Lexical Cast],
+[@../../libs/format/index.html Format],
+[@../../libs/tuple/index.html Tuple],
+[@../../libs/any/index.html Any] and
+[@../../libs/optional/index.html Optional]"]
+]
+
+[blurb [*NPC International]\n\n
+With about 800 restaurants, [@http://www.npcinternational.com NPC International]
+is the world's largest Pizza Hut franchisee.\n\n
+['"We make extensive use of boost in our internally developed point of sale,
+restaurant management, communications, and accounting systems.
+We use the following Boost libraries in approximate order of frequency of use:
+[@../../libs/bind/index.html Bind],
+[@../../libs/function/index.html Function],
+[@../../libs/optional/index.html Optional],
+[@../../libs/smart_ptr/index.html Shared Pointer],
+[@../../libs/date_time/index.html Date Time],
+[@../../libs/thread/index.html Thread],
+[@../../libs/lambda/index.html Lambda],
+[@../../libs/type_traits/index.html Type Traits],
+[@../../libs/mpl/index.html MPL],
+[@../../libs/tuple/index.html Tuple],
+[@../../libs/utility/enable_if.html Enable If],
+[@../../libs/variant/index.html Variant],
+[@../../libs/spirit/index.html Spirit],
+[@../../libs/algorithm/string/index.html String Algorithm],
+[@../../libs/preprocessor/index.html Preprocessor],
+[@../../libs/filesystem/index.html Filesystem],
+[@../../libs/utility/operators.htm Operator],
+[@../../libs/iterator/index.html Iterators] and
+[@../../libs/tokenizer/index.html Tokenizer]."]
+]
+
+[blurb [*Rational Discovery LLC]\n\n
+[@http://www.rationaldiscovery.com Rational Discovery]
+provides computational modeling, combinatorial
+library design and custom software development services to the
+pharmaceutical, biotech and chemical industries.\n\n
+['"We do a substantial amount of internal research to develop new
+approaches for applying machine-learning techniques to solve chemical
+problems. Because we're a small organization and chemistry is a large
+and complex field, it is essential that we be able to quickly and
+easily prototype and test new algorithms. We have found the Boost
+libraries, a reliable source of high-quality code, to be
+indispensable.\n\n
+Boost libraries used:
+[@../../libs/python/index.html Python],
+[@../../libs/graph/index.html Graph],
+[@../../libs/smart_ptr/index.html Smart Pointer],
+[@../../libs/any/index.html Any],
+[@../../libs/conversion/lexical_cast.htm Lexical Cast],
+[@../../libs/random/index.html Random],
+[@../../libs/algorithm/string/index.html String Algorithms],
+[@../../libs/tuple/index.html Tuple],
+[@../../libs/numeric/ublas/index.html uBLAS]."]
+]
+
+[blurb [*Archelon LLC]\n\n
+[@http://www.archelon-us.com Archelon LLC] is a global securities firm
+headquartered in Chicago. We actively trade equities, futures and
+derivatives in both electronic and floor-based markets. Archelon is
+one of the highest volume market makers on EUREX and a leading
+U.S. option market maker focusing on the most active securities.\n\n
+['"We use:
+[@../../libs/any/index.html Any],
+[@../../libs/array/index.html Array],
+[@../../libs/bind/index.html Bind],
+[@../../libs/date_time/index.html Date Time],
+[@../../libs/function/index.html Function],
+[@../../libs/conversion/lexical_cast.htm Lexical Cast],
+[@../../libs/optional/index.html Optional],
+[@../../libs/rational/index.html Rational],
+[@../../libs/regex/index.html Regex],
+[@../../libs/signals/index.html Signals],
+[@../../libs/smart_ptr/index.html Smart Pointer],
+[@../../libs/tokenizer/index.html Tokenizer],
+[@../../libs/tuple/index.html Tuple] and
+[@../../libs/utility/index.html Utility]."]
+]
+
+[blurb [*Automated Trading Deck] \n\n
+[@http://www.atdesk.com Automated Trading Deck] (ATD) uses a large number
+of Boost libraries. ATD is a technology company specializing in
+automated trading and customized equity execution solutions for its
+customers. We offer automated execution solutions in all domestic cash
+equity markets, including the listed, over-the-counter, exchange traded
+fund and bulletin board marketplaces. Our proprietary "Pricing Engine"
+and automated limit-order trading algorithms apply advanced expert
+systems to limit-order trading and customer executions.
+]
+
+[endsect]
+
+[section:submit Submissions]
+
+If you have an application or library that's using Boost and would like to be
+listed here, please post the following information to the
+[@http://www.boost.org/more/mailing_lists.htm#main main Boost developer
+mailing list]:
+
+* The name of the Application/Product/Service.
+* The name of the company (where appropriate).
+* A paragraph describing the Application/Product/Service.
+* Any information you can provide about which parts of Boost you used,
+ along with any comments you may have on how Boost helped your product
+ development.
+* URLs to your companies home page, and the home page of the
+ Application/Product/Service if there is one.
+
+Finally, if the subheadings used in the structure of these pages
+don't fit your Product/Application/Service please say so: we're
+always interested to hear how these pages can be improved or better
+structured.
+
+[endsect]
+
+
+
diff --git a/more/writingdoc/design.html b/more/writingdoc/design.html
new file mode 100644
index 0000000000..7e95a63ff0
--- /dev/null
+++ b/more/writingdoc/design.html
@@ -0,0 +1,576 @@
+
+
+
+
+
+
+
+
+ Writing Documentation for Boost - HTML Design
+
+
+
+
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.
+
+
In several places this document assumes you're writing the documentation
+ to conform to the structure described in the Documentation Structure 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.
+
+
This document also contains links to HTML template
+ files that can be used to rapidly develop documentation for a library
+ submission. These templates follow the guidelines presented here and in the
+ Documentation Structure document.
+
+
Common Pages Included in
+ HTML Documentation
+
+
Most HTML documentation projects will contain some common pages. General
+ guidelines for these common pages are provided below.
+
+
Index
+
+
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 Page Index, 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 Documentation Structure) 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.
+
+
The index list should generally be constructed using an HTML "definition
+ list" (<dl> and <dt> tags). A definition list has no bullets or
+ ordered specifications and produces a cleaner layout then an unordered list
+ (<ul> and <li> tags) or an ordered list (<ol> and
+ <li> tags). If you choose to use the common Boost Style Sheet you should add a
+ class="index" attribute/value pair to the <dl> tag.
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
+ Rational Page.
+
+
Like most content pages, the Overview page should include a Page Index.
The Definitions page is used to provide a list of definitions for terms
+ that a user may be unfamiliar with.
+
+
The definition list should generally be constructed using an HTML
+ "definition list" (<dl> and <DT> tags). A definition list has
+ no bullets or ordered specifications and produces a cleaner layout then an
+ unordered list (<UL> and <li> tags) or an ordered list
+ (<ol> and <li> tags). If you choose to use the common Boost Style Sheet you should add a
+ class="definition" attribute/value pair to the <dl>
+ tag.
+
+
Because this page's content should only contain a list of definitions,
+ it should not have a Page Index.
+
+
A Definitions page template is
+ provided for use.
+
+
Rationale
+
+
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 Rationale rationale
+ in the general submission guidelines.
+
+
Like most content pages, the Rationale page should include a Page Index.
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
+ <boost/config.hpp>, macros used by library users to
+ detect platform configuration information and macros defined by library
+ users to configure library behavior.
+
+
Like most content pages, the Overview page should include a Page Index.
+
+
A Configuration page template is
+ provided for use.
+
+
Frequently Asked Questions
+
+
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.
+
+
The Page Index 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.
+
+
A Frequently Asked Questions page template
+ is provided for use.
+
+
Bibliography
+
+
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 here.
+
+
Since the Bibliography page should contain only bibliographical
+ information there is no need for a Page
+ Index.
+
+
A Bibliography page template is
+ provided for use.
+
+
Acknowledgment
+
+
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.
+
+
Since the Acknowledgment page should contain only a list of
+ acknowledgment there is no need for a Page
+ Index.
+
+
An Acknowledgments page template is provided for use.
+
+
Header Reference
+
+
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 Documentation Structure when writing the content for
+ these pages.
+
+
Like most content pages, the Header Reference pages should include a
+ Page Index.
+
+
A Header Reference page template is
+ provided for use.
+
+
Layout
+
+
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.
+
+
Page Banner
+
+
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 <title> tag for the HTML page should consist of the documentation
+ title and the page title separated by a hyphen.
+
+
The Page Banner should be separated from the rest of the page by the use
+ of an <hr> tag. This helps to clearly separate the actual content
+ from the title information and produces cleaner text.
+
+
Page Index
+
+
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.
+
+
The index list should generally be constructed using an HTML "definition
+ list" (<dl> and <DT> tags). A definition list has no bullets or
+ ordered specifications and produces a cleaner layout then an unordered list
+ (<UL> and <li> tags) or an ordered list (<ol> and
+ <li> tags). If you choose to use the Boost Style Sheet you should add
+ a class="page-index" attribute/value pair to the <dl>
+ tag.
+
+
Most pages should include a Page Index.
+
+
Documentation Content
+
+
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.
+
+
Footnotes
+
+
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
+ <sup> 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
+ Boost Style Sheet, a footnote
+ class is defined for this purpose.
+
+
Revision
+ Information
+
+
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 <hr> 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):
The very bottom of the page should contain any copyright information
+ that applies to the document.
+
+
Format
+
+
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.
+
+
Code
+
+
Code within the documentation should be placed within either
+ <code></code> or <pre></pre> tags. For code that's
+ placed inline with other text you use <code></code> tags, while
+ <pre></pre> 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 <pre></pre> tags to indent the text, to help
+ separate code blocks from other structural HTML blocks. The Boost Style Sheet specifies formatting for these
+ tags.
+
+
Note: "Code" includes variable names, function names, etc.
+
+
Lists
+
+
Lists should be constructed as unordered (<UL> and <li>
+ tags), ordered (<ol> and <li> tags) or definition (<dl>
+ and <DT> 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 Documentation Structure.
+
+
Graphics
+
+
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 <img> tag, in order to
+ allow the user's browser to optimize the formatting of the text before the
+ image is loaded.
+
+
Non-breaking
+ Spaces
+
+
Non-breaking spaces ( ) 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.
+
+
Cascading Style
+ Sheets
+
+
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.
+
+
Boost Style
+ Sheet
+
+
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.
+
+
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:
+
+
+
index Used for <dl> tags when writing index lists.
+
+
page-index Used for <dl> tags when writing page index
+ lists.
+
+
Footnote Used when writing Footnote numbers.
+
+
function-semantics Used for <dl> tags when writing
+ function semantic lists.
+
+
+
Templates
+
+
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 boost/libs/library/doc. They may need correcting if the
+ file will reside in some other location.
+
+
Note: 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).
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.
+
+
The section on Documentation Structure
+ 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).
+
+
The section on HTML Design 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.
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.
+
+
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.
+
+
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.
+
+
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.
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.
+
+
Paragraphs labeled "Note(s):" or "Example(s):" are informative, other
+ paragraphs are normative.
+
+
The summary and the detailed specifications are presented in the
+ order:
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:
+
+
+
Template arguments
+
+
Derived classes
+
+
Containers, iterators, and/or algorithms that meet an interface
+ convention
+
+
+
Interface convention requirements are stated as generally as possible.
+ Instead of stating "class X has to define a member function
+ operator++()," the interface requires "for any object
+ x of class X, ++x is defined." That
+ is, whether the operator is a member is unspecified.
+
+
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.
+
+
Template argument requirements are sometimes referenced by name.
+
+
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.(2)
Postconditions: the observable
+ results established by the function
+
+
Returns: a description of the value(s)
+ returned by the function
+
+
Throws: any exceptions thrown by the
+ function, and the conditions that would cause the exception
+
+
Complexity: the time and/or space
+ complexity of the function
+
+
Rationale: the rationale for the
+ function's design or existence
+
+
+
Complexity requirements specified in the library clauses are upper
+ bounds, and implementations that provide better complexity guarantees
+ satisfy the requirements.
The function semantic element description above is taken directly from the C++ standard, and
+ is quite terse. Here is a more detailed explanation of each of the
+ elements.
+
+
Note the use of the <code> ... </code> font tag
+ to distinguish actual C++ usage from English prose.
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,
+
+
+void limit( int * p, int min, int max );
+
+
+
+
Requires:p != 0 && min <= max
+
+
+
Requirements already enforced by the C++ language rules (such as the
+ type of arguments) are not repeated in Requires paragraphs.
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.
+
+
If an effect is specified in one of the other elements, particularly
+ postconditions, returns, or throws, it is not also
+ described in the effects paragraph. Having only a single description
+ ensures that there is one and only one specification, and thus eliminates
+ the risk of divergence.
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:
Specify both the type of exception thrown, and the condition that causes
+ the exception to be thrown. For example, the std::basic_string
+ class specifies:
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.
+
+
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.
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.
(1) 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.
+
+
(2) Although
+ in some cases the code is unambiguously the optimum implementation.
+
+
(3) 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.
+
+
(4) 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.
{{library}} uses several configuration macros in <boost/config.hpp>,
+ as well as configuration macros meant to be supplied by the application.
+ These macros are documented here.
+
+
Application Defined
+ Macros
+
+
These are the macros that may be defined by an application using
+ {{library}}.
+
+
+
+
Macro
+
+
Meaning
+
+
+
+
{{macro}}
+
+
{{meaning}}
+
+
+
+
{{macro}}
+
+
{{meaning}}
+
+
+
+
Public Library
+ Defined Macros
+
+
These macros are defined by {{library}} but are expected to be used by
+ application code.
+
+
+
+
Macro
+
+
Meaning
+
+
+
+
{{macro}}
+
+
{{meaning}}
+
+
+
+
{{macro}}
+
+
{{meaning}}
+
+
+
+
Library Defined
+ Implementation Macros
+
+
These macros are defined by {{library}} and are implementation details
+ of interest only to implementers.
Aleksey Gurtovoy is a Russian guy from Siberia, who now lives and works
+ in the United States. He is a technical lead at MetaCommunications, a job and people which
+ have taught him so much.
+
+
He was born in early 1977, has been in love with computers since 1989,
+ and still has a lot of exciting ideas for his "spare time" in the next few
+ years. He graduated with honors from Krasnoyarsk Technical State University
+ in 1998 with a Master Degree in Computer Science.
+
+
While being acknowledged as a talented programmer, Aleksey tries to be a
+ better engineer than he is now and hopes that reading good books will help
+ him with that task. He reads a lot. One of his favorite books about his
+ profession is 'The Mythical Man-Month' by Frederic P. Brooks, Jr.
Andreas Huber is a software architect at
+ Phonak Hearing Systems, where he is responsible for the development and
+ maintenance of operations software. At former companies Andreas has
+ been developing systems ranging from PC control software for machinery to
+ custom-made CRM applications. In recent years, more and more of his
+ professional work has shifted to the .NET platform (C# and C++/CLI).
+
+
In his spare time Andreas still enjoys to program in standard C++, which
+ is how Boost.Statechart came
+ into being. His other hobbies include swimming, camping, hiking and
+ traveling.
+
+
Andreas lives in Zurich, Switzerland with his wife Ruth.
Darin Adler has
+ been programming computers since 1976. He loves to do it.
+
+
His first major professional experience was at Apple Computer. In 1988 he led the team that rewrote
+ the Macintosh Finder in C++. Before that project was completed, he was
+ shanghaied to be the technical lead for the System 7 project (these days
+ they would call it "Mac OS 7"). The group he formed to help him do that,
+ the Blue Meanies, is still a legend
+ in the Apple community.
+
+
Since Apple, Darin has worked at General Magic as an architect of the
+ Magic Cap OS, used
+ the moniker Bent Spoon Software to do
+ consulting, and helped start Eazel, a company that worked to make Linux
+ easier to use and developed the Nautilus graphical shell for GNOME. Since 1997, he has worked from his home
+ in Los Angeles, CA, collaborating with clients and coworkers in other
+ locations.
+
+
He prefers to use and program Macintosh computers with C++. But work on
+ the GNOME project is best accomplished with a non-Macintosh PC. (That's why
+ Darin is sitting in front of two computers.)
+ The other people working on the GNOME project don't like C++, so he's
+ writing a lot of C code these days.
+
+
The larger
+ version of his picture shows him hard at work with his C++ guru, his
+ daughter Sophia.
+
+
He has hobbies and stuff but you don't want to read about that here.
+
+ Dave Abrahams is a founding
+ member and moderator of Boost, and an active member of the wider open-source
+ community. He has been an ANSI/ISO C++ committee member since 1996, and has
+ worked in the software industry since 1988. In 2001 He founded
+ Boost Consulting
+ , a company dedicated to providing professional support and development
+ services for the Boost C++ libraries and associated tools.
+
+ Dave often shows up at C++ standards committee meetings on a bicycle. He lives
+ in Somerville, Massachusetts with his beautiful wife, Luann.
Dietmar Kuehl (the "ue" is
+ actually a "u-umlaut", ie. one of those funny German characters which has
+ two dots above it) was fork(2)ed in early 1968.
+
+
He visited school more or less successfully from 1973 to 1987. In 1987
+ he started to study at the Technical University of Berlin. He finished his
+ studies in 1997 with a Diplom (roughly the German equivalent of a masters)
+ in Mathematics. His thesis was "Design Pattern for the Implementation of
+ Graph Algorithms"; strike the "Design Pattern" and put in "Generic" somehow
+ to get an idea of the main topic. The thesis is available from http://www.dietmar-kuehl.de/generic-graph-algorithms.pdf.
+
+
Since 1997 he has worked as consultant for a small company called Claas
+ Solutions (the "aa" is no typo), mainly working for major German banks.
+ Since late 1995 Dietmar Kuehl has been one of the moderators of the
+ newsgroup comp.lang.c++.moderated. He is active on
+ the C++ Standards committee.
As a generic programming zealot, his search for the One True Generic
+ Language has seen him through the trials of the Generic Programming Group, and
+ manydiversions.
+
+
When not hunched over in front of an XEmacs window, Doug looks to his wife Amy to
+ help him navigate through the daylight. Once there, he enjoys tennis and
+ the occasional game of paintball.
Ed Brey lives in Menomonee Falls, Wisconsin, a village outside of
+ Milwaukee. In the summertime, he likes to play tennis with his wife, and in
+ the winter, if there is enough snow, he likes to go tobogganing or
+ ice-skating. If it is not nice enough outside for either of those, he plays
+ on the piano.
+
+
Ed works at Eaton Corporation in
+ Milwaukee. He started working there as part of Marquette University's engineering co-op program.
+ Upon graduation in 1995 from Marquette with a BS in electrical and computer
+ engineering, he was hired on full-time, where he initially worked on
+ firmware for industrial controls. More recently, he has been working on a
+ PC-based configuration tool for industrial networks. Ed received his MS in
+ computer engineering in 2001 from NTU
+ .
+
+
Ed has held programming as a pastime since his grade school days, when
+ he wrote a babysitting invoicing program. Soon after, he wrote a game
+ inspired by the TV game show “Press Your Luck”. Ever since,
+ programming languages and concepts, along with finding ways to improve the
+ art and science of coding software, have always peeked his interest.
+
+
Lastly, Ed has managed to retain his perspective. As fun as computers
+ and programming are, Ed's true loves in life are the Lord Jesus whom he
+ serves and his dear wife Beth.
Eric Friedman is an undergraduate at Stanford University. Born
+ in 1984, he discovered programming at 10 and Boost at 17. He is a Computer
+ Science major, with interests in Political Science and Arabic.
+
+ Eric is co-author of the Variant
+ library and intends to author more.
+
+ He enjoys rap music, discussing politics, and, of course, programming.
+
+ Though not starving, Eric is a college student and so appreciates both
+ spontaneous donations and internship opportunities. He can be contacted at
+ ebf@users.sourceforge.net.
Fernando Cacciola has
+ been programming since 1984 when he got his hand on a Tandy Color Computer
+ II for the first time. He started with BASIC at the time, but quickly moved
+ to Assembly Language to get the most out of the Home Computers of the time
+ (from a Sinclair 1500 [Z80] to a Commodore 64 [Motorola 6510]).
+
+
In 1990 he discovered the C programming language and started to work as
+ a professional programmer. In 1995 he discovered C++, and during his long
+ time employement in a company producing CAD systems, the fields of
+ Geometric Computing, Computer Graphics, Image Processing and Numerics in
+ general.
+
+
He studied Biochemistry at the John F. Kennedy (Argentina) University
+ for 4+ years, but had to drop because of his full-time job as a programmer.
+ He would complete a CS degree if he only had the time.
+
+
After 13 years of being an employed programmer (in just a couple of
+ companies), by the end of 2003, he became a freelancer and founded SciSoft,
+ a company specialized in technically/scientifically-oriented software.
Gary Powell has been messing around with C++ since
+ '87 when he dreamed about adding his own operators to the language. Since
+ then he's been busy overloading everything in sight, and working on
+ bringing functional programming to C++.
+
+
He currently works for Sierra On-line http://www.sierra.com a division of Havas
+ Interactive, a wholly owned subsidiary of Vivedi Universal of France,
+ http://www.vivendi.com as a game
+ programmer where he writes AI.
+
+
He can be reached at gary.powell@sierra.com but don't ask
+ him how to solve the riddle of the left handed troll.
Gennadiy Rozental is a software developer from
+ Ukraine, who now lives in New Jersey, United States and work for Thomson
+ Financial in New York. He is married, with son and daughter.
+
+
Gennadiy graduated from MIPT: Moscow Institute of Physics and Technology
+ with Master degree in computer science. Ever since Gennadiy has been
+ programming mostly in C++.
+
+
In his spare time he not only works on boost, but also enjoy origami
+ making.
+
+
You can contact him by sending mail to rogeeff at mail dot com
Dr. Greg Colvin has been hacking happily
+ since 1972. He is a member of the ANSI/ISO C++ standards committee and a
+ Principal Member of Technical Staff with the Java Products Group at Oracle
+ Corporation. In his spare time he plays apocalyptic electric blues guitar
+ in his Colorado, USA home studio.
After 15+ interesting years
+ that Hartmut spent working in industrial software development, he still
+ tremendously enjoys working with modern software development technologies
+ and techniques. His preferred field of interest is the software development
+ in the area of object-oriented and component-based programming in C++ and
+ its application in complex contexts, such as for spatial information
+ systems, internet based applications and parser technologies. Hartmut
+ enjoys using and learning about modern C++ programming techniques, such as
+ template based generic and meta-programming and preprocessor based
+ meta-programming.
+
+
You can contact him by sending mail to: Hartmut.Kaiser [at] gmail [dot]
+ com
Hervé Brönnimann is an Assistant
+ Professor at the Polytechnic University
+ in Brooklyn, NY. His research deals with computational geometry,
+ algorithms, and implementation. Prior to crossing the Atlantic, he was a
+ researcher at INRIA, participating in the development of the CGAL library for geometric computation.
+
+ In Boost, he is one of the authors of the Interval library, and of the
+ Minmax library.
When Howard Hinnant is not monkeying around, he is a
+ software engineer for Apple and represents Apple on the C++ Standards
+ committee as Library Working Group Chairman. Howard has is also one of the
+ co-authors / co-inventors of the rvalue reference work for C++09 making move
+ semantics and perfect forwarding practical in C++. In the past Howard was the
+ principal author of the CodeWarrior C++ library.
+
+
Howard is married with four children, four dogs (he really isn't that fond of
+ dogs), a rabbit, several exotic lizards with the usual accompaniment of
+ insects (which the lizards are supposed to eat but find more entertaining to
+ turn loose in the house), um... let's see ... fish, wild mice (they eventually
+ kidnapped all the domesticated rodents), several dozen chickens (no I'm not
+ kidding)... The neighbors are trying to turn my property into a federally
+ protected wildlife preserve. They've got a fighting chance ... the kids alone
+ would qualify.
+
+
When not sitting in front of his computer, Howard enjoys snow skiing and ...
+ more, snow skiing.
Hubert Holin is a mathematician. He is
+ currently a civil servant of the french state (no longer indentured, but
+ still stuck). He has also worked as a developper in a small french start-up
+ , and as a math teacher in a private non-religious higher-ed school.
+
+
His first programs were in assembly language/micro-code on an
+ Hewlett-Packard HP 25
+ hand-held calculator (a marked improvement over his father's use of
+ binary-on-strips-of-paper on some forgoten piece of metal...), back in the
+ mists of time. He is a Mac-using refugee of the Atari, and on a personal
+ jihad against The Evil Empire Of Computing ™.
+
+
Very much a Child of the World, he has lived in Europe, Africa, the
+ U.S.A., and is married with a chinese girl (with whom he has both a
+ daughter and a son).
Jeff Garland a
+ software developer/consultant from sunny Phoenix, Arizona USA (that's
+ always UTC-7 since there's no DST in AZ). He is the author of the boost date-time library
+ as well as a book on representing software
+ architecture.
+
+
Jeff has been distracted from finishing all those cool features people
+ want in date-time by running the Boost
+ Wiki, serving as a review manager, and a Boost Moderator.
+
+
On the rare day that he's not in front of a computer from morning till
+ night you might find him out hiking, biking, or skiing in Arizona's
+ mountains and canyons with his wife and 2 daughters.
Jens Maurer is a software developer from Germany who
+ lives close to Frankfurt/Main. He was born in 1973 and hasn't died yet.
+
+
He has worked for a multimedia company programming home-banking
+ applications, CGI scripts and Java applications. He also helped program
+ some simulation systems for long-term decision support to aid businessmen
+ in arguing about company investments.
+
+
He is neither married nor does he have a girl friend, but asked his
+ colleagues to find one for him.
+
+
In his spare time, he likes visiting foreign countries but dislikes
+ getting there in uncomfortable airplane seats. On random week-ends, he
+ enjoys participating in historic dance courses (without a costume, of
+ course). Sometimes, he needs fresh air and goes for a walk.
Jeremy Siek is a Ph.D. student at Indiana Univ.
+ Bloomington.
+
+ He is the author of the Matrix Template Library (MTL), and helped design
+ the Generic Graph Component Library, which is now the Boost Graph Library
+ (BGL).
+
+ Once in a while Jeremy "comes up for air" and enjoys fencing, hiking,
+ skiing, and reading. He's also been spotted at a few fightin' irish
+ tailgaters (BYOB).
+
+ Jeremy has an intense fear for the ancient dark forests where dusty decks
+ thrive and devour programmers, places where the light of abstraction has
+ not yet reached.
Joaquín is a telecom engineer from the Polytechnic University of Madrid. He currently
+ works at Telefónica,
+ Investigación y Desarrollo, the R&D branch of the
+ Telefónica Group, where he leads a small group of engineers working on
+ advanced mobile services. Though actual programming is not one of his
+ job responsibilities, he still does some C++ for fun when nobody's
+ around.
+
+
Joaquín's professional career began with his first exposure to a
+ Dragon 32 (a Tandy TRS-80 clone) at the age of 13, though at the time he
+ probably was unaware of the future impact of this event. He enjoys
+ Mathematics, Logic and Latin; his lower case interests include paper
+ folding, compulsive reading, travel and visiting all sorts of pubs and
+ restaurants. You can contact him at joaquin@tid.es.
Joel got into electronics
+ and programming in the 80s because almost everything in music, his first
+ love, is becoming electronic and digital. Back then, he used to build his
+ own guitars, effect boxes and synths. He enjoys playing distortion-laden
+ rock guitar, composes and produces his own music in his home studio.
+
+
In the 90s, he went to Japan and worked there as a software engineer.
+ There, he learned C++ and immediately fell in love it. He's still trying
+ his best to master the language in all its immensity.
+
+
Joel is quite adept in writing code using modern C++ techniques such as
+ template metaprogramming and C++ functional programming. He's very happy
+ and enthusiastic with his current job as a consultant and engineer at
+ Boost Consulting.
Jonathan Turkanis is a Ph.D. Candidate in
+ mathematical logic at the University of California at Berkeley and a
+ coauthor of the forthcoming C++ Cookbook, published by O'Reily.
Kevlin Henney (mailto:kevlin@curbralan.com, http://www.curbralan.com) is an independent
+ consultant and trainer based in the UK. He has developed and delivered
+ training course material and consultancy on many aspects of OO development,
+ which he has practiced across a number of domains for longer than he cares
+ (or can) remember. His professional interests include patterns, OO and
+ component-based design, architecture, distributed object systems, and
+ languages, including C++, C#, Java, and Ruby. He is also a member of the
+ BSI C++ standards committee.
+
+
Now that writing code is no longer the core responsibility of his job,
+ his non-professional interests seem to include the hacking associated with
+ the aforementioned professional interests. However, never being one to keep
+ something to himself (like C++'s relationship with C, this is regarded as
+ both a strength and a weakness), he shares/inflicts (delete as necessary)
+ his professional and non-professional development experiences with/on
+ (ditto) others through writing articles and presenting tutorials, workshops
+ and papers at conferences.
+
+
He is married, and not just to his work. He and Carolyn have one child,
+ Stefan. The little spare time that remains to him is taken up with music,
+ reading, pub appreciation, etc. Although with a newborn, there is more
+ reading and less pub appreciation (pubs are still appreciated, but more in
+ memory than in interaction). Finally, although he enjoys writing,
+ Kevlin is not really one for writing in the third person.
Lie-Quan Lee, AKA Rich Lee, is a graduate stduent in
+ Computer Science at University of Notre Dame. He is the author of the
+ Generic Graph Component Library (GGCL).
+
+
He has a strong desire of learning to disassemble and assemable any
+ electrical appliances. He likes playing bridge but never had a chance to
+ play it after he entered the wonderful world of computers.
Mac Murrett is an Advanced Developer at Vanteon. He lives in Rochester, NY, where
+ everything closes at 10 PM. This gives him plenty of time to think.
+
+
Mac graduated from SUNY: University at Buffalo with a degree in
+ Mathematics. He has been programming Macintoshes since he was 12 years old,
+ and recently won the
+ Best Hack Contest at MacHack
+ 2001. Nonetheless, he swears up and down that his name has nothing to
+ do with the computer.
Mark Rodgers lives in Wellington, the capital of New
+ Zealand, with his wife, Clare, and their son, Ronnie.
+
+
He studied Computer Science at Victoria University of Wellington
+ from 1983 to 1986, completing a B.Sc. (Hons). He now works as
+ consultant through his company, Cadenza New Zealand Ltd, and also markets
+ Cadenza Drawing Board™, a CAD system he developed.
+
+
Mark has been programming in C++ since about 1990, and loves every
+ minute of it, but is continually amazed at how much more he still has to
+ learn.
Mat Marcus is a senior computer
+ scientist in the Software Technology Lab at Adobe Systems, Inc. He has been
+ developing software since 1985. Recent projects include a collaboration
+ with Alex Stepanov on a
+ programming class and work on the Adobe Source Library. Mat's first
+ contribution to Boost came in the summer of 2000, when he discovered a way
+ to exploit the properties of the sizeof operator to simulate partial
+ specialization (is_pointer, etc. with Jesse Jones). Mat lives in Seattle
+ with his wife and son.
Paul
+ Moore lives in Cheshire, England. He is married, with one son. His "day
+ job" is as an Oracle DBA, but he writes C and C++ programs in his spare
+ time.
+
Paul started programming on Acorn's BBC Micro and RISC PC series of computers,
+ but finally went mainstream and bought a PC, on which he now runs Windows and
+ Linux. Paul's main interest is in porting and developing open-source software,
+ and so his main programming language is C (at least until the open source
+ community switches to C++).
+
Paul's main claim to C++ fame is that he owns all 3 editions of Bjarne
+ Stroustrup's "The C++ Programming language", plus the ARM and the C++
+ standard, but he didn't own a C++ compiler until after the 3rd edition of
+ Stroustrup's book came out. Make of that what you will...
Pavol Droba lives in Bratislava, the
+ capital of Slovakia with his beautiful wife Lenka.
+
+
Since childhood he has always been messing with computers in one way or
+ the other until he settled down with C++. Since then he did a lot of
+ various projects but he retained his affinity to his favorite programming
+ language.
+
+
He loves to design nice programs that works and to see how the pieces of
+ the puzzle called design come together.
+
+
Currently he is a developer in a small company where he leads a group of
+ 5 other guys.
+
+
When he is not at the computer Pavol enjoys his time with his wife. In
+ winter he likes skiing, in summer he does some scuba diving.
Ralf is a crystallographer. He has a
+ degree in Mineralogy (Bochum,
+ Germany), and a Ph.D. in Crystallography (ETH Zurich ,
+ Switzerland). Real Mineralogists and Crystallographers run experiments with
+ x-rays and hardware that is not normally associated with C++ and Boost.
+ However, when Ralf kept breaking the expensive experimental equipment too
+ often, he decided that he would cause less damage as a computational
+ crystallographer.
+
+
Being a scientist, Ralf spent most of his life programming in Fortran,
+ the great grand-father of all good programming languages (if you know
+ Backus-Naur you know the name of the inventor
+ of Fortran). Ralf is a co-author of the CNS Fortran program that is very popular in
+ structural biology. When he learned that a real programmer can write
+ Fortran in any language, Ralf knew that it was time for him to learn C++.
+ Of course, absorbing four decades of progress in the field of computer
+ science all at once crashed his brain. To be able to deal with the
+ challenge, he spawned two child processes and named them Lisa and Anna. To
+ see Lisa, click on the picture and turn your monitor by 180 degrees around
+ the view axis. (Other pictures of Lisa and Anna do not require
+ gymnastics with the monitor.)
+
+
Right now, Ralf is working for the Computational Crystallography Initiative at the
+ Lawrence Berkeley National Laboratory in
+ California. The goal of this initiative is to write a software system for
+ high-throughput protein crystal structure determination, also known as
+ Structural
+ Genomics. Surprisingly, the gestation period for such a system turns
+ out to be much longer than it was for Lisa and Anna. However, pre-natal
+ diagnosis already revealed that Python and C++ are the parents-to-be. For
+ an ultra-sound image of the new system at its early developmental stage
+ click here.
Rene has spent most of his
+ life programming in one language or another. From assembly, through BASIC,
+ and up to C++ and Lisp, he has managed to program on a variety of computers
+ and operating systems.
+
+
Currently he is running Redshift Software, Inc. (redshift-software.com), a company he
+ founded with the help of some friends in 1997.
+
+
In the past he managed to get a concurrent MS and BS in Computer Science
+ from Loyola University at Chicago. Work for the Institute for the Learning
+ Sciences at Northwestern University building AI related systems. And worked
+ on game development at Jellyvision Inc. (jellyvision.com). Where he lead the
+ programming of "You Don't Know Jack: The 5th Dementia", and of "That's a
+ Fact: Jack! Read.". Which where the basis for the development of the first
+ two versions of "Who Wants To Be a Millionaire".
+
+
His motto of "clean code, clean graphics, it can always stand
+ improvement" has repeatedly gotten him in trouble.
Robert Ramey is a contract software developer
+ living in Santa Barbara, California. He has been involved in all aspects of
+ the computer industry for more than 30 years.
+
+
After graduating with an MS in Operations Research from U.C. Berkeley in
+ 1971 and serving 18 months in the miltary, he left on a trip to Ecuador.
+ There he founded a data processing company which is still in operation
+ today. Returning to California in 1986, he focused on the more technical
+ aspects of software development. This has resulted in the completion of
+ projects such as the Postman's Sort and Boost serialization library - among
+ others.
+
+
Other current interests include hanggliding, squash, hiking and bike
+ riding.
Ronald Garcia is a
+ Ph.D. student at Indiana University in Bloomington, Indiana. He is the
+ author of the Boost Multidimensional Array Library (MultiArray). His research
+ interests include software engineering tools and techniques, programming
+ languages, generic and generative programming and high performance
+ scientific computing.
+
+
When he's not in front of a computer, Ron's interests include playing
+ ultimate frisbee, bass guitar, drumset, and West African
+ percussion.
Samuel Krempp is a PhD
+ student in mathematics, at the CMLA in the 'Ecole Normale
+ Supérieure' de Cachan (France). He spends most of his time
+ implementing complicated image recognition algorithms, and thus had to get
+ acquainted with C++.
+
+
He enjoys many other things - one of them is diving in wonderful, warm,
+ sunny seas when he can afford it. And obviously, another is eating
+ camembert and bread, drinking wine... and other activities typical of a
+ French guy :)
Thomas Witt is a senior software developer at Zephyr Associates, Inc.. Being a
+ mechanical engineer by training, he nowadays spends most of his time
+ developing applications and libraries in C++. Twice a year he is allowed to
+ leave his office to attend C++ standards committee meetings.
+
+
Thomas is coauthor of the Boost.Iterator library and in a less busy and
+ distant past was acting as Boost Review
+ Wizard
+
+
In his spare time Thomas likes reading, running, swimming and skiing.
+ There is also rumor of him being a railroad enthusiast, but Thomas refuses
+ to comment on this. Thomas lives in Stateline, Nevada enjoying the view of
+ Lake Tahoe and the slopes of the surrounding ski resorts.
Thorsten Ottosen holds a Bsc in
+ Computer Science at Aalborg University, Denmark. After having studied
+ mathematics at University of Technology in Sydney, Australia, he has now
+ returned to Denmark to write a second thesis in the area of decision
+ support systems. His first thesis was in computer graphics
+ since he used to dream about making computer games.
+
+
Thorsten is also a co-owner and part-time employee of Dezide, a company that specializes is
+ trouble-shooting programs based on Bayesian-network technology.
+
+
In his spare-time he codes/reads/hacks C++ and participates in ANSI/ISO
+ C++ committee meetings. In his spare-time of his spare-time he enjoys
+ jogging, reading, and being with family and friends.
If
+ we are to believe MBTI tests, Vesa is an
+ INTJ. He has been like that probably since late 1978-1979, because,
+ according to some sources, it takes 2-3 years to develop the basic temperament.
+ Previously he saw himself mostly as a "builder of systems" and
+ "applier of theoretical models", but nowadays he is beginning to see
+ the "mastermind" aspect of his personality. As a
+ "Free-Thinker", his mind hardly ever rests.
+
Vesa enjoys healthy and sustainable ways of life. He is a vegetarian and likes
+ cooking. Exercise is a daily part of his life - he needs to be in good shape in
+ order to sit all day in work. He likes going to the gym, swimming, spinning,
+ running, roller skating, etc... He also practices dancing.
+
For the past years, he has been working in a small
+ company that develops console games. His role is the development of
+ software technology, such as class libraries, frameworks and tools, for making
+ games. He doesn't see himself as a game or a graphics programmer, although he
+ has been involved in quite a few such projects. For the past few years, most of
+ his programming has been in C++, but recently he has also enjoyed writing some
+ Ocaml.
+
He likes buying technical books using the company credit card, but lately he
+ hasn't had the time to read as much as he would like (hopefully this changes
+ soon). He likes reading (a lot) computer science and software engineering, but
+ also psychology, philosophy and various self-help books, because he knows that
+ all the really hard problems are social - not technical. Fantasy is also close
+ to his heart.
+
Vesa is a bit ambivalent about his university studies. He is a self-educated
+ programmer and has experience ranging from bit twiddling to generative
+ programming and also leading of small teams. Like many of his close colleagues,
+ he sees that the depth of computer science education, at least in Finland, is,
+ frankly, insufficient. He'll probably complete his studies some day, because
+ sadly most people respect authority by rank, title or publication far more than
+ he does.
+
Vesa is an eXtreme Programmer. He has found out that in order for pair
+ programming to work, both pairs must share a similar level of experience and
+ must be both willing and able to externalize their thoughts. If he is sometimes
+ forced to stop refactoring, he'll probably quit his job. He thinks that
+ optimization, including improving readability and simplifying structure, is the
+ root of all fun in programming. He dislikes writing documentation and reports
+ that are never read.
+
One of his friends coerced him to use the image that you see on this page. The
+ image was scanned from a rather worn out picture taken by an ex-girlfriend and
+ is probably the only picture of Vesa having his natural smile. Vesa is neither
+ married nor engaged, but just recently he met a very nice girl... While
+ programming is interesting and fun, it is love that really makes him happy. ;)
+
+
diff --git a/people/vladimir_prus.htm b/people/vladimir_prus.htm
new file mode 100644
index 0000000000..342ea69695
--- /dev/null
+++ b/people/vladimir_prus.htm
@@ -0,0 +1,65 @@
+
+
+
+
+
+
+
+ Vladimir Prus
+
+
+
+
Vladimir Prus is a PhD student at Moscow State
+ University. He's supposed to do some research about program analysis,
+ processors and graphs, but also has various other interests, like software
+ engineering tools and compilers.
+
+
Volodya would probably spend all his time staring at the monitor and
+ haunting MSU corridors, but luckily is married and hardly can be seen in
+ front of a computer on weekends. He's not into any extreme sports, and
+ spends spare time going to cinema or just walking with his wife Caroline in
+ quiet parts of Moscow.
Bill Kempf lives in Omaha, NE with his wife
+ Bonnie, his cat Dexter and his two Chinchillas, Chimney and Minuet. He
+ married on Oct. 30, 1999 where he and his wife held a Halloween costume
+ reception. If that doesn't give you an idea of what kind of guy he is,
+ nothing will.
+
+
Bill graduated from Doane, a small private college in Nebraska in 1992
+ with a B.S. in Computer Science/Math. Being in the wrong place at the wrong
+ time he had to take a job as the only person in an IS shop for a local
+ affiliate of the Bunge Grain Company. In 1995 he moved on to a job as a
+ software engineer for First Data Resources where he worked on client/server
+ financial applications.
Will all Boost libraries work with your compiler?
+Unfortunately, the answer is "it depends". See the
+Compiler Status Summary
+to see exactly what works and what doesn't.
+
+
Boost libraries rely on modern C++ features such as templates
+and the C++ Standard Library. Most modern compilers support
+those major features fairly well. But even today, years after the
+adoption of the C++ Standard, some compilers still don't support
+important minor features like partial template specialization.
+
+
Boost library authors often expend a great deal of effort
+trying to work around compiler deficiencies. Nevertheless,
+some libraries will not compile at all with certain compilers or
+may have crippled functionality. Even if the current
+release of a compiler supports a boost library, older versions of
+the compiler may not work properly.
+
+
Boost releases are run through regression
+tests which
+automatically generates Compiler Status Tables for various
+platforms. Unless otherwise indicated, the C++ Standard Library
+implementation is the one shipped with the compiler.
+
+
Warnings:
+
+
+
These tables are not a good indication of a
+particular compiler's compliance with the C++ Standard. The
+Boost libraries often contain workarounds which mask compiler
+deficiencies.
+
+
Some regression tests are run only occasionally, and so are relatively
+ out-of-date. Check the date for each table.
+
+
+
The
+Compiler Status Summary
+includes table summaries for specific releases, as well as table summaries for
+recent CVS snapshots. Release
+tables are identified by the release number appended to the table name. CVS
+snapshot tables do not have a release number appended.
+
+
The CVS
+code is being updated several times a day, so it may contain bug fixes, compiler
+workarounds, new features, and even whole new libraries. It may be unstable,
+however.
The Run Date is important because the regression tests
+which create the status tables are run asynchronously, and thus
+may not represent the most current Boost release.
+
+
The Program column identifies the actual source file
+for the test. Each row in the table represents a different
+test.
+
+
The Test Type column identifies
+the type of test performed:
+
+
+
+
Test Type
+
Action
+
Required to Pass
+
Description and Use
+
+
+
compile
+
compile only
+
Compiler returns 0.
+
Verify that a source file will compile correctly, but
+ without any attempt to link or execute. Used when
+ factors such as possible object library unavailability
+ make a run test impractical.
+
+
+
compile-fail
+
compile only
+
Compiler must return non-zero.
+
Verify that a source file fails to compile. Used to
+ verify that an expected compile-time error was detected.
+
+
+
link
+
compile, link
+
Both compiler & linker return 0.
+
Verify that a source file will compile and link
+ correctly, but without any attempt to execute the result.
+ Used when factors such as possible data file
+ unavailability make a run test impractical.
+
+
+
link-fail
+
compile, link
+
Either the compiler or linker must return non-zero.
+
Verify that a source file fails to compile and link.
+ Used to verify that error detect which depends on
+ unresolved externals works correctly.
+
+
+
run
+
compile, link, execute
+
Compiler, linker, and executable must all return 0.
+
Verify that a source file compiles, links, and the
+ resulting program executes correctly (as indicated by a
+ zero return code.) This is the primary test type
+ for most uses.
+
+
+
run-fail
+
compile, link, execute
+
Both compiler and linker must return 0, and the
+ executable must return non-zero.
+
Verify that a source file compiles and links
+ correctly, and that execution of the resulting program
+ detects some error. Used to verify runtime error
+ detection code works properly.
+
+
+
+
Each remaining column in the table represents the individual
+compiler indicated. Unless otherwise indicated, the C++ Standard
+Library implementation is the one shipped with the compiler. A Pass
+entry indicates success for the indicated Test Type, while
+a Fail entry indicates
+failure. See Required to Pass in the above table for specifics.
+
+
When possible, Fail entries are linked to
+error messages indicating the reason for the failure. Note that the web page
+containing error messages may be as much as one megabyte in size.
The compiler status tables have been prepared with resources
+donated by a number of individuals, educational institutions, and
+companies. Boost would like to thank them for their support.
Note, however, that Boost does not endorse any product or
+service, nor does Boost guarantee that some or all of its
+libraries work with any of the products or services mentioned
+above.
+
+
+
+
Revised
+22 January 2004
+
+
+
diff --git a/status/explicit-failures-markup.xml b/status/explicit-failures-markup.xml
new file mode 100644
index 0000000000..445ad11e6b
--- /dev/null
+++ b/status/explicit-failures-markup.xml
@@ -0,0 +1,5157 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The compiler does not support features that are essential for the library.
+
+
+
+
+
+
+
+ The toolset is not supported by Boost.Regex.
+
+
+
+
+
+
+
+
+
+
+
+ The test fail with ICE, but the exact reason for ICE is not
+ known. A minimal example of casting any to reference type
+ seem to work. Anyone interested in using this functionality
+ with msvc is suggested to do additional testing.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Compilers need to support partial template specialization
+ to work with zero length arrays.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The test would (most likely) compile and run properly if the workaround
+ syntax .to_container( c ) was applied to all list_of() expressions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This test could probably be made to work if somebody with knowledge
+ about the compilers would submit a patch.
+
+
+
+
+
+
+
+
+
+
+
+ The test would (most likely) compile and run properly if the workaround
+ syntax .to_container( c ) was applied to all list_of() expressions.
+
+
+
+
+
+
+
+ The test could probably be made to work if somebody submitted a patch.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The test would (most likely) compile and run properly if the workaround
+ syntax .to_container( c ) was applied to all list_of() expressions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The test depends on Boost.Pointer Container which probably does not work for
+ this compiler.
+
+
+
+
+
+
+
+
+
+
+
+ The test depends on Boost.Pointer Container which probably does not work for
+ this compiler.
+
+
+
+
+
+
+
+
+
+
+
+ The test depends on Boost.Pointer Container which probably does not work for
+ this compiler.
+
+
+
+
+
+
+ The test does not work for
+ this compiler.
+
+
+
+
+
+
+
+
+
+ The test depends on Boost.Tuple which probably does not work for
+ this compiler.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by Boost.Function.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by a bug in the compiler triggered by the
+ use of the debug flag '-gall'. It has been reported to the
+ compiler vendor.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is only present in release mode and is caused by /OPT:ICF.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Long double NaN's are apparently handled incorrectly on this platform.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is due to NaNs trapping.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The serialization library does not support this compiler.
+
+
+
+
+
+
+
+ XML serialization is not supported on this compiler.
+
+
+
+
+
+
+
+
+ The serialization library does not support this compiler.
+
+
+
+
+
+
+
+ XML serialization is not supported on this compiler.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ These are strange runtime failures for
+ which there is no obvious explanation. Later versions of the
+ Intel compiler (eg:8.0) seem to have resolved the issue.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ For some reason Code Warrior has difficulty compiling some of the
+ input code. This may be related to limitations of locale handling,
+ but it's unclear at this time (2005-May-21).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Some older compilers are confused by the template code here.
+ These are new features to date-time in 1.33 and there is no
+ plan to backport to these non-compliant compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Some older compilers are confused by the template code here.
+ These are new features to date-time in 1.33 and there is no
+ plan to backport to these non-compliant compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Some older compilers are confused by the template code here.
+ These are new features to date-time in 1.33 and there is no
+ plan to backport to these non-compliant compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Some older compilers are confused by the template code here.
+ These are new features to date-time in 1.33 and there is no
+ plan to backport to these non-compliant compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Some compilers are confused by the template code here.
+ These are new features to date-time in 1.33 and there is no
+ plan to backport to these non-compliant compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Some older compilers are confused by the template code here.
+ These are new features to date-time in 1.33 and there is no
+ plan to backport to these non-compliant compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Some older compilers are confused by the template code here.
+ These are new features to date-time in 1.33 and there is no
+ plan to backport to these non-compliant compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+ Some older compilers are confused by the template code here.
+ These are new features to date-time in 1.33 and there is no
+ plan to backport to these non-compliant compilers.
+
+
+
+
+
+
+
+
+
+
+
+ Some older compilers are confused by the template code here.
+ These are new features to date-time in 1.33 and there is no
+ plan to backport to these non-compliant compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+ Some compilers are confused by the template code here.
+ These are new features to date-time in 1.33 and there is no
+ plan to backport to these non-compliant compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ These compilers are unfortunately able to correctly compile the
+ new format-based input-output code for date time. Suitable, but
+ less flexible, alternatives are available on these compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ These compilers are unfortunately able to correctly compile the
+ new format-based input-output code for date time. Suitable, but
+ less flexible, alternatives are available on these compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ These compilers are unfortunately able to correctly compile the
+ new format-based input-output code for date time. Suitable, but
+ less flexible, alternatives are available on these compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+ These compilers are unfortunately able to correctly compile the
+ new format-based input-output code for date time. Suitable, but
+ less flexible, alternatives are available on these compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+ These compilers are unfortunately able to correctly compile the
+ new format-based input-output code for date time. Suitable, but
+ less flexible, alternatives are available on these compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ There is apparently a bug in Borland library
+ such that std::local_time and std::gmtime are
+ returning a time that's 1 hour ahead GetSystemTimeAsFileTime
+ during DST. This is a rather serious problem in that
+ some of the date-time clock interfaces will give the wrong
+ current time.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The sun 5.8 compiler and standard library have a problem with
+ the classic facet which causes some of the io tests for date-time
+ to fail. Overall this should not affect most uses of the library.
+
+
+
+
+
+
+
+
+ The STLPort standard library has issues with some custom
+ facet settings causing an unexplained failure in these
+ facet tests.
+
+
+
+
+
+
+
+
+
+
+ The STLPort standard library has issues with the handling
+ of the classic facet which causes some fo the i/o tests
+ for date-time to fail. Overall this should not affect
+ most uses of the library.
+
+
+
+
+
+
+
+
+
+
+
+ MSVC 7.1 with its standard library passes all date-time tests.
+ For some reason when paired with stlport a few widestream
+ io tests do not format output correctly. Overall this should
+ not affect most uses of the library.
+
+
+
+
+
+
+
+
+
+ Although these tests compile, the execution aborts for
+ an unknown reason. Note that sometimes the excution is
+ ok on cw-9_4. This may be fixable if someone
+ can track down the source of the problem.
+
+
+
+
+
+
+
+
+
+ These tests are failing with the beta2 version of VC_8. At least
+ one of them is directly a result of the new VC_8 standard library
+ restricting the year value in a tm struct to be positive (that is
+ greater than year 1900). This is a change from VC7_1 and Microsoft
+ is considering removing this restriction.
+
+
+
+
+
+
+
+
+ These tests are for serialization which has been marked as unusable.
+ The issue was specifically noted on
+ AIX version : 5.2.0.41 using IBM XL Version 8.0.0.0.
+
+
+
+
+
+
+
+
+
+
+ The failure is caused by a standard library bug. It doesn't
+ support user defined facets which are not default
+ constructible. This has been reported to the compiler vendor.
+
+
+
+
+
+
+
+
+
+
+ These tests rely on the ability of an std::map to be
+ instantiated on an incomplete type. The Rogue Wave
+ version 2.2 and higher does not allow this.
+
+
+
+
+
+
+
+ The failure is caused by a standard library bug. It doesn't
+ support user defined facets which are not default
+ constructible. This has been reported to the compiler vendor.
+
+
+
+
+
+
+
+
+
+
+ The failure is caused by a standard library bug. The end-of-stream
+ istream iterator can only be constructed when the istream iterator
+ has been instantiated with char as the character type. This has
+ been reported to the compiler vendor.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The exact reason of this (linker related) bug is unresearched. The test passes
+ on some environments. The test was found to fail on a platform whit a german
+ version of the compiler.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Due to standard library bugs this configuration is not supported by
+ the most recent version of the library.
+
+
+
+
+
+ Due to standard library bugs, this version is not supported.
+ More recent version of the library should work OK.
+
+
+
+
+
+
+ fstream for this compiler has serious problems and is not supported
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The library does not support wide paths on this compiler because
+ it does not support SFINAE.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ These failures are reported to be fixed in Sun's
+ next compiler release.
+
+
+
+
+
+
+
+
+
+
+ This compiler does not support the Boost.Range
+ library, on which Boost.Foreach depends.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This compiler does not support detection of
+ const rvalues.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This compiler does not support detection of
+ rvalues.
+
+
+
+
+
+
+
+
+ These compilers cannot handle BOOST_FOREACH
+ in a template, where the collection type
+ depends on a template parameter.
+
+
+
+
+
+
+
+ This failure is because the Boost.Range extension
+ mechanism is broken on these compilers. It requires
+ ADL which these compilers do not support.
+
+
+
+
+
+
+ is_base_and_derived<> is broken on this compiler, but
+ the problem can be worked around by specializing
+ boost::foreach::is_noncopyable<> for collection
+ types that are noncopyable.
+
+
+
+
+
+
+
+
+
+ The failure is caused by a standard library bug: the
+ iostream components fail to handle ios::internal
+ flag.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ hash_value is not overloaded for arrays for older versions
+ of Visual C++. There is a work around so that
+ boost::hash<T[N]>, boost::hash_combine and boost::hash_range
+ work.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ On this compiler the hash function is returning the same value
+ for std::numeric_limits<long double>::max(),
+ std::numeric_limits<long double>::max() / 2 and
+ std::numeric_limits<long double>::max() * 3 / 4.
+ This suggests the hash function isn't taking into account the
+ full range of long double - it might be
+ converting it to a double. This won't cause
+ anything to break, but means that the hash function isn't
+ as good as it should be for long doubles.
+
+
+
+
+
+
+
+ On this platform both std::frexp and std::ldexp treat long
+ doubles as longs, so the hashing algorithm does the same.
+ This means that you'll get very bad results for long doubles
+ that can't be represented by doubles.
+
+
+
+
+
+
+
+
+
+ These examples only work on compilers with support for ADL.
+ It is possible to work around this, but I wanted to keep the
+ example code as clean as possible.
+
+
+
+
+
+
+
+
+ It appears that Borland doesn't find friend functions defined
+ in a class by ADL. This is easily fixed but this example is
+ meant to show the typical way of customising boost::hash, not
+ the portable way.
+
+
+
+
+
+
+
+
+ The test demonstrates a Borland bug - functions that aren't
+ in a namespace don't appear to be found by ADL.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is due to a problem with partial ordering
+ of class template partial specializations.
+
+
+
+
+
+
+
+
+ The test fails due to compile error in relaxed_heap.hpp.
+ The compile error is likely caused by a compiler bug.
+
+
+
+
+
+
+ The test fails from completely unknown reason -- it might
+ be compiler bug, or compiler misconfiguration or testing
+ system bug.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This is gcc bug 26526, and is fixed in later releases.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ compiler can't compile "windows.h" in strict mode
+
+
+
+
+
+
+
+ The failure reflects a problem with the build system: the zlib
+ object files are generated in the wrong directory.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ I'm not sure whether CodeWarrior is correct to report that the member
+ in question is inaccessible; however, when the member is made public
+ an internal error occur that I have not been able to fix, so for
+ now the question is moot.
+
+
+
+
+
+
+ Memory mapped files are not supported in QNX Neutrino version 6.3.0.
+
+
+
+
+
+
+ Fails to compile on some installations but not others; may
+ depend on which compiler updates have been installed
+
+
+
+
+
+
+ These six tests pass individually but cause a compiler stack overflow
+ when compiled as a group
+
+
+
+
+
+
+ No bzip2 support on the testing machine and no way to
+ disable this test with BBv2 at present.
+
+
+
+
+
+
+ The test fails at runtime for unknown reasons.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The compiler is not supported by the library due to an
+ utterly broken templates support.
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by a deficient SFINAE implementation; the bug
+ was fixed in the next major compiler version (CodeWarrior 9.x).
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by a deficient SFINAE implementation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by a problem with recursive templates and default template parameters, fixed in Update 2.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by a lack of compiler support for template template
+ parameters.
+
+
+
+
+
+
+
+
+
+
+
+
+ This is an advanced functionality that hasn't been ported to the deficient
+ compilers (yet). Patches are welcome!
+
+
+
+
+
+
+
+
+ This is an advanced functionality that hasn't been ported to the deficient
+ compilers (yet). Patches are welcome!
+
+
+
+
+
+
+
+
+ This is a regression in the gcc 4.1 series that will be
+ fixed in gcc 4.1.2. See bug
+ #28088 for details.
+
+
+
+
+
+
+ This is reported to be fixed in the next Sun
+ compiler release.
+
+
+
+
+
+
+ When compiling this test, aCC6 runs out of memory. The HP
+ compiler group is aware of this issue and is working on the fix.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This library has never worked [on Borland 5.5.1 and 5.6.4], and the only tests
+ that 'pass' are compile-fail tests failing for the wrong reasons!
+
+
+
+
+
+
+
+
+
+
+
+
+ Known error in MSVC. see
+
+http://boost-consulting.com/boost/libs/multi_index/doc/compiler_specifics.html#msvc_60
+for more information.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The VC++ 6.0 backend runs out of internal resources while
+ trying to process the Comeau output for this library;
+ Comeau Computing has been asked about a solution.
+ On the other hand, Comeau 4.3.3 with VC++ 7.0 backend works
+ fine.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This error shows when using the dynamic version of the STLport
+ library. The problem is reportedly fixed in STLport 5.0 (in beta
+ stage as of this writing.)
+
+
+
+
+
+
+ Boost.Serialization is not supported on this platform.
+
+
+
+
+
+
+
+
+ This test fails due to limitations of the template
+ instantiation model used in the testing environment
+ (-timplicit_local) resulting in erroneous duplication of some
+ function-static variables. The test passes with other template
+ instantiation models.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The test is exposing the following known error of Sun Studio 11:
+ overload resolution fails if
+ a) some class has a conversion operator to a reference to
+ a built-in type, and
+ b) overload resolution involves a user-defined operator as well
+ as a built-in operator, and
+ c) the built-in operator takes the result of the conversion
+ mentioned in a) as an operand.
+ A fix will be reportedly included in patch no 6 of Sun Studio 11.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This error shows when the code has become too complex for the
+ compiler to handle. The problem has no relationship with the
+ functionality being tested, which in fact does work for
+ MSVC++ 7.0.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ msvc 6 compiler failure. The facility being tested conflicts the the
+ compiler in a fundamental way and cannnot be worked around.
+
+
+
+
+
+
+
+ msvc 6 compiler failure. The facility being tested conflicts the the
+ compiler in a fundamental way and cannnot be worked around.
+
+
+
+
+
+
+
+
+ This failure appears when STLPort is built and used as a DLL with msvc 6.
+ STLPort suggests that the next version of STLPort(5.0) will include a workaround
+ for this problem.
+
+
+
+
+
+
+
+ The library is believed to work in this configuration if compiled against
+ Spirit 1.6. The latter is not provided by the particular testing
+ environment these tests have been run in.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ All tests that serialize derived pointers currently fail with Metrowerks compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This is caused by a compiler bug in this particular version, but not present
+ in version thereafter. The compiler has some difficulties resolving operators
+ to methods in the archive classes. This can be worked around by calling the
+ operator directly, and such a work around is already present in library code.
+ This test demonstrates that this can happen in user code.
+
+
+
+
+
+
+
+
+ The CW compilers have problems with the static construction idiom used to
+ implement the type registration in the Boost.Serialization library. In many
+ cases CW specific work arounds are implemented in the library but this one
+ is not immediately solvable. There is a user work around possible, please
+ contact the library developers on the Boost list for information on the
+ work around if needed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The variant library is not supported for this compiler version.
+ Therefore serialization of variants doesn't work.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The compiler fails with an error supposedly related to std::fpos<>::_Stz from the
+ <iosfwd> header. It is not known what causes the compiler to instantiate this
+ field and what causes the instantiation to fail.
+
+
+
+
+
+
+
+ This failure is caused by an unresearched compiler bug; the
+ conditions under which the bug manifests itself seem to be
+ uncommon, however, and the static version of this same test
+ builds and runs correctly.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Historically, Spirit supported a lot of compilers, including (to some
+ extent) poorly conforming compilers such as VC6. Spirit v1.6.x will be
+ the last release that will support older poorly conforming compilers.
+ Starting from Spirit v1.8.0, ill conforming compilers will not be
+ supported. If you are still using one of these older compilers, you can
+ still use Spirit v1.6.x.
+
+
+ The reason why Spirit v1.6.x worked on old non-conforming compilers is
+ that the authors laboriously took the trouble of searching for
+ workarounds to make these compilers happy. The process takes a lot of
+ time and energy, especially when one encounters the dreaded ICE or
+ "Internal Compiler Error". Sometimes searching for a single workaround
+ takes days or even weeks. Sometimes, there are no known workarounds. This
+ stifles progress a lot. And, as the library gets more progressive and
+ takes on more advanced C++ techniques, the difficulty is escalated to
+ even new heights.
+
+
+ Spirit v1.6.x will still be supported. Maintenance and bug fixes will
+ still be applied. There will still be active development for the back-
+ porting of new features introduced in Spirit v1.8.0 (and Spirit 1.9.0)
+ to lesser able compilers; hopefully, fueled by contributions from the
+ community. For instance, there is already a working AST tree back-port
+ for VC6 and VC7 by Peder Holt.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by a compiler bug that manifests itself in the
+ particular environment/hardware configuration the test has been run in.
+ You may or may not experience this issue in your local setup.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This compiler is not supported.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Native mode is not supported for this compiler.
+
+
+
+
+
+
+
+
+ Emulation mode is not supported for this compiler.
+
+
+
+
+
+
+
+
+
+
+ The feature is not supported by this compiler.
+
+
+
+
+
+
+ The feature is not supported by this compiler.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by a compiler bug. Templated operators
+ that combine different iterators built with iterator_facade or
+ iterator_adaptor may be present in an overload set even when those
+ iterators are not interoperable. The usual result is that error
+ messages generated by illegal use of these operators will be of
+ lower quality.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by a compiler bug.
+ is_convertible<T,U>::value may be true for unrelated
+ iterators T and U
+ (including many of the Boost specialized adaptors) which use
+ enable_if_convertible to restrict the applicability
+ of converting constructors, even when T is not
+ convertible to U because instantiating the
+ conversion will cause a compilation failure.
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by a compiler bug. The
+ compiler tends to drop const-ness and as a result
+ some indirect_iterators will have pointer and
+ reference members of T* and T& that should
+ have been T const* and T const&.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This test fails with a link error that is most likely
+ a STLport issue. As STLport 4 is officially unsupported
+ there is no known resolution.
+
+
+
+
+
+
+
+ For some currently unknown reason, with aCC6, this test can be compiled
+ only in strict ansi mode. Since on HP-UX/aCC6 boost testing is done in the
+ default compilation mode, this test fails to compile on this platform.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ There appears to be a bug in gcc's std::exp (long
+ double) on this platform.
+
+
+
+
+
+
+
+ std::numeric_limits>long double<::infinity() is apparently
+ broken in this compiler: it's filed as bug 6347520 with Sun.
+
+
+
+
+
+
+
+ Not yet diagnosed the precise reason these tests give bad results.
+
+
+
+
+
+
+ std::numeric_limits>long double<::infinity() is apparently
+ broken in this compiler.
+
+
+
+
+
+
+ Incomplete std::complex support make these tests pointless
+ (the complex trig functions are absent).
+
+
+
+
+
+
+
+
+
+ These have yet to fully investigated, but the code is known
+ to compile with more conforming compilers, probably workarounds
+ are possible if someone is prepared to invest the time.
+
+
+
+
+
+
+
+
+
+ This compiler is not sufficiently conforming to compile these tests.
+
+
+
+
+
+
+ Appears to be a bug in STLport's complex abs function, but needs more investigation.
+
+
+
+
+
+
+ This appears to be a problem with STLPort's abs function: the issue only effects the
+ test code. A workaround should be possible but users should be encouraged to use
+ STLport 5 instead.
+
+
+
+
+
+
+
+ No true long double standard lib support causes these tests to fail.
+
+
+
+
+
+
+
+
+
+ This is Intel issue 409291, it should be fixed from
+ compiler package l_cc_c_9.1.046 onwards.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure appears to be caused by a compiler bug: please note
+ that the issue only effects the test suite, not the library itself.
+ A workaround is available but breaks other compilers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This test ensures the inclusion property of interval
+ arithmetic is available for built-in floating-point types
+ float and double. If the test
+ fails, interval<float> and
+ interval<double> should not be used
+ on this compiler/platform since there will be no
+ numerical guarantee.
+
+
+
+
+
+
+
+
+ This compiler has some problems with name looup / overload resolution.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is unresearched. Presumably, the problem
+ is that the abs function is not available in the "right"
+ namespace with this compiler/stdlib combination.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This old version of the stlport library causes the BOOST_NO_STDC_NAMESPACE
+ macro to be set. But this conflicts with the requirements of the library.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The failure is caused by standard library deficiencies
+ -- it lacks the basic_string class template and
+ the <locale> header.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The failures are caused by problems
+ with std::locale implementation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The failures are caused by compiler bug: it's not possible to
+ explicitly pass template arguments to member template function. The
+ failure is serious and makes one of the primary interfaces
+ unusable.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Several compiler bugs were worked around in order to get
+ this test to pass, so it could be considered to be only
+ partially working. However, the library's macro system,
+ which is really being tested here, does work on this
+ compiler, which is why we worked around the failures.
+ Please see the test's
+ source file for details.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ These compilers do not support SFINAE, so are expected to
+ fail this test.
+
+
+
+
+
+
+
+
+ Borland does not support this feature. A compatibility syntax
+ might be developed later on.
+
+
+
+
+
+
+
+
+
+
+ This feature generally requires advanced compiler
+ features not supported by these compilers. It might
+ be possible to work around the issue on VC6/7, but
+ at this time no such workaround has been done.
+
+
+
+
+
+
+
+ This is old and should not be tested any more.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ These test failure are reported to be under investigation
+ at Sun's compiler labs.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The error is due to problems in the standard library implementation.
+ It should be fixed in newer versions of the compiler.
+
+
+
+
+
+
+ The error is due to problems in the standard library implementation.
+ It should be fixed in newer versions of the compiler.
+
+
+
+
+
+
+ This error seems to be a bug the compiler. Please submit a
+ patch.
+
+
+
+
+
+
+
+
+
+ This error seems to be a bug the standard library. Please submit a
+ patch.
+
+
+
+
+
+
+
+ This test fails because the test ptr_vector fails. Please see the note
+ for that test.
+
+
+
+
+
+
+
+ For sun the problem is that insert(iterator,range)
+ is not available due to partial ordering errors (the core library remains usable).
+ For codewarrior the problem is at least std::auto_ptr overloads (the core library remains usable).
+
+
+
+
+
+
+
+ For sun the problem is that insert(iterator,range)
+ is not available due to partial ordering errors (the core library remains usable).
+ For codewarrior the problem is at least std::auto_ptr overloads (the core library remains usable).
+
+
+
+
+
+
+
+ For sun the problem is that insert(iterator,range)
+ is not available due to partial ordering errors (the core library remains usable).
+ For codewarrior the problem is at least std::auto_ptr overloads (the core library remains usable).
+
+
+
+
+
+
+
+
+ For hp, this compiler bug is insignificant.
+ For sun the problem is that transfer(range,ptr_map)
+ is not available due to partial ordering errors (the core library remains usable).
+ For codewarrior the problem is not known so please submit a patch.
+
+
+
+
+
+
+
+ For sun the problem is that transfer(range,ptr_map) and
+ insert(range)code>
+ is not available due to partial ordering errors (the core library remains usable).
+ For codewarrior the problem is at least std::auto_ptr overloads (the core library remains usable)..
+
+
+
+
+
+
+ This cause of this problem is unknown. Please submit a patch.
+
+
+
+
+
+
+ For sun the problem is due to Boost.Test.
+
+
+
+
+
+
+ Seem like a bug in the compiler. Please submit a patch.
+
+
+
+
+
+
+ Seem like a bug in the compiler. Please submit a patch.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The library fails to compile because of an error in the C++
+ standard library implementation on this platform. It incorrectly
+ assumes that fpos_t is of an integral type, which is not always
+ the case. This is fixed in a later release.
+
+
+
+
+
+ This compiler seems to be having trouble digesting
+ Boost.Tuple. Until it can handle Boost.Tuple there's
+ little chance it will handle Boost.Python
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The problems with GCC 2.x only occur when C++ exceptions are thrown and
+ the framework catches them, which happens quite often in the tests.
+ So technically GCC 2.x is usable if you're careful.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This test assumes standard-compliant dependent template name lookup which
+ is performed by aCC6 only in strict ansi mode. Since on HP-UX/aCC6 boost
+ testing is done in the default compilation mode, this test fails to
+ compile on this platform (in strict ansi mode, it compiles and succeeds).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Reported to Intel as issue 409291, and confirmed
+ as a problem. Probably this relates to a specific
+ Linux-Kernal or GLibC version.
+
+
+
+
+
+ Test fails with ranlux*_O1 RNGs when saving and recalling the state due to a bug in the
+ double to string conversion. The problem has been reported to QNX as PR29252.
+
+
+
+
+
+ This test fails because of limitations in the system assembler
+ version used by GCC. It most probably would pass if the test
+ were split into multiple source files.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ For most compilers this is due to problems
+ with built-in arrays (notably char arrays) and operator==()
+ and operator!=() for iterator_range. Thus, not using built-in arrays
+ fixes the problem.
+
+ For other compilers it is simply a bug in the standard library.
+
+
+
+
+
+
+
+ This test probably fails because it uses built-in arrays. So do expect these
+ functions to work in normal code.
+
+
+
+
+
+
+
+
+
+
+ The string functionality is expected to work if
+ the user employs std::string and stays away from built-in
+ arrays.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ For most compilers this is due to problems
+ with built-in arrays (notably char arrays) and operator==()
+ and operator!=() for iterator_range. Thus, not using built-in arrays
+ fixes the problem.
+
+
+
+
+
+
+ At the time of release I couldn't figure out why this was failing.
+ Anyway, the failure is not very important; also, the well-definedness of
+ "singularity" of an iterator range is likely to change.
+
+
+
+
+
+
+
+ The test requires support for Argument Dependent Lookup (ADL)
+ which the compiler in question does not provide.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ No Wide character support on this platform.
+
+
+
+
+
+
+
+ No Wide character support on this platform.
+
+
+
+
+
+
+
+ This test requires features that are unsupported by Como:
+ use and building of dll's mainly.
+
+
+
+
+
+
+
+
+ This test requires features that are unsupported by Como:
+ use and building of dll's mainly.
+
+
+
+
+
+
+ GCC on tru64 appears not to cope with C++ exceptions
+ thrown from within threads.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This test fails because a dependency (Boost.Program Options) doesn't build with this compiler.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ There appears to be a linker bug that prevents these
+ projects from building, see http://qc.borland.com/wc/qcmain.aspx?d=32020.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ There appears to be a linker bug that prevents these
+ projects from building, see http://qc.borland.com/wc/qcmain.aspx?d=32020.
+
+
+
+
+
+
+ Test fails due to unresilved externals from STLport: appears to be
+ an STLport bug.
+
+
+
+
+
+
+
+
+
+ These tests pass when run directly from the command line,
+ but fail when run under the regression test script.
+ The issue has never been fully pinned down, but appears
+ to be related to how long the tests take to run.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A runtime failure of this test indicates that this platform
+ dynamically links code in a manner such that under
+ certain circumstances more than one instance of a
+ header-defined static class member can exist at runtime. See
+ here
+ for more information.
+
+
+
+
+
+
+ A runtime failure of this test indicates that this platform
+ statically links code in a manner such that under
+ certain circumstances more than one instance of a
+ header-defined static class member can exist at runtime. See
+ here
+ for more information.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This test runs without problem on Borland compilers,
+ which means the static assertion is not being caught.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The test verifies that Boost.Test detects division by
+ zero. Division by zero has an undefined result
+ on PowerPC processors. The compiler has to emit extra
+ code to assert that the divisor isn't zero.
+
+ Compiler options -fno-trapping-math and -fnon-call-exceptions
+ might affect this. However, in default configuration
+ no check is done, and division by zero is not detected.
+
+
+
+
+
+
+
+ The test appears to test that failed assertion result
+ in non-zero exit status. That seems to be not the
+ case, for unknown reasons.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by a conflict between the compiler
+ and the testing environment: the tests are run on a platform with
+ too recent version of glibc, which is not currently
+ supported by the compiler vendor (Intel).
+
+ If you are having the same problem and really want to make
+ things work, renaming strol symbol in the
+ compiler's static runtime library (libcprts.a) to
+ something else is known to resolve the issue.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ When a thread ends, tss data needs to be cleaned up. This process
+ is mostly automatic. When threads are launched by the Boost.Thread API
+ cleanup is handled by the library implementation. For threads, launched
+ by the native operating system API it is not possible to get this cleanup
+ on every compiler/platform. A warning (error) will be present in this case,
+ which cleary states this fact. It is recommended to start threads only
+ by means of the Boost.Thread API if you need to avoid the leaks that appear
+ on the end of the thread. If this is not possible the cleanup can be invoked
+ from user code before the process actually ends. For library implementors
+ this means to call these functions during library initialization and
+ finalization.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by the lack of compiler support for class template
+ partial specialization. A limited subset of the tested functionality is
+ available on the compiler through a user-side workaround (see
+
+ http://www.boost.org/libs/type_traits/index.html#transformations for
+ details).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This functionality is available only on compilers that implement C++ Core Language
+ Defect Report 337.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The Type Traits library is broken when used with Sunpro-5.3 and the
+ argument to the template is an array or function type. Most other argument types
+ do work as expected: in other words the functionality is limited
+ with this compiler, but not so much as to render the library unuseable.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The Type Traits library is broken when used with Sunpro-5.8 and the
+ argument to the template is a function type. Most other argument types
+ do work as expected: in other words the functionality is limited
+ with this compiler, but not so much as to render the library unuseable.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Older versions of MWCW incorrectly align pointers to member functions
+ (they use 12-byte boundaries, rather than a power-of-2 boundary),
+ leading to alignment_of / aligned_storage
+ to fail with these types on this compiler.
+
+
+
+
+
+
+
+
+
+
+ VC6/7 has a buggy using declaration syntax which
+ basically makes it impossible to implement the
+ namespace forwarding that this library relies upon.
+ See KB article 263630 here: http://support.microsoft.com/default.aspx?scid=kb;en-us;263630
+
+
+
+
+
+ Metrowerks Codeworrier has partial TR1 support built in
+ which conflicts with this implementation. Porting to this
+ compiler is almost certainly possible, but will require some
+ work by someone who has this compiler.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ These tests test features that are not supported in the
+ current Boost implementations of TR1 components, they will
+ currently fail on all compilers, unless that compiler has
+ native TR1 support.
+
+
+
+
+
+
+
+
+
+
+
+
+ These tests fail on this platform due to a lack of
+ wide character support.
+
+
+
+
+
+
+
+
+ These tests fail on this platform due to incomplete
+ wide character support.
+
+
+
+
+
+
+
+
+ These tests fail on this platform due to incomplete
+ wide character support.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Support for Borland C++ in the various TR1 libraries is pretty
+ poor (due to numerous compiler bugs sadly). The TR1 concept
+ checks are *very* strict, and are expected to fail with this
+ compiler. In addition most of the type_traits tests fail
+ whenever debugging support is turned on with an internal
+ compiler error. More conservative uses are more likely to succeed
+ with this compiler however.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Support for Borland C++ in the various TR1 libraries is pretty
+ poor (due to numerous compiler bugs sadly). The TR1 concept
+ checks are *very* strict, and are expected to fail with this
+ compiler. More conservative uses are more likely to succeed
+ with this compiler however.
+
+
+
+
+
+
+
+
+
+ These tests fail on this platform due to a recuring GCC bug.
+
+
+
+
+
+
+
+
+
+
+
+ These tests fail due to a known compiler bug
+ that is fixed in more recent GNU compiler releases. Users are
+ very unlikely to encounter this as a real problem
+ in practice.
+
+
+
+
+
+
+
+
+
+
+
+
+ These tests fail due to a known compiler bug
+ that is fixed in more recent releases. Users are
+ very unlikely to encounter this as a real problem
+ in practice.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ These tests fail due to a known compiler bug
+ that is fixed in more recent releases. This
+ functionality may not be usable with this compiler.
+
+
+
+
+
+
+
+
+
+
+ These tests fail due to a known stdlib bug
+ that has been reported to the vendor.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by the lack of compiler support for class template
+ partial specialization. A limited subset of the tested functionality is
+ available on the compiler through a user-side workaround (see
+
+ http://www.boost.org/libs/type_traits/index.html#transformations for
+ details).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This functionality is available only on compilers that implement C++ Core Language
+ Defect Report 337.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The Type Traits library is broken when used with Sunpro-5.3 and the
+ argument to the template is an array or function type. Most other argument types
+ do work as expected: in other words the functionality is limited
+ with this compiler, but not so much as to render the library unuseable.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The Type Traits library is broken when used with Sunpro-5.8 and the
+ argument to the template is a function type. Most other argument types
+ do work as expected: in other words the functionality is limited
+ with this compiler, but not so much as to render the library unuseable.
+
+
+
+
+
+
+
+
+ These failures appear to represent a genuine issue with the
+ Boost.Random library that has yet to be addressed.
+
+
+
+
+
+
+
+
+
+
+ These failures are completely spurious: they're caused by the tests
+ being run with bjam -j2 and the post-processing not coping with the
+ resulting output. These failures should clear if these tests
+ are re-run at some point in the future.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This library is almost unusable with VC7 due to name lookup issues.
+
+
+
+
+
+
+ Older versions of MWCW incorrectly align pointers to member functions
+ (they use 12-byte boundaries, rather than a power-of-2 boundary),
+ leading to alignment_of / aligned_storage
+ to fail with these types on this compiler.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Compiler has a problem with BOOST_STATIC_CONSTANT in nested templates
+ inside class template specializations.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This failure is caused by an UNRELATED compiler bug resulted from the particular test strategy.
+ 'boost::none' DOES work correctly in this compiler.
+
+
+
+
+
+
+
+ This failure is caused by a compiler bug (default-constructed scalar
+ types are not zero-initialized) that has been fixed in the latest
+ versions of the compiler (VC 7.1 and greater).
+
+
+
+
+
+
+ The test takes more that 30 minutes to compile and the
+ compilation is automatically killed. It is likely caused
+ by the compiler bug, but it unknown how much this
+ bug affects regular use of the operators library. Is it
+ also unknown if the test can be refactored so that
+ not to trigger this bug.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This toolset isn't supported because of the used Spirit V1.8.x, which in turn is
+ not usable with this toolset.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ These compilers do not support class template partial
+ specialization.
+
+
+
+
+
+ Boost.Fusion doesn't work on this compiler.
+
+
+
+
+
+ This compiler doesn't support SFINAE / enable_if
+
+
+
+
+
+ Digital Mars cannot seem to handle dependent default template parameters,
+ such as "template < class T, bool B = is_foo < T > ::value >"
+
+
+
+
+
+
+
+
+
+
+
+
+ This test fails only intermittently.
+
+
+
+ The failure is caused by a problem in Boost code. The Boost developers are aware of
+ the problem and plan to fix it.
+
+
+
+ The failure is caused by a compiler bug.
+
+
+
+ The failure is caused by a compiler bug, which has been reported to the compiler
+ supplier (or is already known to them).
+
+
+
+ The failure is caused by a standard library bug.
+
+
+
+ The failure is caused by a standard library bug, which has been reported to the
+ standard library supplier (or is already known to them).
+
+
+
+ The failure is probably caused by the test code, harness, or configuration. Thus,
+ it may not affect users of the library.
+
+
+
+ The failure is serious and likely to prevent all use of this Boost library with this compiler.
+
+
+
+ The failure is serious and likely to prevent all use of this Boost library with this
+ compiler. The failure is caused by a compiler bug, which has been reported to the compiler
+ supplier (or is already known to them).
+
+
+
+ The failure is caused by a platform API bug.
+
+
+
+ The failure is caused by a platform API bug, which has been reported to the platform API
+ supplier (or is already known to them).
+
+
+
+ The failure is not serious and will not affect most users. The library degrades gracefully.
+
+
+
+ This compiler's bugs are not supported by the library.
+
+
+
+ Locales missing or adequately supported by this compiler.
+
+
+
+ Missing or inadequate wchar/wstring/wstream support for this compiler.
+
+
+
+ No std iterator traits for this compiler.
+
+
+
+ Library has limited input/output support due to compiler inadequacies.
+
+
+
+ No high precision clock for this platform.
+
+
+
+ A bug in standard library prevents passing std::set from DLL to
+ application. A fixed <tree> header is available from
+ http://www.dinkumware.com/vc_fixes.html.
+
+
+
+ Although the documentation from the Comeau website would make it appear
+ that windows DLL's are supported using the --windows option, after some
+ experimentation we have been unsuccessful in making dll configurations
+ work correctly.
+
+
+
+ The failure is caused by a runtime limitation. Locale support is only
+ available with the static linked variant of the runtime. Generally
+ the dynamic linked variant is required when building dynamic modules,
+ DLL, so, etc.
+
+
+
+ This failure is caused by a compiler bug with no known workaround.
+ Patches are welcome!
+
+
+
+ This failure is caused by bugs in the standard library implementation and/or
+ bugs in the compiler.
+
+
+
+ Unresearched failure -- please contact library developers for more
+ information about possible causes.
+
+
+
+ The test fails due to unresearched issues. The library
+ developers are aware of this failure, but need help with
+ investigating/addressing it for future releases.
+
+
+
+ The support for this deficient compiler will be dropped starting
+ from Boost 1.33.0 release. Please use one of the previous Boost
+ releases if you need the library to work on this compiler.
+
+
+
+ This failure is caused by compiler bugs or limitations. Some advanced
+ or esoteric library features may be unavailable or only partially available.
+ This does not impact most common uses of the library.
+
+
+
+ This failure is caused by a compiler bug. Certain code constructs that should
+ fail compilation are accepted by the compiler. This can mask some programming
+ errors, but does not impact the usability of the library.
+
+
+
+ The failures are caused by the wrong handling of the
+ std::internal flag in the iostreams implementation of the
+ standard library used on that compiler/platform combo. Apart from that,
+ the format library works as expected.
+
+
+
+ The failures are caused by the fact that the iword and pword arrays seem
+ to share the same memory area in the iostreams implementation of the
+ standard library used on that compiler/platform combo. As long as you
+ stay clear of iword and pword, the library should work ok.
+
+
+
+ This failure occurs only when using shared libraries for this
+ compiler and platform, although the same programs should work
+ properly when using static libraries. This problem has not
+ been researched.
+
+
+
+ Wide character support is disabled in the GNU Standard C++ library as
+ supplied on the QNX Neutrino version 6.3.0 distribution.
+
+
+
+ This problem is due to the non-conforming STLport
+ implementation of vector's swap: it can be easily
+ reproduced with the following code snippet:
+
+ typedef std::vector<int> vector_type;
+ typedef vector_type::reference reference_type;
+
+ vector_type v1(4u, 1);
+ vector_type v2(7u, 0);
+
+ reference_type ref = v1[2];
+ int x = ref;
+
+ std::swap(v1, v2);
+ BOOST_CHECK(v2[2] == x); // ok
+ v2[2] = 1 - v2[2];
+ BOOST_CHECK(ref != x); // oops
+
+
+
diff --git a/status/explicit-failures.xsd b/status/explicit-failures.xsd
new file mode 100644
index 0000000000..6c77750720
--- /dev/null
+++ b/status/explicit-failures.xsd
@@ -0,0 +1,99 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/status/index.html b/status/index.html
new file mode 100644
index 0000000000..ef88d3195f
--- /dev/null
+++ b/status/index.html
@@ -0,0 +1,9 @@
+
+
+
+
+
+Automatic redirection failed, please go to
+compiler_status.html.
+
+
\ No newline at end of file
diff --git a/status/intel_logo.gif b/status/intel_logo.gif
new file mode 100644
index 0000000000..47f9ded887
Binary files /dev/null and b/status/intel_logo.gif differ
diff --git a/status/kai_logo.gif b/status/kai_logo.gif
new file mode 100644
index 0000000000..42defced07
Binary files /dev/null and b/status/kai_logo.gif differ
diff --git a/status/ms_logo.gif b/status/ms_logo.gif
new file mode 100644
index 0000000000..09dca73b9f
Binary files /dev/null and b/status/ms_logo.gif differ
diff --git a/status/notes.html b/status/notes.html
new file mode 100644
index 0000000000..3ac028830b
--- /dev/null
+++ b/status/notes.html
@@ -0,0 +1,54 @@
+
+
+
+
+
+
+
+Win32 Regression Testing Notes
+
+
+
+
+
The failure is serious and likely to prevent all use of this Boost library
+with this compiler. The failure is caused by a compiler bug, which has been reported to the
+compiler supplier (or is already known to them).
Boost developers, testers, and maintainers have developed various programs to
+ help with the administration of the Boost Libraries. Like everything else about
+ Boost, these tools are available in source form, and are part of the regular
+ Boost distribution.
+
Users may find these tools useful when porting Boost libraries to a new
+ platform, or for use with their own applications.
+
+
+ Boost.Build - The Boost build system, including
+ the full Boost version of the jam sources.
+
+
+ Regression - The Boost regression testing
+ system reporting sources.
+
+
+ Inspect - The inspection tool used to detect
+ errors in the Boost directory hierarchy.
+
+
+ bcp - A utility to extract subsets of Boost; to
+ determine which parts of Boost your code is using; and to print reports on
+ Boost usage (including Licence information).
+
+
+ QuickBook - QuickBook is a WikiWiki style
+ documentation tool geared towards C++ documentation using simple rules and markup
+ for simple formatting tasks. QuickBook generates
+ BoostBook XML.
+
+
+ Wave - A Standards conformant C/C++
+ preprocessor usable on top of any other compiler. Usable for instance for the debugging
+ of the expansion of macros in your code or as a replacement for your build in
+ preprocessor.
+