organicmaps/boost
13
Fork 0
mirror of https://github.com/boostorg/boost.git synced 2025-04-06 22:14:59 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions

Move more to a new repository which will be a submodule of boost

Browse source
This commit is contained in:
Glen Fernandes 2020-05-19 14:45:02 -04:00
parent 1c2d6d9774
commit e9fcb19867
41 changed files with 0 additions and 5681 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
more/BoostSponsorshipAgreement.pdf
View file

Binary file not shown.

104
more/blanket-permission.txt
View file

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

12
more/getting_started.html
View file

@ -1,12 +0,0 @@
<html>
<head>
<meta http-equiv="refresh" content="0; URL=getting_started/index.html">
</head>
<body>
Automatically loading index page... if nothing happens, please go to
<a href="getting_started/index.html">getting_started/index.html</a>.
</body>
</html>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->

23
more/getting_started/Jamfile.v2
View file

@ -1,23 +0,0 @@
# Copyright David Abrahams 2006. Distributed under the Boost
# Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
import docutils ;
import path ;
sources = [ path.glob . : *.rst ] ;
bases = $(sources:S=) ;
# This is a path relative to the html/ subdirectory where the
# generated output will eventually be moved.
stylesheet = "--stylesheet=../../rst.css" ;
for local b in $(bases)
{
html $(b) : $(b).rst :
<docutils-html>"--link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet)
;
}
alias htmls : $(bases) ;
stage . : $(bases) ;

10
more/getting_started/detail/binary-head.rst
View file

@ -1,10 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Prepare to Use a Boost Library Binary
=====================================
If you want to use any of the separately-compiled Boost libraries,
you'll need to acquire library binaries.

113
more/getting_started/detail/build-from-source-head.rst
View file

@ -1,113 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Install Boost.Build
...................
Boost.Build_ is a text-based system for developing, testing, and
installing software. First, you'll need to build and
install it. To do this:
1. Go to the directory ``tools``\ |/|\ ``build``\ |/|.
2. Run |bootstrap|
3. Run ``b2 install --prefix=``\ *PREFIX* where *PREFIX* is
the directory where you want Boost.Build to be installed
4. Add *PREFIX*\ |/|\ ``bin`` to your PATH environment variable.
.. _Boost.Build: ../../tools/build/index.html
.. _Boost.Build documentation: Boost.Build_
.. _toolset:
.. _toolset-name:
Identify Your Toolset
.....................
First, find the toolset corresponding to your compiler in the
following table (an up-to-date list is always available `in the
Boost.Build documentation`__).
__ http://www.boost.org/build/doc/html/bbv2/reference/tools.html
.. Note:: If you previously chose a toolset for the purposes of
`building b2`_, you should assume it won't work and instead
choose newly from the table below.
.. _building b2: ../../doc/html/bbv2/installation.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. |
+-----------+--------------------+------------------------------------------------------------+
|``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 | |
+-----------+--------------------+------------------------------------------------------------+
|``msvc`` |Microsoft | |
+-----------+--------------------+------------------------------------------------------------+
|``sun`` |Oracle |Only very recent versions are known to work well with |
| | |Boost. Note that the Oracle/Sun compiler has a large number|
| | |of options which effect binary compatibility: it is vital |
| | |that the libraries are built with the same options that your|
| | |appliction will use. In particular be aware that the default|
| | |standard library may not work well with Boost, *unless you |
| | |are building for C++11*. The particular compiler options you|
| | |need can be injected with the b2 command line options |
| | |``cxxflags=``and ``linkflags=``. For example to build with |
| | |the Apache standard library in C++03 mode use |
| | |``b2 cxxflags=-library=stdcxx4 linkflags=-library=stdcxx4``.|
+-----------+--------------------+------------------------------------------------------------+
|``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 ``b2``
...............
.. |build-directory| replace:: *build-directory*
.. |toolset-name| replace:: *toolset-name*
Change your current directory to the Boost root directory and
invoke ``b2`` as follows:
.. parsed-literal::
b2 **--build-dir=**\ |build-directory|_ **toolset=**\ |toolset-name|_ |build-type-complete| stage
For a complete description of these and other invocation options,
please see the `Boost.Build documentation`__.
__ http://www.boost.org/build/doc/html/bbv2/overview/invocation.html

73
more/getting_started/detail/build-from-source-tail.rst
View file

@ -1,73 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Building the special ``stage`` target places Boost
library binaries in the ``stage``\ |/|\ ``lib``\ |/| subdirectory of
the Boost tree. To use a different directory pass the
``--stagedir=``\ *directory* option to ``b2``.
.. Note:: ``b2`` 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
``b2``, type::
b2 --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.
.. Note:: Boost.Build can produce a great deal of output, which can
make it easy to miss problems. If you want to make sure
everything is went well, you might redirect the output into a
file by appending “``>build.log 2>&1``” to your 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
`here`__. 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`_.
__ http://www.boost.org/build/doc/html/bbv2/overview/configuration.html

28
more/getting_started/detail/build-simple-head.rst
View file

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

22
more/getting_started/detail/common-footnotes.rst
View file

@ -1,22 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
.. [#warnings] Remember that warnings are specific to each compiler
implementation. The developer of a given Boost library might
not have access to your compiler. Also, some warnings are
extremely difficult to eliminate in generic code, to the point
where it's not worth the trouble. Finally, some compilers don't
have any source code mechanism for suppressing warnings.
.. [#distinct] This convention distinguishes the static version of
a Boost library from the import library for an
identically-configured Boost DLL, which would otherwise have the
same name.
.. [#debug-abi] These libraries were compiled without optimization
or inlining, with full debug symbols enabled, and without
``NDEBUG`` ``#define``\ d. Although it's true that sometimes
these choices don't affect binary compatibility with other
compiled code, you can't count on that with Boost libraries.

29
more/getting_started/detail/common-unix.rst
View file

@ -1,29 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
.. |//| replace:: **/**
.. |/| replace:: ``/``
.. |default-root| replace:: ``/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
.. |pathsep| replace:: colon
.. |path| replace:: ``echo $PATH``
.. |bootstrap| replace:: ``bootstrap.sh``
.. include:: common.rst

40
more/getting_started/detail/common-windows.rst
View file

@ -1,40 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
.. |//| replace:: **\\**
.. |/| replace:: ``\``
.. |default-root| replace:: ``C:\Program Files\boost\``\ |boost_ver|
.. |default-root-bold| replace:: **C:\\Program Files\\boost\\**\ |boost_ver-bold|
.. |root| replace:: *path\\to\\*\ |boost_ver|
.. |include-paths| replace:: Specific steps for setting up ``#include``
paths in Microsoft Visual Studio follow later in this document;
if you use another IDE, please consult your product's
documentation for instructions.
.. |forward-slashes| replace:: Even Windows users can (and, for
portability reasons, probably should) use forward slashes in
``#include`` directives; your compiler doesn't care.
.. |precompiled-dir| replace::
**lib**\ |//| .....................\ *precompiled library binaries*
.. |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`_
.. |pathsep| replace:: semicolon
.. |path| replace:: ``PATH``
.. |bootstrap| replace:: ``bootstrap.bat``
.. include:: common.rst

5
more/getting_started/detail/common.rst
View file

@ -1,5 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
.. |next| replace:: *skip to the next step*

35
more/getting_started/detail/conclusion.rst
View file

@ -1,35 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Conclusion and Further Resources
================================
This concludes your introduction to Boost and to integrating it
with your programs. As you start using Boost in earnest, there are
surely a few additional points you'll wish we had covered. One day
we may have a “Book 2 in the Getting Started series” that addresses
them. Until then, we suggest you pursue the following resources.
If you can't find what you need, or there's anything we can do to
make this document clearer, please post it to the `Boost Users'
mailing list`_.
* `Boost.Build reference manual`_
* `Boost Users' mailing list`_
* `Boost.Build mailing list`_
* `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/index.html
.. _Boost Users' mailing list: http://www.boost.org/more/mailing_lists.htm#users
.. _Boost.Build mailing list: http://www.boost.org/more/mailing_lists.htm#jamboost

88
more/getting_started/detail/distro.rst
View file

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

16
more/getting_started/detail/errors-and-warnings.rst
View file

@ -1,16 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Errors and Warnings
-------------------
Don't be alarmed if you see compiler warnings originating in Boost
headers. We try to eliminate them, but doing so isn't always
practical. [#warnings]_ **Errors are another matter**. If you're
seeing compilation errors at this point in the tutorial, check to
be sure you've copied the `example program`__ correctly and that you've
correctly identified the `Boost root directory`_.
__ `Build a Simple Program Using Boost`_

70
more/getting_started/detail/header-only.rst
View file

@ -1,70 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Header-Only Libraries
=====================
The first thing many people want to know is, “how do I build
Boost?” The good news is that often, there's nothing to build.
.. admonition:: Nothing to Build?
Most Boost libraries are **header-only**: they consist *entirely
of header files* containing templates and inline functions, and
require no separately-compiled library binaries or special
treatment when linking.
.. .. _separate:
The only Boost libraries that *must* be built separately are:
* Boost.Chrono_
* Boost.Context_
* Boost.Filesystem_
* Boost.GraphParallel_
* Boost.IOStreams_
* Boost.Locale_
* Boost.Log_ (see `build documentation`__)
* Boost.MPI_
* Boost.ProgramOptions_
* Boost.Python_ (see the `Boost.Python build documentation`__
before building and installing it)
* Boost.Regex_
* Boost.Serialization_
* Boost.Thread_
* Boost.Timer_
* Boost.Wave_
__ ../../libs/log/doc/html/log/installation/config.html
__ ../../libs/python/doc/html/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.Math_ has binary components for the TR1 and C99
cmath functions.
* Boost.Random_ has a binary component which is only needed if
you're using ``random_device``.
* Boost.Test_ can be used in “header-only” or “separately compiled”
mode, although **separate compilation is recommended for serious
use**.
* Boost.Exception_ provides non-intrusive implementation of
exception_ptr for 32-bit _MSC_VER==1310 and _MSC_VER==1400
which requires a separately-compiled binary. This is enabled by
#define BOOST_ENABLE_NON_INTRUSIVE_EXCEPTION_PTR.
* Boost.System_ is header-only since Boost 1.69. A stub library is
still built for compatibility, but linking to it is no longer
necessary.
__ ../../libs/graph/doc/read_graphviz.html

106
more/getting_started/detail/library-naming.rst
View file

@ -1,106 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
In order to choose the right binary for your build configuration
you need to know how Boost binaries are named. Each library
filename is composed of a common sequence of elements that describe
how it was built. For example,
``libboost_regex-vc71-mt-d-x86-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: |Boost.Build option |
+=====+==============================================================================+=====================+
|``s``|linking statically to the C++ standard library and compiler runtime support |runtime-link=static |
| |libraries. | |
+-----+------------------------------------------------------------------------------+---------------------+
|``g``|using debug versions of the standard and runtime support libraries. |runtime-debugging=on |
+-----+------------------------------------------------------------------------------+---------------------+
|``y``|using a special `debug build of Python`__. |python-debugging=on |
+-----+------------------------------------------------------------------------------+---------------------+
|``d``|building a debug version of your code. [#debug-abi]_ |variant=debug |
+-----+------------------------------------------------------------------------------+---------------------+
|``p``|using the STLPort standard library rather than the default one supplied with |stdlib=stlport |
| |your compiler. | |
+-----+------------------------------------------------------------------------------+---------------------+
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,
the tag would be: ``-sgdp``. If none of the above apply, the
ABI tag is ommitted.
``-x86``
*Architecture and address model tag*: in the first letter, encodes the architecture as follows:
+-----+------------------+---------------------+
|Key |Architecture |Boost.Build option |
+=====+==================+=====================+
|``x``|x86-32, x86-64 |architecture=x86 |
+-----+------------------+---------------------+
|``a``|ARM |architecture=arm |
+-----+------------------+---------------------+
|``i``|IA-64 |architecture=ia64 |
+-----+------------------+---------------------+
|``s``|Sparc |architecture=sparc |
+-----+------------------+---------------------+
|``m``|MIPS/SGI |architecture=mips* |
+-----+------------------+---------------------+
|``p``|RS/6000 & PowerPC |architecture=power |
+-----+------------------+---------------------+
The two digits following the letter encode the address model as follows:
+------+------------------+---------------------+
|Key |Address model |Boost.Build option |
+======+==================+=====================+
|``32``|32 bit |address-model=32 |
+------+------------------+---------------------+
|``64``|64 bit |address-model=64 |
+------+------------------+---------------------+
``-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 ``.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/html/building/python_debugging_builds.html

39
more/getting_started/detail/link-head.rst
View file

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

26
more/getting_started/detail/links.rst
View file

@ -1,26 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
.. _Boost.Chrono: ../../libs/chrono/index.html
.. _Boost.Context: ../../libs/context/index.html
.. _Boost.DateTime: ../../libs/date_time/index.html
.. _Boost.Exception: ../../libs/exception/index.html
.. _Boost.Filesystem: ../../libs/filesystem/index.html
.. _Boost.Graph: ../../libs/graph/index.html
.. _Boost.GraphParallel: ../../libs/graph_parallel/index.html
.. _Boost.IOStreams: ../../libs/iostreams/index.html
.. _Boost.Locale: ../../libs/locale/index.html
.. _Boost.Log: ../../libs/log/index.html
.. _Boost.Math: ../../libs/math/index.html
.. _Boost.MPI: ../../libs/mpi/index.html
.. _Boost.ProgramOptions: ../../libs/program_options/index.html
.. _Boost.Python: ../../libs/python/doc/html/building.html
.. _Boost.Random: ../../libs/random/index.html
.. _Boost.Regex: ../../libs/regex/index.html
.. _Boost.Serialization: ../../libs/serialization/index.html
.. _Boost.System: ../../libs/system/index.html
.. _Boost.Test: ../../libs/test/index.html
.. _Boost.Thread: ../../libs/thread/index.html
.. _Boost.Timer: ../../libs/timer/index.html
.. _Boost.Wave: ../../libs/wave/index.html

12
more/getting_started/detail/release-variables.rst
View file

@ -1,12 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
.. This file contains all the definitions that need to be updated
.. for each new release of Boost.
.. |boost-version-number| replace:: 74
.. |boost_ver| replace:: ``boost_1_74_0``
.. |boost_ver-bold| replace:: **boost_1_74_0**
.. _sf-download: http://www.boost.org/users/history/version_1_74_0.html

16
more/getting_started/detail/test-head.rst
View file

@ -1,16 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Test Your Program
-----------------
To test our subject extraction, we'll filter the following text
file. Copy it out of your browser and save it as ``jayne.txt``::
To: George Shmidlap
From: Rita Marlowe
Subject: Will Success Spoil Rock Hunter?
---
See subject.

65
more/getting_started/index.html
View file

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

70
more/getting_started/index.rst
View file

@ -1,70 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
============================
|(logo)|__ Getting Started
============================
.. |(logo)| image:: ../../boost.png
:alt: Boost
:class: boost-logo
__ ../../index.htm
.. Admonition:: Use the latest version of this Getting Started guide
The `Boost website version of this Getting Started guide`_ may
have updated information, such as the location of additional installers
or improved installation procedures, so you might want use that version
if you've got an Internet connection available.
.. _`Boost website version of this Getting Started guide`:
http://www.boost.org/more/getting_started/index.html
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

863
more/getting_started/unix-variants.html
View file

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

242
more/getting_started/unix-variants.rst
View file

@ -1,242 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
=============================================
|(logo)|__ Getting Started on Unix Variants
=============================================
.. meta::
:description: Getting Started with Boost on Unix Variants (including Linux and MacOS)
.. |(logo)| image:: ../../boost.png
:alt: Boost
:class: boost-logo
__ ../../index.htm
.. section-numbering::
.. maybe we don't need this
.. Admonition:: A note to Cygwin_ and MinGW_ users
If you plan to build from the Cygwin_ bash shell, you're in the
right place. If you plan to use your tools from the Windows
command prompt, you should follow the instructions for `getting
started on Windows`_. Other command shells, such as MinGW_\ 's
MSYS, are not supported—they may or may not work.
.. _`Getting Started on Windows`: windows.html
.. _Cygwin: http://www.cygwin.com
.. _MinGW: http://mingw.org
.. Contents:: Index
Get Boost
=========
The most reliable way to get a copy of Boost is to download a
distribution from SourceForge_:
.. _SourceForge: `sf-download`_
1. Download |boost.tar.bz2|_.
2. In the directory where you want to put the Boost installation,
execute
.. parsed-literal::
tar --bzip2 -xf */path/to/*\ |boost_ver|\ .tar.bz2
.. |boost.tar.bz2| replace:: |boost_ver|\ ``.tar.bz2``
.. _`boost.tar.bz2`: `sf-download`_
.. Admonition:: Other Packages
RedHat, Debian, and other distribution packagers supply Boost
library packages, however you may need to adapt these
instructions if you use third-party packages, because their
creators usually choose to break Boost up into several packages,
reorganize the directory structure of the Boost distribution,
and/or rename the library binaries. [#packagers]_ If you have
any trouble, we suggest using an official Boost distribution
from SourceForge_.
.. include:: detail/distro.rst
.. include:: detail/header-only.rst
.. include:: detail/build-simple-head.rst
Now, in the directory where you saved ``example.cpp``, issue the
following command:
.. parsed-literal::
c++ -I |root| example.cpp -o example
To test the result, type:
.. parsed-literal::
echo 1 2 3 | ./example
.. include:: detail/errors-and-warnings.rst
.. include:: detail/binary-head.rst
Easy Build and Install
----------------------
Issue the following commands in the shell (don't type ``$``; that
represents the shell's prompt):
.. parsed-literal::
**$** cd |root|
**$** ./bootstrap.sh --help
Select your configuration options and invoke ``./bootstrap.sh`` 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::
**$** ./bootstrap.sh **--prefix=**\ *path*\ /\ *to*\ /\ *installation*\ /\ *prefix*
to install somewhere else. Also, consider using the
``--show-libraries`` and ``--with-libraries=``\ *library-name-list* options to limit the
long wait you'll experience if you build everything. Finally,
.. parsed-literal::
**$** ./b2 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|
$ b2 **--build-dir=**\ /tmp/build-boost **toolset=**\ gcc stage
That will build static and shared non-debug multi-threaded variants of the libraries. To build all variants, pass the additional option, “``--build-type=complete``”.
.. 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/stage/lib/libboost_regex-gcc34-mt-d-1_36.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/stage/lib/ -lboost_regex-gcc34-mt-d-1_36**
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: http://www.boost.org/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.
.. |build-type-complete| replace:: `` ``
.. include:: detail/common-footnotes.rst
.. include:: detail/release-variables.rst
.. include:: detail/common-unix.rst
.. include:: detail/links.rst

960
more/getting_started/windows.html
View file

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

340
more/getting_started/windows.rst
View file

@ -1,340 +0,0 @@
.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
=======================================
|(logo)|__ Getting Started on Windows
=======================================
.. |(logo)| image:: ../../boost.png
:alt: Boost
:class: boost-logo
.. role:: raw-html(raw)
:format: html
__ ../../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 most reliable way to get a copy of Boost is to
download |boost.7z|_ or |boost_zip|_ and unpack it to install a complete Boost
distribution. [#zip]_
.. |boost.7z| replace:: |boost_ver|\ ``.7z``
.. _`boost.7z`: `sf-download`_
.. |boost_zip| replace:: |boost_ver|\ ``.zip``
.. _`boost_zip`: `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
Simplified Build From Source
----------------------------
If you wish to build from source with Visual C++, you can use a
simple build procedure described in this section. Open the command prompt
and change your current directory to the Boost root directory. Then, type
the following commands::
bootstrap
.\b2
The first command prepares the Boost.Build system for use. The second
command invokes Boost.Build to build the separately-compiled Boost
libraries. Please consult the `Boost.Build documentation`__ for a list
of allowed options.
__ http://www.boost.org/build/doc/html/bbv2/overview/invocation.html
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|> b2 **^**
More? **--build-dir=**\ "C:\\Documents and Settings\\dave\\build-boost" **^**
More? **--build-type=complete** **msvc** stage
Be sure to read `this note`__ about the appearance of ``^``,
``More?`` and quotation marks (``"``) in that line.
The option “\ **--build-type=complete**\ ” causes Boost.Build to build
all supported variants of the libraries. For instructions on how to
build only specific variants, please ask on the `Boost.Build mailing
list`_.
__ continuation_
.. 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] We recommend
downloading |boost.7z|_ and using 7-Zip_ to decompress
it. We no longer recommend .zip files for Boost because they are twice
as large as the equivalent .7z files. We don't recommend using Windows'
built-in decompression as it can be painfully slow for large archives.
.. _7-Zip: http://www.7-zip.org
.. [#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, and must be the
**final character** used on the line to be continued (i.e. do
not follow it with spaces). 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.
The command prompt treats each bit of whitespace in the command
as an argument separator. That means quotation marks (``"``)
are required to keep text together whenever a single
command-line argument contains spaces, as in
.. parsed-literal::
--build-dir=\ :raw-html:`<strong style="background-color:#B4FFB4">"</strong>`\ C:\\Documents\ :raw-html:`<strong style="color:#B4B4B4; background-color:#B4FFB4">_</strong>`\ and\ :raw-html:`<strong style="color:#B4B4B4; background-color:#B4FFB4">_</strong>`\ Settings\\dave\\build-boost\ \ :raw-html:`<strong style="background-color:#B4FFB4">"</strong>`
Also, for example, you can't add spaces around the ``=`` sign as in
.. parsed-literal::
--build-dir\ :raw-html:`<strong style="color:#B4B4B4; background-color:#FFB4B4">_</strong>`\ =\ :raw-html:`<strong style="color:#B4B4B4; background-color:#FFB4B4">_</strong>`\ "C:\\Documents and Settings\\dave\\build-boost"
.. |boost.zip| replace:: |boost_ver|\ ``.zip``
.. _`boost.zip`: `sf-download`_
.. |build-type-complete| replace:: **--build-type=complete**
.. include:: detail/common-footnotes.rst
.. include:: detail/release-variables.rst
.. include:: detail/common-windows.rst
.. include:: detail/links.rst

102
more/index.htm
View file

@ -1,102 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Boost More Information</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<link rel="stylesheet" href="../doc/src/boostbook.css" type="text/css" />
</head>
<body bgcolor="#ffffff" text="#000000">
<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<tr>
<td width="277">
<a href="../index.html">
<img src="../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td>
<td width="337" align="middle">
<font size="7">More Info</font>
</td>
</tr>
</table>
<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" height="26" width="681">
<tr>
<td height="16" width="671"><a href="../more/getting_started/index.html">Getting Started</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
</font>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="../libs/libraries.htm">
Libraries</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
</font>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="../tools/index.html">Tools&nbsp;</a>&nbsp;<font color="#FFFFFF">&nbsp;
</font>&nbsp;&nbsp;&nbsp;&nbsp; <a href="http://www.boost.org">Web Site</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
</font>&nbsp;&nbsp;&nbsp;&nbsp; <a href="http://www.boost.org/users/news/">News</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
</font>&nbsp;&nbsp;&nbsp; <a href="http://www.boost.org/community/">Community</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
</font>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="http://www.boost.org/users/faq.html">FAQ</a>&nbsp;</td>
</tr>
</table>
<h2>Boost Policies</h2>
<blockquote>
<p><b><a href="http://www.boost.org/community/policy.html">Mailing List Discussion Policy.</a></b>&nbsp;
What's acceptable and what isn't.</p>
<p><b><a href="http://www.boost.org/development/requirements.html">Library Requirements and Guidelines</a></b>.&nbsp;
Basic standards for those preparing a submission.</p>
<P><STRONG>
<a href="http://www.boost.org/development/separate_compilation.html">Guidelines for Libraries with Separate
Source</a></STRONG>.&nbsp; Basic tutorial for libraries that require the
building of a separate link library.</P>
<p><strong><a href="writingdoc/index.html">Writing Documentation for Boost</a>.&nbsp; </strong>&nbsp;Basic guidelines for writing documentation and templates for quickly generating
documentation that follows the guidelines.</p>
<p><b><a href="http://www.boost.org/development/test.html">Test Policies and Protocols</a></b>.&nbsp;
What tests must be in place for a Boost library.</p>
<p><b><a href="http://www.boost.org/development/submissions.html">Library Submission Process</a></b>.&nbsp;
How to submit a library to Boost.</p>
<p><b><a href="http://www.boost.org/community/reviews.html">Library Formal Review Process</a></b>.
Including how to submit a review comment.</p>
<p><b><a href="http://www.boost.org/development/header.html">Header Policy</a></b>.&nbsp; Headers are where a
library contacts its users, so programming practices are particularly
important.</p>
<p><b><a href="http://www.boost.org/development/reuse.html">Library Reuse</a></b>.&nbsp; Should Boost
libraries use other boost libraries?&nbsp; What about the C++ Standard
Library?&nbsp; It's another trade-off.</p>
<p><b><a href="http://www.boost.org/community/moderators.html">Moderators</a></b>.&nbsp; Who they are and what
they do.</p>
</blockquote>
<h2>Boost Whatever</h2>
<blockquote>
<p><b><a href="http://www.boost.org/users/license.html">License Information</a> </b>&nbsp;Information
about the Boost Software License.</p>
<p><b><a href="http://www.boost.org/users/bibliography.html">Bibliography</a> </b>&nbsp;Print and online
publications relating to Boost and Boost libraries.</p>
<p><b><a href="http://www.boost.org/users/uses.html">Who's Using Boost?</a> </b>&nbsp;
Products and organizations that are using Boost.</p>
<p><b><a href="http://www.boost.org/community/review_schedule.html">Formal Review Schedule</a></b>&nbsp;
Future, current, and recently past Formal Reviews.</p>
<p><b><a href="http://www.boost.org/users/proposal.pdf">Proposal for a C++ Library Repository Web Site</a></b>&nbsp;
The original 1998 proposal that launched Boost.</p>
<p><b><a href="http://www.boost.org/support/bugs.html">How to report bugs</a></b>&nbsp; Ways to report Boost
bugs.</p>
<p><b><a href="http://www.boost.org/community/requests.html">How to request features</a></b> Ways
to request new library features.</p>
</blockquote>
<h2>Articles and Papers</h2>
<blockquote>
<p><strong>
<a href="http://www.boost.org/development/int_const_guidelines.html">Coding Guidelines for Integral Constant
Expressions</a></strong> describes how to work through the maze of
compiler related bugs surrounding this tricky topic.</p>
</blockquote>
<hr>
<p>
Revised
<!--webbot bot="Timestamp" s-type="EDITED"
s-format="%d %B, %Y" startspan -->13 March, 2008<!--webbot bot="Timestamp" endspan i-checksum="28995" --></p>
<p>
© Copyright Beman Dawes 2003.</p>
<p>
Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</body>
</html>

576
more/writingdoc/design.html
View file

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

57
more/writingdoc/index.html
View file

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

68
more/writingdoc/introduction.html
View file

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

461
more/writingdoc/structure.html
View file

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

48
more/writingdoc/template/acknowledgments.html
View file

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

48
more/writingdoc/template/bibliography.html
View file

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

145
more/writingdoc/template/configuration.html
View file

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

78
more/writingdoc/template/definitions.html
View file

@ -1,78 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<title>{{Library}} - Definitions</title>
</head>
<body link="#0000FF" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
"header">
<tr>
<td valign="top" width="300">
<h3><a href="../../../index.htm"><img height="86" width="277" alt=
"C++ Boost" src="../../../boost.png" border="0"></a></h3>
</td>
<td valign="top">
<h1 align="center">{{Library}}</h1>
<h2 align="center">Definitions</h2>
</td>
</tr>
</table>
<hr>
<h2>Contents</h2>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#definitions">Definitions</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#definition-term1">Term 1</a></dt>
<dt><a href="#definition-term2">Term 2</a></dt>
</dl>
</dd>
</dl>
<hr>
<h2><a name="introduction" id="introduction"></a>Introduction</h2>
<p>{{Introductory text}}</p>
<h2><a name="definitions" id="definitions"></a>Definitions</h2>
<dl class="definitions">
<dt><a name="definition-term1" id="definition-term1"></a><b>{{term}}:</b>
{{definition}}</dt>
<dt><a name="definition-term2" id="definition-term2"></a><b>{{term}}:</b>
{{definition}}</dt>
</dl>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2006 <a href=
"mailto:{{address}}">{{author}}</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

61
more/writingdoc/template/faq.html
View file

@ -1,61 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<title>{{Library}} - FAQ</title>
</head>
<body link="#0000FF" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
"header">
<tr>
<td valign="top" width="300">
<h3><a href="../../../index.htm"><img height="86" width="277" alt=
"C++ Boost" src="../../../boost.png" border="0"></a></h3>
</td>
<td valign="top">
<h1 align="center">{{Library}}</h1>
<h2 align="center">Frequently Asked Questions (FAQs)</h2>
</td>
</tr>
</table>
<hr>
<dl class="page-index">
<dt><a href="#question1">{{question}}</a></dt>
<dt><a href="#question2">{{question}}</a></dt>
</dl>
<h2><a name="question1" id="question1"></a>{{question}}</h2>
<p>{{answer}}</p>
<h2><a name="question2" id="question2"></a>{{question}}</h2>
<p>{{answer}}</p>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2006 <a href=
"mailto:{{address}}">{{author}}</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

346
more/writingdoc/template/header.html
View file

@ -1,346 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<title>{{library}} - Header &lt;{{header}}&gt;</title>
</head>
<body link="#0000FF" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
"header">
<tr>
<td valign="top" width="300">
<h3><a href="../../../index.htm"><img height="86" width="277" alt=
"C++ Boost" src="../../../boost.png" border="0"></a></h3>
</td>
<td valign="top">
<h1 align="center">{{library}}</h1>
<h2 align="center">Header &lt;{{header}}&gt;</h2>
</td>
</tr>
</table>
<hr>
<h2>Contents</h2>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#macros">Macros</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#macro-spec">{{macro name}}</a></dt>
</dl>
</dd>
<dt><a href="#values">Values</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#value-spec">{{value name}}</a></dt>
</dl>
</dd>
<dt><a href="#types">Types</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#type-spec">{{type name}}</a></dt>
</dl>
</dd>
<dt><a href="#classes">Classes</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#class-spec">Class <code>{{class name}}</code></a></dt>
<dd>
<dl class="page-index">
<dt><a href="#class-spec-synopsis">Class <code>{{class
name}}</code> synopsis</a></dt>
<dt><a href="#class-spec-ctors">Class <code>{{class name}}</code>
constructors and destructor</a></dt>
<dt><a href="#class-spec-comparisons">Class <code>{{class
name}}</code> comparison functions</a></dt>
<dt><a href="#class-spec-modifiers">Class <code>{{class
name}}</code> modifier functions</a></dt>
<dt><a href="#class-spec-observers">Class <code>{{class
name}}</code> observer functions</a></dt>
<dt><a href="#class-spec-statics">Class <code>{{class
name}}</code> static functions</a></dt>
</dl>
</dd>
</dl>
</dd>
<dt><a href="#functions">Functions</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#function-spec">{{function name}}</a></dt>
</dl>
</dd>
<dt><a href="#objects">Objects</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#object-spec">{{object name}}</a></dt>
</dl>
</dd>
<dt><a href="#examples">Example(s)</a></dt>
</dl>
<hr>
<h2><a name="introduction" id="introduction"></a>Introduction</h2>
<p>{{Introductory text}}</p>
<h2><a name="macros" id="macros"></a>Macros</h2>
<p><a name="macro-spec" id="macro-spec"></a>{{Macro specifications}}</p>
<h2><a name="values" id="values"></a>Values</h2>
<p><a name="value-spec" id="value-spec"></a>{{Value specifications}}</p>
<h2><a name="types" id="types"></a>Types</h2>
<p><a name="type-spec" id="type-spec"></a>{{Type specifications}}</p>
<h2><a name="classes" id="classes"></a>Classes</h2>
<h3><a name="class-spec" id="class-spec"></a>Class <code>{{class
name}}</code></h3>
<p>{{class overview text}}</p>
<h4><a name="class-spec-synopsis" id="class-spec-synopsis"></a>Class
<code>{{class name}}</code> synopsis</h4>
<pre>
namespace boost
{
class {{class name}}
{
};
};
</pre>
<h4><a name="class-spec-ctors" id="class-spec-ctors"></a>Class
<code>{{class name}}</code> constructors and destructor</h4>
<pre>
{{constructor}}
</pre>
<dl class="function-semantics">
<dt><b>Requires:</b> {{text}}</dt>
<dt><b>Effects:</b> {{text}}</dt>
<dt><b>Postconditions:</b> {{text}}</dt>
<dt><b>Returns:</b> {{text}}</dt>
<dt><b>Throws:</b> {{text}}</dt>
<dt><b>Complexity:</b> {{text}}</dt>
<dt><b>Note:</b> {{text}}</dt>
<dt><b>Danger:</b> {{text}}</dt>
<dt><b>Rationale:</b> {{text}}</dt>
</dl>
<pre>
{{destructor}}
</pre>
<dl class="function-semantics">
<dt><b>Requires:</b> {{text}}</dt>
<dt><b>Effects:</b> {{text}}</dt>
<dt><b>Postconditions:</b> {{text}}</dt>
<dt><b>Returns:</b> {{text}}</dt>
<dt><b>Throws:</b> {{text}}</dt>
<dt><b>Complexity:</b> {{text}}</dt>
<dt><b>Note:</b> {{text}}</dt>
<dt><b>Danger:</b> {{text}}</dt>
<dt><b>Rationale:</b> {{text}}</dt>
</dl>
<h4><a name="class-spec-comparisons" id="class-spec-comparisons"></a>Class
<code>{{class name}}</code> comparison functions</h4>
<pre>
{{function}}
</pre>
<dl class="function-semantics">
<dt><b>Requires:</b> {{text}}</dt>
<dt><b>Effects:</b> {{text}}</dt>
<dt><b>Postconditions:</b> {{text}}</dt>
<dt><b>Returns:</b> {{text}}</dt>
<dt><b>Throws:</b> {{text}}</dt>
<dt><b>Complexity:</b> {{text}}</dt>
<dt><b>Note:</b> {{text}}</dt>
<dt><b>Danger:</b> {{text}}</dt>
<dt><b>Rationale:</b> {{text}}</dt>
</dl>
<h4><a name="class-spec-modifiers" id="class-spec-modifiers"></a>Class
<code>{{class name}}</code> modifier functions</h4>
<pre>
{{function}}
</pre>
<dl class="function-semantics">
<dt><b>Requires:</b> {{text}}</dt>
<dt><b>Effects:</b> {{text}}</dt>
<dt><b>Postconditions:</b> {{text}}</dt>
<dt><b>Returns:</b> {{text}}</dt>
<dt><b>Throws:</b> {{text}}</dt>
<dt><b>Complexity:</b> {{text}}</dt>
<dt><b>Note:</b> {{text}}</dt>
<dt><b>Danger:</b> {{text}}</dt>
<dt><b>Rationale:</b> {{text}}</dt>
</dl>
<h4><a name="class-spec-observers" id="class-spec-observers"></a>Class
<code>{{class name}}</code> observer functions</h4>
<pre>
{{function}}
</pre>
<dl class="function-semantics">
<dt><b>Requires:</b> {{text}}</dt>
<dt><b>Effects:</b> {{text}}</dt>
<dt><b>Postconditions:</b> {{text}}</dt>
<dt><b>Returns:</b> {{text}}</dt>
<dt><b>Throws:</b> {{text}}</dt>
<dt><b>Complexity:</b> {{text}}</dt>
<dt><b>Note:</b> {{text}}</dt>
<dt><b>Danger:</b> {{text}}</dt>
<dt><b>Rationale:</b> {{text}}</dt>
</dl>
<h4><a name="class-spec-statics" id="class-spec-statics"></a>Class
<code>{{class name}}</code> static functions</h4>
<pre>
{{function}}
</pre>
<dl class="function-semantics">
<dt><b>Requires:</b> {{text}}</dt>
<dt><b>Effects:</b> {{text}}</dt>
<dt><b>Postconditions:</b> {{text}}</dt>
<dt><b>Returns:</b> {{text}}</dt>
<dt><b>Throws:</b> {{text}}</dt>
<dt><b>Complexity:</b> {{text}}</dt>
<dt><b>Note:</b> {{text}}</dt>
<dt><b>Danger:</b> {{text}}</dt>
<dt><b>Rationale:</b> {{text}}</dt>
</dl>
<h2><a name="functions" id="functions"></a>Functions</h2>
<pre>
<a name="function-spec" id="function-spec"></a>{{function}}
</pre>
<dl class="function-semantics">
<dt><b>Requires:</b> {{text}}</dt>
<dt><b>Effects:</b> {{text}}</dt>
<dt><b>Postconditions:</b> {{text}}</dt>
<dt><b>Returns:</b> {{text}}</dt>
<dt><b>Throws:</b> {{text}}</dt>
<dt><b>Complexity:</b> {{text}}</dt>
<dt><b>Note:</b> {{text}}</dt>
<dt><b>Danger:</b> {{text}}</dt>
<dt><b>Rationale:</b> {{text}}</dt>
</dl>
<h2><a name="objects" id="objects"></a>Objects</h2>
<p><a name="object-spec" id="object-spec"></a>{{Object specifications}}</p>
<h2><a name="examples" id="examples"></a>Example(s)</h2>
<p>{{Example(s)}}</p>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2006 <a href=
"mailto:{{address}}">{{author}}</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

126
more/writingdoc/template/index.html
View file

@ -1,126 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<title>{{Library}}</title>
</head>
<body link="#0000FF" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
"header">
<tr>
<td valign="top" width="300">
<h3><a href="../../../index.htm"><img height="86" width="277" alt=
"C++ Boost" src="../../../boost.png" border="0"></a></h3>
</td>
<td valign="top">
<h1 align="center">{{Library}}</h1>
<h2 align="center">Index</h2>
</td>
</tr>
</table>
<hr>
<h2>Contents</h2>
<dl class="index">
<dt><a href="overview.html">Overview</a></dt>
<dt>Reference</dt>
<dd>
<dl class="index">
<dt><a href="header.html">{{header}}</a></dt>
<dd>
<dl class="index">
<dt><a href="header.html#macros">Macros</a></dt>
<dd>
<dl class="index">
<dt><a href="header.html#macro-spec">{{macro name}}</a></dt>
</dl>
</dd>
<dt><a href="header.html#values">Values</a></dt>
<dd>
<dl class="index">
<dt><a href="header.html#value-spec">{{value name}}</a></dt>
</dl>
</dd>
<dt><a href="header.html#types">Types</a></dt>
<dd>
<dl class="index">
<dt><a href="header.html#value-spec">{{type name}}</a></dt>
</dl>
</dd>
<dt><a href="header.html#classes">Classes</a></dt>
<dd>
<dl class="index">
<dt><a href="header.html#value-spec">{{class name}}</a></dt>
</dl>
</dd>
<dt><a href="header.html#functions">Functions</a></dt>
<dd>
<dl class="index">
<dt><a href="header.html#value-spec">{{function
name}}</a></dt>
</dl>
</dd>
<dt><a href="header.html#objects">Objects</a></dt>
<dd>
<dl class="index">
<dt><a href="header.html#value-spec">{{object name}}</a></dt>
</dl>
</dd>
</dl>
</dd>
</dl>
</dd>
<dt><a href="configuration.html">Configuration Information</a></dt>
<dt><a href="rationale.html">Rationale</a></dt>
<dt><a href="definitions.html">Definitions</a></dt>
<dt><a href="faq.html">Frequently Asked Questions (FAQs)</a></dt>
<dt><a href="bibliography.html">Bibliography</a></dt>
<dt><a href="acknowledgments.html">Acknowledgments</a></dt>
</dl>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2006 <a href=
"mailto:{{address}}">{{author}}</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

79
more/writingdoc/template/overview.html
View file

@ -1,79 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<title>{{Library}} - Overview</title>
</head>
<body link="#0000FF" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
"header">
<tr>
<td valign="top" width="300">
<h3><a href="../../../index.htm"><img height="86" width="277" alt=
"C++ Boost" src="../../../boost.png" border="0"></a></h3>
</td>
<td valign="top">
<h1 align="center">{{Library}}</h1>
<h2 align="center">Overview</h2>
</td>
</tr>
</table>
<hr>
<dl class="index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#topic1">First topic</a></dt>
<dt><a href="#topic2">Second topic</a></dt>
<dt><a href="#footnotes">Footnotes</a></dt>
</dl>
<h2><a name="introduction" id="introduction"></a>Introduction</h2>
<p>{{text}}</p>
<h2><a name="topic1" id="topic1"></a>First Topic</h2>
<p>{{text}}</p>
<h2><a name="topic2" id="topic2"></a>Second Topic</h2>
<p>{{text}}</p>
<h2><a name="footnotes" id="footnotes"></a>Footnotes</h2>
<dl>
<dt><a name="footnote1" class="footnote" id="footnote1">(1)</a>
{{text}}</dt>
<dt><a name="footnote2" class="footnote" id="footnote2">(2)</a>
{{text}}</dt>
</dl>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2006 <a href=
"mailto:{{address}}">{{author}}</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

79
more/writingdoc/template/rationale.html
View file

@ -1,79 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<title>{{Library}} - Rationale</title>
</head>
<body link="#0000FF" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
"header">
<tr>
<td valign="top" width="300">
<h3><a href="../../../index.htm"><img height="86" width="277" alt=
"C++ Boost" src="../../../boost.png" border="0"></a></h3>
</td>
<td valign="top">
<h1 align="center">{{Library}}</h1>
<h2 align="center">Rationale</h2>
</td>
</tr>
</table>
<hr>
<dl class="index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#topic1">First topic</a></dt>
<dt><a href="#topic2">Second topic</a></dt>
<dt><a href="#footnotes">Footnotes</a></dt>
</dl>
<h2><a name="introduction" id="introduction"></a>Introduction</h2>
<p>{{text}}</p>
<h2><a name="topic1" id="topic1"></a>First Topic</h2>
<p>{{text}}</p>
<h2><a name="topic2" id="topic2"></a>Second Topic</h2>
<p>{{text}}</p>
<h2><a name="footnotes" id="footnotes"></a>Footnotes</h2>
<dl>
<dt><a name="footnote1" class="footnote" id="footnote1">(1)</a>
{{text}}</dt>
<dt><a name="footnote2" class="footnote" id="footnote2">(2)</a>
{{text}}</dt>
</dl>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
<p><i>Copyright &copy; 2006 <a href=
"mailto:{{address}}">{{author}}</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>