ceph/src/boost/libs/spirit/doc/structure.qbk

   1 [/==============================================================================
   2     Copyright (C) 2001-2011 Joel de Guzman
   3     Copyright (C) 2001-2011 Hartmut Kaiser
   4
   5     Distributed under the Boost Software License, Version 1.0. (See accompanying
   6     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   7 ===============================================================================/]
   8
   9 [section Structure]
  10
  11 [section Include]
  12
  13 Spirit is a header file only library. There are no libraries to link to.
  14 This section documents the structure of the Spirit headers.
  15
  16 Spirit contains five sub-libraries plus a 'support' module where common
  17 support classes are placed:
  18
  19 * Classic
  20 * Qi
  21 * Karma
  22 * Lex
  23 * Phoenix
  24 * Support
  25
  26 The top Spirit directory is:
  27
  28     BOOST_ROOT/boost/spirit
  29
  30 Currently, the directory contains:
  31
  32     [actor]     [attribute]     [core]      [debug]
  33     [dynamic]   [error_handling][home]      [include]
  34     [iterator]  [meta]          [phoenix]   [repository]
  35     [symbols]   [tree]          [utility]
  36
  37 These include some old v1.8 directories that are now deprecated. These
  38 are: actor, attribute, core, debug, dynamic, error_handling, iterator,
  39 meta, phoenix, symbols, tree and utility. There is no guarantee that these
  40 directories will still be present in future versions of Spirit. We only
  41 keep them for backward compatibility. Please be warned.
  42
  43 Each directory (except include, home, and repository) has a corresponding
  44 header file that contains forwarding includes of each relevant include file
  45 that the directory contains. For example, there exists a
  46 <boost/spirit/actor.hpp> header file which includes all the relevant files
  47 from the boost/spirit/actor directory.
  48
  49 To distinguish between Spirit versions, you can inspect the version file:
  50
  51     <boost/spirit/version.hpp>
  52
  53 using the preprocessor define
  54
  55     SPIRIT_VERSION
  56
  57 It is a hex number where the first two digits determine the major version while
  58 the last two digits determine the minor version. For example:
  59
  60     #define SPIRIT_VERSION 0x2010 // version 2.1
  61
  62 The include directory at:
  63
  64     BOOST_ROOT/boost/spirit/include
  65
  66 is a special flat directory that contains all the Spirit headers. To
  67 accommodate the flat structure, the headers are prefixed with the
  68 sub-library name:
  69
  70 * classic_
  71 * karma_
  72 * lex_
  73 * phoenix1_
  74 * phoenix_
  75 * qi_
  76 * support_
  77
  78 For example, if you used to include <boost/spirit/actor.hpp>,
  79 which is now a deprecated header, you should instead include
  80 <boost/spirit/include/classic_actor.hpp>
  81
  82 If you want to simply include the main sub-library name, then you can
  83 include:
  84
  85 * <boost/spirit/include/classic.hpp>
  86 * <boost/spirit/include/karma.hpp>
  87 * <boost/spirit/include/lex.hpp>
  88 * <boost/spirit/include/phoenix1.hpp>
  89 * <boost/spirit/include/phoenix.hpp>
  90 * <boost/spirit/include/qi.hpp>
  91 * <boost/spirit/include/support.hpp>
  92
  93 The home directory:
  94
  95     BOOST_ROOT/boost/spirit/home
  96
  97 is the /real/ home of Spirit. It is the place where the various sub-libraries
  98 actually exist. The home directory contains:
  99
 100     [classic]   [karma]     [lex]
 101     [phoenix]   [qi]        [support]
 102
 103 As usual, these directories have their corresponding include files:
 104
 105 * <boost/spirit/home/classic.hpp>
 106 * <boost/spirit/home/karma.hpp>
 107 * <boost/spirit/home/lex.hpp>
 108 * <boost/spirit/home/phoenix.hpp>
 109 * <boost/spirit/home/qi.hpp>
 110 * <boost/spirit/home/support.hpp>
 111
 112 The various sub-libraries include files can be found in each
 113 sub-directory containing the particular sub-library. The include
 114 structure of a sub-library is covered in its documentation. For
 115 consistency, each library follows the same scheme as above.
 116
 117 To keep it simple, you should use the flat include directory at
 118 boost/spirit/include.
 119
 120 For some additional information about the rationale you might want to have a
 121 look at the FAQ entry __include_structure_faq__.
 122
 123 The subdirectory `boost/spirit/repository` does not belong to the main Spirit
 124 distribution. For more information please refer to:
 125 [link spirit.repository Spirit Repository].
 126
 127 [endsect] [/Include]
 128
 129 [endsect]