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