A.3. Preprocessor Library Structure

Since in-depth coverage of the Boost Preprocessor library is beyond the scope of this book, we'll try to give you the tools to gain an in-depth understanding of the library here. To do that, you'll need to use the electronic Preprocessor library documentation, which begins with the index.html file in the libs/preprocessor/ subdirectory of your Boost installation.

On the left of your browser window you'll see an index, and if you follow the "Headers" link, it will reveal the structure of the boost/preprocessor/ directory. Most of the library's headers are grouped into subdirectories according to related functionality. The top-level directory contains only a few headers that provide general-purpose macros, along with a header for each subdirectory that simply #includes all the headers in that subdirectory. For example, boost/preprocessor/selection.hpp does nothing more than to #include the min.hpp and max.hpp headers that comprise the contents of boost/preprocessor/selection/. The headers whose names don't correspond to subdirectories generally declare a macro whose name is the same as the name of the header, without the extension, and with a BOOST_PP_ prefix. For example, boost/preprocessor/selection/max.hpp declares BOOST_PP_MAX.

You'll also notice that often a header will declare an additional macro with a _D, _R, or _Z suffix.^[4] For instance, boost/preprocessor/selection/max.hpp also declares BOOST_PP_MAX_D. For the purposes of this appendix, you should ignore those macros. Eventually you will want to understand the reason for their existence and how they can be used to optimize preprocessing speed; consult the Topics section of the library documentation under the subheading "reentrancy" for that information.

^[4] Macros with _1ST, _2ND, or _3RD suffixes, if they appear, should be ignored for a different reason: They are deprecated and will be removed from the library soon.