ceph/src/boost/more/getting_started/detail/distro.rst

   1 .. Copyright David Abrahams 2006. Distributed under the Boost
   2 .. Software License, Version 1.0. (See accompanying
   3 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   4
   5 The Boost Distribution
   6 ======================
   7
   8 This is a sketch of the resulting directory structure:
   9
  10 .. parsed-literal::
  11
  12  |boost_ver-bold|\ |//| .................\ *The “boost root directory”*
  13     **index.htm** .........\ *A copy of www.boost.org starts here*
  14     **boost**\ |//| .........................\ *All Boost Header files*
  15     |precompiled-dir|
  16     **libs**\ |//| ............\ *Tests, .cpp*\ s\ *, docs, etc., by library*
  17       **index.html** ........\ *Library documentation starts here*
  18       **algorithm**\ |//|
  19       **any**\ |//|
  20       **array**\ |//|
  21                       *…more libraries…*
  22     **status**\ |//| .........................\ *Boost-wide test suite*
  23     **tools**\ |//| ...........\ *Utilities, e.g. Boost.Build, quickbook, bcp*
  24     **more**\ |//| ..........................\ *Policy documents, etc.*
  25     **doc**\ |//| ...............\ *A subset of all Boost library docs*
  26
  27 .. sidebar:: Header Organization
  28
  29    .. class:: pre-wrap
  30
  31      The organization of Boost library headers isn't entirely uniform,
  32      but most libraries follow a few patterns:
  33
  34      * Some older libraries and most very small libraries place all
  35        public headers directly into ``boost``\ |/|.
  36
  37      * Most libraries' public headers live in a subdirectory of
  38        ``boost``\ |/|, named after the library.  For example, you'll find
  39        the Python library's ``def.hpp`` header in
  40
  41        .. parsed-literal::
  42
  43          ``boost``\ |/|\ ``python``\ |/|\ ``def.hpp``.
  44
  45      * Some libraries have an “aggregate header” in ``boost``\ |/| that
  46        ``#include``\ s all of the library's other headers.  For
  47        example, Boost.Python_'s aggregate header is
  48
  49        .. parsed-literal::
  50
  51          ``boost``\ |/|\ ``python.hpp``.
  52
  53      * Most libraries place private headers in a subdirectory called
  54        ``detail``\ |/|, or ``aux_``\ |/|.  Don't expect to find
  55        anything you can use in these directories.
  56
  57 It's important to note the following:
  58
  59 .. _Boost root directory:
  60
  61 1. The path to the **boost root directory** (often |default-root|) is
  62    sometimes referred to as ``$BOOST_ROOT`` in documentation and
  63    mailing lists .
  64
  65 2. To compile anything in Boost, you need a directory containing
  66    the ``boost``\ |/| subdirectory in your ``#include`` path.  |include-paths|
  67
  68 3. Since all of Boost's header files have the ``.hpp`` extension,
  69    and live in the ``boost``\ |/| subdirectory of the boost root, your
  70    Boost ``#include`` directives will look like:
  71
  72    .. parsed-literal::
  73
  74      #include <boost/\ *whatever*\ .hpp>
  75
  76    or
  77
  78    .. parsed-literal::
  79
  80      #include "boost/\ *whatever*\ .hpp"
  81
  82    depending on your preference regarding the use of angle bracket
  83    includes.  |forward-slashes|
  84
  85 4. Don't be distracted by the ``doc``\ |/| subdirectory; it only
  86    contains a subset of the Boost documentation.  Start with
  87    ``libs``\ |/|\ ``index.html`` if you're looking for the whole enchilada.
  88